Elegir un modelo

Recomendamos usar el último modelo Claude Sonnet (4.5) o Claude Opus (4.1) para herramientas complejas y consultas ambiguas; manejan múltiples herramientas mejor y buscan aclaraciones cuando es necesario. Usa modelos Claude Haiku para herramientas directas, pero ten en cuenta que pueden inferir parámetros faltantes.
Si usas Claude con uso de herramientas y pensamiento extendido, consulta nuestra guía aquí para más información.

Especificar herramientas del cliente

Las herramientas del cliente (tanto definidas por Anthropic como 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:
ParámetroDescripción
nameEl nombre de la herramienta. Debe coincidir con la expresión regular ^[a-zA-Z0-9_-]{1,64}$.
descriptionUna descripción detallada en texto plano de qué hace la herramienta, cuándo debe usarse y cómo se comporta.
input_schemaUn objeto JSON Schema que define los parámetros esperados para la herramienta.
JSON
{
  "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, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}
Esta herramienta, llamada get_weather, espera un objeto de entrada con una cadena location requerida y una cadena unit opcional que debe ser “celsius” o “fahrenheit”.

Indicación del sistema de uso de herramientas

Cuando llamas a la API de Claude con el parámetro tools, construimos un indicador del sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier indicador del sistema especificado por el usuario. El indicador construido está diseñado para instruir al modelo para usar las herramientas especificadas y proporcionar 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, sigue estas directrices:
  • Proporciona descripciones extremadamente detalladas. Este es, con mucho, el factor más importante en el rendimiento de la herramienta. Tus 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 puedas dar a Claude sobre tus herramientas, mejor será para decidir cuándo y cómo usarlas. Apunta a al menos 3-4 oraciones por descripción de herramienta, más si la herramienta es compleja.
  • Prioriza descripciones sobre ejemplos. Aunque puedes incluir ejemplos de cómo usar una herramienta en su descripción o en el indicador adjunto, esto es menos importante que tener una explicación clara y completa del propósito y los parámetros de la herramienta. Solo agrega ejemplos después de haber desarrollado completamente la descripción.
JSON
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}
JSON
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}
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.

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 uses el ejecutor de herramientas para la mayoría de implementaciones de uso de herramientas.
El ejecutor de herramientas está actualmente en beta y solo está disponible en los SDK de Python y TypeScript.

Uso básico

Usa el decorador @beta_tool para definir herramientas y client.beta.messages.tool_runner() para ejecutarlas.
Si estás usando el cliente asincrónico, reemplaza @beta_tool con @beta_async_tool y define la función con async def.
import anthropic
import json
from anthropic import beta_tool

# Initialize client
client = anthropic.Anthropic()

# Define tools using the decorator
@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    # In a full implementation, you'd call a weather API here
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

@beta_tool
def calculate_sum(a: int, b: int) -> str:
    """Add two numbers together.

    Args:
        a: First number
        b: Second number
    """
    return str(a + b)

# Use the tool runner
with client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, calculate_sum],
    messages=[
        {"role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?"}
    ]
) as runner:
    for message in runner:
        print(message.content[0].text)
La función decorada 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 deseas devolver un objeto JSON estructurado a Claude, codifícalo a una cadena JSON antes de devolverlo. Los números, booleanos u otros primitivos que no sean cadenas también deben convertirse a cadenas.El decorador @beta_tool inspeccionará los argumentos de la función y la cadena de documentación para extraer una representación de esquema json de la función dada, en el ejemplo anterior calculate_sum se convertirá en:
{
  "name": "calculate_sum",
  "description": "Adds two integers together.",
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "left": {
        "description": "The first integer to add.",
        "title": "Left",
        "type": "integer"
      },
      "right": {
        "description": "The second integer to add.",
        "title": "Right",
        "type": "integer"
      }
    },
    "required": ["left", "right"],
    "type": "object"
  }
}
El ejecutor de herramientas del SDK está en beta. El resto de este documento cubre la implementación manual de herramientas.

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 así:
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 cualquiera de 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.
Cuando uses almacenamiento en caché de indicadores, los cambios en el parámetro tool_choice invalidarán los bloques de mensajes en caché. Las definiciones de herramientas y los indicadores del sistema permanecen en caché, pero el contenido del mensaje debe reprocesarse.
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 explicación antes de los bloques de contenido tool_use, incluso si se les pide explícitamente que lo hagan.
Cuando uses pensamiento extendido con uso de herramientas, tool_choice: {"type": "any"} y tool_choice: {"type": "tool", "name": "..."} no son compatibles y resultarán en un error. Solo tool_choice: {"type": "auto"} (el predeterminado) y tool_choice: {"type": "none"} son compatibles con pensamiento extendido.
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 solicitas 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 necesitan 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 trabajo.

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, dada la indicación “¿Cuál es el clima en San Francisco ahora mismo y qué hora es allí?”, Claude podría responder con:
JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in 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 una consulta del usuario. Puedes deshabilitar este comportamiento por:
  • Establecer disable_parallel_tool_use=true cuando el tipo de tool_choice es auto, lo que asegura 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 asegura que Claude use exactamente una herramienta
Más simple con ejecutor de herramientas: El ejemplo a continuación muestra manejo manual de herramientas paralelas. Para la mayoría de casos de uso, ejecutor de herramientas maneja automáticamente la ejecución paralela de herramientas con mucho menos código.
Aquí hay un ejemplo completo que muestra cómo formatear correctamente llamadas de herramientas paralelas en el historial de mensajes:
import anthropic

client = anthropic.Anthropic()

# Define tools
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"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Initial request
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the weather in SF and NYC, and what time is it there?"
        }
    ]
)

# Claude's response with parallel tool calls
print("Claude wants to use tools:", response.stop_reason == "tool_use")
print("Number of tool calls:", len([c for c in response.content if c.type == "tool_use"]))

# Build the conversation with tool results
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contains multiple tool_use blocks
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Must match the ID from tool_use
                "content": "San Francisco: 68°F, partly cloudy"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, clear skies"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "San Francisco time: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "New York time: 5:30 PM EST"
            }
        ]
    }
]

# Get final response
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)
El mensaje del asistente con llamadas de herramientas paralelas se vería así:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the weather and time for both San Francisco and New York City."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}
Aquí hay un script completo y ejecutable para probar y verificar que las llamadas de herramientas paralelas funcionan correctamente:
#!/usr/bin/env python3
"""Test script to verify parallel tool calls with the Claude API"""

import os
from anthropic import Anthropic

# Initialize client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Define tools
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"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"

    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continue conversation with tool results
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # All results in one message!
])

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")
Este script demuestra:
  • Cómo formatear correctamente llamadas de herramientas paralelas y resultados
  • Cómo verificar que se están realizando llamadas paralelas
  • La estructura de mensaje correcta que fomenta el uso futuro de herramientas paralelas
  • Errores comunes a evitar (como texto antes de resultados de herramientas)
Ejecuta este script para probar tu implementación y asegurar que Claude está realizando llamadas de herramientas paralelas de manera efectiva.

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:
Para modelos Claude 4 (Opus 4.1, Opus 4 y Sonnet 4), agrega esto a tu indicador del sistema:
For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
Para un uso paralelo de herramientas aún más fuerte (recomendado si el predeterminado no es suficiente), usa:
<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
</use_parallel_tool_calls>
También puedes fomentar el uso paralelo de herramientas dentro de mensajes de usuario específicos:
# Instead of:
"What's the weather in Paris? Also check London."

# Use:
"Check the weather in Paris and London simultaneously."

# Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."
Uso paralelo de herramientas con Claude Sonnet 3.7Claude Sonnet 3.7 puede ser menos probable que realice llamadas de herramientas paralelas en una respuesta, incluso cuando no hayas establecido disable_parallel_tool_use. Para solucionar esto, recomendamos habilitar uso eficiente de herramientas en tokens, que ayuda a fomentar que Claude use herramientas paralelas. Esta característica beta también reduce la latencia y ahorra un promedio del 14% en tokens de salida.Si prefieres no optar por la beta de uso eficiente de herramientas en tokens, también puedes introducir una “herramienta de lote” que pueda actuar como una meta-herramienta para envolver invocaciones a otras herramientas simultáneamente. Encontramos que si esta herramienta está presente, el modelo la usará para llamar simultáneamente a múltiples herramientas en paralelo para ti.Consulta este ejemplo en nuestro libro de recetas para cómo usar esta solución alternativa.

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

Más simple con ejecutor de herramientas: El manejo manual de herramientas descrito en esta sección es administrado automáticamente por ejecutor de herramientas. Usa esta sección cuando necesites control personalizado sobre la ejecución de herramientas.
La respuesta de Claude difiere según si usa una herramienta del cliente o del servidor.

Manejo de resultados de herramientas del 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 tarde.
  • 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.
JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-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 herramienta para una herramienta del 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 que 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.
Requisitos de formato importantes:
  • 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 del usuario que contiene resultados de herramientas, los bloques tool_result deben venir PRIMERO en la matriz de contenido. Cualquier texto debe venir DESPUÉS de todos los resultados de herramientas.
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:
{"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.
JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}
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
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}
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 a la indicación original del usuario.

Manejo de resultados de herramientas del servidor

Claude ejecuta la herramienta internamente e incorpora los resultados directamente en su respuesta sin requerir interacción adicional del usuario.
Diferencias de otras APIsA diferencia de las APIs que separan el uso de herramientas o usan roles especiales como tool o function, la API de Claude integra herramientas directamente en la estructura de mensajes user y assistant.Los mensajes contienen matrices 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 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-sonnet-4-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

Manejo de la razón de parada pause_turn

Cuando se usan herramientas del 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)
Al manejar 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

Manejo de errores integrado: Ejecutor de herramientas proporciona manejo automático de errores para la mayoría de escenarios comunes. Esta sección cubre el manejo manual de errores para casos de uso avanzados.
Hay varios tipos diferentes de errores que pueden ocurrir al usar herramientas con Claude:
Si la herramienta misma lanza un error durante la ejecución (p. ej. un error de red al obtener datos meteorológicos), puedes devolver el mensaje de error en el content junto con "is_error": true:
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, p. ej. “Lo siento, no pude recuperar el clima actual porque el servicio de API meteorológica no está disponible. Por favor, intenta de nuevo más tarde.”
Si el intento de Claude de usar una herramienta es inválido (p. ej. parámetros requeridos faltantes), 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 hacia adelante con un tool_result que indique el error, y Claude intentará usar la herramienta de nuevo con la información faltante completada:
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 faltan parámetros, Claude reintentará 2-3 veces con correcciones antes de disculparse con el usuario.
Para evitar que Claude reflexione sobre la calidad de los resultados de búsqueda devueltos con etiquetas <search_quality_reflection>, agrega “Do not reflect on the quality of the returned search results in your response” a tu indicador.
Cuando las herramientas del servidor encuentran errores (p. ej., problemas de red con Búsqueda Web), Claude manejará estos errores de manera transparente e intentará proporcionar una respuesta alternativa o explicación al usuario. A diferencia de las herramientas del cliente, no necesitas manejar resultados is_error para herramientas del servidor.Para búsqueda web específicamente, los códigos de error posibles incluyen:
  • too_many_requests: Límite de velocidad excedido
  • invalid_input: Parámetro de consulta de búsqueda inválido
  • max_uses_exceeded: Máximo de usos de herramienta de búsqueda web excedido
  • query_too_long: La consulta excede la longitud máxima
  • unavailable: Ocurrió un error interno
Si Claude no está realizando llamadas de herramientas paralelas cuando se espera, verifica estos problemas comunes:1. Formato incorrecto de resultado de herramientaEl problema más común es formatear incorrectamente los resultados de herramientas en el historial de conversación. Esto “enseña” a Claude a evitar llamadas paralelas.Específicamente para uso paralelo de herramientas:
  • Incorrecto: Enviar mensajes de usuario separados para cada resultado de herramienta
  • Correcto: Todos los resultados de herramientas deben estar en un único mensaje de usuario
// ❌ Esto reduce el uso paralelo de herramientas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]

// ✅ Esto mantiene el uso paralelo de herramientas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]
Consulta los requisitos de formato general anteriores para otras reglas de formato.2. Indicación débilLa indicación predeterminada puede no ser suficiente. Usa lenguaje más fuerte:
<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations,
invoke all relevant tools simultaneously rather than sequentially.
Prioritize calling tools in parallel whenever possible.
</use_parallel_tool_calls>
3. Medición del uso paralelo de herramientasPara verificar que las llamadas de herramientas paralelas están funcionando:
# Calculate average tools per tool-calling message
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"])
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working
4. Comportamiento específico del modelo
  • Claude Opus 4.1, Opus 4 y Sonnet 4: Excelentes en uso paralelo de herramientas con indicación mínima
  • Claude Sonnet 3.7: Puede necesitar indicación más fuerte o uso eficiente de herramientas en tokens
  • Claude Haiku: Menos probable que use herramientas paralelas sin indicación explícita