Cargando

Manejo de respuestas de uso de herramientas

Lección 247 min
Cargando

Cuando Claude decide usar una herramienta, devuelve una estructura de respuesta especial que requiere un manejo cuidadoso. Comprender este formato de respuesta e implementar una gestión adecuada de la conversación es crucial para construir aplicaciones robustas habilitadas para herramientas.

Configuración de elección de herramienta

Antes de profundizar en las respuestas, vale la pena entender cómo controlar cuándo Claude usa herramientas. El parámetro toolChoice te ofrece tres opciones:

Tres configuraciones de toolChoice escritas como JSON, "auto", "any" y "tool" con un nombre, emparejadas con los comportamientos listados abajo.

  • auto - Claude decide si usar una herramienta (comportamiento predeterminado)
  • any - Claude debe usar una herramienta pero puede elegir cuál
  • specific tool - Fuerza a Claude a usar una herramienta en particular por nombre

La tercera opción es especialmente útil para pruebas cuando quieres asegurarte de que Claude llame a una función específica.

Estructura de mensaje de múltiples partes

Cuando Claude quiere usar una herramienta, devuelve un mensaje del asistente con múltiples partes de contenido en lugar de solo texto:

Lista de contenido del mensaje del asistente: una parte de "Text" y una parte "toolUse" que llama a get_current_datetime con date_format %H:%M:%S.

La respuesta contiene dos partes:

  • Text Part - Explicación legible para humanos como "Puedo ayudarte a averiguar la hora actual. Déjame buscar esa información para ti"
  • ToolUse Part - Datos estructurados que indican qué herramienta ejecutar y con qué argumentos

Comprendiendo la parte ToolUse

La parte ToolUse contiene tres piezas clave de información:

Ejemplo de parte ToolUse que nombra la herramienta "get_current_datetime" con la entrada date_format "%H:%M:%S", además de un toolUseId.

  • toolUseId - Un identificador único que necesitarás al enviar de vuelta el resultado de la herramienta
  • name - El nombre exacto de la herramienta de tu esquema JSON que Claude quiere llamar
  • input - Un diccionario de argumentos que Claude quiere pasar a la función de tu herramienta

Flujo de conversación con herramientas

El uso de herramientas sigue un patrón de conversación específico que requiere mantener el historial completo de mensajes:

Nuestro servidor envía a Claude todo el historial: usuario "¿Qué hora es?", texto del asistente y parte ToolUse, usuario parte ToolResult.

Cuando recibes una solicitud de uso de herramienta, necesitas:

  1. Extraer la información de la herramienta de la parte ToolUse
  2. Ejecutar la función real de tu herramienta
  3. Enviar de vuelta un mensaje ToolResult junto con el historial completo de la conversación
  4. Incluir el mensaje original del usuario y el mensaje de uso de herramienta del asistente en tu siguiente solicitud

Actualización de funciones auxiliares

Para manejar correctamente los mensajes de múltiples partes, necesitarás actualizar tus funciones de manejo de mensajes. Así es como puedes hacer que tus funciones sean lo suficientemente flexibles para manejar tanto texto simple como contenido complejo de múltiples partes:

python
def add_user_message(messages, content):
    if isinstance(content, str):
        user_message = {"role": "user", "content": [{"text": content}]}
    else:
        user_message = {"role": "user", "content": content}
    messages.append(user_message)

def add_assistant_message(messages, content):
    if isinstance(content, str):
        assistant_message = {"role": "assistant", "content": [{"text": content}]}
    else:
        assistant_message = {"role": "assistant", "content": content}
    messages.append(assistant_message)

También querrás actualizar tu función de chat para que devuelva tanto el texto como la lista completa de partes:

python
def chat(messages, system=None, temperature=1.0, stop_sequences=[], tools=None):
    # ... código de configuración existente ...
    
    response = client.converse(**params)
    
    text = response["output"]["message"]["content"][0]["text"]
    parts = response["output"]["message"]["content"]
    
    return text, parts

Revisando el motivo de detención

La respuesta de Claude también incluye un campo stopReason de nivel superior. Cuando es igual a "tool_use", Claude quiere llamar a una herramienta en lugar de simplemente proporcionar una respuesta de texto; esa es tu señal para extraer la información de la herramienta y ejecutar la función solicitada. El asistente chat() de arriba aún no expone este campo, así que por ahora puedes detectar el uso de herramientas revisando la lista de partes devuelta en busca de una entrada con una clave toolUse. Extenderás chat() para que devuelva stopReason directamente en una lección posterior.

Con estos patrones implementados, estás listo para manejar las solicitudes de uso de herramientas de Claude y mantener un flujo de conversación adecuado a lo largo de interacciones de herramientas de múltiples turnos.