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 que Claude ejecute comandos Bash y manipule archivos, incluida la escritura de código, en un entorno seguro y aislado.

La ejecución de código es gratuita cuando se usa con búsqueda web o búsqueda web fetch. Cuando web_search_20260209 o web_fetch_20260209 se incluyen en tu solicitud, no hay cargos adicionales para las llamadas de 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 se incluyen.

La ejecución de código es una primitiva central para construir agentes de alto rendimiento. Permite el filtrado dinámico en herramientas de búsqueda web y búsqueda web fetch, permitiendo que Claude procese resultados antes de que lleguen a la 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:

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

La ejecución de código no está disponible actualmente en Amazon Bedrock o Google Vertex AI.

Inicio rápido

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 añades 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: Ejecuta comandos de shell para operaciones del sistema y gestión de paquetes
   • Operaciones de archivos: Crea, visualiza y edita archivos directamente, incluida la escritura de código
3. Claude puede usar cualquier combinación de estas capacidades en una única solicitud
4. Todas las operaciones se ejecutan en un entorno sandbox seguro
5. Claude proporciona resultados con cualquier gráfico generado, cálculos o análisis

Usar ejecución de código con otras herramientas de ejecución

Cuando proporcionas ejecución de código junto con herramientas proporcionadas por el cliente que también ejecutan código (como una herramienta bash o REPL personalizado), Claude está operando en un entorno multi-computadora. 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 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, añade 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 búsqueda web fetch, 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 (CSV, Excel, imágenes, etc.), cárgalos a través de la API de Archivos y haz referencia a ellos en tu solicitud:

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

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

Carga y analiza archivos

1. Carga tu archivo usando la API de Archivos
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()

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

# Usa el file_id con ejecución de código
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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)

Recupera archivos generados

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

# Inicializa el cliente
client = Anthropic()

# Solicita ejecución de código que crea archivos
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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 file IDs 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":
                # concrete-typed list: 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 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: Ejecuta 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 dependiendo de 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 operación de archivo

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 archivo:

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

Razón de parada pause_turn

La respuesta puede incluir una razón de parada pause_turn, que indica que la API pausó un turno de larga duración. Puedes proporcionar la respuesta tal como está 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 contenedorizado seguro diseñado específicamente para la ejecución de código, con un enfoque mayor 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 RAM
• Espacio en disco: 5GiB de almacenamiento de espacio de trabajo
• CPU: 1 CPU

Redes 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 solo al directorio de espacio de trabajo
• Alcance del espacio de trabajo: Como Archivos, los contenedores se limitan 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 en sandbox 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 e informática: 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 archivos creados entre solicitudes.

Ejemplo

# Primera solicitud: Crear un archivo con un número aleatorio
response1 = client.messages.create(
    model="claude-opus-4-7",
    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"}],
)

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

# Segunda solicitud: Reutilizar el contenedor para leer el archivo
response2 = client.messages.create(
    container=container_id,  # Reutilizar el mismo contenedor
    model="claude-opus-4-7",
    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)

Transmisión

Con la transmisión habilitada, recibirá eventos de ejecución de código a medida que ocurran:

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

// Código ejecutado transmitido
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())\"}"}}

// Pausa mientras se ejecuta el código

// Resultados de ejecución transmitidos
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

Puede incluir la herramienta de ejecución de código en la API de Lotes de Mensajes. Las llamadas de la herramienta de ejecución de código a través de la API de Lotes de Mensajes se cotizan igual que las de las solicitudes regulares de la API de Mensajes.

Uso y precios

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

• Execution time has a minimum of 5 minutes
• Each organization receives 1,550 free hours of usage per month
• Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
• If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

"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, obtiene acceso a capacidades de manipulación de archivos y Bash, incluido código en varios idiomas. No hay diferencia de precio.

Qué ha cambiado

Compatibilidad hacia atrás

• 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 solo de Python

Pasos de actualización

Para actualizar, actualice el tipo de herramienta en sus solicitudes de API:

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

Revisar el manejo de respuestas (si analiza respuestas mediante programación):

• 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 operaciones de Bash y archivos (consulte la sección Formato de respuesta)

Llamada de herramienta programática

Para ejecutar herramientas dentro del contenedor de ejecución de código, consulte Llamada de herramienta programática.

Retención de datos

La ejecución de código se ejecuta en contenedores de espacio aislado del lado del servidor. Los datos del contenedor, incluidos artefactos de ejecución, archivos cargados y salidas, se retienen durante hasta 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 API de Archivos (recuperables mediante client.beta.files.download()) persisten hasta que se eliminen explícitamente.

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

Usar ejecución de código con Agent Skills

La herramienta de ejecución de código permite que Claude use Agent Skills. Las habilidades son capacidades modulares que consisten en instrucciones, scripts y recursos que amplían la funcionalidad de Claude.

Obtenga más información en la documentación de Agent Skills y la guía de API de Agent Skills.