Cómo implementar el uso de herramientas

Elegir un modelo

Recomendamos usar el último modelo Claude Opus (4.6) para herramientas complejas y consultas ambiguas; maneja múltiples herramientas mejor y busca aclaraciones cuando es necesario.

Use modelos Claude Haiku para herramientas directas, pero tenga en cuenta que pueden inferir parámetros faltantes.

Especificar herramientas del cliente

Las herramientas del cliente (tanto las definidas por Anthropic como las definidas por el usuario) se especifican en el parámetro de nivel superior tools de la solicitud de API. Cada definición de herramienta incluye:

Indicación del sistema de uso de herramientas

Cuando llama a la API de Claude con el parámetro tools, construimos una indicación del sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier indicación del sistema especificada por el usuario. La indicación construida está diseñada para instruir al modelo que use la(s) herramienta(s) especificada(s) y proporcione el contexto necesario para que la herramienta funcione correctamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Mejores prácticas para definiciones de herramientas

Para obtener el mejor rendimiento de Claude al usar herramientas, siga estas directrices:

• Proporcione descripciones extremadamente detalladas. Este es, con mucho, el factor más importante en el rendimiento de la herramienta. Sus descripciones deben explicar cada detalle sobre la herramienta, incluyendo:
  • Qué hace la herramienta
  • Cuándo debe usarse (y cuándo no)
  • Qué significa cada parámetro y cómo afecta el comportamiento de la herramienta
  • Cualquier advertencia o limitación importante, como qué información la herramienta no devuelve si el nombre de la herramienta no es claro. Cuanto más contexto pueda dar a Claude sobre sus herramientas, mejor será para decidir cuándo y cómo usarlas. Apunte a al menos 3-4 oraciones por descripción de herramienta, más si la herramienta es compleja.
• Priorice las descripciones, pero considere usar input_examples para herramientas complejas. Las descripciones claras son lo más importante, pero para herramientas con entradas complejas, objetos anidados o parámetros sensibles al formato, puede usar el campo input_examples (beta) para proporcionar ejemplos validados por esquema. Consulte Proporcionar ejemplos de uso de herramientas para más detalles.

La buena descripción explica claramente qué hace la herramienta, cuándo usarla, qué datos devuelve y qué significa el parámetro ticker. La descripción deficiente es demasiado breve y deja a Claude con muchas preguntas abiertas sobre el comportamiento y el uso de la herramienta.

Proporcionar ejemplos de uso de herramientas

Puede proporcionar ejemplos concretos de entradas de herramientas válidas para ayudar a Claude a entender cómo usar sus herramientas de manera más efectiva. Esto es particularmente útil para herramientas complejas con objetos anidados, parámetros opcionales o entradas sensibles al formato.

Uso básico

Agregue un campo input_examples opcional a su definición de herramienta con una matriz de objetos de entrada de ejemplo. Cada ejemplo debe ser válido de acuerdo con el input_schema de la herramienta:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    betas=["advanced-tool-use-2025-11-20"],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature"
                    }
                },
                "required": ["location"]
            },
            "input_examples": [
                {
                    "location": "San Francisco, CA",
                    "unit": "fahrenheit"
                },
                {
                    "location": "Tokyo, Japan",
                    "unit": "celsius"
                },
                {
                    "location": "New York, NY"  # 'unit' is optional
                }
            ]
        }
    ],
    messages=[
        {"role": "user", "content": "What's the weather like in San Francisco?"}
    ]
)

Los ejemplos se incluyen en la indicación junto con su esquema de herramienta, mostrando a Claude patrones concretos para llamadas de herramientas bien formadas. Esto ayuda a Claude a entender cuándo incluir parámetros opcionales, qué formatos usar y cómo estructurar entradas complejas.

Requisitos y limitaciones

• Validación de esquema - Cada ejemplo debe ser válido de acuerdo con el input_schema de la herramienta. Los ejemplos inválidos devuelven un error 400
• No compatible con herramientas del lado del servidor - Solo las herramientas definidas por el usuario pueden tener ejemplos de entrada
• Costo de tokens - Los ejemplos se agregan a los tokens de indicación: ~20-50 tokens para ejemplos simples, ~100-200 tokens para objetos anidados complejos

Ejecutor de herramientas (beta)

El ejecutor de herramientas proporciona una solución lista para usar para ejecutar herramientas con Claude. En lugar de manejar manualmente llamadas de herramientas, resultados de herramientas y gestión de conversación, el ejecutor de herramientas automáticamente:

• Ejecuta herramientas cuando Claude las llama
• Maneja el ciclo de solicitud/respuesta
• Gestiona el estado de la conversación
• Proporciona seguridad de tipos y validación

Recomendamos que use el ejecutor de herramientas para la mayoría de las implementaciones de uso de herramientas.

Uso básico

Defina herramientas usando los ayudantes del SDK, luego use el ejecutor de herramientas para ejecutarlas.

La función de herramienta debe devolver un bloque de contenido o una matriz de bloques de contenido, incluyendo texto, imágenes o bloques de documentos. Esto permite que las herramientas devuelvan respuestas ricas y multimodales. Las cadenas devueltas se convertirán en un bloque de contenido de texto. Si desea devolver un objeto JSON estructurado a Claude, codifíquelo como una cadena JSON antes de devolverlo. Los números, booleanos u otros primitivos que no sean cadenas también deben convertirse a cadenas.

Iteración sobre el ejecutor de herramientas

El ejecutor de herramientas es iterable que produce mensajes de Claude. Esto a menudo se denomina "bucle de llamada de herramienta". En cada iteración, el ejecutor verifica si Claude solicitó un uso de herramienta. Si es así, llama a la herramienta y envía el resultado a Claude automáticamente, luego produce el siguiente mensaje de Claude para continuar su bucle.

Puede terminar el bucle en cualquier iteración con una declaración break. El ejecutor hará un bucle hasta que Claude devuelva un mensaje sin un uso de herramienta.

Si no necesita mensajes intermedios, puede obtener el mensaje final directamente:

Uso avanzado

Dentro del bucle, puede personalizar completamente la siguiente solicitud del ejecutor de herramientas a la API de Mensajes. El ejecutor automáticamente agrega resultados de herramientas al historial de mensajes, por lo que no necesita administrarlos manualmente. Opcionalmente puede inspeccionar el resultado de la herramienta para registro o depuración, y modificar los parámetros de solicitud antes de la siguiente llamada de API.

Depuración de la ejecución de herramientas

Cuando una herramienta lanza una excepción, el ejecutor de herramientas la captura y devuelve el error a Claude como un resultado de herramienta con is_error: true. De forma predeterminada, solo se incluye el mensaje de excepción, no el seguimiento de pila completo.

Para ver seguimientos de pila completos e información de depuración, establezca la variable de entorno ANTHROPIC_LOG:

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

Cuando está habilitado, el SDK registra detalles de excepción completos (usando el módulo logging de Python, la consola en TypeScript o el registrador de Ruby), incluyendo el seguimiento de pila completo cuando una herramienta falla.

Interceptar errores de herramientas

De forma predeterminada, los errores de herramientas se devuelven a Claude, que puede responder apropiadamente. Sin embargo, es posible que desee detectar errores y manejarlos de manera diferente, por ejemplo, para detener la ejecución temprano o implementar manejo de errores personalizado.

Use el método de respuesta de herramienta para interceptar resultados de herramientas y verificar errores antes de que se envíen a Claude:

Modificar resultados de herramientas

Puede modificar resultados de herramientas antes de que se envíen de vuelta a Claude. Esto es útil para agregar metadatos como cache_control para habilitar almacenamiento en caché de indicaciones en resultados de herramientas, o para transformar la salida de la herramienta.

Use el método de respuesta de herramienta para obtener el resultado de la herramienta, modificarlo y luego agregar su versión modificada a los mensajes:

Transmisión

Habilite la transmisión para recibir eventos a medida que llegan. Cada iteración produce un objeto de transmisión que puede iterar para eventos.

Controlar la salida de Claude

Forzar el uso de herramientas

En algunos casos, es posible que desees que Claude use una herramienta específica para responder la pregunta del usuario, incluso si Claude cree que puede proporcionar una respuesta sin usar una herramienta. Puedes hacer esto especificando la herramienta en el campo tool_choice de la siguiente manera:

tool_choice = {"type": "tool", "name": "get_weather"}

Al trabajar con el parámetro tool_choice, tenemos cuatro opciones posibles:

• auto permite que Claude decida si llamar a las herramientas proporcionadas o no. Este es el valor predeterminado cuando se proporcionan tools.
• any le dice a Claude que debe usar una de las herramientas proporcionadas, pero no fuerza una herramienta en particular.
• tool nos permite forzar a Claude a usar siempre una herramienta en particular.
• none evita que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionan tools.

Este diagrama ilustra cómo funciona cada opción:

Ten en cuenta que cuando tienes tool_choice como any o tool, rellenaremos previamente el mensaje del asistente para forzar el uso de una herramienta. Esto significa que los modelos no emitirán una respuesta en lenguaje natural o una explicación antes de los bloques de contenido tool_use, incluso si se les pide explícitamente que lo hagan.

Nuestras pruebas han demostrado que esto no debería reducir el rendimiento. Si deseas que el modelo proporcione contexto en lenguaje natural o explicaciones mientras aún solicita que el modelo use una herramienta específica, puedes usar {"type": "auto"} para tool_choice (el predeterminado) y agregar instrucciones explícitas en un mensaje user. Por ejemplo: ¿Cuál es el clima en Londres? Usa la herramienta get_weather en tu respuesta.

Salida JSON

Las herramientas no necesariamente tienen que ser funciones del cliente — puedes usar herramientas en cualquier momento que desees que el modelo devuelva una salida JSON que siga un esquema proporcionado. Por ejemplo, podrías usar una herramienta record_summary con un esquema particular. Consulta Uso de herramientas con Claude para un ejemplo completo de funcionamiento.

Respuestas del modelo con herramientas

Al usar herramientas, Claude a menudo comentará sobre lo que está haciendo o responderá naturalmente al usuario antes de invocar herramientas.

Por ejemplo, dado el indicador "¿Cuál es el clima en San Francisco ahora mismo, y qué hora es allí?", Claude podría responder con:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Te ayudaré a verificar el clima actual y la hora en San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Este estilo de respuesta natural ayuda a los usuarios a entender qué está haciendo Claude y crea una interacción más conversacional. Puedes guiar el estilo y el contenido de estas respuestas a través de tus indicadores del sistema y proporcionando <examples> en tus indicadores.

Es importante notar que Claude puede usar varias frases y enfoques al explicar sus acciones. Tu código debe tratar estas respuestas como cualquier otro texto generado por el asistente, y no depender de convenciones de formato específicas.

Uso paralelo de herramientas

Por defecto, Claude puede usar múltiples herramientas para responder a una consulta del usuario. Puedes desactivar este comportamiento mediante:

• Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es auto, lo que garantiza que Claude use como máximo una herramienta
• Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es any o tool, lo que garantiza que Claude use exactamente una herramienta

Maximizar el uso paralelo de herramientas

Aunque los modelos Claude 4 tienen excelentes capacidades de uso paralelo de herramientas por defecto, puedes aumentar la probabilidad de ejecución paralela de herramientas en todos los modelos con indicaciones dirigidas:

Manejo de bloques de contenido de uso de herramientas y resultado de herramientas

La respuesta de Claude difiere según si usa una herramienta de cliente o 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 herramienta 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á utilizando.
• input: Un objeto que contiene la entrada que se pasa a la herramienta, de conformidad con el input_schema de la herramienta.

Cuando recibas una respuesta de uso de herramienta 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, 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 (p. ej. "content": "15 degrees"), una lista de bloques de contenido anidados (p. ej. "content": [{"type": "text", "text": "15 degrees"}]), o una lista de bloques de documentos (p. ej. "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 usará esa información para continuar generando una respuesta a la solicitud 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 la razón de parada max_tokens

Si la respuesta de Claude se corta debido a alcanzar el límite max_tokens, y la respuesta truncada contiene un bloque de uso de herramienta incompleto, deberás reintentar la solicitud con un valor max_tokens más alto para obtener el uso de herramienta completo.

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-opus-4-6",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

Manejo de la razón de parada pause_turn

Cuando se usan herramientas de servidor como búsqueda web, la API puede devolver una razón de parada pause_turn, indicando que la API ha pausado un turno de larga duración.

Aquí se explica cómo manejar la razón de parada pause_turn:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )

    print(continuation)
else:
    print(response)

Cuando manejes pause_turn:

• Continúa la conversación: Pasa la respuesta pausada tal como está en una solicitud posterior para permitir que Claude continúe su turno
• Modifica si es necesario: Opcionalmente puedes modificar el contenido antes de continuar si deseas interrumpir o redirigir la conversación
• Preserva el estado de la herramienta: Incluye las mismas herramientas en la solicitud de continuación para mantener la funcionalidad

Solución de problemas de errores

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