Llamada programática de herramientas

La "programmatic tool calling" (llamada programática de herramientas) permite que Claude escriba código que llama 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 "latency" (latencia) en flujos de trabajo con múltiples herramientas y disminuye el consumo de tokens al permitir que Claude filtre o procese los 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 la llamada programática de herramientas sobre las herramientas de búsqueda básicas mejoró el rendimiento en un promedio del 11% mientras usaba un 24% menos de tokens de entrada (consulta Improved web search with dynamic filtering).

Considera verificar el cumplimiento del presupuesto de 20 empleados: el enfoque tradicional requiere 20 viajes de ida y vuelta al modelo por separado, incorporando miles de partidas de gastos al contexto en el camino. Con la llamada programática de herramientas, un solo script ejecuta las 20 consultas, filtra los resultados y devuelve solo los empleados que excedieron sus límites, reduciendo lo que Claude necesita razonar de cientos de kilobytes a unas pocas líneas.

La llamada programática de herramientas requiere la herramienta de ejecución de código con la versión de herramienta code_execution_20260120 o posterior. Para comprobar si un modelo admite la llamada programática de herramientas antes de enviar una solicitud, lee su valor capabilities.code_execution.supported desde la Models API. Uso de la API de Models describe el campo.

Inicio rápido

Aquí hay un ejemplo en el que Claude consulta una base de datos de forma programática varias veces y agrega los resultados. Agregar allowed_callers: ["code_execution_20260120"] a una definición de herramienta es lo que hace que esa herramienta se pueda llamar desde dentro de la ejecución de código (consulta El campo allowed_callers):

client = anthropic.Anthropic()

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

La respuesta se detiene con stop_reason: "tool_use", un ID de container y un bloque tool_use para query_database cuyo campo caller identifica la ejecución de código que lo llamó. Devuelve el resultado como se muestra en el Paso 3 del flujo de trabajo de ejemplo para que el código pueda finalizar.

Cómo funciona la llamada programática de herramientas

Cuando configuras una herramienta para que se pueda llamar desde la ejecución de código y Claude determina que esa herramienta es necesaria:

1. Claude escribe código Python que invoca la herramienta como una función, incluyendo potencialmente múltiples llamadas a herramientas y lógica de pre/posprocesamiento
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. 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 finaliza, 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 los resultados de las herramientas antes de que lleguen al contexto de Claude
• Flujos de trabajo de múltiples pasos: Ahorra tokens y latencia llamando a las herramientas en serie o en un bucle sin muestrear a Claude entre las llamadas a herramientas
• Lógica condicional: Toma decisiones basadas en resultados intermedios de las 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

Tanto "code_execution_20260120" como "code_execution_20260521" se aceptan en allowed_callers y son intercambiables: una solicitud que use cualquiera de las dos versiones de la herramienta de ejecución de código satisface a las herramientas que listan cualquiera de los dos llamadores. Los bloques de respuesta siempre etiquetan al llamador como code_execution_20260120 independientemente de la versión que haya declarado la solicitud.

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 es el id del bloque server_tool_use de ejecución de código que realizó la llamada, por lo que puedes asociar cada tool_use programático con la ejecución de código que lo produjo.

Ciclo de vida del contenedor

La llamada programática de herramientas usa 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
• ID del contenedor: Se devuelve en las respuestas en el campo container, junto con una marca de tiempo expires_at
• Reutilización: Pasa el ID del contenedor de vuelta en la siguiente solicitud para mantener el estado. Mientras una llamada programática de herramienta está esperando tu resultado, el ID del contenedor es obligatorio en esa solicitud, no opcional: la API rechaza la solicitud sin él.
• Expiración: expires_at te indica cuánto tiempo le queda al contenedor. Actualmente, los contenedores inactivos se recuperan después de unos 5 minutos, y ningún contenedor puede reutilizarse más de 30 días después de su creación.

Flujo de trabajo de ejemplo

Así es como funciona un flujo completo de llamada programática de herramientas:

Paso 1: Solicitud inicial

Envía una solicitud con ejecución de código y una herramienta que permita la llamada programática. Para habilitar la llamada programática, 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": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, 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

Envía el historial completo de la conversación más el resultado de tu herramienta. Tres detalles importan en esta solicitud:

• El mensaje de usuario que lleva tu resultado solo puede contener bloques tool_result. Consulta Restricciones de formato de mensajes.
• Pasa el ID de container de la respuesta pausada. La API rechaza una continuación que tenga llamadas programáticas de herramientas pendientes pero ningún ID de contenedor.
• Envía el mismo arreglo tools que en la solicitud original. La herramienta de ejecución de código debe seguir presente para que el código pausado se reanude, y las herramientas que envíes en esta solicitud son las definiciones que Claude y el código en ejecución pueden usar durante el resto del turno.

response = client.messages.create(
    model="claude-opus-5-5",
    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}, ...]',
                }
            ],
        },
    ],
    # El mismo array de herramientas que en la solicitud original
    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)

Paso 4: Siguiente llamada a herramienta o finalización

El código retoma donde se pausó y procesa tu resultado. Cada respuesta de continuación o bien se pausa de nuevo con más bloques tool_use programáticos, o bien completa la ejecución de código y permite que Claude continúe el turno (Paso 5). Revisa stop_reason y el caller de cada bloque tool_use para distinguir ambos casos: una respuesta que se pausa para ti tiene stop_reason: "tool_use" y un bloque tool_use cuyo caller nombra una versión de ejecución de código, y repites el Paso 3 con un tool_result para cada llamada programática pendiente en un solo mensaje de usuario.

Paso 5: Respuesta final

Una vez que la ejecución de código finaliza, 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 forma eficiente:

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# 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 grandes conjuntos de resultados de forma programática antes de volver 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:

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

Selección condicional de herramientas

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)

Filtrado de datos

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)

Formato de respuesta

Llamada programática de 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 se han satisfecho y el código finaliza:

{
  "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 la llamada a la herramienta

Si el resultado de tu herramienta no llega en unos 4 minutos, la llamada pendiente lanza un TimeoutError dentro del código en ejecución de Claude. Claude ve el error en stderr y normalmente reintenta la llamada:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

Para evitar los tiempos de espera agotados:

• Monitorea el campo expires_at en las respuestas
• Implementa tiempos de espera para la ejecución de tus herramientas
• Considera dividir las operaciones largas en partes más pequeñas

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 forma apropiada.

Restricciones y limitaciones

Incompatibilidades de funcionalidades

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

Limitaciones del esquema de entrada

Las herramientas personalizadas cuyo input_schema contiene un $ref recursivo (un ciclo de referencias, como un esquema que se refiere a sí mismo) no pueden habilitarse para la llamada programática. Incluir una versión de la herramienta de ejecución de código en allowed_callers para una herramienta así hace que la solicitud falle con un 400 invalid_request_error cuyo mensaje contiene Circular $ref detected. El mismo esquema se acepta para la llamada directa de herramientas.

Para solucionar esto, haz una de las siguientes cosas:

• Mantén la herramienta solo como directa omitiendo allowed_callers (o estableciéndolo en ["direct"]). Otras herramientas en la misma solicitud aún pueden usar la llamada programática.
• Elimina el ciclo del esquema. Por ejemplo, desenrolla la recursión hasta una profundidad fija y describe cualquier anidamiento más profundo en la description del nivel más interno, o reemplaza la propiedad recursiva con un simple {"type": "object"} cuya description explique la forma esperada.

Restricciones de herramientas

Las siguientes herramientas no pueden llamarse de forma programática:

• Herramientas proporcionadas por un conector MCP
• Los conjuntos de herramientas de uso de computadora y uso de navegador (computer_toolset_20260801 y browser_toolset_20260801), cuyo campo allowed_callers acepta solo "direct"

Restricciones de formato de mensajes

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

Respuestas solo con resultados de herramientas: Si hay llamadas programáticas de herramientas 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 las herramientas.

No válido - No se puede incluir texto al responder a llamadas programáticas de 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 de herramientas:

{
  "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 herramientas programáticas (de ejecución de código). Para las llamadas de herramientas regulares del lado del cliente, puedes incluir contenido de texto después de los resultados de las herramientas.

Contenido de resultado de herramienta solo de texto: El content de cada tool_result que responde a una llamada programática debe ser una cadena o bloques text. Los bloques de imagen, documento y otros tipos de bloques de contenido se rechazan.

Límites de velocidad

Las llamadas programáticas de herramientas están sujetas a los mismos "rate limits" (límites de velocidad) que las llamadas de herramientas regulares. 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 de forma programática:

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

Eficiencia de tokens

La llamada programática de herramientas reduce el consumo de tokens de tres maneras:

• Los resultados de herramientas de las 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 ~10 veces los tokens de llamarlas de forma programática y devolver un resumen.

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

• En un benchmark de agente de gestión de proyectos con 75 herramientas, habilitar la llamada programática de 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 a herramientas secuenciales, la llamada programática de herramientas dejó las puntuaciones sin cambios y costó 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 la llamada programática de herramientas habilitada.

Los ahorros reales varían según la forma de la carga de trabajo. Consulta Cuándo usar la llamada programática.

Uso y precios

La llamada programática de herramientas usa los mismos precios que la ejecución de código. Consulta los precios de la 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 el formato (estructura JSON y tipos de campos)
• Devuelve datos estructurados: JSON u otros formatos legibles por máquina 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 la llamada programática

La llamada programática de herramientas intercambia una pequeña sobrecarga fija (inicio del contenedor, generación del script) 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.

Buen ajuste:

• Operaciones de distribución (fan-out) o en paralelo sobre muchos elementos (por ejemplo, verificar 50 endpoints o buscar 20 registros)
• Resultados de herramientas grandes 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

Mal ajuste:

• 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 superar 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 de forma generalizada.

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

invalid_request_error al establecer tool_choice

• tool_choice no puede nombrar una herramienta cuyo allowed_callers omita "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

• Responde a cada llamada programática de herramienta mucho antes de la marca de tiempo expires_at de la respuesta pausada. El código de Claude deja de esperar un resultado después de unos 4 minutos, y actualmente los contenedores inactivos se recuperan después de unos 5 minutos.
• 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 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 seguir el flujo
2. Revisa el campo caller para confirmar la invocación programática
3. Monitorea los ID de contenedor para asegurar una reutilización adecuada
4. Prueba las herramientas de forma independiente antes de habilitar la llamada programática

Por qué funciona la llamada programática de herramientas

Claude está entrenado con grandes cantidades de código, por lo que presentar las herramientas como funciones de Python invocables le permite aprovechar esa fortaleza:

• Composición de herramientas: Las llamadas encadenadas, los bucles y los condicionales son flujo de control ordinario de Python en lugar de una serie de viajes de ida y vuelta al modelo
• Procesamiento de resultados: El código de Claude filtra y agrega salidas grandes de herramientas, o las escribe en archivos, y solo la salida final entra en la ventana de contexto
• Latencia: El modelo no se vuelve a muestrear entre las llamadas a herramientas dentro de una misma ejecución de código

Implementaciones alternativas

La llamada programática de herramientas es un patrón generalizable que también puede implementarse en tu propia infraestructura. Así 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:

• Mínima reestructuración de tu aplicación
• 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 la implementación más pequeña y la oferta administrada 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 con restricciones de seguridad (por ejemplo, sin salida de red). Si tus herramientas requieren recursos externos, necesitarás un protocolo para ejecutar las llamadas a herramientas fuera del sandbox.

Ventajas:

• Llamada programática de herramientas segura 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 administrada de Anthropic no se ajusta a tus requisitos.

Ejecución administrada por Anthropic

La llamada programática de herramientas de Anthropic es una versión administrada de la ejecución en sandbox con un entorno de Python con criterios definidos y ajustado 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 y protegido por defecto
• Se habilita con una definición de herramienta, sin infraestructura que operar
• Entorno e instrucciones optimizados para Claude

Considera usar la solución administrada de Anthropic si usas la Claude API, Claude Platform en AWS o Microsoft Foundry. En Microsoft Foundry, la llamada programática de herramientas requiere un despliegue Hosted on Anthropic.

Retención de datos

La llamada programática de herramientas está construida sobre la infraestructura de ejecución de código y usa 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 la elegibilidad de ZDR en todas las funcionalidades, consulta API y retención de datos.

Próximos pasos

Compatibility