Uso de herramientas (llamadas a funciones)
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.
¡Aprenda todo lo que necesita para dominar el uso de herramientas con Claude a través de nuestro nuevo y completo curso de uso de herramientas! Continúe compartiendo sus ideas y sugerencias utilizando este formulario.
Aquí hay un ejemplo de cómo proporcionar herramientas a Claude usando la API de Messages:
Cómo funciona el uso de herramientas
Integre herramientas externas con Claude en estos pasos:
Proporcione a Claude herramientas y un mensaje del usuario
- Defina herramientas con nombres, descripciones y esquemas de entrada en su solicitud de API.
- Incluya un mensaje del usuario que pueda 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.
- La respuesta de la API tiene un
stop_reason
detool_use
, lo que indica la intención de Claude.
Extraiga la entrada de la herramienta, ejecute el código y devuelva los resultados
- En su extremo, extraiga el nombre de la herramienta y la entrada de la solicitud de Claude.
- Ejecute el código real de la herramienta del lado del cliente.
- Continúe la conversación con un nuevo mensaje de
user
que contenga un bloque de contenidotool_result
.
Claude utiliza 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 necesita, sin enviar los resultados de vuelta 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 da control total y flexibilidad sobre las herramientas que Claude puede usar.
Cómo implementar el uso de herramientas
Elegir un modelo
En general, use Claude 3 Opus para herramientas complejas y consultas ambiguas; maneja mejor múltiples herramientas y busca aclaraciones cuando es necesario.
Use Haiku para herramientas sencillas, pero tenga en cuenta que puede 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:
Parámetro | Descripción |
---|---|
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 plano 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. |
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:
- Lo que 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 podrá 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.
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.
Controlar la salida de Claude
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"}
Cuando se trabaja con el parámetro tool_choice, tenemos tres opciones posibles:
auto
permite que Claude decida si llamar o no a las herramientas proporcionadas. 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 en particular.
Este diagrama ilustra cómo funciona cada opción:
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) y aun así solicitar 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? Use la herramienta get_weather en su 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 y funcional.
Cadena de pensamiento
Cuando usa 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:
{
"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, explique su razonamiento paso a paso entre 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. 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>
.
Manejo de 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 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 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 elinput_schema
de la herramienta.
Cuando reciba una respuesta de uso de herramienta, debe:
- Extraer el
name
,id
einput
del bloquetool_use
. - Ejecutar la herramienta real en su base de código correspondiente a ese nombre de herramienta, pasando la
input
de la herramienta. - [opcional] Continuar la conversación enviando un nuevo mensaje con el
role
deuser
y un bloque decontent
que contenga el tipotool_result
y la siguiente información:tool_use_id
: Elid
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 tipostext
oimage
.is_error
(opcional): Establecer entrue
si la ejecución de la herramienta resultó en un error.
Después de recibir el resultado de la herramienta, Claude usará esa información para continuar generando una respuesta al mensaje original del usuario.
Diferencias con otras API
A diferencia de las API que separan el uso de herramientas o usan roles especiales como tool
o function
, la API de Anthropic integra las herramientas directamente en la estructura de mensajes de user
y assistant
.
Los mensajes contienen matrices de bloques text
, image
, tool_use
y tool_result
. Los mensajes de user
incluyen contenido del lado del cliente y tool_result
, mientras que los mensajes de assistant
contienen contenido generado por IA y tool_use
.
Solución de problemas de errores
Hay algunos tipos diferentes de errores que pueden ocurrir al usar herramientas con Claude:
Ejemplos de uso de herramientas
Aquí hay algunos ejemplos de código que demuestran varios patrones y técnicas de uso de herramientas. Por motivos de brevedad, las herramientas son herramientas simples y las descripciones de las herramientas son más cortas de lo que sería ideal para garantizar el mejor rendimiento.
Precios
Las solicitudes de uso de herramientas tienen el mismo precio que cualquier otra solicitud de la API de Claude, según el número total de tokens de entrada enviados al modelo (incluidos 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 la API (nombres de herramientas, descripciones y esquemas) - Bloques de contenido
tool_use
en solicitudes y respuestas de la API - Bloques de contenido
tool_result
en solicitudes de la API
Cuando usa 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 enumerados anteriormente):
Modelo | Elección de herramienta | Recuento de tokens del mensaje del sistema de uso de herramientas |
---|---|---|
Claude 3.5 Sonnet | auto any , tool | 294 tokens 261 tokens |
Claude 3 Opus | auto any , tool | 530 tokens 281 tokens |
Claude 3 Sonnet | auto any , tool | 159 tokens 235 tokens |
Claude 3 Haiku | auto any , tool | 264 tokens 340 tokens |
Estos recuentos de tokens se suman a sus tokens de entrada y salida normales para calcular el costo total de una solicitud. Consulte nuestra tabla de resumen de modelos para conocer los precios actuales por modelo.
Cuando envía un mensaje de uso de herramienta, al igual que cualquier otra solicitud de la API, la respuesta generará recuentos de tokens de entrada y salida como parte de las métricas de usage
informadas.
Próximos pasos
Explore nuestro repositorio de ejemplos de código de uso de herramientas listos para implementar en nuestros libros de cocina:
Herramienta de calculadora
Aprenda cómo integrar una herramienta de calculadora simple con Claude para cálculos numéricos precisos.
Agente de servicio al cliente
Construya un bot de servicio al cliente receptivo que aproveche las herramientas del lado del cliente para mejorar el soporte.
Extractor de JSON
Vea cómo Claude y el uso de herramientas pueden extraer datos estructurados de texto no estructurado.