Uso de herramientas con Claude

El uso de herramientas permite que Claude llame a funciones que defines o que proporciona Anthropic. Claude decide cuándo llamar a una herramienta basándose en 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í está el ejemplo más simple usando una herramienta de servidor, donde Anthropic maneja la ejecución:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "tools": [{"type": "web_search_20260209", "name": "web_search"}],
    "messages": [{"role": "user", "content": "What'\''s the latest on the Mars rover?"}]
  }'

Cómo funciona el uso de herramientas

Las herramientas se diferencian principalmente por dónde se ejecuta el código. Las herramientas de cliente (incluyendo herramientas definidas por el usuario y herramientas de esquema 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 devuelves un tool_result. Las herramientas de servidor (web_search, code_execution, web_fetch, tool_search) se ejecutan en la infraestructura de Anthropic: ves los resultados directamente sin manejar la ejecución.

Para el modelo conceptual completo incluyendo el bucle de agentes y cuándo elegir cada enfoque, consulta Cómo funciona el uso de herramientas.

Para conectarse a servidores MCP, consulta el conector MCP. Para construir tu propio cliente MCP, consulta modelcontextprotocol.io.

El acceso a herramientas es uno de los primitivos de mayor apalancamiento que puedes dar a un agente. En benchmarks como LAB-Bench FigQA (interpretación de figuras científicas) y SWE-bench (ingeniería de software del mundo real), agregar incluso herramientas básicas produce ganancias de capacidad desproporcionadas, a menudo superando los puntos de referencia de expertos humanos.

Ejemplos de uso de herramientas

Para un tutorial completo práctico, consulta el tutorial. Para ejemplos de referencia de conceptos individuales, consulta Definir herramientas y Manejar llamadas de herramientas.

Precios

Tool use requests are priced based on:

1. The total number of input tokens sent to the model (including in the tools parameter)
2. The number of output tokens generated
3. For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage.

The additional tokens from tool use come from:

• The tools parameter in API requests (tool names, descriptions, and schemas)
• tool_use content blocks in API requests and responses
• tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

These token counts are added to your normal input and output tokens to calculate the total cost of a request.

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

Cuando envías una solicitud de uso de herramientas, como cualquier otra solicitud de API, la respuesta mostrará tanto los recuentos de tokens de entrada como de salida como parte de las métricas de usage reportadas.

Próximos pasos

Elige tu camino