Cómo implementar el uso de herramientas

​

Elegir un modelo

Generalmente, utiliza 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 aclaraciones cuando es necesario.

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

​

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 API. Cada definición de herramienta incluye:

​

Prompt del sistema para uso de herramientas

Cuando llamas a la API de Anthropic con el parámetro tools, construimos un prompt de sistema especial a partir de las definiciones de herramientas, la configuración de herramientas y cualquier prompt de sistema especificado por el usuario. El prompt construido está diseñado para instruir al modelo a usar la(s) herramienta(s) especificada(s) 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, con diferencia, 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. Intenta incluir 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 los parámetros de la herramienta. Solo añade 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 uso de la herramienta.

​

Controlando 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 a 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 campo tool_choice de la siguiente manera:

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

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

• auto permite a Claude decidir si llamar a cualquiera de las herramientas proporcionadas o no. Este es el valor predeterminado cuando se proporcionan tools.
• 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.
• none impide que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionan tools.

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

Ten en cuenta que cuando tienes tool_choice como any o tool, prerellenaremos 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 sigues solicitando 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: ¿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 cliente; puedes usar herramientas siempre que quieras 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 Opus 3 hará esto si tool_choice está configurado como auto (este es el valor predeterminado, consulta 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:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers 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 Sonnet 3, la cadena de pensamiento es menos común por defecto, pero puedes indicarle a Claude que muestre su razonamiento agregando algo como "Antes de responder, explica tu razonamiento paso a paso en etiquetas." al mensaje del usuario o al prompt 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>.

​

Uso de herramientas en paralelo

Por defecto, Claude puede usar múltiples herramientas para responder a una consulta del usuario. Puedes desactivar este comportamiento mediante:

• Configurando disable_parallel_tool_use=true cuando el tipo de tool_choice es auto, lo que asegura que Claude use como máximo una herramienta
• Configurando disable_parallel_tool_use=true cuando el tipo de tool_choice es any o tool, lo que asegura que Claude use exactamente una herramienta

​

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

La respuesta de Claude difiere según si utiliza una herramienta de cliente o de servidor.

​

Manejo de resultados de herramientas de 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 particular de uso de herramienta. Se utilizará 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, conforme al input_schema de la herramienta.

Cuando recibes una respuesta de uso de herramienta para una herramienta de cliente, debes:

1. Extraer el name, id e input del bloque tool_use.
2. Ejecutar la herramienta real en tu código 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 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): Establecido como true si la ejecución de la herramienta resultó en un error.

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

​

Manejo de resultados de herramientas de servidor

Claude ejecuta la herramienta internamente e incorpora los resultados directamente en su respuesta sin requerir interacción adicional del usuario.

​

Manejo de la razón de parada pause_turn

Al usar herramientas de servidor como la 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.

Así es como manejar la razón de parada pause_turn:

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {"role": "user", "content": "Search for comprehensive information about quantum computing breakthroughs in 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Send the continuation request
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

Al manejar pause_turn:

• Continuar la conversación: Pasa la respuesta pausada tal cual en una solicitud posterior para permitir que Claude continúe su turno
• Modificar si es necesario: Opcionalmente puedes modificar el contenido antes de continuar si deseas interrumpir o redirigir la conversación
• Preservar el estado de la herramienta: Incluye las mismas herramientas en la solicitud de continuación para mantener la funcionalidad

​

Solución de problemas y errores

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