Elegir un modelo
Recomendamos usar el último modelo Claude Sonnet (4.5) o Claude Opus (4.1) para herramientas complejas y consultas ambiguas; manejan múltiples herramientas mejor y buscan aclaraciones cuando es necesario. Usa modelos Claude Haiku para herramientas directas, pero ten en cuenta que pueden inferir parámetros faltantes.Especificar herramientas del cliente
Las herramientas del cliente (tanto definidas por Anthropic como definidas por el usuario) se especifican en el parámetro de nivel superiortools 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 qué 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. |
Ejemplo de definición de herramienta simple
Ejemplo de definición de herramienta simple
get_weather, espera un objeto de entrada con una cadena location requerida y una cadena unit opcional que debe ser “celsius” o “fahrenheit”.Indicación del sistema de uso de herramientas
Cuando llamas a la API de Claude con el parámetrotools, construimos un indicador del sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier indicador del sistema especificado por el usuario. El indicador construido está diseñado para instruir al modelo para usar las herramientas especificadas y proporcionar el contexto necesario para que la herramienta funcione correctamente:
Mejores prácticas para definiciones de herramientas
Para obtener el mejor rendimiento de Claude al usar herramientas, sigue estas directrices:- Proporciona descripciones extremadamente detalladas. Este es, con mucho, el factor más importante en el rendimiento de la herramienta. 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 la herramienta no devuelve si el nombre de la herramienta no es claro. Cuanto más contexto puedas dar 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 descripciones sobre ejemplos. Aunque puedes incluir ejemplos de cómo usar una herramienta en su descripción o en el indicador adjunto, 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.
Ejemplo de una buena descripción de herramienta
Ejemplo de una buena descripción de herramienta
Ejemplo de descripción de herramienta deficiente
Ejemplo de descripción de herramienta deficiente
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.
Ejecutor de herramientas (beta)
El ejecutor de herramientas proporciona una solución lista para usar para ejecutar herramientas con Claude. En lugar de manejar manualmente llamadas de herramientas, resultados de herramientas y gestión de conversación, el ejecutor de herramientas automáticamente:- Ejecuta herramientas cuando Claude las llama
- Maneja el ciclo de solicitud/respuesta
- Gestiona el estado de la conversación
- Proporciona seguridad de tipos y validación
Uso básico
@beta_tool para definir herramientas y client.beta.messages.tool_runner() para ejecutarlas.@beta_tool con @beta_async_tool y define la función con async def.@beta_tool inspeccionará los argumentos de la función y la cadena de documentación para extraer una representación de esquema json de la función dada, en el ejemplo anterior calculate_sum se convertirá en: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 cree que puede proporcionar una respuesta sin usar una herramienta. Puedes hacer esto especificando la herramienta en el campotool_choice así:
autopermite que Claude decida si llamar a cualquiera de las herramientas proporcionadas o no. Este es el valor predeterminado cuando se proporcionantools.anyle dice a Claude que debe usar una de las herramientas proporcionadas, pero no fuerza una herramienta en particular.toolnos permite forzar a Claude a usar siempre una herramienta en particular.noneevita que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionantools.
tool_choice invalidarán los bloques de mensajes en caché. Las definiciones de herramientas y los indicadores del sistema permanecen en caché, pero el contenido del mensaje debe reprocesarse.
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 una respuesta en lenguaje natural o explicación antes de los bloques de contenido tool_use, incluso si se les pide explícitamente que lo hagan.
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 pensamiento extendido.{"type": "auto"} para tool_choice (el predeterminado) y agregar instrucciones explícitas en un mensaje user. Por ejemplo: ¿Cuál es 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 desees que el modelo devuelva una salida JSON que siga un esquema proporcionado. Por ejemplo, podrías usar una herramientarecord_summary con un esquema particular. Consulta Uso de herramientas con Claude para un ejemplo completo de trabajo.
Respuestas del modelo con herramientas
Al usar herramientas, Claude a menudo comentará sobre lo que está haciendo o responderá naturalmente al usuario antes de invocar herramientas. Por ejemplo, dada la indicación “¿Cuál es el clima en San Francisco ahora mismo y qué hora es allí?”, Claude podría responder con:<examples> en tus indicadores.
Es importante notar que Claude puede usar varias frases y enfoques al explicar sus acciones. Tu código debe tratar estas respuestas como cualquier otro texto generado por el asistente, y no depender de convenciones de formato específicas.
Uso paralelo de herramientas
Por defecto, Claude puede usar múltiples herramientas para responder una consulta del usuario. Puedes deshabilitar este comportamiento por:- Establecer
disable_parallel_tool_use=truecuando el tipo de tool_choice esauto, lo que asegura que Claude use como máximo una herramienta - Establecer
disable_parallel_tool_use=truecuando el tipo de tool_choice esanyotool, lo que asegura que Claude use exactamente una herramienta
Ejemplo completo de uso paralelo de herramientas
Ejemplo completo de uso paralelo de herramientas
Script de prueba completo para herramientas paralelas
Script de prueba completo para herramientas paralelas
- Cómo formatear correctamente llamadas de herramientas paralelas y resultados
- Cómo verificar que se están realizando llamadas paralelas
- La estructura de mensaje correcta que fomenta el uso futuro de herramientas paralelas
- Errores comunes a evitar (como texto antes de resultados de herramientas)
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 indicaciones dirigidas:Indicadores del sistema para uso paralelo de herramientas
Indicadores del sistema para uso paralelo de herramientas
Indicación de mensaje de usuario
Indicación de mensaje de usuario
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 del 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 de lote” que pueda 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 a múltiples herramientas en paralelo para ti.Consulta este ejemplo en nuestro libro de recetas para cómo usar esta solución alternativa.Manejo de bloques de contenido de uso de herramientas y resultado de herramientas
Manejo de resultados de herramientas del cliente
La respuesta tendrá unstop_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_schemade la herramienta.
Ejemplo de respuesta de API con un bloque de contenido `tool_use`
Ejemplo de respuesta de API con un bloque de contenido `tool_use`
- Extraer el
name,ideinputdel bloquetool_use. - Ejecutar la herramienta real en tu base de código correspondiente a ese nombre de herramienta, pasando la
inputde la herramienta. - Continuar la conversación enviando un nuevo mensaje con el
roledeuser, y un bloque decontentque contenga el tipotool_resulty la siguiente información:tool_use_id: Elidde la solicitud de uso de herramienta para la que este es un resultado.content: El resultado de la herramienta, como una cadena (p. ej."content": "15 degrees"), una lista de bloques de contenido anidados (p. ej."content": [{"type": "text", "text": "15 degrees"}]), o una lista de bloques de documentos (p. ej."content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Estos bloques de contenido pueden usar los tipostext,imageodocument.is_error(opcional): Establece entruesi la ejecución de la herramienta resultó en un error.
- Los bloques de resultado de herramienta deben seguir inmediatamente a sus bloques de uso de herramienta 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 la matriz de contenido. Cualquier texto debe venir DESPUÉS de todos los resultados de herramientas.
Ejemplo de resultado de herramienta exitoso
Ejemplo de resultado de herramienta exitoso
Ejemplo de resultado de herramienta con imágenes
Ejemplo de resultado de herramienta con imágenes
Ejemplo de resultado de herramienta vacío
Ejemplo de resultado de herramienta vacío
Ejemplo de resultado de herramienta con documentos
Ejemplo de resultado de herramienta con documentos
Manejo de 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.tool o function, la API de Claude integra herramientas directamente en la estructura de mensajes user y assistant.Los mensajes contienen matrices 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.Manejo de la razón de parada max_tokens
Si la respuesta de Claude se corta debido a alcanzar el límite max_tokens, y la respuesta truncada contiene un bloque de uso de herramienta incompleto, deberás reintentar la solicitud con un valor max_tokens más alto para obtener el uso de herramienta completo.
Manejo de la razón de parada pause_turn
Cuando se usan 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í se explica cómo manejar la razón de parada pause_turn:
pause_turn:
- Continúa la conversación: Pasa la respuesta pausada tal como está en una solicitud posterior para permitir que Claude continúe su turno
- Modifica si es necesario: Opcionalmente puedes modificar el contenido antes de continuar si deseas 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
Solución de problemas de errores
Error de ejecución de herramienta
Error de ejecución de herramienta
content junto con "is_error": true:Nombre de herramienta inválido
Nombre de herramienta inválido
description más detallados en tus definiciones de herramientas.Sin embargo, también puedes continuar la conversación hacia adelante con un tool_result que indique el error, y Claude intentará usar la herramienta de nuevo con la información faltante completada:Etiquetas <search_quality_reflection>
Etiquetas <search_quality_reflection>
Errores de herramientas del servidor
Errores de herramientas del servidor
is_error para herramientas del servidor.Para búsqueda web específicamente, los códigos de error posibles incluyen:too_many_requests: Límite de velocidad excedidoinvalid_input: Parámetro de consulta de búsqueda inválidomax_uses_exceeded: Máximo de usos de herramienta de búsqueda web excedidoquery_too_long: La consulta excede la longitud máximaunavailable: Ocurrió un error interno
Las llamadas de herramientas paralelas no funcionan
Las llamadas de herramientas paralelas no funcionan
- ❌ Incorrecto: Enviar mensajes de usuario separados para cada resultado de herramienta
- ✅ Correcto: Todos los resultados de herramientas deben estar en un único mensaje de usuario
- Claude Opus 4.1, Opus 4 y Sonnet 4: Excelentes en uso paralelo de herramientas con indicación mínima
- Claude Sonnet 3.7: Puede necesitar indicación más fuerte o uso eficiente de herramientas en tokens
- Claude Haiku: Menos probable que use herramientas paralelas sin indicación explícita