Herramienta de ejecución de código

Claude puede analizar datos, crear visualizaciones, realizar cálculos complejos, ejecutar comandos del sistema, crear y editar archivos, y procesar archivos cargados directamente dentro de la conversación de la API. La herramienta de ejecución de código permite a Claude ejecutar comandos Bash y manipular archivos, incluyendo escribir código, en un entorno seguro y aislado.

La ejecución de código es gratuita cuando se usa con búsqueda web o recuperación web. Cuando web_search_20260209 (o posterior) o web_fetch_20260209 (o posterior) se incluye en tu solicitud, no hay cargos adicionales por las llamadas a la herramienta de ejecución de código más allá de los costos estándar de tokens de entrada y salida. Los cargos estándar de ejecución de código se aplican cuando estas herramientas no están incluidas.

La ejecución de código es una primitiva fundamental para construir agentes de alto rendimiento. Permite el filtrado dinámico en las herramientas de búsqueda web y recuperación web, lo que permite a Claude procesar resultados antes de que lleguen a la "context window" (ventana de contexto), mejorando la precisión mientras reduce el consumo de tokens.



Compatibilidad de modelos

La herramienta de ejecución de código está disponible en los siguientes modelos:



Disponibilidad de plataforma

La ejecución de código está disponible en:

• API de Claude (Anthropic)
• Claude Platform en AWS
• Microsoft Foundry (requiere una implementación alojada en Anthropic)

La ejecución de código no está disponible actualmente en Amazon Bedrock ni en Google Cloud.



Inicio rápido

Aquí tienes un ejemplo simple que le pide a Claude que realice un cálculo:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response)



Cómo funciona la ejecución de código

Cuando agregas la herramienta de ejecución de código a tu solicitud de API:

1. Claude evalúa si la ejecución de código ayudaría a responder tu pregunta
2. La herramienta proporciona automáticamente a Claude las siguientes capacidades:
   • Comandos Bash: Ejecutar comandos de shell para operaciones del sistema y gestión de paquetes
   • Operaciones de archivos: Crear, ver y editar archivos directamente, incluyendo escribir código
3. Claude puede usar cualquier combinación de estas capacidades en una sola solicitud
4. Todas las operaciones se ejecutan en un entorno sandbox seguro
5. Claude proporciona resultados con cualquier gráfico, cálculo o análisis generado



Cuándo ejecuta código Claude

Claude ejecuta código cuando la solicitud se beneficia de la computación o el manejo de archivos:

• Matemáticas no triviales (números grandes, muchos pasos, resultados sensibles a la precisión)
• Análisis de datos, procesamiento de archivos o visualización
• Ejecución de algoritmos o simulación
• Solicitudes explícitas de "ejecutar", "calcular" o "computar"

Claude responde directamente sin ejecutar código para:

• Aritmética simple y hechos matemáticos bien conocidos
• Solicitudes factuales, conversacionales o creativas
• Conversiones de unidades simples o traducciones

Si quieres que Claude ejecute código para una solicitud ambigua, pídelo explícitamente (por ejemplo, "ejecuta código para verificar esto").



Uso de la ejecución de código con otras herramientas de ejecución

Cuando proporcionas la ejecución de código junto con herramientas proporcionadas por el cliente que también ejecutan código (como una herramienta bash o un REPL personalizado), Claude está operando en un entorno de múltiples computadoras. La herramienta de ejecución de código se ejecuta en el contenedor aislado de Anthropic, mientras que tus herramientas proporcionadas por el cliente se ejecutan en un entorno separado que tú controlas. Claude a veces puede confundir estos entornos, intentando usar la herramienta incorrecta o asumiendo que el estado se comparte entre ellos.

Para evitar esto, agrega instrucciones a tu indicación del sistema que aclaren la distinción:

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

Esto es especialmente importante cuando se combina la ejecución de código con búsqueda web o recuperación web, que habilitan la ejecución de código automáticamente. Si tu aplicación ya proporciona una herramienta de shell del lado del cliente, la ejecución de código automática crea un segundo entorno de ejecución que Claude necesita distinguir.



Cómo usar la herramienta



Carga y analiza tus propios archivos

Para analizar tus propios archivos de datos (como CSV, Excel o imágenes), cárgalos a través de la Files API y haz referencia a ellos en tu solicitud:

El entorno de Python puede procesar varios tipos de archivos cargados a través de la Files API, incluyendo:

• CSV
• Excel (.xlsx, .xls)
• JSON
• XML
• Imágenes (JPEG, PNG, GIF, WebP)
• Archivos de texto (.txt, .md, .py y otros)



Cargar y analizar archivos

1. Carga tu archivo usando la Files API
2. Haz referencia al archivo en tu mensaje usando un bloque de contenido container_upload
3. Incluye la herramienta de ejecución de código en tu solicitud de API

client = anthropic.Anthropic()

# Sube un archivo
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Usa el file_id con la ejecución de código
response = client.beta.messages.create(
    model="claude-opus-4-8",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response)



Recuperar archivos generados

Cuando Claude crea archivos durante la ejecución de código, puedes recuperar estos archivos usando la Files API:

# Inicializa el cliente
client = Anthropic()

# Solicita la ejecución de código que crea archivos
response = client.beta.messages.create(
    model="claude-opus-4-8",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a matplotlib visualization and save it as output.png",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# Extrae los IDs de archivo de la respuesta
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # lista con tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Descarga los archivos creados
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id)
    file_content = client.beta.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")



Definición de la herramienta

La herramienta de ejecución de código no requiere parámetros adicionales:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Cuando se proporciona esta herramienta, Claude obtiene automáticamente acceso a dos subherramientas:

• bash_code_execution: Ejecutar comandos de shell
• text_editor_code_execution: Ver, crear y editar archivos, incluyendo escribir código



Formato de respuesta

La herramienta de ejecución de código puede devolver dos tipos de resultados según la operación:



Respuesta de comando Bash

{
  "type": "server_tool_use",
  "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "name": "bash_code_execution",
  "input": {
    "command": "ls -la | head -5"
  }
},
{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
  "content": {
    "type": "bash_code_execution_result",
    "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
    "stderr": "",
    "return_code": 0
  }
}



Respuestas de operaciones de archivos

Ver archivo:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "text_editor_code_execution",
  "input": {
    "command": "view",
    "path": "config.json"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": {
    "type": "text_editor_code_execution_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 4
  }
}

Crear archivo:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "text_editor_code_execution",
  "input": {
    "command": "create",
    "path": "new_file.txt",
    "file_text": "Hello, World!"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": {
    "type": "text_editor_code_execution_result",
    "is_file_update": false
  }
}

Editar archivo (str_replace):

{
  "type": "server_tool_use",
  "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "name": "text_editor_code_execution",
  "input": {
    "command": "str_replace",
    "path": "config.json",
    "old_str": "\"debug\": true",
    "new_str": "\"debug\": false"
  }
},
{
  "type": "text_editor_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
  "content": {
    "type": "text_editor_code_execution_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Resultados

Todos los resultados de ejecución incluyen:

• stdout: Salida de la ejecución exitosa
• stderr: Mensajes de error si la ejecución falla
• return_code: 0 para éxito, distinto de cero para fallo

Campos adicionales para operaciones de archivos:

• Ver: file_type, content, numLines, startLine, totalLines
• Crear: is_file_update (si el archivo ya existía)
• Editar: oldStart, oldLines, newStart, newLines, lines (formato diff)



Errores

Cada tipo de herramienta puede devolver errores específicos:

Errores comunes (todas las herramientas):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Códigos de error por tipo de herramienta:



Motivo de detención pause_turn

La respuesta puede incluir un stop_reason pause_turn, que indica que la API pausó un turno de larga duración. Puedes proporcionar la respuesta tal cual en una solicitud posterior para permitir que Claude continúe su turno, o modificar el contenido si deseas interrumpir la conversación.



Contenedores

La herramienta de ejecución de código se ejecuta en un entorno seguro y contenedorizado diseñado específicamente para la ejecución de código, con un mayor enfoque en Python.



Entorno de ejecución

• Versión de Python: 3.11.12
• Sistema operativo: Contenedor basado en Linux
• Arquitectura: x86_64 (AMD64)



Límites de recursos

• Memoria: 5GiB de RAM
• Espacio en disco: 5GiB de almacenamiento de espacio de trabajo
• CPU: 1 CPU



Red y seguridad

• Acceso a internet: Completamente deshabilitado por seguridad
• Conexiones externas: No se permiten solicitudes de red salientes
• Aislamiento de sandbox: Aislamiento completo del sistema host y otros contenedores
• Acceso a archivos: Limitado únicamente al directorio del espacio de trabajo
• Alcance del espacio de trabajo: Al igual que Files, los contenedores están limitados al espacio de trabajo de la clave de API
• Expiración: Los contenedores expiran 30 días después de su creación



Bibliotecas preinstaladas

El entorno de Python aislado incluye estas bibliotecas de uso común:

• Ciencia de datos: pandas, numpy, scipy, scikit-learn, statsmodels
• Visualización: matplotlib, seaborn
• Procesamiento de archivos: pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Matemáticas y computación: sympy, mpmath
• Utilidades: tqdm, python-dateutil, pytz, joblib, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite



Reutilización de contenedores

Puedes reutilizar un contenedor existente en múltiples solicitudes de API proporcionando el ID del contenedor de una respuesta anterior. Esto te permite mantener los archivos creados entre solicitudes.



Ejemplo

# Primera solicitud: Crea un archivo con un número aleatorio
response1 = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Write a file with a random number and save it to '/tmp/number.txt'",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Extrae el ID del contenedor de la primera respuesta
container_id = response1.container.id

# Segunda solicitud: Reutiliza el contenedor para leer el archivo
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Read the number from '/tmp/number.txt' and calculate its square",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response2)



Streaming

Con el streaming habilitado, recibirás eventos de ejecución de código a medida que ocurren:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}}

// Code execution streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// Pause while code executes

// Execution results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}



Solicitudes por lotes

Puedes incluir la herramienta de ejecución de código en la Messages Batches API. Las llamadas a la herramienta de ejecución de código a través de la Messages Batches API tienen el mismo precio que las de las solicitudes regulares de la Messages API.



Uso y precios

La ejecución de código es gratuita cuando se usa con búsqueda web o recuperación web. Cuando web_search_20260209 (o posterior) o web_fetch_20260209 (o posterior) se incluye en tu solicitud de API, no hay cargos adicionales por las llamadas a la herramienta de ejecución de código más allá de los costos estándar de tokens de entrada y salida.

Cuando se usa sin estas herramientas, la ejecución de código se factura por tiempo de ejecución, que se registra de forma separada del uso de tokens:

• El tiempo de ejecución tiene un mínimo de 5 minutos
• Cada organización recibe 1.550 horas gratuitas de uso al mes
• El uso adicional más allá de las 1.550 horas se factura a $0,05 por hora, por contenedor
• Si se incluyen archivos en la solicitud, el tiempo de ejecución se factura incluso si la herramienta no se invoca, debido a que los archivos se precargan en el contenedor

El uso de la ejecución de código se registra en la respuesta:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



Actualizar a la versión más reciente de la herramienta

Al actualizar a code-execution-2025-08-25, obtienes acceso a capacidades de manipulación de archivos y Bash, incluyendo código en múltiples lenguajes. No hay diferencia de precio.



Qué ha cambiado



Retrocompatibilidad

• Toda la ejecución de código Python existente continúa funcionando exactamente como antes
• No se requieren cambios en los flujos de trabajo existentes que solo usan Python



Pasos de actualización

Para actualizar, modifica el tipo de herramienta en tus solicitudes de API:

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

Revisa el manejo de respuestas (si procesas respuestas programáticamente):

• Los bloques anteriores para respuestas de ejecución de Python ya no se enviarán
• En su lugar, se enviarán nuevos tipos de respuesta para Bash y operaciones de archivos (consulta la sección Formato de respuesta)



Llamadas programáticas a herramientas

Para ejecutar herramientas dentro del contenedor de ejecución de código, consulta Llamadas programáticas a herramientas.



Retención de datos

La ejecución de código se ejecuta en contenedores sandbox del lado del servidor. Los datos del contenedor, incluidos los artefactos de ejecución, los archivos cargados y las salidas, se retienen hasta por 30 días. Esta retención se aplica a todos los datos procesados dentro del entorno del contenedor. Los archivos que la ejecución de código crea en la Files API (recuperables mediante client.beta.files.download()) persisten hasta que se eliminen explícitamente.

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



Uso de la ejecución de código con Agent Skills

La herramienta de ejecución de código permite a Claude usar Agent Skills. Las Skills son capacidades modulares que consisten en instrucciones, scripts y recursos que extienden la funcionalidad de Claude.

Obtén más información en Agent Skills y Uso de Agent Skills con la API.