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

La herramienta de ejecución de código está actualmente en beta.

Esta función requiere el encabezado beta: "anthropic-beta": "code-execution-2025-05-22"

​
Modelos compatibles

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

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Inicio rápido

Aquí tienes 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-05-22" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Calcula la media y la desviación estándar de [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
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. Claude escribe y ejecuta código Python en un entorno sandbox seguro
  3. La ejecución de código puede ocurrir múltiples veces durante una sola solicitud
  4. Claude proporciona resultados con cualquier gráfico, cálculo o análisis generado

​
Definición de herramienta

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

JSON
{
  "type": "code_execution_20250522",
  "name": "code_execution"
}

​
Formato de respuesta

Aquí tienes un ejemplo de respuesta con ejecución de código:

{
  "role": "assistant",
  "container": {
    "id": "container_011CPR5CNjB747bTd36fQLFk",
    "expires_at": "2025-05-23T21:13:31.749448Z"
  },
  "content": [
    {
      "type": "text",
      "text": "Calcularé la media y la desviación estándar para ti."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "name": "code_execution",
      "input": {
        "code": "import numpy as np\ndata = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\nmean = np.mean(data)\nstd = np.std(data)\nprint(f\"Media: {mean}\")\nprint(f\"Desviación estándar: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Media: 5.5\nDesviación estándar: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "La media del conjunto de datos es 5.5 y la desviación estándar es aproximadamente 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
  }
}

​
Resultados

Los resultados de la ejecución de código incluyen:

  • stdout: Salida de las declaraciones print y ejecución exitosa
  • stderr: Mensajes de error si la ejecución de código falla
  • return_code (0 para éxito, no cero para falla)
{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "NameError: name 'undefined_variable' is not defined",
    "return_code": 1
  }
}

​
Errores

Si hay un error al usar la herramienta, habrá un code_execution_tool_result_error

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Los posibles errores incluyen

  • unavailable: La herramienta de ejecución de código no está disponible
  • code_execution_exceeded: El tiempo de ejecución excedió el máximo permitido
  • container_expired: El contenedor ha expirado y no está disponible

​
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.

​
Trabajar con archivos en la ejecución de código

La ejecución de código puede analizar archivos cargados a través de la API de archivos, como archivos CSV, archivos Excel y otros formatos de datos. Esto permite a Claude leer, procesar y generar información de tus datos. Puedes pasar múltiples archivos por solicitud.

Usar la API de archivos con la ejecución de código requiere dos encabezados beta: "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"

​
Tipos de archivo compatibles

El entorno Python es capaz de trabajar con, pero no se limita a, los siguientes tipos de archivo

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

​
Cargar archivos para la ejecución de código

  1. Sube tu archivo usando la API de archivos
  2. Referencia el 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
# Primero, sube un archivo
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"' \

# Luego usa el file_id con la ejecución de código
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-05-22,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-20250514",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analiza estos datos CSV"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Recuperar archivos creados por la ejecución de código

Cuando Claude crea archivos durante la ejecución de código (por ejemplo, guardar gráficos de matplotlib, generar CSVs), puedes recuperar estos archivos usando la API de archivos:

from anthropic import Anthropic

# Inicializa el cliente
client = Anthropic()

# Solicita ejecución de código que crea archivos
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22", "files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Crea una visualización matplotlib y guárdala como output.png"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "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 == 'code_execution_tool_result':
            content_item = item.content
            if content_item.get('type') == 'code_execution_result':
                for file in content_item.get('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"Descargado: {file_metadata.filename}")

​
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 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: 1GiB 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 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: Como los archivos, los contenedores están limitados al espacio de trabajo de la clave API
  • Expiración: Los contenedores expiran 1 hora después de la creación

​
Bibliotecas preinstaladas

El entorno Python aislado incluye estas bibliotecas comúnmente utilizadas:

  • Ciencia de datos: pandas, numpy, scipy, scikit-learn, statsmodels
  • Visualización: matplotlib
  • Procesamiento de archivos: pyarrow, openpyxl, xlrd, pillow
  • Matemáticas y computación: sympy, mpmath
  • Utilidades: tqdm, python-dateutil, pytz, joblib

​
Reutilización de contenedores

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

​
Ejemplo

import os
from anthropic import Anthropic

# Inicializa el cliente
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Primera solicitud: Crear un archivo con un número aleatorio
response1 = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Escribe un archivo con un número aleatorio y guárdalo en '/tmp/number.txt'"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

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

# Segunda solicitud: Reutilizar el contenedor para leer el archivo
response2 = client.beta.messages.create(
    container=container_id,  # Reutilizar el mismo contenedor
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Lee el número de '/tmp/number.txt' y calcula su cuadrado"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

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

// Ejecución de código transmitida
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

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

The code execution tool usage is tracked separately from token usage. Execution time is 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.

Pricing: $0.05 per session-hour.