Uso de herramientas con Claude

Claude es capaz de interactuar con herramientas y funciones, lo que te permite extender las capacidades de Claude para realizar una variedad más amplia de tareas.

¡Aprende todo lo que necesitas para dominar el uso de herramientas con Claude como parte de nuestros nuevos cursos! Por favor continúa compartiendo tus ideas y sugerencias usando este formulario.

Aquí tienes un ejemplo de cómo proporcionar herramientas a Claude usando la API de Mensajes:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

Cómo funciona el uso de herramientas

Claude soporta dos tipos de herramientas:

Herramientas del cliente: Herramientas que se ejecutan en tus sistemas, que incluyen:
- Herramientas personalizadas definidas por el usuario que tú creas e implementas
- Herramientas definidas por Anthropic como uso de computadora y editor de texto que requieren implementación del cliente
Herramientas del servidor: Herramientas que se ejecutan en los servidores de Anthropic, como las herramientas de búsqueda web y obtención web. Estas herramientas deben especificarse en la solicitud de API pero no requieren implementación de tu parte.

Las herramientas definidas por Anthropic usan tipos versionados (por ejemplo, web_search_20250305, text_editor_20250124) para asegurar compatibilidad entre versiones de modelos.

Herramientas del cliente

Integra herramientas del cliente con Claude en estos pasos:

Proporciona a Claude herramientas y un prompt del usuario

Define herramientas del cliente con nombres, descripciones y esquemas de entrada en tu solicitud de API.
Incluye un prompt del usuario que podría requerir estas herramientas, por ejemplo, “¿Cómo está el clima en San Francisco?”

Claude decide usar una herramienta

Claude evalúa si alguna herramienta puede ayudar con la consulta del usuario.
Si es así, Claude construye una solicitud de uso de herramienta correctamente formateada.
Para herramientas del cliente, la respuesta de la API tiene un stop_reason de tool_use, señalando la intención de Claude.

Ejecuta la herramienta y devuelve los resultados

Extrae el nombre de la herramienta y la entrada de la solicitud de Claude
Ejecuta el código de la herramienta en tu sistema
Devuelve los resultados en un nuevo mensaje user que contenga un bloque de contenido tool_result

Claude usa el resultado de la herramienta para formular una respuesta

Claude analiza los resultados de la herramienta para elaborar su respuesta final al prompt original del usuario.

Nota: Los pasos 3 y 4 son opcionales. Para algunos flujos de trabajo, la solicitud de uso de herramienta de Claude (paso 2) podría ser todo lo que necesitas, sin enviar resultados de vuelta a Claude.

Herramientas del servidor

Las herramientas del servidor siguen un flujo de trabajo diferente:

Proporciona a Claude herramientas y un prompt del usuario

Las herramientas del servidor, como búsqueda web y obtención web, tienen sus propios parámetros.
Incluye un prompt del usuario que podría requerir estas herramientas, por ejemplo, “Busca las últimas noticias sobre IA” o “Analiza el contenido en esta URL.”

Claude ejecuta la herramienta del servidor

Claude evalúa si una herramienta del servidor puede ayudar con la consulta del usuario.
Si es así, Claude ejecuta la herramienta, y los resultados se incorporan automáticamente en la respuesta de Claude.

Claude usa el resultado de la herramienta del servidor para formular una respuesta

Claude analiza los resultados de la herramienta del servidor para elaborar su respuesta final al prompt original del usuario.
No se necesita interacción adicional del usuario para la ejecución de herramientas del servidor.

Ejemplos de uso de herramientas

Aquí tienes algunos ejemplos de código que demuestran varios patrones y técnicas de uso de herramientas. Por brevedad, las herramientas son herramientas simples, y las descripciones de las herramientas son más cortas de lo que sería ideal para asegurar el mejor rendimiento.

Ejemplo de herramienta única

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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, either \"celsius\" or \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
}'

Claude devolverá una respuesta similar a:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "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"}
    }
  ]
}

Entonces necesitarías ejecutar la función get_weather con la entrada proporcionada, y devolver el resultado en un nuevo mensaje user:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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, either \"celsius\" or \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "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"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

Esto imprimirá la respuesta final de Claude, incorporando los datos del clima:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

Uso de herramientas en paralelo

Ejemplo de múltiples herramientas

Puedes proporcionar a Claude múltiples herramientas para elegir en una sola solicitud. Aquí tienes un ejemplo con una herramienta get_weather y una herramienta get_time, junto con una consulta del usuario que pide ambas.

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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, either 'celsius' or 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

En este caso, Claude puede:

Usar las herramientas secuencialmente (una a la vez) — llamando get_weather primero, luego get_time después de recibir el resultado del clima
Usar llamadas de herramientas en paralelo — produciendo múltiples bloques tool_use en una sola respuesta cuando las operaciones son independientes

Cuando Claude hace llamadas de herramientas en paralelo, debes devolver todos los resultados de las herramientas en un solo mensaje user, con cada resultado en su propio bloque tool_result.

Información faltante

Si el prompt del usuario no incluye suficiente información para llenar todos los parámetros requeridos para una herramienta, Claude Opus es mucho más probable que reconozca que falta un parámetro y lo pida. Claude Sonnet puede preguntar, especialmente cuando se le solicita pensar antes de producir una solicitud de herramienta. Pero también puede hacer su mejor esfuerzo para inferir un valor razonable.Por ejemplo, usando la herramienta get_weather anterior, si le preguntas a Claude “¿Cómo está el clima?” sin especificar una ubicación, Claude, particularmente Claude Sonnet, puede hacer una suposición sobre las entradas de las herramientas:

JSON

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

Este comportamiento no está garantizado, especialmente para prompts más ambiguos y para modelos menos inteligentes. Si Claude Opus no tiene suficiente contexto para llenar los parámetros requeridos, es mucho más probable que responda con una pregunta aclaratoria en lugar de hacer una llamada de herramienta.

Herramientas secuenciales

Algunas tareas pueden requerir llamar múltiples herramientas en secuencia, usando la salida de una herramienta como entrada para otra. En tal caso, Claude llamará una herramienta a la vez. Si se le solicita llamar todas las herramientas de una vez, Claude probablemente adivinará parámetros para herramientas más adelante en el flujo si dependen de resultados de herramientas para herramientas más arriba en el flujo.Aquí tienes un ejemplo de usar una herramienta get_location para obtener la ubicación del usuario, luego pasar esa ubicación a la herramienta get_weather:

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

En este caso, Claude primero llamaría la herramienta get_location para obtener la ubicación del usuario. Después de que devuelvas la ubicación en un tool_result, Claude entonces llamaría get_weather con esa ubicación para obtener la respuesta final.La conversación completa podría verse así:

Rol	Contenido
Usuario	¿Cómo está el clima donde estoy?
Asistente	Primero encontraré tu ubicación actual, luego verificaré el clima allí. [Uso de herramienta para get_location]
Usuario	[Resultado de herramienta para get_location con id coincidente y resultado de San Francisco, CA]
Asistente	[Uso de herramienta para get_weather con la siguiente entrada]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Usuario	[Resultado de herramienta para get_weather con id coincidente y resultado de “59°F (15°C), mayormente nublado”]
Asistente	Basado en tu ubicación actual en San Francisco, CA, el clima ahora mismo es 59°F (15°C) y mayormente nublado. Es un día bastante fresco y nublado en la ciudad. Podrías querer llevar una chaqueta ligera si vas a salir.

Este ejemplo demuestra cómo Claude puede encadenar múltiples llamadas de herramientas para responder una pregunta que requiere recopilar datos de diferentes fuentes. Los pasos clave son:

Claude primero se da cuenta de que necesita la ubicación del usuario para responder la pregunta del clima, así que llama la herramienta get_location.
El usuario (es decir, el código del cliente) ejecuta la función get_location real y devuelve el resultado “San Francisco, CA” en un bloque tool_result.
Con la ubicación ahora conocida, Claude procede a llamar la herramienta get_weather, pasando “San Francisco, CA” como el parámetro location (así como un parámetro unit adivinado, ya que unit no es un parámetro requerido).
El usuario nuevamente ejecuta la función get_weather real con los argumentos proporcionados y devuelve los datos del clima en otro bloque tool_result.
Finalmente, Claude incorpora los datos del clima en una respuesta en lenguaje natural a la pregunta original.

Uso de herramientas con cadena de pensamiento

Modo JSON

Puedes usar herramientas para hacer que Claude produzca salida JSON que siga un esquema, incluso si no tienes intención de ejecutar esa salida a través de una herramienta o función.Cuando uses herramientas de esta manera:

Usualmente quieres proporcionar una sola herramienta
Deberías establecer tool_choice (ver Forzar uso de herramientas) para instruir al modelo a usar explícitamente esa herramienta
Recuerda que el modelo pasará la input a la herramienta, así que el nombre de la herramienta y la descripción deberían ser desde la perspectiva del modelo.

Lo siguiente usa una herramienta record_summary para describir una imagen siguiendo un formato particular.

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image."}
        ]}
    ]
}'

Precios

Tool use requests are priced based on:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
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.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4.1	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Opus 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.7	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct) (deprecated)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June) (deprecated)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3 (deprecated)	`auto`, `none` `any`, `tool`	530 tokens 281 tokens
Claude Sonnet 3	`auto`, `none` `any`, `tool`	159 tokens 235 tokens
Claude Haiku 3	`auto`, `none` `any`, `tool`	264 tokens 340 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request. Consulta nuestra tabla de resumen de modelos para precios actuales por modelo. Cuando envías un prompt de uso de herramientas, al igual que cualquier otra solicitud de API, la respuesta mostrará tanto los conteos de tokens de entrada como de salida como parte de las métricas de usage reportadas.

Próximos Pasos

Explora nuestro repositorio de ejemplos de código de uso de herramientas listos para implementar en nuestros libros de cocina:

Herramienta Calculadora

Aprende cómo integrar una herramienta de calculadora simple con Claude para cálculos numéricos precisos.

Agente de Servicio al Cliente

Construye un bot de servicio al cliente receptivo que aprovecha herramientas del cliente para mejorar el soporte.

Extractor JSON

Ve cómo Claude y el uso de herramientas pueden extraer datos estructurados de texto no estructurado.

Primeros pasos

Modelos y precios

Aprende sobre Claude

Capacidades

Herramientas

Protocolo de Contexto del Modelo (MCP)

Casos de uso

Ingeniería de prompts

Probar y evaluar

Fortalecer las barreras de protección

Centro legal

Uso de herramientas con Claude

Cómo funciona el uso de herramientas

Herramientas del cliente

Herramientas del servidor

Ejemplos de uso de herramientas

Precios

Próximos Pasos

Herramienta Calculadora

Agente de Servicio al Cliente

Extractor JSON

Primeros pasos

Modelos y precios

Aprende sobre Claude

Capacidades

Herramientas

Protocolo de Contexto del Modelo (MCP)

Casos de uso

Ingeniería de prompts

Probar y evaluar

Fortalecer las barreras de protección

Centro legal

​Cómo funciona el uso de herramientas

​Herramientas del cliente

​Herramientas del servidor

​Ejemplos de uso de herramientas

​Precios

​Próximos Pasos

Herramienta Calculadora

Agente de Servicio al Cliente

Extractor JSON

Cómo funciona el uso de herramientas

Herramientas del cliente

Herramientas del servidor

Ejemplos de uso de herramientas

Precios

Próximos Pasos