Uso de herramientas con Claude

Claude es capaz de interactuar con herramientas y funciones, lo que te permite ampliar las capacidades de Claude para realizar una mayor variedad de tareas.

Aprende todo lo que necesitas para dominar el uso de herramientas con Claude a través de nuestro nuevo curso integral sobre uso de herramientas. Por favor, continúa compartiendo tus ideas y sugerencias usando este formulario.

Aquí hay 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-20250514",
    "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 admite 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 (beta) y editor de texto que requieren implementación del cliente
Herramientas del servidor: Herramientas que se ejecutan en los servidores de Anthropic, como la herramienta de búsqueda web. Estas herramientas deben especificarse en la solicitud de API pero no requieren implementación por tu parte.

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

Herramientas del cliente

Integra herramientas del cliente con Claude en estos pasos:

Proporciona a Claude herramientas y un mensaje del usuario

Define herramientas del cliente con nombres, descripciones y esquemas de entrada en tu solicitud de API.
Incluye un mensaje 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 con el formato adecuado.
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 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 contiene 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 mensaje 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 mensaje del usuario

Las herramientas del servidor, como búsqueda web, tienen sus propios parámetros.
Incluye un mensaje del usuario que podría requerir estas herramientas, por ejemplo, “Busca las últimas noticias sobre IA.”

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 mensaje original del usuario.
No se necesita interacción adicional del usuario para la ejecución de la herramienta del servidor.

Ejemplos de uso de herramientas

Aquí hay algunos ejemplos de código que demuestran varios patrones y técnicas de uso de herramientas. Por brevedad, las herramientas son simples y las descripciones de las herramientas son más cortas de lo que sería ideal para garantizar 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-20250514",
    "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-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Luego tendrías que 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-20250514",
    "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": "<thinking>I need to use get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
                },
                {
                    "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-20250514",
  "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!"
    }
  ]
}

Ejemplo de múltiples herramientas

Puedes proporcionar a Claude múltiples herramientas para elegir en una sola solicitud. Aquí hay un ejemplo con una herramienta get_weather y una herramienta get_time, junto con una consulta de 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-20250514",
    "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 probablemente intentará usar dos herramientas separadas, una a la vez — get_weather y luego get_time — para responder completamente a la pregunta del usuario. Sin embargo, ocasionalmente también puede generar dos bloques tool_use a la vez, particularmente si no dependen uno del otro. Tendrías que ejecutar cada herramienta y devolver sus resultados en bloques tool_result separados dentro de un solo mensaje user.

Información faltante

Si el mensaje del usuario no incluye suficiente información para completar todos los parámetros requeridos para una herramienta, Claude Opus es mucho más propenso a reconocer que falta un parámetro y preguntar por él. Claude Sonnet puede preguntar, especialmente cuando se le indica que piense antes de generar una solicitud de herramienta. Pero también puede hacer lo posible por 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 mensajes más ambiguos y para modelos menos inteligentes. Si Claude Opus no tiene suficiente contexto para completar los parámetros requeridos, es mucho más probable que responda con una pregunta aclaratoria en lugar de hacer una llamada a la herramienta.

Herramientas secuenciales

Algunas tareas pueden requerir llamar a múltiples herramientas en secuencia, utilizando la salida de una herramienta como entrada para otra. En tal caso, Claude llamará a una herramienta a la vez. Si se le indica que llame a todas las herramientas a la vez, Claude probablemente adivinará parámetros para herramientas posteriores si dependen de los resultados de herramientas anteriores.

Aquí hay un ejemplo de uso de una herramienta get_location para obtener la ubicación del usuario, y 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-20250514",
    "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 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 llamaría 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	<thinking>Para responder a esto, primero necesito determinar la ubicación del usuario usando la herramienta get_location. Luego puedo pasar esa ubicación a la herramienta get_weather para encontrar el clima actual allí.</thinking>[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	Según tu ubicación actual en San Francisco, CA, el clima en este momento es de 59°F (15°C) y mayormente nublado. Es un día bastante fresco y nublado en la ciudad. Es posible que quieras llevar una chaqueta ligera si vas a salir.

Este ejemplo demuestra cómo Claude puede encadenar múltiples llamadas a herramientas para responder a 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 a la pregunta sobre el clima, por lo que llama a la herramienta get_location.
El usuario (es decir, el código del cliente) ejecuta la función real get_location y devuelve el resultado “San Francisco, CA” en un bloque tool_result.
Con la ubicación ahora conocida, Claude procede a llamar a 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 real get_weather 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 una salida JSON que siga un esquema, incluso si no tienes ninguna intención de ejecutar esa salida a través de una herramienta o función.

Cuando uses herramientas de esta manera:

Normalmente querrás proporcionar una única herramienta
Deberías establecer tool_choice (ver Forzar el uso de herramientas) para instruir al modelo a usar explícitamente esa herramienta
Recuerda que el modelo pasará la input a la herramienta, por lo que el nombre de la herramienta y la descripción deben ser desde la perspectiva del modelo.

El siguiente ejemplo 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-20250514",
    "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	`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)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3	`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 descripción general de modelos para conocer los precios actuales por modelo.

Cuando envías un mensaje para uso de herramientas, al igual que 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

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

Herramienta de Calculadora

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

Agente de Servicio al Cliente

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

Extractor JSON

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

Primeros pasos

Modelos y precios

Explorar funciones

Probar y evaluar

Conoce a Claude

Centro legal

Componentes del agente

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 de Calculadora

Agente de Servicio al Cliente

Extractor JSON

Primeros pasos

Modelos y precios

Explorar funciones

Probar y evaluar

Conoce a Claude

Centro legal

Componentes del agente

​Cómo funciona el uso de herramientas

​Herramientas del cliente

​Herramientas del servidor

​Ejemplos de uso de herramientas

​Precios

​Próximos pasos

Herramienta de 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