Llamadas de herramientas programáticas

Las llamadas de herramientas programáticas permiten que Claude escriba código que llame a 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 para flujos de trabajo de 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 puntos de referencia de búsqueda agéntica como BrowseComp y DeepSearchQA, que prueban investigación web de múltiples pasos y recuperación de información compleja, agregar llamadas de herramientas programáticas además de herramientas de búsqueda básicas fue el factor clave que desbloqueó completamente el rendimiento del agente.

La diferencia se compone 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 separados del modelo, extrayendo miles de elementos de gastos al contexto en el camino. Con llamadas de herramientas programáticas, un único script ejecuta las 20 búsquedas, filtra los resultados y devuelve solo los empleados que excedieron sus límites, reduciendo lo que Claude necesita razonar de cientos de kilobytes a solo algunas líneas.

Compatibilidad de modelos

Las llamadas de herramientas programáticas requieren code_execution_20260120, que es compatible con los siguientes modelos:

Para la matriz completa de versiones de la herramienta de ejecución de código, consulta la tabla de compatibilidad de modelos de la herramienta de ejecución de código. Las llamadas de 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 una base de datos de forma programática varias veces y agrega resultados:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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"],
        },
    ],
)

print(response)

Cómo funcionan las llamadas de 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 de herramientas y lógica de pre/post-procesamiento
2. Claude ejecuta este código en un contenedor aislado a través de 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 datos grandes: 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 Claude entre llamadas de herramientas
• Lógica condicional: Toma decisiones basadas en resultados de herramientas intermedias

Conceptos principales

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 (predeterminado si se omite)
• ["code_execution_20260120"] - Solo invocable desde dentro de la ejecución de código
• ["direct", "code_execution_20260120"] - Invocable tanto directamente como desde la ejecución de código

El campo caller en 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 de herramientas programáticas utilizan los mismos contenedores que la ejecución de código:

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

Flujo de trabajo de ejemplo

Aquí se muestra cómo funciona un flujo completo de llamadas de 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 llamadas programáticas, agrega el campo allowed_callers a tu definición de 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 desees que Claude invoque desde código, y envía tu mensaje de usuario.

Paso 2: Respuesta de API con llamada de 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 resultado de herramienta

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

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    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=[...],
)

print(response)

Paso 4: Siguiente llamada de herramienta o finalización

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

Paso 5: Respuesta final

Una vez que se completa la ejecución del código, 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 conjuntos de resultados grandes de manera programática antes de devolver a Claude
• Ahorra tokens devolviendo solo conclusiones agregadas en lugar de datos sin procesar

Terminación temprana

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 herramienta

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 de herramienta programática

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 de resultado de herramienta

Tu resultado de herramienta se devuelve 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 ejecución de código

Cuando se satisfacen todas las llamadas de herramienta 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 de contenedor durante llamada de herramienta

Si tu herramienta tarda demasiado en responder, la ejecución de código recibe un TimeoutError. Claude ve esto en stderr e típicamente reintentos:

{
  "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:

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

Errores de ejecución de herramienta

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 apropiadamente.

Restricciones y limitaciones

Incompatibilidades de características

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

Restricciones de herramienta

Las siguientes herramientas actualmente no pueden ser llamadas programáticamente, pero el soporte puede agregarse en futuras versiones:

• Herramientas proporcionadas por un conector MCP

Restricciones de formato de mensaje

Al responder a llamadas de herramienta programáticas, hay requisitos estrictos de formato:

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

Inválido - No puedes incluir texto al responder a llamadas de herramienta programáticas:

{
  "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 herramienta al responder a llamadas de herramienta programáticas:

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

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

Límites de velocidad

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

Valida resultados de herramienta antes de usar

Al implementar herramientas definidas por el usuario que serán llamadas programáticamente:

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

Eficiencia de tokens

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

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

Por ejemplo, llamar a 10 herramientas directamente usa ~10x los tokens de llamarlas programáticamente y devolver un resumen.

Uso y precios

Las llamadas de herramienta programáticas usan los mismos precios que la ejecución de código. Consulta los precios de ejecución de código para obtener detalles.

Mejores prácticas

Diseño de herramienta

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

Cuándo usar llamadas programáticas

Casos de uso buenos:

• Procesar grandes conjuntos de datos donde solo necesitas agregados o resúmenes
• Flujos de trabajo de múltiples pasos con 3+ llamadas de herramienta dependientes
• Operaciones que requieren filtrado, clasificación o transformación de resultados de herramienta
• Tareas donde datos intermedios no deberían influir en el razonamiento de Claude
• Operaciones paralelas en muchos elementos (p. ej., verificar 50 puntos finales)

Casos de uso menos ideales:

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

Optimización de rendimiento

• Reutiliza contenedores cuando hagas múltiples solicitudes relacionadas para mantener estado
• Agrupa operaciones similares en una única ejecución de código cuando sea posible

Solución de problemas

Problemas comunes

Error "Tool not allowed"

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

Expiración de contenedor

• Asegúrate de responder a llamadas de herramienta antes de que el contenedor se agote (4.5 minutos de inactividad; máximo duro de 30 días)
• Monitorea el campo expires_at en respuestas
• Considera implementar ejecución de herramienta más rápida

Resultado de herramienta no analizado correctamente

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

Consejos de depuración

1. Registra todas las llamadas de herramienta y resultados para rastrear el flujo
2. Verifica el campo caller para confirmar invocación programática
3. Monitorea IDs de contenedor para asegurar reutilización adecuada
4. Prueba herramientas independientemente antes de habilitar llamadas programáticas

Por qué funcionan las llamadas de herramienta programáticas

El entrenamiento de Claude incluye exposición extensa a código, lo que lo hace efectivo en razonar y encadenar llamadas de función. 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 naturalmente sobre composición de herramienta: Encadenar operaciones y manejar dependencias tan naturalmente como escribir cualquier código Python
• Procesar resultados grandes eficientemente: Filtrar salidas grandes de herramienta, extraer solo datos relevantes, o escribir resultados intermedios a archivos antes de devolver resúmenes al contexto de ventana
• Reducir latencia significativamente: Eliminar la sobrecarga de re-muestreo de Claude entre cada llamada de herramienta en flujos de trabajo de múltiples pasos

Este enfoque habilita flujos de trabajo que serían impracticables con uso de herramienta tradicional (como procesar archivos sobre 1M tokens) al permitir que Claude trabaje con datos programáticamente en lugar de cargar todo en el contexto de conversación.

Implementaciones alternativas

Las llamadas de herramienta programáticas son un patrón generalizable que puede implementarse fuera de la ejecución de código administrada 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 la ejecuta localmente donde esas funciones están definidas.

Ventajas:

• Simple de implementar con mínima re-arquitectura
• Control total sobre el entorno e instrucciones

Desventajas:

• Ejecuta código no confiable fuera de una caja de arena
• Las invocaciones de herramienta pueden ser vectores para inyección de código

Usar cuando: Tu aplicación puede ejecutar código arbitrario de manera segura, quieres una solución simple, y la oferta administrada de Anthropic no se ajusta a tus necesidades.

Ejecución en caja de arena auto-administrada

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

Ventajas:

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

Desventajas:

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

Usar cuando: La seguridad es crítica y la solución administrada de Anthropic no se ajusta a tus requisitos.

Ejecución administrado de Anthropic

Las llamadas de herramienta programáticas de Anthropic son una versión administrada de ejecución en caja de arena con un entorno Python opinado sintonizado para Claude. Anthropic maneja la administración de contenedor, ejecución de código y comunicación segura de invocación de herramienta.

Ventajas:

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

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

Retención de datos

Las llamadas de herramienta programáticas se construyen sobre la infraestructura de ejecución de código y usan los mismos contenedores de caja de arena. Los datos de contenedor, incluyendo artefactos de ejecución y salidas, se retienen hasta 30 días.

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

Características relacionadas