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.

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í hay un ejemplo simple que pide a Claude realizar 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": "Calculate the mean and standard deviation of [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 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. Claude escribe y ejecuta código Python en un entorno aislado seguro
  3. La ejecución de código puede ocurrir varias veces durante una sola solicitud
  4. Claude proporciona resultados con cualquier gráfico, cálculo o análisis generado

​
Definición de la 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í hay un ejemplo de respuesta con ejecución de código:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll calculate the mean and standard deviation for you."
    },
    {
      "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\"Mean: {mean}\")\nprint(f\"Standard deviation: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Mean: 5.5\nStandard deviation: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "The mean of the dataset is 5.5 and the standard deviation is approximately 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
    "server_tool_use": {
      "execution_time_seconds": 1.5
    }
  }
}

​
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 del código falla
  • return_code (0 para éxito, distinto de cero para fallo)
{
  "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

​
Motivo de parada pause_turn

La respuesta puede incluir un motivo de parada 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 contenedorizado seguro 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 trabajo
  • CPU: 1 CPU
  • Tiempo de espera de ejecución: La ejecución está limitada por solicitud de mensajes y puede controlarse con el parámetro max_execution_duration
  • Expiración del contenedor: Después de 1 hora de inactividad, el contenedor no puede ser accedido nuevamente

​
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 de trabajo

​
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, xlrd, pillow
  • Matemáticas y computación: sympy, mpmath
  • Utilidades: tqdm, python-dateutil, pytz, joblib

​
Trabajando 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 a partir de tus datos.

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

​
Tipos de archivos compatibles

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

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

​
Ejemplo

  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": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "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

El uso de la herramienta de ejecución de código se rastrea por separado del uso de tokens. El tiempo de ejecución es de un mínimo de 5 minutos. Si se incluyen archivos en la solicitud, el tiempo de ejecución se factura incluso si la herramienta no se utiliza debido a que los archivos se precargan en el contenedor.

Precio: $0.05 por hora de sesión.