Cómo implementar el uso de herramientas
Elegir un modelo
En general, usa Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 o Claude Opus 3 para herramientas complejas y consultas ambiguas; manejan mejor múltiples herramientas y buscan aclaración cuando es necesario.
Usa Claude Haiku 3.5 o Claude Haiku 3 para herramientas sencillas, pero ten en cuenta que pueden inferir parámetros faltantes.
Si usas Claude Sonnet 3.7 con uso de herramientas y pensamiento extendido, consulta nuestra guía aquí para más información.
Especificar herramientas del cliente
Las herramientas del cliente (tanto las definidas por Anthropic como las definidas por el usuario) 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. |
Prompt del sistema para uso de herramientas
Cuando llamas a la API de Anthropic con el parámetro tools
, construimos un prompt del sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier prompt del sistema especificado por el usuario. El prompt construido está diseñado para instruir al modelo a usar las herramientas especificadas y proporcionar el contexto necesario para que la herramienta opere correctamente:
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 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. Mientras más contexto puedas darle a Claude sobre tus herramientas, mejor será para decidir cuándo y cómo usarlas. Apunta a al menos 3-4 oraciones por descripción de herramienta, más si la herramienta es compleja.
- Prioriza las descripciones sobre los ejemplos. Aunque puedes incluir ejemplos de cómo usar una herramienta en su descripción o en el prompt que la acompaña, esto es menos importante que tener una explicación clara y completa del propósito y parámetros de la herramienta. Solo agrega 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 pobre 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 quieras 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í:
Al trabajar con el parámetro tool_choice, tenemos cuatro opciones posibles:
auto
permite a Claude decidir si llamar cualquiera de las herramientas proporcionadas o no. Este es el valor predeterminado cuando se proporcionantools
.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.none
evita que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionantools
.
Al usar caché de prompts, los cambios al parámetro tool_choice
invalidarán los bloques de mensajes en caché. Las definiciones de herramientas y prompts del sistema permanecen en caché, pero el contenido del mensaje debe reprocesarse.
Este diagrama ilustra cómo funciona cada opción:
Ten en cuenta que cuando tienes tool_choice
como any
o tool
, precompletaremos el mensaje del asistente para forzar que se use 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.
Al usar pensamiento extendido con uso de herramientas, tool_choice: {"type": "any"}
y tool_choice: {"type": "tool", "name": "..."}
no son compatibles y resultarán en un error. Solo tool_choice: {"type": "auto"}
(el predeterminado) y tool_choice: {"type": "none"}
son compatibles con el pensamiento extendido.
Nuestras pruebas han mostrado que esto no debería reducir el rendimiento. Si quieres mantener la cadena de pensamiento (particularmente con Opus) mientras sigues solicitando que el modelo use una herramienta específica, puedes usar {"type": "auto"}
para tool_choice
(el predeterminado) y agregar instrucciones explícitas en un mensaje user
. Por ejemplo: ¿Cómo está el clima en Londres? Usa la herramienta get_weather en tu respuesta.
Salida JSON
Las herramientas no necesariamente necesitan ser funciones del cliente — puedes usar herramientas en cualquier momento que quieras que el modelo devuelva salida JSON que siga un esquema proporcionado. Por ejemplo, podrías usar una herramienta record_summary
con un esquema particular. Ve Uso de herramientas con Claude para un ejemplo completo funcional.
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 Opus 3 hará esto si tool_choice
está configurado en auto
(este es el valor predeterminado, ve Forzar el uso de herramientas), y Sonnet y Haiku pueden ser inducidos a hacerlo.
Por ejemplo, dado el prompt “¿Cómo está el clima en San Francisco ahora mismo, y qué hora es allí?”, Claude podría responder con:
Esta cadena de pensamiento da información sobre el proceso de razonamiento de Claude y puede ayudarte a depurar comportamientos inesperados.
Con el modelo Claude Sonnet 3, 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 prompt del sistema.
Es importante notar que aunque 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 formato específico de las etiquetas <thinking>
.
Uso paralelo de herramientas
Por defecto, Claude puede usar múltiples herramientas para responder una consulta del usuario. Puedes deshabilitar este comportamiento:
- Configurando
disable_parallel_tool_use=true
cuando el tipo de tool_choice esauto
, lo que asegura que Claude use como máximo una herramienta - Configurando
disable_parallel_tool_use=true
cuando el tipo de tool_choice esany
otool
, lo que asegura que Claude use exactamente una herramienta
Maximizar el uso paralelo de herramientas
Aunque los modelos Claude 4 tienen excelentes capacidades de uso paralelo de herramientas por defecto, puedes aumentar la probabilidad de ejecución paralela de herramientas en todos los modelos con prompting dirigido:
Uso paralelo de herramientas con Claude Sonnet 3.7
Claude Sonnet 3.7 puede ser menos propenso a hacer llamadas de herramientas paralelas en una respuesta, incluso cuando no has configurado disable_parallel_tool_use
. Para solucionar esto, recomendamos habilitar uso eficiente de herramientas en tokens, que ayuda a fomentar que Claude use herramientas paralelas. Esta característica beta también reduce la latencia y ahorra un promedio de 14% en tokens de salida.
Si prefieres no optar por la beta de uso eficiente de herramientas en tokens, también puedes introducir una “herramienta por lotes” que puede actuar como una meta-herramienta para envolver invocaciones a otras herramientas simultáneamente. Encontramos que si esta herramienta está presente, el modelo la usará para llamar simultáneamente múltiples herramientas en paralelo para ti.
Ve este ejemplo en nuestro cookbook para cómo usar esta solución alternativa.
Manejar bloques de contenido de uso de herramientas y resultado de herramientas
La respuesta de Claude difiere según si usa una herramienta del cliente o del servidor.
Manejar resultados de herramientas del cliente
La respuesta tendrá un stop_reason
de tool_use
y uno o más bloques de contenido tool_use
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 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 alinput_schema
de la herramienta.
Cuando recibes una respuesta de uso de herramienta para una herramienta del cliente, debes:
- Extraer el
name
,id
einput
del bloquetool_use
. - Ejecutar la herramienta real en tu código base correspondiente a ese nombre de herramienta, pasando el
input
de la herramienta. - Continuar la conversación enviando un nuevo mensaje con el
role
deuser
, y un bloquecontent
que contenga el tipotool_result
y la siguiente información:tool_use_id
: Elid
de la solicitud de uso de herramienta para la cual este es un resultado.content
: El resultado de la herramienta, como una cadena (ej."content": "15 grados"
) o lista de bloques de contenido anidados (ej."content": [{"type": "text", "text": "15 grados"}]
). Estos bloques de contenido pueden usar los tipostext
oimage
.is_error
(opcional): Configurar entrue
si la ejecución de la herramienta resultó en un error.
Requisitos importantes de formato:
- Los bloques de resultado de herramientas deben seguir inmediatamente a sus bloques de uso de herramientas correspondientes en el historial de mensajes. No puedes incluir ningún mensaje entre el mensaje de uso de herramienta del asistente y el mensaje de resultado de herramienta del usuario.
- En el mensaje del usuario que contiene resultados de herramientas, los bloques tool_result deben venir PRIMERO en el array de contenido. Cualquier texto debe venir DESPUÉS de todos los resultados de herramientas.
Por ejemplo, esto causará un error 400:
Esto es correcto:
Si recibes un error como “se encontraron IDs de tool_use sin bloques tool_result inmediatamente después”, verifica que tus resultados de herramientas estén formateados correctamente.
Después de recibir el resultado de la herramienta, Claude usará esa información para continuar generando una respuesta al prompt original del usuario.
Manejar resultados de herramientas del servidor
Claude ejecuta la herramienta internamente e incorpora los resultados directamente en su respuesta sin requerir interacción adicional del usuario.
Diferencias de otras APIs
A diferencia de las APIs 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 user
y assistant
.
Los mensajes contienen arrays de bloques text
, image
, tool_use
y tool_result
. Los mensajes user
incluyen contenido del cliente y tool_result
, mientras que los mensajes assistant
contienen contenido generado por IA y tool_use
.
Manejar la razón de parada max_tokens
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, necesitarás reintentar la solicitud con un valor de max_tokens
más alto para obtener el uso completo de la herramienta.
Manejar la razón de parada pause_turn
Al usar herramientas del servidor como búsqueda web, la API puede devolver una razón de parada pause_turn
, indicando que la API ha pausado un turno de larga duración.
Aquí está cómo manejar la razón de parada pause_turn
:
Al manejar pause_turn
:
- Continúa la conversación: Pasa la respuesta pausada tal como está en una solicitud subsecuente para permitir que Claude continúe su turno
- Modifica si es necesario: Opcionalmente puedes modificar el contenido antes de continuar si quieres interrumpir o redirigir la conversación
- Preserva el estado de la herramienta: Incluye las mismas herramientas en la solicitud de continuación para mantener la funcionalidad
Solucionar errores
Hay algunos tipos diferentes de errores que pueden ocurrir al usar herramientas con Claude: