Manejar llamadas a herramientas

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. 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 o uso de navegador 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.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-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.
   • 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 (los miembros de gestión de pestañas devuelven solo ese bloque).

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

{
  "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..."
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
    }
  ]
}

{
  "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.

Manejo de errores con is_error

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

{
  "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
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Próximos pasos