---
title: Manejar llamadas a herramientas
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/handle-tool-calls
description: 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview#how-tool-use-works).
## 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. 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.
Un bloque `tool_use` para un miembro del conjunto de herramientas de [uso de computadora](https://platform.claude.com/docs/es/agents-and-tools/tool-use/computer-use-tool) o [uso de navegador](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool) también lleva un campo `toolset_name` (`"computer"` o `"browser"`). Su `name` es la herramienta miembro que Claude está llamando, como `screenshot` o `navigate`, así que despacha esos bloques según ambos campos.
```json JSON
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}
```
Cuando recibas una respuesta de uso de herramientas para una herramienta de cliente, debes:
1. Extraer el `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, pasándole el `input` de la herramienta.
3. 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 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`](https://platform.claude.com/docs/es/build-with-claude/search-results).
* `is_error` (opcional): Establécelo en `true` si la ejecución de la herramienta resultó en un error.
Un `tool_result` que responde a un bloque miembro de uso de computadora o uso de navegador también debe repetir el mismo valor de `toolset_name` que el bloque `tool_use`; un resultado de miembro que lo omita es rechazado. Su `content` también es más restringido: un resultado de miembro puede contener solo bloques `text` e `image`, y un resultado de uso de navegador puede agregar un bloque [`browser_state`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state) (los [miembros de gestión de pestañas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/browser-use-tool#tab-management-results) devuelven solo ese bloque).
**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 resultados de herramientas, los bloques tool\_result deben ir PRIMERO en el array 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](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools) que aún no tiene bloque de resultado, el mensaje del usuario debe contener solo 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 entonces falla con un error 400 que nombra la herramienta de servidor no resuelta. Consulta [Razones de detención y alternativas](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#tool-use).
Por ejemplo, esto causará un error 400:
```json
{
"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:
```json
{
"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, archivos subidos por usuarios, APIs de terceros. Trata ese contenido como no confiable: un atacante que pueda influir en él puede incrustar instrucciones que intenten redirigir a Claude ("indirect prompt injection", o inyección indirecta de prompts). Mantén el contenido no confiable dentro de bloques `tool_result` en lugar de indicaciones `system` o bloques `text` de usuario simples, y consulta [Mitigar jailbreaks e inyecciones de prompts](https://platform.claude.com/docs/es/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks#indirect-prompt-injection) para un mayor endurecimiento.
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}
```
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}
```
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.
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 la 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 solo 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 alternativas](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#tool-use).
**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`.
## Manejo de errores con is\_error
Hay algunos tipos diferentes de errores que pueden ocurrir al usar herramientas con Claude:
Si la herramienta misma lanza un error durante la ejecución (por ejemplo, un error de red al obtener datos del clima), puedes devolver el mensaje de error en el `content` junto con `"is_error": true`:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}
```
Claude entonces incorporará este error en su respuesta al usuario. Por ejemplo: "Lo siento, no pude obtener el clima actual porque la API del servicio meteorológico no está disponible. Por favor, inténtalo de nuevo más tarde."
Escribe mensajes de error instructivos. En lugar de errores genéricos como `"failed"`, incluye qué salió mal y qué debería intentar Claude a continuación (por ejemplo, `"Rate limit exceeded. Retry after 60 seconds."`). Esto le da a Claude el contexto que necesita para recuperarse o adaptarse sin adivinar.
Si el intento de Claude de usar una herramienta es inválido (por ejemplo, faltan parámetros requeridos), generalmente significa que no había suficiente información para que Claude usara la herramienta correctamente. Tu mejor opción durante el desarrollo es intentar la solicitud de nuevo con valores de `description` más detallados en tus definiciones de herramientas.
Sin embargo, también puedes continuar la conversación con un `tool_result` que indique el error, y Claude intentará usar la herramienta de nuevo con la información faltante completada:
```json JSON
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}
```
Si una solicitud de herramienta es inválida o le faltan parámetros, Claude reintentará 2-3 veces con correcciones antes de disculparse con el usuario.
Para eliminar por completo las llamadas a herramientas inválidas, usa el [uso estricto de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/strict-tool-use) con `strict: true` en tus definiciones de herramientas. Esto garantiza que las entradas de las herramientas siempre coincidan exactamente con tu esquema, evitando parámetros faltantes y discrepancias de tipos.
Cuando las herramientas de servidor encuentran errores (por ejemplo, problemas de red con Web Search), Claude manejará estos errores de forma transparente e intentará proporcionar una respuesta alternativa o una explicación al usuario. A diferencia de las herramientas de cliente, no necesitas manejar resultados `is_error` para las herramientas de servidor.
Para la búsqueda web específicamente, los posibles códigos de error incluyen:
* `too_many_requests`: Límite de velocidad excedido
* `invalid_input`: Parámetro de consulta de búsqueda inválido
* `max_uses_exceeded`: Se excedió el máximo de usos de la herramienta de búsqueda web
* `query_too_long`: La consulta excede la longitud máxima
* `unavailable`: Ocurrió un error interno
## Próximos pasos
Maneja respuestas donde Claude llama a varias herramientas en un solo turno.
Deja que el SDK gestione el bucle de `tool_use`, el formato de resultados y los reintentos por ti.
Escribe esquemas y descripciones que guíen a Claude hacia la herramienta correcta.