Cómo implementar el uso de herramientas

Elegir un modelo

En general, usa Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (obsoleto) o Claude Opus 3 (obsoleto) 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.

Ejemplo de definición de herramienta simple

JSON

{
  "name": "get_weather",
  "description": "Obtener el clima actual en una ubicación dada",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "La ciudad y estado, ej. 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”.

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:

En este entorno tienes acceso a un conjunto de herramientas que puedes usar para responder la pregunta del usuario.
{{ INSTRUCCIONES DE FORMATO }}
Los parámetros de cadena y escalares deben especificarse tal como están, mientras que las listas y objetos deben usar formato JSON. Ten en cuenta que los espacios para valores de cadena no se eliminan. La salida no se espera que sea XML válido y se analiza con expresiones regulares.
Aquí están las funciones disponibles en formato JSONSchema:
{{ DEFINICIONES DE HERRAMIENTAS EN JSON SCHEMA }}
{{ PROMPT DEL SISTEMA DEL USUARIO }}
{{ CONFIGURACIÓN DE HERRAMIENTAS }}

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 debe usarse)
  • 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 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 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.

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 ticker dado. El símbolo ticker debe ser un símbolo válido para una empresa que cotiza públicamente en una bolsa de valores importante de EE.UU. como NYSE o NASDAQ. La herramienta devolverá el precio de la última transacción en USD. Debe usarse cuando el usuario pregunte 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 empresa.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "El símbolo ticker de la acción, ej. AAPL para Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Ejemplo de descripción pobre de herramienta

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 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, puedes querer 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í:

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 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 particular.
• tool nos permite forzar a Claude a usar siempre una herramienta particular.
• none evita que Claude use cualquier herramienta. Este es el valor predeterminado cuando no se proporcionan tools.

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, prellenaremos 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 quisieras mantener la cadena de pensamiento (particularmente con Opus) mientras aún solicitas 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 descomponer el problema y decidir qué herramientas usar. El modelo Claude Opus 3 (obsoleto) 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:

JSON

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Para responder esta pregunta, haré: 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."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Esta cadena de pensamiento da una visión del proceso de razonamiento de Claude y puede ayudarte a depurar comportamientos inesperados.

Es importante notar que Claude puede usar varios formatos para denotar su cadena de pensamiento. Tu código debe tratar la cadena de pensamiento 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:

• 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

Ejemplo completo de uso paralelo de herramientas

Aquí hay un ejemplo completo que muestra cómo formatear correctamente las llamadas de herramientas paralelas en el historial de mensajes:

Python

import anthropic

client = anthropic.Anthropic()

# Definir herramientas
tools = [
    {
        "name": "get_weather",
        "description": "Obtener el clima actual en una ubicación dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ciudad y estado, ej. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obtener la hora actual en una zona horaria dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "La zona horaria, ej. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Solicitud inicial
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "¿Cómo está el clima en SF y NYC, y qué hora es allí?"
        }
    ]
)

# Respuesta de Claude con llamadas de herramientas paralelas
print("Claude quiere usar herramientas:", response.stop_reason == "tool_use")
print("Número de llamadas de herramientas:", len([c for c in response.content if c.type == "tool_use"]))

# Construir la conversación con resultados de herramientas
messages = [
    {
        "role": "user",
        "content": "¿Cómo está el clima en SF y NYC, y qué hora es allí?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contiene múltiples bloques tool_use
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Debe coincidir con el ID de tool_use
                "content": "San Francisco: 68°F, parcialmente nublado"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "Nueva York: 45°F, cielos despejados"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "Hora de San Francisco: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "Hora de Nueva York: 5:30 PM EST"
            }
        ]
    }
]

# Obtener respuesta final
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

El mensaje del asistente con llamadas de herramientas paralelas se vería así:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Verificaré el clima y la hora tanto para San Francisco como para la Ciudad de Nueva York."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

Script de prueba completo para herramientas paralelas

Aquí hay un script completo y ejecutable para probar y verificar que las llamadas de herramientas paralelas funcionen correctamente:

Python

#!/usr/bin/env python3
"""Script de prueba para verificar llamadas de herramientas paralelas con la API de Anthropic"""

import os
from anthropic import Anthropic

# Inicializar cliente
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Definir herramientas
tools = [
    {
        "name": "get_weather",
        "description": "Obtener el clima actual en una ubicación dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "La ciudad y estado, ej. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Obtener la hora actual en una zona horaria dada",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "La zona horaria, ej. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Conversación de prueba con llamadas de herramientas paralelas
messages = [
    {
        "role": "user",
        "content": "¿Cómo está el clima en SF y NYC, y qué hora es allí?"
    }
]

# Hacer solicitud inicial
print("Solicitando llamadas de herramientas paralelas...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Verificar llamadas de herramientas paralelas
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude hizo {len(tool_uses)} llamadas de herramientas")

if len(tool_uses) > 1:
    print("✓ ¡Llamadas de herramientas paralelas detectadas!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No se detectaron llamadas de herramientas paralelas")

# Simular ejecución de herramientas y formatear resultados correctamente
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, parcialmente nublado"
        else:
            result = "Nueva York: 45°F, cielos despejados"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continuar conversación con resultados de herramientas
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # ¡Todos los resultados en un mensaje!
])

# Obtener respuesta final
print("\nObteniendo respuesta final...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nRespuesta de Claude:\n{final_response.content[0].text}")

# Verificar formato
print("\n--- Verificación ---")
print(f"✓ Resultados de herramientas enviados en un solo mensaje de usuario: {len(tool_results)} resultados")
print("✓ Sin texto antes de los resultados de herramientas en el array de contenido")
print("✓ Conversación formateada correctamente para uso futuro de herramientas paralelas")

Este script demuestra:

• Cómo formatear correctamente las llamadas y resultados de herramientas paralelas
• Cómo verificar que se estén haciendo llamadas paralelas
• La estructura de mensaje correcta que fomenta el uso futuro de herramientas paralelas
• Errores comunes a evitar (como texto antes de los resultados de herramientas)

Ejecuta este script para probar tu implementación y asegurar que Claude esté haciendo llamadas de herramientas paralelas efectivamente.

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:

Prompts del sistema para uso paralelo de herramientas

Para los modelos Claude 4 (Opus 4.1, Opus 4 y Sonnet 4), agrega esto a tu prompt del sistema:

Para máxima eficiencia, siempre que necesites realizar múltiples operaciones independientes, invoca todas las herramientas relevantes simultáneamente en lugar de secuencialmente.

Para un uso de herramientas paralelas aún más fuerte (recomendado si el predeterminado no es suficiente), usa:

<use_parallel_tool_calls>
Para máxima eficiencia, siempre que realices múltiples operaciones independientes, invoca todas las herramientas relevantes simultáneamente en lugar de secuencialmente. Prioriza llamar herramientas en paralelo siempre que sea posible. Por ejemplo, al leer 3 archivos, ejecuta 3 llamadas de herramientas en paralelo para leer los 3 archivos en contexto al mismo tiempo. Al ejecutar múltiples comandos de solo lectura como `ls` o `list_dir`, siempre ejecuta todos los comandos en paralelo. Inclínate hacia maximizar las llamadas de herramientas paralelas en lugar de ejecutar demasiadas herramientas secuencialmente.
</use_parallel_tool_calls>

Prompting de mensajes de usuario

También puedes fomentar el uso paralelo de herramientas dentro de mensajes de usuario específicos:

# En lugar de:
"¿Cómo está el clima en París? También verifica Londres."

# Usa:
"Verifica el clima en París y Londres simultáneamente."

# O sé explícito:
"Por favor usa llamadas de herramientas paralelas para obtener el clima de París, Londres y Tokio al mismo tiempo."

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 función 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 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 resultados 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 particular de uso de herramienta. 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 al input_schema de la herramienta.

Ejemplo de respuesta de API con un bloque de contenido `tool_use`

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Necesito usar get_weather, y el usuario quiere SF, que probablemente sea San Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

1. Extraer el name, id e input del bloque tool_use.
2. Ejecutar la herramienta real en tu código base 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 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 cual este es un resultado.
   • content: El resultado de la herramienta, como una cadena (ej. "content": "15 grados"), una lista de bloques de contenido anidados (ej. "content": [{"type": "text", "text": "15 grados"}]), o una lista de bloques de documento (ej. "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 grados"}]). Estos bloques de contenido pueden usar los tipos text, image o document.
   • is_error (opcional): Configurar en true si la ejecución de la herramienta resultó en un error.

Requisitos importantes de formato:

• 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 el array de contenido. Cualquier texto debe venir DESPUÉS de todos los resultados de herramientas.

Por ejemplo, esto causará un error 400:

{"role": "user", "content": [
  {"type": "text", "text": "Aquí están los resultados:"},  // ❌ Texto antes de tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Esto es correcto:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "¿Qué debo hacer después?"}  // ✅ Texto después de tool_result
]}

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.

Ejemplo de resultado de herramienta exitoso

JSON

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

Ejemplo de resultado de herramienta con imágenes

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

Ejemplo de resultado de herramienta vacío

JSON

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

Ejemplo de resultado de herramienta con documentos

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "El clima es"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 grados"
          }
        }
      ]
    }
  ]
}

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.

Python

# Verificar si la respuesta fue truncada durante el uso de herramientas
if response.stop_reason == "max_tokens":
    # Verificar si el último bloque de contenido es un tool_use incompleto
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Enviar la solicitud con max_tokens más alto
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # Límite aumentado
            messages=messages,
            tools=tools
        )

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:

Python

import anthropic

client = anthropic.Anthropic()

# Solicitud inicial con búsqueda web
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Busca información completa sobre avances en computación cuántica en 2025"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# Verificar si la respuesta tiene razón de parada pause_turn
if response.stop_reason == "pause_turn":
    # Continuar la conversación con el contenido pausado
    messages = [
        {"role": "user", "content": "Busca información completa sobre avances en computación cuántica en 2025"},
        {"role": "assistant", "content": response.content}
    ]
    
    # Enviar la solicitud de continuación
    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:

• 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 quieres interrumpir o redirigir la conversación
• **Preserva el estado de la herrami

enta**: 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:

Error de ejecución de herramienta

Si la herramienta misma arroja un error durante la ejecución (ej. un error de red al obtener datos del clima), puedes 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: la API del servicio meteorológico no está disponible (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude entonces incorporará este error en su respuesta al usuario, ej. “Lo siento, no pude recuperar el clima actual porque la API del servicio meteorológico no está disponible. Por favor intenta de nuevo más tarde.”

Nombre de herramienta inválido

Si el intento de uso de una herramienta por parte de Claude es inválido (ej. parámetros requeridos faltantes), usualmente significa que no había suficiente información para que Claude use la herramienta correctamente. Tu mejor opción durante el desarrollo es intentar la solicitud de nuevo con valores de 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:

JSON

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

Si una solicitud de herramienta es inválida o le faltan parámetros, Claude reintentará 2-3 veces con correcciones antes de disculparse con el usuario.

Etiquetas <search_quality_reflection>

Para evitar que Claude reflexione sobre la calidad de búsqueda con etiquetas <search_quality_reflection>, agrega “No reflexiones sobre la calidad de los resultados de búsqueda devueltos en tu respuesta” a tu prompt.

Errores de herramientas del servidor

Cuando las herramientas del servidor encuentran errores (ej. problemas de red con Búsqueda Web), Claude manejará transparentemente estos errores e intentará proporcionar una respuesta alternativa o explicación al usuario. A diferencia de las herramientas del cliente, no necesitas manejar resultados 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 excedido
• invalid_input: Parámetro de consulta de búsqueda inválido
• max_uses_exceeded: Usos máximos de herramienta de búsqueda web excedidos
• query_too_long: La consulta excede la longitud máxima
• unavailable: Ocurrió un error interno

Las llamadas de herramientas paralelas no funcionan

Si Claude no está haciendo llamadas de herramientas paralelas cuando se espera, verifica estos problemas comunes:

1. Formato incorrecto de resultados de herramientas

El problema más común es formatear incorrectamente los resultados de herramientas en el historial de conversación. Esto “enseña” a Claude a evitar llamadas paralelas.

Específicamente para uso paralelo de herramientas:

• ❌ Incorrecto: Enviar mensajes de usuario separados para cada resultado de herramienta
• ✅ Correcto: Todos los resultados de herramientas deben estar en un solo mensaje de usuario

// ❌ Esto reduce el uso de herramientas paralelas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Mensaje separado
]

// ✅ Esto mantiene el uso de herramientas paralelas
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Un solo mensaje
]

Ve los requisitos generales de formato arriba para otras reglas de formato.

2. Prompting débil

El prompting predeterminado puede no ser suficiente. Usa lenguaje más fuerte:

<use_parallel_tool_calls>
Para máxima eficiencia, siempre que realices múltiples operaciones independientes, 
invoca todas las herramientas relevantes simultáneamente en lugar de secuencialmente. 
Prioriza llamar herramientas en paralelo siempre que sea posible.
</use_parallel_tool_calls>

3. Medir el uso de herramientas paralelas

Para verificar que las llamadas de herramientas paralelas funcionen:

# Calcular promedio de herramientas por mensaje que llama herramientas
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Promedio de herramientas por mensaje: {avg_tools_per_message}")
# Debería ser > 1.0 si las llamadas paralelas funcionan

4. Comportamiento específico del modelo

• Claude Opus 4.1, Opus 4 y Sonnet 4: Excelentes en uso paralelo de herramientas con prompting mínimo
• Claude Sonnet 3.7: Puede necesitar prompting más fuerte o uso eficiente de herramientas en tokens
• Claude Haiku: Menos propenso a usar herramientas paralelas sin prompting explícito