Uso de herramientas con Claude

El "tool use" (uso de herramientas), también llamado "function calling" (llamada de funciones), permite que Claude llame a funciones que tú defines o que Anthropic proporciona. Claude determina cuándo llamar a una herramienta según la solicitud del usuario y la descripción de la herramienta. Luego devuelve una llamada estructurada que tu aplicación ejecuta (herramientas de cliente) o que Anthropic ejecuta (herramientas de servidor).

Aquí tienes un ejemplo mínimo que usa una herramienta de servidor, la herramienta de búsqueda web, que Anthropic ejecuta por ti:

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
    messages=[{"role": "user", "content": "What's the latest on the Mars rover?"}],
)
print(response.content)

Claude ejecuta la búsqueda en la infraestructura de Anthropic y devuelve los resultados citados en la misma respuesta. Para que Claude llame a una función que tú defines, pasa una herramienta con un input_schema y luego ejecuta la llamada cuando Claude devuelva un bloque tool_use. Cómo funciona el uso de herramientas muestra ese ciclo de ida y vuelta de principio a fin. Obtén más información sobre cómo definir herramientas y manejar llamadas a herramientas.

Cómo funciona el uso de herramientas

Las herramientas se diferencian principalmente por dónde se ejecuta el código. Las herramientas de cliente (incluidas las herramientas definidas por el usuario y las herramientas con esquemas definidos por Anthropic, como bash y text_editor) se ejecutan en tu aplicación. Claude responde con stop_reason: "tool_use" y uno o más bloques tool_use. Tu código ejecuta la operación y envía de vuelta un tool_result. Las herramientas de servidor (como web_search, web_fetch, code_execution y tool_search) se ejecutan en la infraestructura de Anthropic: ves los resultados directamente sin manejar la ejecución, a menos que Claude llame a la herramienta en el mismo grupo de llamadas paralelas a herramientas que una de tus herramientas de cliente (consulta Razones de detención y respaldo).

Aquí tienes ese ciclo de ida y vuelta completo para una herramienta de cliente. La primera solicitud define una herramienta get_weather, y Claude responde la pregunta llamándola: la respuesta contiene un bloque tool_use, tu código ejecuta la consulta y una segunda solicitud envía el resultado de vuelta en un bloque tool_result para que Claude pueda responder con la respuesta.

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather for a given location.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "City and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]
messages = [{"role": "user", "content": "What's the weather in San Francisco?"}]

# Claude responde con un bloque tool_use que indica la herramienta y sus argumentos.
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    # Pide como máximo una llamada a herramienta por turno.
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)
tool_use = next(block for block in response.content if block.type == "tool_use")
print(f"Claude called {tool_use.name} with {json.dumps(tool_use.input)}")

# Ejecuta la herramienta y luego envía el resultado en un bloque tool_result.
weather = "15 degrees Celsius, partly cloudy"  # your weather lookup goes here
messages += [
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {"type": "tool_result", "tool_use_id": tool_use.id, "content": weather}
        ],
    },
]
followup = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto", "disable_parallel_tool_use": True},
    messages=messages,
)

# Claude usa el resultado para responder la pregunta original.
final_text = next(block for block in followup.content if block.type == "text")
print(final_text.text)

Claude called get_weather with {"location": "San Francisco, CA"}
The current weather in San Francisco is 15 degrees Celsius with partly cloudy skies.

Manejar llamadas a herramientas cubre cada paso en detalle, incluido el formato de los resultados y la señalización de errores; Uso de herramientas en paralelo cubre las respuestas que llaman a varias herramientas a la vez. Para evitar escribir este ciclo de ida y vuelta tú mismo, usa Tool Runner: los SDKs ejecutan tus herramientas y envían los resultados de vuelta automáticamente.

Para conocer el modelo conceptual completo, incluido el bucle agéntico y cuándo elegir cada enfoque, consulta Cómo funciona el uso de herramientas.

Para conectarte a servidores de Model Context Protocol (MCP), consulta el conector MCP. Para crear tu propio cliente MCP, consulta la guía de Model Context Protocol para crear un cliente MCP.

Cuándo Claude usa herramientas

Con el tool_choice predeterminado de {"type": "auto"}, Claude determina en cada turno si llamar a una herramienta o responder directamente. Llama a una herramienta cuando la solicitud corresponde a la capacidad descrita de esa herramienta y la respuesta no está ya en el contexto. Responde directamente para conocimiento estable, tareas creativas y turnos conversacionales.

Este límite se puede ajustar mediante tu indicación del sistema. Si Claude no llama a las herramientas cuando lo esperas, una instrucción ligera como "Use the tools to investigate before responding." aumenta el uso de herramientas. Una forma más fuerte como "Always call a tool first before responding." empuja aún más. Por el contrario, "Use your judgment about whether to call a tool or respond directly." mantiene conservador el comportamiento de activación.

Para exigir una llamada a herramienta en lugar de depender del prompting, configura tool_choice.

La página de cada herramienta de servidor describe su propio límite de activación con más detalle.

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "location": "New York, NY", "unit": "fahrenheit" }
}

Elige una herramienta

Para las cadenas type, versiones y encabezados beta, consulta la Referencia de herramientas.

Tus propias herramientas

Para las herramientas que tú defines, escribes el esquema y tu aplicación ejecuta cada llamada.

Herramientas de cliente con esquema de Anthropic

Anthropic publica el esquema y entrena a Claude con él. Tu aplicación sigue ejecutando cada llamada y devuelve el tool_result.

Herramientas de servidor

Las herramientas de servidor se ejecutan en la infraestructura de Anthropic, sin código de manejo en tu aplicación. Consulta Herramientas de servidor para conocer la mecánica que comparten.

Precios

Las solicitudes de "tool use" (uso de herramientas) se cobran en función de:

1. El número total de tokens de entrada enviados al modelo (incluidos los del parámetro tools)
2. El número de tokens de salida generados
3. Para las herramientas del lado del servidor, precios adicionales basados en el uso (por ejemplo, la búsqueda web cobra por cada búsqueda realizada)

Las herramientas del lado del cliente tienen el mismo precio que cualquier otra solicitud a la Claude API, aunque las herramientas del lado del servidor pueden generar cargos adicionales según su uso específico.

Los tokens adicionales del uso de herramientas provienen de:

• El parámetro tools en las solicitudes a la API (nombres, descripciones y esquemas de las herramientas)
• Los bloques de contenido tool_use en las solicitudes y respuestas de la API
• Los bloques de contenido tool_result en las solicitudes a la API

Cuando usas tools, la API también incluye automáticamente un "system prompt" (indicación del sistema) especial para el modelo que habilita el uso de herramientas. El número de tokens de uso de herramientas requeridos para cada modelo se indica en la siguiente tabla (sin incluir los tokens adicionales mencionados anteriormente). Ten en cuenta que la tabla asume que se proporciona al menos 1 herramienta. Si no se proporcionan tools, entonces una elección de herramienta de none usa 0 tokens adicionales de indicación del sistema.

Estas cantidades de tokens se suman a tus tokens normales de entrada y salida para calcular el costo total de una solicitud.

Consulta la tabla de Descripción general de modelos para ver los precios actuales por modelo.

Cuando envías un prompt de uso de herramientas, al igual que con cualquier otra solicitud a la API, la respuesta incluye los recuentos de tokens de entrada y de salida en las métricas usage reportadas.

Algunas herramientas de servidor agregan cargos basados en el uso además de los tokens: consulta la Herramienta de búsqueda web y la Herramienta de ejecución de código para conocer sus tarifas.

Próximos pasos