MensajesHerramientas

Maneja 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.

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

Manejo de 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 herramientas en particular. Esto 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 base de 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 herramientas 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 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, document o search_result.
- is_error (opcional): Establécelo en true si la ejecución de la herramienta resultó en un error.

Requisitos de formato importantes:

Los bloques de resultado de herramienta deben seguir inmediatamente a sus bloques de uso de herramientas correspondientes en el historial de mensajes. No puedes incluir ningún mensaje entre el mensaje de uso de herramientas del asistente y el mensaje de resultado de herramienta del usuario.
En el mensaje del usuario que contiene los resultados de herramientas, los bloques tool_result deben ir PRIMERO en el arreglo de contenido. Cualquier texto debe ir 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 un bloque de resultado, el mensaje del usuario debe contener solo bloques tool_result. El texto después de los resultados termina el turno antes de tiempo; para una herramienta de servidor que Claude llamó directamente, la solicitud entonces falla con un error 400 que nombra la herramienta de servidor no resuelta. 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 solo 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.

Manejo de 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.

Manejo de 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 formato de resultados y los reintentos por ti.

Define herramientas

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

Was this page helpful?

MensajesHerramientas

Maneja llamadas a herramientas

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

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

Manejo de 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 herramientas en particular. Esto 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 base de 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 herramientas 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 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, document o search_result.
- is_error (opcional): Establécelo en true si la ejecución de la herramienta resultó en un error.

Requisitos de formato importantes:

Los bloques de resultado de herramienta deben seguir inmediatamente a sus bloques de uso de herramientas correspondientes en el historial de mensajes. No puedes incluir ningún mensaje entre el mensaje de uso de herramientas del asistente y el mensaje de resultado de herramienta del usuario.
En el mensaje del usuario que contiene los resultados de herramientas, los bloques tool_result deben ir PRIMERO en el arreglo de contenido. Cualquier texto debe ir 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 un bloque de resultado, el mensaje del usuario debe contener solo bloques tool_result. El texto después de los resultados termina el turno antes de tiempo; para una herramienta de servidor que Claude llamó directamente, la solicitud entonces falla con un error 400 que nombra la herramienta de servidor no resuelta. 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 solo 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.

Manejo de 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.

Manejo de 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 formato de resultados y los reintentos por ti.

Define herramientas

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

Was this page helpful?

Manejo de 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

Manejo de resultados de herramientas de servidor

Manejo de errores con is_error

Error de ejecución de herramienta

Nombre de herramienta inválido

Errores de herramientas de servidor

Próximos pasos

Manejo de 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

Manejo de resultados de herramientas de servidor

Manejo de errores con is_error

Error de ejecución de herramienta

Nombre de herramienta inválido

Errores de herramientas de servidor

Próximos pasos

Manejo de resultados de herramientas de cliente

Manejo de resultados de herramientas de servidor

Manejo de errores con is_error

Próximos pasos

Manejo de resultados de herramientas de cliente

Manejo de resultados de herramientas de servidor

Manejo de errores con is_error

Próximos pasos