Llamadas a herramientas programáticas

Las llamadas a herramientas programáticas permiten que Claude escriba código que invoca tus herramientas de forma programática dentro de un contenedor de ejecución de código, en lugar de requerir viajes de ida y vuelta a través del modelo para cada invocación de herramienta. Esto reduce la latencia en flujos de trabajo con múltiples herramientas y disminuye el consumo de tokens al permitir que Claude filtre o procese datos antes de que lleguen a la ventana de contexto del modelo. En benchmarks de búsqueda agéntica como BrowseComp y DeepSearchQA, que prueban la investigación web de múltiples pasos y la recuperación de información compleja, agregar llamadas a herramientas programáticas sobre las herramientas de búsqueda básicas fue el factor clave que desbloqueó completamente el rendimiento del agente.

La diferencia se amplifica rápidamente en flujos de trabajo reales. Considera verificar el cumplimiento del presupuesto en 20 empleados: el enfoque tradicional requiere 20 viajes de ida y vuelta al modelo por separado, extrayendo miles de líneas de gastos al contexto en el camino. Con las llamadas a herramientas programáticas, un único script ejecuta las 20 consultas, filtra los resultados y devuelve solo los empleados que superaron sus límites, reduciendo lo que Claude necesita razonar de cientos de kilobytes a unas pocas líneas.

Compatibilidad de modelos

Para detalles de compatibilidad de modelos y versiones de herramientas, consulta la referencia de herramientas. Las llamadas a herramientas programáticas están disponibles a través de la API de Claude y Microsoft Foundry.

Inicio rápido

Aquí hay un ejemplo simple donde Claude consulta programáticamente una base de datos varias veces y agrega resultados:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
            }
        ],
        "tools": [
            {
                "type": "code_execution_20260120",
                "name": "code_execution"
            },
            {
                "name": "query_database",
                "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
                "input_schema": {
                    "type": "object",
                    "properties": {
                        "sql": {
                            "type": "string",
                            "description": "SQL query to execute"
                        }
                    },
                    "required": ["sql"]
                },
                "allowed_callers": ["code_execution_20260120"]
            }
        ]
    }'

Cómo funcionan las llamadas a herramientas programáticas

Cuando configuras una herramienta para que sea invocable desde la ejecución de código y Claude decide usar esa herramienta:

1. Claude escribe código Python que invoca la herramienta como una función, potencialmente incluyendo múltiples llamadas a herramientas y lógica de pre/post-procesamiento
2. Claude ejecuta este código en un contenedor aislado mediante la ejecución de código
3. Cuando se llama a una función de herramienta, la ejecución de código se pausa y la API devuelve un bloque tool_use
4. Proporcionas el resultado de la herramienta y la ejecución de código continúa (los resultados intermedios no se cargan en la ventana de contexto de Claude)
5. Una vez que se completa toda la ejecución de código, Claude recibe la salida final y continúa trabajando en la tarea

Este enfoque es particularmente útil para:

• Procesamiento de grandes volúmenes de datos: Filtra o agrega resultados de herramientas antes de que lleguen al contexto de Claude
• Flujos de trabajo de múltiples pasos: Ahorra tokens y latencia llamando a herramientas en serie o en un bucle sin muestrear a Claude entre llamadas a herramientas
• Lógica condicional: Toma decisiones basadas en resultados intermedios de herramientas

Conceptos fundamentales

El campo allowed_callers

El campo allowed_callers especifica qué contextos pueden invocar una herramienta:

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

Valores posibles:

• ["direct"] - Solo Claude puede llamar a esta herramienta directamente (valor predeterminado si se omite)
• ["code_execution_20260120"] - Solo se puede llamar desde dentro de la ejecución de código
• ["direct", "code_execution_20260120"] - Se puede llamar tanto directamente como desde la ejecución de código

El campo caller en las respuestas

Cada bloque de uso de herramienta incluye un campo caller que indica cómo fue invocado:

Invocación directa (uso tradicional de herramientas):

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

Invocación programática:

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

El tool_id hace referencia a la herramienta de ejecución de código que realizó la llamada programática.

Ciclo de vida del contenedor

Las llamadas a herramientas programáticas utilizan los mismos contenedores que la ejecución de código:

• Creación del contenedor: Se crea un nuevo contenedor para cada sesión a menos que reutilices uno existente
• Expiración: Los contenedores tienen una vida máxima de 30 días y se limpian después de 4,5 minutos de tiempo de inactividad
• ID del contenedor: Se devuelve en las respuestas a través del campo container
• Reutilización: Pasa el ID del contenedor para mantener el estado entre solicitudes

Flujo de trabajo de ejemplo

Así es como funciona un flujo completo de llamadas a herramientas programáticas:

Paso 1: Solicitud inicial

Envía una solicitud con ejecución de código y una herramienta que permita llamadas programáticas. Para habilitar las llamadas programáticas, agrega el campo allowed_callers a la definición de tu herramienta.

La forma de la solicitud es idéntica al ejemplo de Inicio rápido: incluye code_execution en tu lista de herramientas, agrega allowed_callers: ["code_execution_20260120"] a cualquier herramienta que quieras que Claude invoque desde el código, y envía tu mensaje de usuario.

Paso 2: Respuesta de la API con llamada a herramienta

Claude escribe código que llama a tu herramienta. La API se pausa y devuelve:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Paso 3: Proporcionar el resultado de la herramienta

Incluye el historial completo de la conversación más el resultado de tu herramienta:

ant messages create <<'YAML'
model: claude-opus-4-6
max_tokens: 4096
container: container_xyz789
messages:
  - role: user
    content: >-
      Query customer purchase history from the last quarter and identify our
      top 5 customers by revenue
  - role: assistant
    content:
      - type: text
        text: I'll query the purchase history and analyze the results.
      - type: server_tool_use
        id: srvtoolu_abc123
        name: code_execution
        input:
          code: "..."
      - type: tool_use
        id: toolu_def456
        name: query_database
        input:
          sql: "<sql>"
        caller:
          type: code_execution_20260120
          tool_id: srvtoolu_abc123
  - role: user
    content:
      - type: tool_result
        tool_use_id: toolu_def456
        content: >-
          [{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2",
          "revenue": 38000}, ...]
tools: [...]
YAML

Paso 4: Siguiente llamada a herramienta o finalización

La ejecución de código continúa y procesa los resultados. Si se necesitan llamadas a herramientas adicionales, repite el Paso 3 hasta que todas las llamadas a herramientas estén satisfechas.

Paso 5: Respuesta final

Una vez que la ejecución de código se completa, Claude proporciona la respuesta final:

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

Patrones avanzados

Procesamiento por lotes con bucles

Claude puede escribir código que procese múltiples elementos de manera eficiente:

async def _claude_code():
    regions = ["West", "East", "Central", "North", "South"]
    results = {}
    for region in regions:
        data = await query_database(f"<sql for {region}>")
        results[region] = sum(row["revenue"] for row in data)

    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Este patrón:

• Reduce los viajes de ida y vuelta del modelo de N (uno por región) a 1
• Procesa grandes conjuntos de resultados de forma programática antes de devolver el control a Claude
• Ahorra tokens al devolver solo conclusiones agregadas en lugar de datos sin procesar

Terminación anticipada

Claude puede dejar de procesar tan pronto como se cumplan los criterios de éxito:

async def _claude_code():
    endpoints = ["us-east", "eu-west", "apac"]
    for endpoint in endpoints:
        status = await check_health(endpoint)
        if status == "healthy":
            print(f"Found healthy endpoint: {endpoint}")
            break  # Stop early, don't check remaining

Selección condicional de herramientas

async def _claude_code():
    file_info = await get_file_info(path)
    if file_info["size"] < 10000:
        content = await read_full_file(path)
    else:
        content = await read_file_summary(path)
    print(content)

Filtrado de datos

async def _claude_code():
    logs = await fetch_logs(server_id)
    errors = [log for log in logs if "ERROR" in log]
    print(f"Found {len(errors)} errors")
    for error in errors[-10:]:  # Only return last 10 errors
        print(error)

Formato de respuesta

Llamada programática a herramienta

Cuando la ejecución de código llama a una herramienta:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

Manejo del resultado de la herramienta

El resultado de tu herramienta se pasa de vuelta al código en ejecución:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

Finalización de la ejecución de código

Cuando todas las llamadas a herramientas están satisfechas y el código se completa:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

Manejo de errores

Errores comunes

Expiración del contenedor durante una llamada a herramienta

Si tu herramienta tarda demasiado en responder, la ejecución de código recibe un TimeoutError. Claude lo ve en stderr y normalmente reintenta:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
    "return_code": 0,
    "content": []
  }
}

Para prevenir tiempos de espera agotados:

• Monitorea el campo expires_at en las respuestas
• Implementa tiempos de espera para la ejecución de tu herramienta
• Considera dividir las operaciones largas en fragmentos más pequeños

Errores de ejecución de herramientas

Si tu herramienta devuelve un error:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

El código de Claude recibe este error y puede manejarlo de manera apropiada.

Restricciones y limitaciones

Incompatibilidades de características

• Salidas estructuradas: Las herramientas con strict: true no son compatibles con las llamadas programáticas
• Elección de herramienta: No puedes forzar la llamada programática de una herramienta específica mediante tool_choice
• Uso paralelo de herramientas: disable_parallel_tool_use: true no es compatible con las llamadas programáticas

Restricciones de herramientas

Las siguientes herramientas actualmente no pueden ser llamadas de forma programática, pero el soporte puede añadirse en versiones futuras:

• Herramientas proporcionadas por un conector MCP

Restricciones de formato de mensajes

Al responder a llamadas programáticas a herramientas, existen requisitos de formato estrictos:

Respuestas solo con resultado de herramienta: Si hay llamadas programáticas a herramientas pendientes esperando resultados, tu mensaje de respuesta debe contener únicamente bloques tool_result. No puedes incluir ningún contenido de texto, ni siquiera después de los resultados de las herramientas.

Inválido - No se puede incluir texto al responder a llamadas programáticas a herramientas:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Válido - Solo resultados de herramientas al responder a llamadas programáticas a herramientas:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Esta restricción solo aplica cuando se responde a llamadas programáticas (de ejecución de código) a herramientas. Para llamadas regulares a herramientas del lado del cliente, puedes incluir contenido de texto después de los resultados de las herramientas.

Límites de velocidad

Las llamadas programáticas a herramientas están sujetas a los mismos límites de velocidad que las llamadas regulares a herramientas. Cada llamada a herramienta desde la ejecución de código cuenta como una invocación separada.

Validar los resultados de las herramientas antes de usarlos

Al implementar herramientas definidas por el usuario que serán llamadas de forma programática:

• Los resultados de las herramientas se devuelven como cadenas de texto: Pueden contener cualquier contenido, incluidos fragmentos de código o comandos ejecutables que pueden ser procesados por el entorno de ejecución.
• Valida los resultados de herramientas externas: Si tu herramienta devuelve datos de fuentes externas o acepta entrada del usuario, ten en cuenta los riesgos de inyección de código si la salida será interpretada o ejecutada como código.

Eficiencia de tokens

Las llamadas programáticas a herramientas pueden reducir significativamente el consumo de tokens:

• Los resultados de herramientas de llamadas programáticas no se añaden al contexto de Claude - solo se añade la salida final del código
• El procesamiento intermedio ocurre en el código - el filtrado, la agregación, etc. no consumen tokens del modelo
• Múltiples llamadas a herramientas en una sola ejecución de código - reduce la sobrecarga en comparación con turnos de modelo separados

Por ejemplo, llamar a 10 herramientas directamente usa aproximadamente 10 veces más tokens que llamarlas de forma programática y devolver un resumen.

Uso y precios

Las llamadas programáticas a herramientas utilizan los mismos precios que la ejecución de código. Consulta los precios de ejecución de código para más detalles.

Mejores prácticas

Diseño de herramientas

• Proporciona descripciones detalladas de la salida: Dado que Claude deserializa los resultados de las herramientas en código, documenta claramente el formato (estructura JSON, tipos de campos, etc.)
• Devuelve datos estructurados: JSON u otros formatos fácilmente analizables funcionan mejor para el procesamiento programático
• Mantén las respuestas concisas: Devuelve solo los datos necesarios para minimizar la sobrecarga de procesamiento

Cuándo usar llamadas programáticas

Buenos casos de uso:

• Procesamiento de grandes conjuntos de datos donde solo necesitas agregados o resúmenes
• Flujos de trabajo de múltiples pasos con 3 o más llamadas a herramientas dependientes
• Operaciones que requieren filtrado, ordenamiento o transformación de resultados de herramientas
• Tareas donde los datos intermedios no deben influir en el razonamiento de Claude
• Operaciones paralelas sobre muchos elementos (p. ej., verificar 50 endpoints)

Casos de uso menos ideales:

• Llamadas únicas a herramientas con respuestas simples
• Herramientas que necesitan retroalimentación inmediata del usuario
• Operaciones muy rápidas donde la sobrecarga de la ejecución de código superaría el beneficio

Optimización del rendimiento

• Reutiliza los contenedores al realizar múltiples solicitudes relacionadas para mantener el estado
• Agrupa operaciones similares en una sola ejecución de código cuando sea posible

Solución de problemas

Problemas comunes

Error "Tool not allowed"

• Verifica que la definición de tu herramienta incluya "allowed_callers": ["code_execution_20260120"]

Expiración del contenedor

• Asegúrate de responder a las llamadas a herramientas antes de que el contenedor quede inactivo (4,5 minutos de inactividad; máximo absoluto de 30 días)
• Monitorea el campo expires_at en las respuestas
• Considera implementar una ejecución de herramientas más rápida

El resultado de la herramienta no se analiza correctamente

• Asegúrate de que tu herramienta devuelva datos en formato de cadena que Claude pueda deserializar
• Proporciona documentación clara del formato de salida en la descripción de tu herramienta

Consejos de depuración

1. Registra todas las llamadas a herramientas y sus resultados para rastrear el flujo
2. Verifica el campo caller para confirmar la invocación programática
3. Monitorea los IDs de contenedor para asegurar la reutilización correcta
4. Prueba las herramientas de forma independiente antes de habilitar las llamadas programáticas

Por qué funcionan las llamadas programáticas a herramientas

El entrenamiento de Claude incluye una exposición extensa al código, lo que lo hace efectivo para razonar y encadenar llamadas a funciones. Cuando las herramientas se presentan como funciones invocables dentro de un entorno de ejecución de código, Claude puede aprovechar esta fortaleza para:

• Razonar de forma natural sobre la composición de herramientas: Encadenar operaciones y manejar dependencias tan naturalmente como escribir cualquier código Python
• Procesar grandes resultados de manera eficiente: Filtrar grandes salidas de herramientas, extraer solo los datos relevantes o escribir resultados intermedios en archivos antes de devolver resúmenes a la ventana de contexto
• Reducir significativamente la latencia: Eliminar la sobrecarga de volver a muestrear Claude entre cada llamada a herramienta en flujos de trabajo de múltiples pasos

Este enfoque permite flujos de trabajo que serían impracticables con el uso tradicional de herramientas (como procesar archivos de más de 1 millón de tokens) al permitir que Claude trabaje con datos de forma programática en lugar de cargar todo en el contexto de la conversación.

Implementaciones alternativas

Las llamadas programáticas a herramientas son un patrón generalizable que puede implementarse fuera de la ejecución de código gestionada de Anthropic. Aquí hay una descripción general de los enfoques:

Ejecución directa del lado del cliente

Proporciona a Claude una herramienta de ejecución de código y describe qué funciones están disponibles en ese entorno. Cuando Claude invoca la herramienta con código, tu aplicación lo ejecuta localmente donde esas funciones están definidas.

Ventajas:

• Simple de implementar con una reestructuración mínima
• Control total sobre el entorno y las instrucciones

Desventajas:

• Ejecuta código no confiable fuera de un sandbox
• Las invocaciones de herramientas pueden ser vectores de inyección de código

Úsalo cuando: Tu aplicación puede ejecutar código arbitrario de forma segura, quieres una solución simple y la oferta gestionada de Anthropic no se adapta a tus necesidades.

Ejecución en sandbox autogestionada

El mismo enfoque desde la perspectiva de Claude, pero el código se ejecuta en un contenedor con sandbox con restricciones de seguridad (p. ej., sin salida de red). Si tus herramientas requieren recursos externos, necesitarás un protocolo para ejecutar llamadas a herramientas fuera del sandbox.

Ventajas:

• Llamadas programáticas a herramientas seguras en tu propia infraestructura
• Control total sobre el entorno de ejecución

Desventajas:

• Complejo de construir y mantener
• Requiere gestionar tanto la infraestructura como la comunicación entre procesos

Úsalo cuando: La seguridad es crítica y la solución gestionada de Anthropic no se adapta a tus requisitos.

Ejecución gestionada por Anthropic

Las llamadas programáticas a herramientas de Anthropic son una versión gestionada de la ejecución en sandbox con un entorno Python con opiniones ajustado para Claude. Anthropic gestiona la administración de contenedores, la ejecución de código y la comunicación segura de invocación de herramientas.

Ventajas:

• Seguro y protegido por defecto
• Fácil de habilitar con configuración mínima
• Entorno e instrucciones optimizados para Claude

Considera usar la solución gestionada de Anthropic si estás usando la API de Claude.

Retención de datos

Las llamadas programáticas a herramientas están construidas sobre la infraestructura de ejecución de código y utilizan los mismos contenedores sandbox. Los datos del contenedor, incluidos los artefactos y salidas de ejecución, se retienen por hasta 30 días.

Para la elegibilidad de ZDR en todas las características, consulta Retención de datos y API.

Características relacionadas