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 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 recuperación web. Cuando web_search_20260209 o web_fetch_20260209 se incluyen 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 central 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 los resultados antes de que lleguen a la ventana de contexto, mejorando la precisión mientras se reduce el consumo de tokens.

Por favor, comunícate a través de nuestro formulario de comentarios para compartir tus comentarios sobre esta función.

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Compatibilidad de modelos

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

Modelo	Versión de herramienta
Claude Opus 4.6 (`claude-opus-4-6`)	`code_execution_20250825`
Claude Sonnet 4.6 (`claude-sonnet-4-6`)	`code_execution_20250825`
Claude Sonnet 4.5 (`claude-sonnet-4-5-20250929`)	`code_execution_20250825`
Claude Opus 4.5 (`claude-opus-4-5-20251101`)	`code_execution_20250825`
Claude Opus 4.1 (`claude-opus-4-1-20250805`)	`code_execution_20250825`
Claude Opus 4 (`claude-opus-4-20250514`)	`code_execution_20250825`
Claude Sonnet 4 (`claude-sonnet-4-20250514`)	`code_execution_20250825`
Claude Sonnet 3.7 (`claude-3-7-sonnet-20250219`) (obsoleto)	`code_execution_20250825`
Claude Haiku 4.5 (`claude-haiku-4-5-20251001`)	`code_execution_20250825`
Claude Haiku 3.5 (`claude-3-5-haiku-latest`) (obsoleto)	`code_execution_20250825`

La versión actual code_execution_20250825 admite comandos Bash y operaciones de archivos. También está disponible una versión heredada code_execution_20250522 (solo Python). Consulta Actualizar a la última versión de la herramienta para obtener detalles de migración.

No se garantiza que las versiones anteriores de la herramienta sean compatibles con versiones anteriores de los modelos más nuevos. Siempre usa la versión de la herramienta que corresponda a la versión de tu modelo.

Disponibilidad en plataformas

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

API de Claude (Anthropic)
Microsoft Azure AI Foundry

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

Inicio rápido

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

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

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

Claude evalúa si la ejecución de código ayudaría a responder tu pregunta
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 la escritura de código
Claude puede usar cualquier combinación de estas capacidades en una sola solicitud
Todas las operaciones se ejecutan en un entorno de sandbox seguro
Claude proporciona resultados con cualquier gráfico generado, cálculos o análisis

Usar la 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 un REPL personalizado), Claude opera 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 las 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 prompt 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

Ejecutar comandos Bash

Pídele a Claude que verifique la información del sistema e instale paquetes:

Crear y editar archivos directamente

Claude puede crear, ver y editar archivos directamente en el sandbox usando las capacidades de manipulación de archivos:

Cargar y analizar 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 referencíalos en tu solicitud:

Usar la API de Archivos con Ejecución de Código requiere el encabezado beta de la API de Archivos: "anthropic-beta": "files-api-2025-04-14"

El entorno 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)

Cargar y analizar archivos

Carga tu archivo usando la API de Archivos
Referencia el archivo en tu mensaje usando un bloque de contenido container_upload
Incluye la herramienta de ejecución de código en tu solicitud de API

Recuperar archivos generados

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

Combinar operaciones

Un flujo de trabajo complejo usando todas las capacidades:

Definición de la herramienta

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

JSON

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

Cuando se proporciona esta herramienta, Claude obtiene automáticamente acceso a dos sub-herramientas:

bash_code_execution: Ejecutar comandos de shell
text_editor_code_execution: Ver, crear y editar archivos, incluyendo la escritura de 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:

Herramienta	Código de error	Descripción
Todas las herramientas	`unavailable`	La herramienta no está disponible temporalmente
Todas las herramientas	`execution_time_exceeded`	La ejecución superó el límite de tiempo máximo
Todas las herramientas	`container_expired`	El contenedor expiró y ya no está disponible
Todas las herramientas	`invalid_tool_input`	Parámetros no válidos proporcionados a la herramienta
Todas las herramientas	`too_many_requests`	Se superó el límite de velocidad para el uso de la herramienta
text_editor	`file_not_found`

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 seguro y en contenedor 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: 5 GiB de RAM
Espacio en disco: 5 GiB de almacenamiento en el 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 del sandbox: Aislamiento completo del sistema host y otros contenedores
Acceso a archivos: Limitado solo al directorio del espacio de trabajo
Alcance del espacio de trabajo: Al igual que los Archivos, los contenedores tienen el alcance del 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 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

Streaming

Con el streaming habilitado, recibirás 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"}}

// 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 API de Lotes de Mensajes. Las llamadas a la herramienta de ejecución de código a través de la API de Lotes de Mensajes tienen el mismo precio 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 última versión de la herramienta

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

Qué ha cambiado

Componente	Heredado	Actual
Encabezado beta	`code-execution-2025-05-22`	`code-execution-2025-08-25`
Tipo de herramienta	`code_execution_20250522`	`code_execution_20250825`
Capacidades	Solo Python	Comandos Bash, operaciones de archivos
Tipos de respuesta	`code_execution_result`	`bash_code_execution_result`, `text_editor_code_execution_result`

Compatibilidad con versiones anteriores

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, actualiza el tipo de herramienta en tus solicitudes de API:

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

Revisa el manejo de respuestas (si analizas 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 Bash y operaciones de archivos (consulta la sección Formato de respuesta)

Llamadas a herramientas mediante programación

La herramienta de ejecución de código impulsa las llamadas a herramientas mediante programación, que permiten a Claude escribir código que llama a tus herramientas personalizadas mediante programación dentro del contenedor de ejecución. Esto permite flujos de trabajo eficientes con múltiples herramientas, filtrado de datos antes de llegar al contexto de Claude y lógica condicional compleja.

Python

# Enable programmatic calling for your tools
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Get weather for 5 cities and find the warmest"}
    ],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "name": "get_weather",
            "description": "Get weather for a city",
            "input_schema": {...},
            "allowed_callers": [
                "code_execution_20250825"
            ],  # Enable programmatic calling
        },
    ],
)

Obtén más información en la documentación de llamadas a herramientas mediante programación.

Retención de datos

La ejecución de código se realiza en contenedores sandbox del lado del servidor. Los datos del contenedor, incluidos los artefactos de ejecución, los archivos cargados y los resultados, se conservan durante un máximo de 30 días. Esta retención se aplica a todos los datos procesados dentro del entorno del contenedor.

Para conocer la elegibilidad de ZDR en todas las funciones, consulte 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 utilizar Agent Skills. Las Skills 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 en la guía de la API de Agent Skills.

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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"
        }]
    }'

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

# First, upload a file
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \

# Then use the file_id with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

from anthropic import Anthropic

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-6",
    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"}],
)


# Extract file IDs from the response
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":
                for file in content_item.content:
                    if hasattr(file, "file_id"):
                        file_ids.append(file.file_id)
    return file_ids


# Download the created files
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}")

# First, upload a file
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"' \
    > file_response.json

# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Then use it with code execution
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
                },
                {
                    "type": "container_upload",
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

import os
from anthropic import Anthropic

# Initialize the client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# First request: Create a file with a random number
response1 = client.messages.create(
    model="claude-opus-4-6",
    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"}],
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-6",
    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"}],
)

Compatibilidad de modelos

Disponibilidad en plataformas

Inicio rápido

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

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

Cómo usar la herramienta

Ejecutar comandos Bash

Crear y editar archivos directamente

Cargar y analizar tus propios archivos

Cargar y analizar archivos

Recuperar archivos generados

Combinar operaciones

Definición de la herramienta

Formato de respuesta

Respuesta de comando Bash

Respuestas de operaciones de archivos

Resultados

Errores

Razón de parada pause_turn

Contenedores

Entorno de ejecución

Límites de recursos

Redes y seguridad

Bibliotecas preinstaladas

Reutilización de contenedores

Ejemplo

Streaming

Solicitudes por lotes

Uso y precios

Actualizar a la última versión de la herramienta

Qué ha cambiado

Compatibilidad con versiones anteriores

Pasos de actualización

Llamadas a herramientas mediante programación

Retención de datos

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

Razón de parada `pause_turn`