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:

Shell

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:

1. 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

2. 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:

1. 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?”
2. 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.
3. 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
4. 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:

1. 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.”
2. 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.
3. 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

Shell

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:

Shell

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

Claude puede llamar múltiples herramientas en paralelo dentro de una sola respuesta, lo cual es útil para tareas que requieren múltiples operaciones independientes. Cuando se usan herramientas en paralelo, todos los bloques tool_use se incluyen en un solo mensaje del asistente, y todos los bloques tool_result correspondientes deben proporcionarse en el mensaje del usuario subsiguiente.

Importante: Los resultados de las herramientas deben formatearse correctamente para evitar errores de API y asegurar que Claude continúe usando herramientas en paralelo. Consulta nuestra guía de implementación para requisitos de formato detallados y ejemplos de código completos.

Para ejemplos completos, scripts de prueba y mejores prácticas para implementar llamadas de herramientas en paralelo, consulta la sección de uso de herramientas en paralelo en nuestra guía de implementación.

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.

Shell

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:

Shell

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:

1. 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.
2. 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.
3. 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).
4. 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.
5. Finalmente, Claude incorpora los datos del clima en una respuesta en lenguaje natural a la pregunta original.

Uso de herramientas con cadena de pensamiento

Por defecto, Claude Opus está programado para pensar antes de responder una consulta de uso de herramientas para determinar mejor si una herramienta es necesaria, qué herramienta usar, y los parámetros apropiados. Claude Sonnet y Claude Haiku están programados para tratar de usar herramientas tanto como sea posible y son más propensos a llamar una herramienta innecesaria o inferir parámetros faltantes. Para solicitar a Sonnet o Haiku que evalúen mejor la consulta del usuario antes de hacer llamadas de herramientas, se puede usar el siguiente prompt:

Prompt de cadena de pensamiento

Responde la solicitud del usuario usando herramientas relevantes (si están disponibles). Antes de llamar una herramienta, haz algo de análisis. Primero, piensa sobre cuál de las herramientas proporcionadas es la herramienta relevante para responder la solicitud del usuario. Segundo, revisa cada uno de los parámetros requeridos de la herramienta relevante y determina si el usuario ha proporcionado directamente o dado suficiente información para inferir un valor. Al decidir si el parámetro puede ser inferido, considera cuidadosamente todo el contexto para ver si apoya un valor específico. Si todos los parámetros requeridos están presentes o pueden ser razonablemente inferidos, procede con la llamada de herramienta. PERO, si uno de los valores para un parámetro requerido falta, NO invoques la función (ni siquiera con rellenos para los parámetros faltantes) y en su lugar, pide al usuario que proporcione los parámetros faltantes. NO pidas más información sobre parámetros opcionales si no se proporciona.

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.

Shell

#!/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:

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.

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.