MensajesHerramientas

Manejar llamadas a herramientas

Analiza bloques tool_use, formatea respuestas tool_result y maneja errores con is_error.

Esta página cubre el ciclo de vida de las llamadas a 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.

Más simple con Tool Runner: El manejo manual de herramientas descrito en esta página es gestionado automáticamente por Tool Runner. Usa esta página cuando necesites control personalizado sobre la ejecución de herramientas.

La respuesta de Claude difiere según si usa una herramienta de cliente o de 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 usará para hacer coincidir los resultados de la herramienta más adelante.
name: El nombre de la herramienta que se está usando.
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 herramientas para una herramienta de cliente, debes:

Extraer el name, id e input del bloque tool_use.
Ejecutar la herramienta real en tu código correspondiente a ese nombre de herramienta, pasando el input de la herramienta.
Continuar la conversación enviando un nuevo mensaje con el role de user, y un bloque 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 (opcional): 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 documento (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, document o search_result.
- is_error (opcional): Establécelo en true si la ejecución de la herramienta resultó en un error.

Requisitos importantes de formato:

Los bloques de resultado de herramienta deben seguir inmediatamente a sus bloques de uso de herramienta correspondientes en el historial de mensajes. No puedes incluir ningún mensaje entre el mensaje de uso de herramienta del asistente y el mensaje de resultado de herramienta del usuario.
En el mensaje de usuario que contiene resultados de herramientas, los bloques tool_result deben aparecer PRIMERO en el array de contenido. Cualquier texto debe aparecer DESPUÉS de todos los resultados de herramientas.
Si el turno del asistente también llamó a una herramienta de servidor que aún no tiene bloque de resultado, el mensaje de usuario debe contener únicamente bloques tool_result. El texto después de los resultados termina el turno anticipadamente; para una herramienta de servidor que Claude llamó directamente, la solicitud falla entonces con un error 400 que nombra la herramienta de servidor sin resolver. Consulta Razones de detención y respaldo.

Por ejemplo, esto causará un error 400:

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

Esto es correcto cuando el turno del asistente llama únicamente a herramientas de cliente:

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

Si recibes un error como "tool_use ids were found without tool_result blocks immediately after", verifica que tus resultados de herramientas estén formateados correctamente.

Los resultados de herramientas a menudo contienen contenido de fuentes fuera de tu control: páginas web, correo electrónico entrante, cargas de usuarios, APIs de terceros. Trata ese contenido como no confiable: un atacante que pueda influir en él podría incrustar instrucciones que intenten redirigir a Claude (inyección indirecta de prompts). Mantén el contenido no confiable dentro de bloques tool_result en lugar de indicaciones del sistema (system) o bloques text simples de usuario, y consulta Mitigar jailbreaks e inyecciones de prompts para un endurecimiento adicional.

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

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.

Una respuesta puede contener tanto un bloque tool_use de cliente como un bloque server_tool_use que no tiene bloque de resultado. Esa llamada a herramienta de servidor aún no ha terminado, y su bloque de resultado llega en una respuesta posterior. Responde con un mensaje de usuario que contenga únicamente los bloques tool_result para las herramientas de cliente y mantén el mismo array tools; para una herramienta de servidor que Claude llamó directamente, la API la ejecuta en esa solicitud y la siguiente respuesta comienza con su bloque de resultado. Consulta Razones de detención y respaldo.

Diferencias con otras APIs

A diferencia de las APIs que separan el uso de herramientas o usan roles especiales como tool o function, la API de Claude integra las herramientas directamente en la estructura de mensajes user y assistant.

Los mensajes contienen arrays de bloques text, image, tool_use y tool_result. Los mensajes user incluyen contenido del cliente y tool_result, mientras que los mensajes assistant contienen contenido generado por IA y tool_use.

Manejar errores con is_error

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

Próximos pasos

Uso de herramientas en paralelo

Maneja respuestas donde Claude llama a varias herramientas en un solo turno.

Tool Runner (SDK)

Deja que el SDK gestione el bucle de tool_use, el formateo de resultados y los reintentos por ti.

Definir herramientas

Escribe esquemas y descripciones que guíen a Claude hacia la herramienta correcta.

Was this page helpful?

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 usará para hacer coincidir los resultados de la herramienta más adelante.

name: El nombre de la herramienta que se está usando.

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 herramientas para una herramienta de cliente, debes:

Extraer el name, id e input del bloque tool_use.

Ejecutar la herramienta real en tu código correspondiente a ese nombre de herramienta, pasando el input de la herramienta.

Continuar la conversación enviando un nuevo mensaje con el role de user, y un bloque 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 (opcional): 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 documento (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, document o search_result.
is_error (opcional): Establécelo en true si la ejecución de la herramienta resultó en un error.

Requisitos importantes de formato:

Los bloques de resultado de herramienta deben seguir inmediatamente a sus bloques de uso de herramienta correspondientes en el historial de mensajes. No puedes incluir ningún mensaje entre el mensaje de uso de herramienta del asistente y el mensaje de resultado de herramienta del usuario.
En el mensaje de usuario que contiene resultados de herramientas, los bloques tool_result deben aparecer PRIMERO en el array de contenido. Cualquier texto debe aparecer DESPUÉS de todos los resultados de herramientas.
Si el turno del asistente también llamó a una herramienta de servidor que aún no tiene bloque de resultado, el mensaje de usuario debe contener únicamente bloques tool_result. El texto después de los resultados termina el turno anticipadamente; para una herramienta de servidor que Claude llamó directamente, la solicitud falla entonces con un error 400 que nombra la herramienta de servidor sin resolver. Consulta Razones de detención y respaldo.

Por ejemplo, esto causará un error 400:

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

Esto es correcto cuando el turno del asistente llama únicamente a herramientas de cliente:

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

Si recibes un error como "tool_use ids were found without tool_result blocks immediately after", verifica que tus resultados de herramientas estén formateados correctamente.

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

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.

Diferencias con otras APIs

Manejar resultados de herramientas de cliente

Ejemplo de respuesta de la API con un bloque de contenido `tool_use`

Ejemplo de resultado de herramienta exitoso

Ejemplo de resultado de herramienta con imágenes

Ejemplo de resultado de herramienta vacío

Ejemplo de resultado de herramienta con documentos

Manejar resultados de herramientas de servidor

Manejar errores con is_error

Error de ejecución de herramienta

Nombre de herramienta inválido

Errores de herramientas de servidor

Próximos pasos

Manejar resultados de herramientas de cliente

Ejemplo de respuesta de la API con un bloque de contenido `tool_use`

Ejemplo de resultado de herramienta exitoso

Ejemplo de resultado de herramienta con imágenes

Ejemplo de resultado de herramienta vacío

Ejemplo de resultado de herramienta con documentos

Manejar resultados de herramientas de servidor

Manejar errores con is_error

Error de ejecución de herramienta

Nombre de herramienta inválido

Errores de herramientas de servidor

Próximos pasos

Manejar resultados de herramientas de cliente

Manejar resultados de herramientas de servidor

Manejar errores con is_error

Próximos pasos

Manejar resultados de herramientas de cliente

Manejar resultados de herramientas de servidor

Manejar errores con is_error

Próximos pasos