Manejar llamadas de herramientas

Esta página cubre el ciclo de vida de las llamadas de herramientas: leer bloques tool_use de la respuesta de Claude, formatear bloques tool_result en tu respuesta y señalar errores. Para la abstracción del SDK que maneja esto automáticamente, consulta Tool Runner.

La respuesta de Claude difiere según si utiliza una herramienta de cliente o servidor.

Manejar resultados de herramientas de cliente

La respuesta tendrá un stop_reason de tool_use y uno o más bloques de contenido tool_use que incluyen:

• id: Un identificador único para este bloque de uso de herramienta en particular. Se utilizará para hacer coincidir los resultados de la herramienta más adelante.
• name: El nombre de la herramienta que se está utilizando.
• input: Un objeto que contiene la entrada que se pasa a la herramienta, conforme al input_schema de la herramienta.

Cuando recibas una respuesta de uso de herramienta para una herramienta de cliente, deberías:

1. Extraer name, id e input del bloque tool_use.
2. Ejecutar la herramienta real en tu base de código correspondiente a ese nombre de herramienta, pasando la input de la herramienta.
3. Continuar la conversación enviando un nuevo mensaje con el role de user y un bloque de content que contenga el tipo tool_result y la siguiente información:
   • tool_use_id: El id de la solicitud de uso de herramienta para la cual este es un resultado.
   • content: El resultado de la herramienta, como una cadena (por ejemplo, "content": "15 degrees"), una lista de bloques de contenido anidados (por ejemplo, "content": [{"type": "text", "text": "15 degrees"}]), o una lista de bloques de documentos (por ejemplo, "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]). Estos bloques de contenido pueden usar los tipos text, image o document.
   • is_error (opcional): Establece en true si la ejecución de la herramienta resultó en un error.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

Después de recibir el resultado de la herramienta, Claude utilizará esa información para continuar generando una respuesta a la solicitud del usuario original.

Manejar resultados de herramientas de servidor

Claude ejecuta la herramienta internamente e incorpora los resultados directamente en su respuesta sin requerir interacción adicional del usuario.

Manejar errores con is_error

Hay varios tipos diferentes de errores que pueden ocurrir al usar herramientas con Claude:

Próximos pasos

• Para ejecutar múltiples herramientas en un turno, consulta Parallel tool use.
• Para la abstracción del SDK que automatiza este bucle, consulta Tool Runner.
• Para el flujo de trabajo completo de uso de herramientas, consulta Define tools.