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.

Compatibilidad de modelos

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

Inicio rápido

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

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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)

import { Anthropic } from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

async function main() {
  const response = await anthropic.beta.messages.create({
    model: "claude-sonnet-4-5",
    betas: ["code-execution-2025-08-25"],
    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"
    }]
  });

  console.log(response);
}

main().catch(console.error);

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

Cuando agrega la herramienta de ejecución de código a su solicitud de API:

1. Claude evalúa si la ejecución de código ayudaría a responder su 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, 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 seguro aislado
5. Claude proporciona resultados con cualquier gráfico generado, cálculos o análisis

Cómo usar la herramienta

Ejecutar comandos Bash

Pida a Claude que verifique la información del sistema e instale paquetes:

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

Crear y editar archivos directamente

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

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

Cargar y analizar sus propios archivos

Para analizar sus propios archivos de datos (CSV, Excel, imágenes, etc.), cárguelos a través de la API de archivos y haga referencia a ellos en su solicitud:

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

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

Cargar y analizar archivos

1. Cargue su archivo usando la API de archivos
2. Haga referencia al archivo en su mensaje usando un bloque de contenido container_upload
3. Incluya la herramienta de ejecución de código en su solicitud de API

# 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: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

Recuperar archivos generados

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

from anthropic import Anthropic

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25", "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}")

Combinar operaciones

Un flujo de trabajo complejo usando todas las capacidades:

# 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: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

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 sub-herramientas:

• bash_code_execution: Ejecutar comandos de shell
• text_editor_code_execution: Ver, crear y editar archivos, incluida 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 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 ejecución exitosa
• stderr: Mensajes de error si la ejecución falla
• return_code: 0 para éxito, no 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. Puede proporcionar la respuesta tal como está en una solicitud posterior para permitir que Claude continúe su turno, o modificar el contenido si desea 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 más alto 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 área 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 área de trabajo
• Alcance del área de trabajo: Como Archivos, los contenedores están limitados al área 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 comúnmente utilizadas:

• 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

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

Ejemplo

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.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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.beta.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

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"}}

// 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

Puede incluir la herramienta de ejecución de código en la API de lotes de mensajes. Las llamadas de 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 de API de mensajes regulares.

Uso y precios

Code execution tool usage is tracked separately from token usage. Execution time has a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container.

Each organization receives 50 free hours of usage with the code execution tool per day. Additional usage beyond the first 50 hours is billed at $0.05 per hour, per container.

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

Al actualizar a code-execution-2025-08-25, obtiene acceso a manipulación de archivos y capacidades de 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, debe realizar los siguientes cambios en sus solicitudes de API:

1. Actualice el encabezado beta:

   - "anthropic-beta": "code-execution-2025-05-22"
   + "anthropic-beta": "code-execution-2025-08-25"

2. Actualice el tipo de herramienta:

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

3. Revise 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)

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.