Claude Academy
Cargando

Manejo de respuestas de uso de herramientas

Lección 247 min

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:

  • auto - Claude decide si usar una herramienta (comportamiento predeterminado)
  • any - Claude debe usar una herramienta pero puede elegir cuál
  • specific tool - Forzar a Claude a usar una herramienta 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 mensajes 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:

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 te indican qué herramienta ejecutar y con qué argumentos

Comprendiendo la parte ToolUse

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

  • 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 tu función de 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:

Cuando recibes una solicitud de uso de herramienta, necesitas:

  1. Extraer la información de la herramienta de la parte ToolUse
  2. Ejecutar tu función de herramienta real
  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. Aquí te mostramos cómo 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

Verificando la razón de detención

La respuesta de Claude también incluye un campo de nivel superior stopReason. 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() anterior 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.