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

¡El uso de herramientas ahora está generalmente disponible en toda la familia de modelos Claude 3 para desarrolladores que utilizan la API de Mensajes de Anthropic, Amazon Bedrock y Google Vertex AI! Continúe compartiendo sus ideas y sugerencias utilizando este formulario.

Aquí hay un ejemplo de cómo proporcionar herramientas a Claude utilizando 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-3-opus-20240229",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Obtener el clima actual en una ubicación determinada",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "¿Cómo está el clima en San Francisco?"
      }
    ]
  }'

​
Cómo funciona el uso de herramientas

El uso de herramientas con Claude implica los siguientes pasos:

  1. Proporcionar a Claude herramientas y un mensaje del usuario: (solicitud de API)
    • Defina el conjunto de herramientas a las que desea que Claude tenga acceso, incluidos sus nombres, descripciones y esquemas de entrada.
    • Proporcione un mensaje del usuario que pueda requerir el uso de una o más de estas herramientas para responder, como “¿Cómo está el clima en San Francisco?“.
  2. Claude usa una herramienta: (respuesta de API)
    • Claude evalúa el mensaje del usuario y decide si alguna de las herramientas disponibles ayudaría con la consulta o tarea del usuario. Si es así, también decide qué herramienta(s) usar y con qué entradas.
    • Claude construye una solicitud de uso de herramienta con el formato adecuado.
    • La respuesta de la API tendrá una stop_reason de tool_use, lo que indica que Claude quiere usar una herramienta externa.
  3. Extraer la entrada de la herramienta, ejecutar el código y devolver los resultados: (solicitud de API)
    • En el lado del cliente, debe extraer el nombre de la herramienta y la entrada de la solicitud de uso de herramienta de Claude.
    • Ejecutar el código real de la herramienta en el lado del cliente.
    • Devolver los resultados a Claude continuando la conversación con un nuevo mensaje de user que contenga un bloque de contenido tool_result.
  4. Claude usa el resultado de la herramienta para formular una respuesta: (respuesta de API)
    • Después de recibir los resultados de la herramienta, Claude usará esa información para formular su respuesta final al mensaje original del usuario.

Los pasos (3) y (4) son opcionales: para algunos flujos de trabajo, el uso de la herramienta por parte de Claude es toda la información que necesita y es posible que no necesite devolver los resultados de la herramienta a Claude.

Todas las herramientas son proporcionadas por el usuario

Es importante tener en cuenta que Claude no tiene acceso a ninguna herramienta integrada del lado del servidor. Todas las herramientas deben ser proporcionadas explícitamente por usted, el usuario, en cada solicitud de API. Esto le brinda control total y flexibilidad sobre las herramientas que Claude puede usar.

​
Especificación de 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: El nombre de la herramienta. Debe coincidir con la expresión regular ^[a-zA-Z0-9_-]{1,64}$.
  • description: Una descripción detallada en texto sin formato de lo que hace la herramienta, cuándo debe usarse y cómo se comporta.
  • input_schema: Un objeto JSON Schema que define los parámetros esperados para la herramienta.

Aquí hay un ejemplo de una definición de herramienta simple:

JSON
{
  "name": "get_weather",
  "description": "Obtener el clima actual en una ubicación determinada",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La ciudad y el estado, por ejemplo, San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "La unidad de temperatura, ya sea 'celsius' o 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Esta herramienta, llamada get_weather, espera un objeto de entrada con una cadena location requerida y una cadena unit opcional que debe ser “celsius” o “fahrenheit”.

​
Mejores prácticas para definiciones de herramientas

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

  • Proporcione descripciones extremadamente detalladas. Este es, por mucho, el factor más importante en el rendimiento de las herramientas. Sus 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 el 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 es claro
      Cuanto más contexto pueda darle a Claude sobre sus herramientas, mejor será para decidir cuándo y cómo usarlas. Apunte a al menos 3-4 oraciones por descripción de herramienta, más si la herramienta es compleja.
  • Priorice las descripciones sobre los ejemplos. Si bien puede incluir ejemplos de cómo usar una herramienta en su descripción o en el mensaje adjunto, esto es menos importante que tener una explicación clara y completa del propósito y los parámetros de la herramienta. Solo agregue ejemplos después de haber desarrollado completamente la descripción.

Aquí hay un ejemplo de una buena descripción de herramienta:

JSON
{
  "name": "get_stock_price",
  "description": "Recupera el precio actual de las acciones para un símbolo de ticker determinado. El símbolo de ticker debe ser un símbolo válido para una empresa que cotiza en bolsa en una bolsa de valores importante de EE. UU., como NYSE o NASDAQ. La herramienta devolverá el último precio de negociación en USD. Debe usarse cuando el usuario pregunta sobre el precio actual o más reciente de una acción específica. No proporcionará ninguna otra información sobre la acción o la empresa.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "El símbolo de ticker de la acción, por ejemplo, AAPL para Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

En contraste, aquí hay un ejemplo de una descripción de herramienta deficiente:

JSON
{
  "name": "get_stock_price",
  "description": "Obtiene el precio de la acción para un 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 descripción deficiente es demasiado breve y deja a Claude con muchas preguntas abiertas sobre el comportamiento y el uso de la herramienta.

​
Bloques de contenido de uso de herramientas y resultados de herramientas

Cuando Claude decide usar una de las herramientas que ha proporcionado, devolverá una respuesta con una 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 de uso de herramienta en particular. Esto se usará para hacer coincidir los resultados de la herramienta más adelante.
  • name: El nombre de la herramienta que se está utilizando.
  • input: Un objeto que contiene la entrada que se pasa a la herramienta, de acuerdo con el input_schema de la herramienta.

Aquí hay un ejemplo de respuesta de API con un bloque de contenido tool_use:

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-opus-20240229",
  "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 reciba una respuesta de uso de herramienta, debe:

  1. Extraer el name, id e input del bloque tool_use.
  2. Ejecutar la herramienta real en su base de código correspondiente a ese nombre de herramienta, pasando la input de la herramienta.
  3. [opcional] 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 este es un resultado.
    • content: El resultado de la herramienta, como una cadena (por ejemplo, "content": "15 grados") o una 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 en true si la ejecución de la herramienta resultó en un error.

Aquí hay un ejemplo de cómo devolver un resultado de herramienta exitoso:

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

Las imágenes también son compatibles en content:

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

Y aquí hay un ejemplo de cómo devolver un resultado de error:

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

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

También puede devolver un resultado de herramienta no erróneo con content vacío, lo que indica que la herramienta se ejecutó con éxito sin ninguna salida:

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

Diferencias con otras API

Es posible que esté familiarizado con otras API que devuelven el uso de herramientas por separado de la salida principal del modelo, o que usan un role de mensaje especial de tool o function.

En contraste, los modelos y la API de Anthropic se basan en mensajes alternos de user y assistant, donde cada mensaje es una matriz de bloques de contenido enriquecido: text, image, tool_use y tool_result.

En este formato, los mensajes de user representan contenido administrado por el cliente y el usuario/humano, y los mensajes de assistant representan contenido administrado por el servidor y la IA. Como tal, no hay un role de mensaje especial de tool o function, y debe incluir bloques tool_result en el content de sus mensajes de user.

​
Forzar el uso de herramientas

En algunos casos, es posible que desee que Claude use una herramienta específica para responder la pregunta del usuario, incluso si Claude cree que puede proporcionar una respuesta sin usar una herramienta. Puede hacer esto especificando la herramienta en el campo tool_choice de la siguiente manera:

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

Al decirle explícitamente a Claude que use la herramienta get_weather, puede alentarlo a usar la herramienta que desea. Esta técnica puede ser útil para probar y depurar sus integraciones de herramientas, o cuando sabe que la herramienta siempre debe usarse, independientemente de la entrada.

También puede decirle a Claude que use cualquiera de las herramientas proporcionadas a través de {"type": "any"}. El tool_choice predeterminado es {"type": "auto"}, que permite a Claude decidir si usar o no una herramienta.

Tenga en cuenta que cuando tiene tool_choice como any o tool, rellenaremos previamente 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 desea mantener la cadena de pensamiento (particularmente con Opus) mientras solicita que el modelo use una herramienta específica, puede usar {"type": "auto"} para tool_choice (el valor predeterminado) y agregar instrucciones explícitas en un mensaje de user. Por ejemplo: ¿Cómo está el clima en Londres? Usa la herramienta get_weather en tu respuesta.

​
Salida JSON

Las herramientas no necesariamente tienen que ser funciones del lado del cliente; puede usar herramientas en cualquier momento que desee que el modelo devuelva una salida JSON que siga un esquema proporcionado. Por ejemplo, puede usar una herramienta record_summary con un esquema particular. Consulte ejemplos de uso de herramientas para obtener un ejemplo completo de trabajo.

​
Manejo de errores

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

​
Error de ejecución de herramienta

Si la herramienta en sí arroja un error durante la ejecución (por ejemplo, un error de red al obtener datos meteorológicos), puede devolver el mensaje de error en el content junto con "is_error": true:

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

Claude incorporará este error en su respuesta al usuario, por ejemplo, “Lo siento, no pude recuperar el clima actual porque el servicio de API del clima no está disponible. Intente nuevamente más tarde.”

​
Tokens máximos excedidos

Si la respuesta de Claude se corta debido a alcanzar el límite de max_tokens, y la respuesta truncada contiene un bloque de uso de herramienta incompleto, deberá volver a intentar la solicitud con un valor de max_tokens más alto para obtener el uso completo de la herramienta.

​
Uso de herramienta no válido

Si el intento de Claude de usar una herramienta no es válido (por ejemplo, faltan parámetros requeridos), generalmente significa que no había suficiente información para que Claude usara la herramienta correctamente. Su mejor apuesta durante el desarrollo es intentar la solicitud nuevamente con valores de description más detallados en sus definiciones de herramientas.

Sin embargo, también puede continuar la conversación con un tool_result que indique el error, y Claude intentará usar la herramienta nuevamente con la información faltante completada:

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

​
Uso de herramientas con cadena de pensamiento

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

Por ejemplo, dado el mensaje “¿Cómo está el clima en San Francisco en este momento y qué hora es allí?”, Claude podría responder con:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>Para responder esta pregunta, haré lo siguiente: 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 brinda información sobre el proceso de razonamiento de Claude y puede ayudarlo a depurar comportamientos inesperados.

Con el modelo Claude 3 Sonnet, la cadena de pensamiento es menos común de forma predeterminada, pero puede indicarle a Claude que muestre su razonamiento agregando algo como “Antes de responder, explica tu razonamiento paso a paso entre etiquetas.” al mensaje del usuario o al mensaje del sistema. Para obtener un ejemplo más detallado, consulte ejemplo de uso de herramienta con cadena de pensamiento.

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

​
Mejores prácticas y limitaciones del uso de herramientas

Al usar herramientas con Claude, tenga en cuenta las siguientes limitaciones y mejores prácticas:

  • Use Claude 3 Opus para navegar por el uso complejo de herramientas, Haiku si se trata de herramientas sencillas: Opus puede manejar la mayor cantidad de herramientas simultáneas y es mejor para detectar argumentos faltantes en comparación con otros modelos. Es más probable que solicite aclaraciones en casos ambiguos donde un argumento no se proporciona explícitamente o cuando una herramienta puede no ser necesaria para completar la solicitud del usuario. Haiku intenta usar herramientas con más frecuencia de forma predeterminada (incluso si no son relevantes para la consulta) e inferirá los parámetros faltantes si no se proporcionan explícitamente.
  • Número de herramientas: Todos los modelos Claude 3 pueden mantener una precisión >90% incluso cuando trabajan con cientos de herramientas simples y un número menor de herramientas complejas. Una herramienta “compleja” sería una con una gran cantidad de parámetros o parámetros con esquemas complejos (por ejemplo, objetos anidados).
  • Herramientas complejas y profundamente anidadas: Al igual que un humano, Claude puede trabajar mejor con interfaces más simples y herramientas más simples. Si Claude tiene dificultades para usar correctamente su herramienta, intente aplanar el esquema de entrada alejándose de los objetos JSON profundamente anidados y reduzca la cantidad de entradas.
  • Uso secuencial de herramientas: Claude generalmente prefiere usar una herramienta a la vez y luego usar la salida de esa herramienta para informar su próxima acción. Si bien puede indicarle a Claude que use varias herramientas en paralelo diseñando cuidadosamente su mensaje y herramientas, esto puede llevar a Claude a completar valores ficticios para parámetros que dependen de los resultados del uso anterior de herramientas. Para obtener los mejores resultados, diseñe su flujo de trabajo y herramientas para obtener y trabajar con una serie de usos secuenciales de herramientas de Claude.
  • Reintentos: Si la solicitud de uso de herramienta de Claude no es válida o faltan parámetros requeridos, puede devolver una respuesta de error y Claude generalmente volverá a intentar la solicitud con la información faltante completada. Sin embargo, después de 2-3 intentos fallidos, Claude puede darse por vencido y devolver una disculpa al usuario en lugar de volver a intentarlo.
  • Depuración: Al depurar un comportamiento inesperado del uso de herramientas, preste atención a la salida de la cadena de pensamiento de Claude (si la hay) para comprender por qué está tomando las decisiones que está tomando. También puede intentar indicarle a Claude que use una herramienta específica para ver si eso conduce al comportamiento esperado. Si Claude está usando mal una herramienta, vuelva a verificar que las descripciones y los esquemas de sus herramientas sean claros y sin ambigüedades.
  • Etiquetas <search_quality_reflection>: A veces, cuando se usan herramientas de búsqueda, el modelo puede devolver etiquetas XML <search_quality_reflection> y una puntuación de calidad de búsqueda en su respuesta. Para evitar que el modelo haga esto, agregue la oración “No reflexione sobre la calidad de los resultados de búsqueda devueltos en su respuesta.” al final de su mensaje.

Al tener en cuenta estas limitaciones y pautas, puede diseñar herramientas efectivas y orquestaciones de agentes que amplíen significativamente las capacidades de Claude para abordar una amplia variedad de tareas.

​
Historial de versiones beta (heredado)

El uso de herramientas ya no está en beta y está disponible de forma general a partir del 30 de mayo de 2024.

  • tools-2024-05-16
    • Cambio de mensaje del sistema para Opus para manejar mejor los escenarios en los que se pueden necesitar varios usos de herramientas en un solo turno
  • tools-2024-04-04: Lanzamiento beta inicial para el uso de herramientas

​
Próximos pasos

El uso de herramientas es una técnica poderosa para extender las capacidades de Claude al conectarlo a fuentes de datos y funcionalidades externas. Con un conjunto bien diseñado de herramientas, puede permitir que Claude aborde una gran variedad de tareas que serían imposibles solo con su conocimiento base.

Algunos posibles próximos pasos para explorar:

  • Explore nuestros libros de cocina de uso de herramientas: explore nuestro repositorio de ejemplos de código de uso de herramientas listos para implementar, como:
  • Mejorar la calidad y confiabilidad del uso de herramientas: Itere y mejore las descripciones de sus herramientas y mensajes para obtener un uso de herramientas más confiable y preciso de Claude
  • Ampliar las capacidades de Claude:
    • Experimente con diferentes herramientas y esquemas para ver cómo Claude maneja diferentes tipos de formatos de entrada y salida.
    • Encadene varias herramientas para desglosar tareas complejas en una serie de pasos más simples.
    • Construya orquestaciones de agentes donde Claude pueda completar una variedad de tareas de principio a fin como si fuera un asistente.
    • Explore arquitecturas complejas de uso de herramientas, como darle a Claude herramientas para realizar búsquedas RAG, o para llamar a subagentes de modelos más pequeños, como Haiku, para que realicen tareas en su nombre

A medida que construya con el uso de herramientas, ¡nos encantaría escuchar sus comentarios y ver lo que crea! Únase a nuestro Discord de desarrolladores para compartir sus proyectos y discutir consejos y técnicas con otros desarrolladores.

Estamos emocionados de ver cómo usa el uso de herramientas para expandir los límites de lo que es posible con Claude. ¡Feliz construcción!

Complemento de Google SheetsEjemplos de uso de herramientas