Uso de herramientas con Claude

Claude es capaz de interactuar con herramientas y funciones externas del lado del cliente, lo que te permite equipar a Claude con tus propias herramientas personalizadas para realizar una mayor variedad de tareas.

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

​

Cómo funciona el uso de herramientas

Integra herramientas externas con Claude en estos pasos:

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.

​

Cómo implementar el uso de herramientas

​

Elegir un modelo

En general, usa Claude 3.7 Sonnet, Claude 3.5 Sonnet o Claude 3 Opus para herramientas complejas y consultas ambiguas; manejan mejor múltiples herramientas y buscan aclaraciones cuando es necesario.

Usa Claude 3.5 Haiku o Claude 3 Haiku para herramientas sencillas, pero ten en cuenta que pueden inferir parámetros faltantes.

​

Especificar herramientas

Las herramientas se especifican en el parámetro de nivel superior tools de la solicitud de API. Cada definición de herramienta incluye:

{
  "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"]
  }
}

​

Mensaje del sistema para uso de herramientas

Cuando llamas a la API de Anthropic con el parámetro tools, construimos un mensaje del sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier mensaje del sistema especificado por el usuario. El mensaje construido está diseñado para instruir al modelo sobre el uso de las herramientas especificadas y proporcionar el contexto necesario para que la herramienta funcione correctamente:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

Mejores prácticas para definiciones de herramientas

Para obtener el mejor rendimiento de Claude al usar herramientas, sigue estas pautas:

• Proporciona descripciones extremadamente detalladas. Este es, por mucho, el factor más importante en el rendimiento de las herramientas. Tus descripciones deben explicar cada detalle sobre la herramienta, incluyendo:
  • Qué hace la herramienta
  • Cuándo debe usarse (y cuándo no)
  • Qué significa cada parámetro y cómo afecta al comportamiento de la herramienta
  • Cualquier advertencia o limitación importante, como qué información no devuelve la herramienta si el nombre de la herramienta no está claro. Cuanto más contexto puedas dar a Claude sobre tus herramientas, mejor será para decidir cuándo y cómo usarlas. Apunta a tener al menos 3-4 oraciones por descripción de herramienta, más si la herramienta es compleja.
• Prioriza las descripciones sobre los ejemplos. Si bien puedes incluir ejemplos de cómo usar una herramienta en su descripción o en el mensaje que la acompaña, esto es menos importante que tener una explicación clara y completa del propósito y los parámetros de la herramienta. Solo agrega ejemplos después de haber desarrollado completamente la descripción.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

La buena descripción explica claramente qué hace la herramienta, cuándo usarla, qué datos devuelve y qué significa el parámetro ticker. La mala descripción es demasiado breve y deja a Claude con muchas preguntas abiertas sobre el comportamiento y uso de la herramienta.

​

Controlar la salida de Claude

​

Forzar el uso de herramientas

En algunos casos, es posible que desees que Claude use una herramienta específica para responder la pregunta del usuario, incluso si Claude piensa que puede proporcionar una respuesta sin usar una herramienta. Puedes hacer esto especificando la herramienta en el campo tool_choice así:

tool_choice = {"type": "tool", "name": "get_weather"}

Al trabajar con el parámetro tool_choice, tenemos tres opciones posibles:

• auto permite que Claude decida si llamar a cualquiera de las herramientas proporcionadas o no. Este es el valor predeterminado.
• any le dice a Claude que debe usar una de las herramientas proporcionadas, pero no fuerza una herramienta en particular.
• tool nos permite forzar a Claude a usar siempre una herramienta particular.

Este diagrama ilustra cómo funciona cada opción:

Ten en cuenta que cuando tienes tool_choice como any o tool, prellenaremos el mensaje del asistente para forzar el uso de una herramienta. Esto significa que los modelos no emitirán un bloque de contenido text de cadena de pensamiento antes de los bloques de contenido tool_use, incluso si se les pide explícitamente que lo hagan.

Nuestras pruebas han demostrado que esto no debería reducir el rendimiento. Si deseas mantener la cadena de pensamiento (particularmente con Opus) mientras solicitas que el modelo use una herramienta específica, puedes usar {"type": "auto"} para tool_choice (el valor predeterminado) y agregar instrucciones explícitas en un mensaje user. Por ejemplo: ¿Qué tiempo hace en Londres? Usa la herramienta get_weather en tu respuesta.

​

Salida JSON

Las herramientas no necesariamente tienen que ser funciones del lado del cliente — puedes usar herramientas en cualquier momento que desees que el modelo devuelva una salida JSON que siga un esquema proporcionado. Por ejemplo, podrías usar una herramienta record_summary con un esquema particular. Consulta ejemplos de uso de herramientas para ver un ejemplo completo y funcional.

​

Cadena de pensamiento

Al usar herramientas, Claude a menudo mostrará su “cadena de pensamiento”, es decir, el razonamiento paso a paso que utiliza para desglosar el problema y decidir qué herramientas usar. El modelo Claude 3 Opus hará esto si tool_choice está configurado como auto (este es el valor predeterminado, ver Forzar el uso de herramientas), y Sonnet y Haiku pueden ser inducidos a hacerlo.

Por ejemplo, dado el mensaje “¿Qué tiempo hace en San Francisco ahora mismo y qué hora es allí?”, Claude podría responder con:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Para responder esta pregunta, voy a: 1. Usar la herramienta get_weather para obtener el clima actual en San Francisco. 2. Usar la herramienta get_time para obtener la hora actual en la zona horaria America/Los_Angeles, que cubre San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Esta cadena de pensamiento proporciona información sobre el proceso de razonamiento de Claude y puede ayudarte a depurar comportamientos inesperados.

Con el modelo Claude 3 Sonnet, la cadena de pensamiento es menos común por defecto, pero puedes inducir a Claude a mostrar su razonamiento agregando algo como "Antes de responder, explica tu razonamiento paso a paso en etiquetas." al mensaje del usuario o al mensaje del sistema.

Es importante tener en cuenta que si bien las etiquetas <thinking> son una convención común que Claude usa para denotar su cadena de pensamiento, el formato exacto (como el nombre de esta etiqueta XML) puede cambiar con el tiempo. Tu código debe tratar la cadena de pensamiento como cualquier otro texto generado por el asistente y no depender de la presencia o el formato específico de las etiquetas <thinking>.

​

Deshabilitar el uso paralelo de herramientas

Por defecto, Claude puede usar múltiples herramientas para responder a una consulta del usuario. Puedes deshabilitar este comportamiento configurando disable_parallel_tool_use=true en el campo tool_choice.

• Cuando el tipo de tool_choice es auto, esto asegura que Claude use como máximo una herramienta
• Cuando el tipo de tool_choice es any o tool, esto asegura que Claude use exactamente una herramienta

​

Manejo de bloques de contenido de uso de herramientas y resultados de herramientas

Cuando Claude decide usar una de las herramientas que has proporcionado, devolverá una respuesta con un stop_reason de tool_use y uno o más bloques de contenido tool_use en la respuesta de la API que incluyen:

• id: Un identificador único para este bloque particular de uso de herramienta. Esto se usará para hacer coincidir los resultados de la herramienta más tarde.
• name: El nombre de la herramienta que se está usando.
• input: Un objeto que contiene la entrada que se pasa a la herramienta, conforme al input_schema de la herramienta.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Necesito usar get_weather, y el usuario quiere SF, que probablemente sea San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Cuando recibas una respuesta de uso de herramienta, deberías:

1. Extraer el name, id e input del bloque tool_use.
2. Ejecutar la herramienta real en tu código base correspondiente a ese nombre de herramienta, pasando la input de la herramienta.
3. Continuar la conversación enviando un nuevo mensaje con el role de user, y un bloque de content que contenga el tipo tool_result y la siguiente información:
   • tool_use_id: El id de la solicitud de uso de herramienta para la que esto es un resultado.
   • content: El resultado de la herramienta, como una cadena (por ejemplo, "content": "15 grados") o lista de bloques de contenido anidados (por ejemplo, "content": [{"type": "text", "text": "15 grados"}]). Estos bloques de contenido pueden usar los tipos text o image.
   • is_error (opcional): Establecer como true si la ejecución de la herramienta resultó en un error.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 grados"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 grados"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

Después de recibir el resultado de la herramienta, Claude usará esa información para continuar generando una respuesta al mensaje original del usuario.

​

Solución de problemas de errores

Hay varios tipos diferentes de errores que pueden ocurrir al usar herramientas con Claude:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: el servicio de clima API no está disponible (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Falta el parámetro requerido 'location'",
      "is_error": true
    }
  ]
}

​

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 herramientas simples, y las descripciones de las herramientas son más cortas de lo que sería ideal para asegurar el mejor rendimiento.

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Necesito llamar a la función get_weather, y el usuario quiere SF, que probablemente sea San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "El clima actual en San Francisco es de 15 grados Celsius (59 grados Fahrenheit). ¡Es un día fresco en la ciudad de la bahía!"
    }
  ]
}

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

​

Precios

Las solicitudes de uso de herramientas tienen el mismo precio que cualquier otra solicitud de API de Claude, basado en el número total de tokens de entrada enviados al modelo (incluyendo en el parámetro tools) y el número de tokens de salida generados.”

Los tokens adicionales del uso de herramientas provienen de:

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

Cuando usas tools, también incluimos automáticamente un mensaje 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 enumeran a continuación (excluyendo los tokens adicionales listados arriba):

Estos conteos de tokens se agregan a tus tokens normales de entrada y salida para calcular el costo total de una solicitud. Consulta nuestra tabla de descripción general de modelos para ver los precios actuales por modelo.

Cuando envías un mensaje de uso de herramienta, 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 recetas: