Llamadas programáticas a herramientas

Las llamadas programáticas a herramientas 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 "latency" (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 "context window" (ventana de contexto) del modelo. En benchmarks de búsqueda agéntica como BrowseComp y DeepSearchQA, que evalúan la investigación web de múltiples pasos y la recuperación de información compleja, agregar llamadas programáticas a herramientas sobre herramientas de búsqueda básicas mejoró el rendimiento en un promedio del 11% mientras se usaban 24% menos tokens de entrada (consulta Improved web search with dynamic filtering).

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



Compatibilidad de modelos

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

Para ver 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 programáticas a herramientas están disponibles en la API de Claude, Claude Platform on AWS y Microsoft Foundry. Actualmente no están disponibles en Amazon Bedrock ni en Vertex AI.



Inicio rápido

Aquí tienes un ejemplo en el que Claude consulta programáticamente una base de datos varias veces y agrega los resultados:



Cómo funcionan las llamadas programáticas a herramientas

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 (sandbox) 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. Tú 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 toda la ejecución de código se completa, 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"] - Se guía a Claude para que llame a esta herramienta directamente (valor predeterminado si se omite)
• ["code_execution_20260120"] - Se guía a Claude para que llame a esta herramienta solo desde dentro de la ejecución de código
• ["direct", "code_execution_20260120"] - Claude puede llamar a esta herramienta directamente o desde dentro de la ejecución de código



El campo caller en las respuestas

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

Invocación directa (uso de herramientas tradicional):

{
  "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 programáticas a herramientas usan los mismos contenedores que la ejecución de código:

• Creación del contenedor: Se crea un nuevo contenedor para cada solicitud a menos que reutilices uno existente
• Expiración: Los contenedores tienen una vida útil máxima de 30 días y se eliminan después de 4,5 minutos de inactividad
• ID del contenedor: Se devuelve en las respuestas en el 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 programáticas a herramientas:



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 código, y envía tu mensaje de usuario. Los pasos restantes de este flujo de trabajo usan el mensaje de usuario "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".



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": "2026-01-20T14: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:



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 adicionales a herramientas, 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: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "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)

    # Procesa los resultados de forma programática
    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 al modelo de N (uno por región) a 1
• Procesa conjuntos de resultados grandes programáticamente antes de devolverlos a Claude
• Ahorra tokens al devolver solo conclusiones agregadas en lugar de datos sin procesar



Terminación anticipada

Claude puede detener el procesamiento 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 ve esto 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 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 apropiadamente.



Restricciones y limitaciones



Incompatibilidades de funciones

• 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 no pueden llamarse programáticamente:

• Herramientas proporcionadas por un conector MCP



Restricciones de formato de mensajes

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

Respuestas solo con resultados de herramientas: 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 al responder a llamadas programáticas a herramientas (ejecución de código). 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.



Valida los resultados de las herramientas antes de usarlos

Al implementar herramientas definidas por el usuario que se llamarán programáticamente:

• 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 agregan al contexto de Claude - solo la salida final del código
• El procesamiento intermedio ocurre en código - el filtrado, la agregación y otras transformaciones 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 separados del modelo

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

En las evaluaciones internas de Anthropic con un modelo de Claude en producción:

• En un benchmark de agente de gestión de proyectos con 75 herramientas, habilitar las llamadas programáticas a herramientas redujo los tokens de entrada facturados en aproximadamente un 38% sin cambios en la precisión de las tareas.
• En τ²-bench (dominios de aerolíneas, comercio minorista y telecomunicaciones), donde cada turno realiza una o dos llamadas secuenciales a herramientas, las llamadas programáticas a herramientas dejaron las puntuaciones sin cambios y costaron aproximadamente un 8% más. Los flujos de trabajo secuenciales de una sola llamada no se benefician.
• En el tráfico de producción de la API, las solicitudes cuyo arreglo tools contiene de 10 a 49 definiciones de herramientas ven ahorros típicos de tokens del 20% al 40% con las llamadas programáticas a herramientas habilitadas.

Los ahorros reales varían según la forma de la carga de trabajo; consulta Cuándo usar llamadas programáticas.



Uso y precios

Las llamadas programáticas a herramientas usan los mismos precios que la ejecución de código. Consulta los precios de ejecución de código para obtener 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 y tipos de campos)
• 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

Las llamadas programáticas a herramientas intercambian una pequeña sobrecarga fija (inicio del contenedor, generación de scripts) por grandes ahorros en tokens de resultados de herramientas y viajes de ida y vuelta al modelo. Si ese intercambio vale la pena depende de la forma de la carga de trabajo.

Buena opción:

• Operaciones de distribución (fan-out) o paralelas sobre muchos elementos (por ejemplo, verificar 50 endpoints o consultar 20 registros)
• Resultados grandes de herramientas que pueden filtrarse, agregarse o resumirse antes de llegar al contexto de Claude
• Búsqueda y recuperación agéntica, donde las consultas iterativas y el filtrado de resultados dominan el flujo de trabajo

Mala opción:

• Flujos de trabajo estrictamente secuenciales donde cada llamada depende de que Claude razone sobre el resultado anterior, porque el script no puede omitir el viaje de ida y vuelta al modelo en ese caso
• Un número pequeño de llamadas a herramientas con respuestas pequeñas, especialmente en el primer turno de una conversación, donde la sobrecarga del contenedor y del script puede exceder los ahorros
• Herramientas que requieren retroalimentación inmediata del usuario entre llamadas

Si no estás seguro, mide los tokens de entrada facturados con y sin allowed_callers en una muestra representativa de tu tráfico antes de habilitarlo ampliamente.



Optimización del rendimiento

• Reutiliza 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

invalid_request_error al configurar tool_choice

• tool_choice no puede nombrar una herramienta cuyo allowed_callers omite "direct". Agrega "direct" al allowed_callers de esa herramienta, o elimina la herramienta de tool_choice y deja que Claude la invoque desde código.

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 de cadena de texto 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 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 una reutilización adecuada
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 amplia exposición 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 naturalmente sobre la composición de herramientas: Encadenar operaciones y manejar dependencias tan naturalmente como escribir cualquier código Python
• Procesar resultados grandes de manera eficiente: Filtrar salidas grandes de herramientas, extraer solo datos relevantes o escribir resultados intermedios en archivos antes de devolver resúmenes a la ventana de contexto
• Reducir la latencia significativamente: Eliminar la sobrecarga de volver a muestrear a 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 de herramientas tradicional (como procesar archivos de más de 1M de tokens) al permitir que Claude trabaje con datos programáticamente 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 también puede implementarse en tu propia infraestructura. Así es como se comparan 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 mínima rearquitectura
• 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 ajusta 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 aislado (sandbox) con restricciones de seguridad (por ejemplo, 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 ajusta 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 preconfigurado y optimizado para Claude. Anthropic se encarga de la gestión de contenedores, la ejecución de código y la comunicación segura de invocación de herramientas.

Ventajas:

• Seguro 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, Claude Platform on AWS o Microsoft Foundry.



Retención de datos

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

Para conocer la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.



Funciones relacionadas