Llamadas programáticas a herramientas

Las llamadas programáticas a herramientas permiten que Claude escriba código que llama a tus herramientas de forma programática dentro de un contenedor de code execution (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 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).

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 solo los empleados que excedieron sus límites, reduciendo lo que Claude necesita razonar de cientos de kilobytes a solo unas pocas líneas.



Compatibilidad de modelos

Las llamadas programáticas a herramientas requieren code_execution_20260120 o posterior, 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 programáticas a herramientas están disponibles en la API de Claude, Claude Platform on AWS y Microsoft Foundry. En Microsoft Foundry, las llamadas programáticas a herramientas requieren una implementación Hosted on Anthropic. Actualmente no están disponibles en Amazon Bedrock ni en Google Cloud.



Inicio rápido

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

client = anthropic.Anthropic()

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

Tanto "code_execution_20260120" como "code_execution_20260521" se aceptan en allowed_callers y son intercambiables: una solicitud que usa cualquiera de las versiones de la herramienta de ejecución de código satisface las herramientas que listan cualquiera de los callers. Los bloques de respuesta siempre etiquetan el caller como code_execution_20260120 independientemente de qué versión declaró 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

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
• 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 a 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. Los contenedores inactivos actualmente se recuperan después de aproximadamente 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 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 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 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 tu resultado de 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 tiene llamadas programáticas a herramientas pendientes pero sin ID de contenedor.
• Envía el mismo array tools que 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ías 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-4-8",
    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 se pausa nuevamente con más bloques tool_use programáticos, o 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 entre ambos casos: una respuesta que se pausa esperándote 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 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 procesa múltiples elementos de manera 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 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 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 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

Tu resultado de 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 la llamada a herramienta

Si tu resultado de herramienta no llega dentro de aproximadamente 4 minutos, la llamada pendiente genera un TimeoutError dentro del código en ejecución de Claude. Claude ve el error en stderr y típicamente 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 prevenir 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 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
• Tool choice: No puedes forzar la llamada programática de una herramienta específica a través de tool_choice
• Uso de herramientas en paralelo: disable_parallel_tool_use: true no es compatible con las llamadas programáticas



Limitaciones del esquema de entrada

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

Para solucionar esto, haz una de las siguientes cosas:

• Mantén la herramienta solo para llamadas directas omitiendo allowed_callers (o estableciéndolo en ["direct"]). Otras herramientas en la misma solicitud aún pueden usar llamadas programáticas.
• 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 {"type": "object"} simple cuya description explique la forma esperada.



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 solo bloques tool_result. No puedes incluir ningún contenido de texto, ni siquiera después de los resultados de herramientas.

No vá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 (de 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 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 tipos de bloques de contenido de imagen, documento y otros son rechazados.



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 herramientas antes de usarlos

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

• Los resultados de herramientas se devuelven como cadenas: 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 reducen el consumo de tokens de tres maneras:

• 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 ~10x los tokens de llamarlas programáticamente y devolver un resumen.

En las evaluaciones internas de Anthropic sobre 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, retail 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 array 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 más detalles.



Mejores prácticas



Diseño de herramientas

• Proporciona descripciones detalladas de la salida: Dado que Claude deserializa los resultados de 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 llamadas programáticas

Las llamadas programáticas a herramientas intercambian 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 paralelas sobre muchos elementos (por ejemplo, verificar 50 endpoints o consultar 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 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 establecer 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

• Responde a cada llamada programática a 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 aproximadamente 4 minutos, y los contenedores inactivos actualmente se recuperan después de aproximadamente 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 resultados para rastrear el flujo
2. Revisa 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

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

• Composición de herramientas: Las llamadas encadenadas, bucles y 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 ejecución de código



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:

• Rediseño mínimo 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 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 con opiniones definidas, 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
• Se habilita con una definición de herramienta, sin infraestructura que ejecutar
• 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. En Microsoft Foundry, las llamadas programáticas a herramientas requieren una implementación Hosted on Anthropic.



Retención de datos

Las llamadas programáticas a herramientas están construidas sobre 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 la elegibilidad de ZDR en todas las funciones, consulta API y retención de datos.



Próximos pasos