Lo strumento di esecuzione del codice consente a Claude di eseguire codice Python in un ambiente sicuro e isolato. Claude può analizzare dati, creare visualizzazioni, eseguire calcoli complessi ed elaborare file caricati direttamente all’interno della conversazione API.

Lo strumento di esecuzione del codice è attualmente in beta.

Questa funzionalità richiede l’header beta: "anthropic-beta": "code-execution-2025-05-22"

​
Modelli supportati

Lo strumento di esecuzione del codice è disponibile su:

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

​
Avvio rapido

Ecco un esempio semplice che chiede a Claude di eseguire un calcolo:

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": "Calcola la media e la deviazione standard di [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Come funziona l’esecuzione del codice

Quando aggiungi lo strumento di esecuzione del codice alla tua richiesta API:

  1. Claude valuta se l’esecuzione del codice aiuterebbe a rispondere alla tua domanda
  2. Claude scrive ed esegue codice Python in un ambiente sandbox sicuro
  3. L’esecuzione del codice può avvenire più volte durante una singola richiesta
  4. Claude fornisce risultati con eventuali grafici generati, calcoli o analisi

​
Definizione dello strumento

Lo strumento di esecuzione del codice non richiede parametri aggiuntivi:

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

​
Formato della risposta

Ecco un esempio di risposta con esecuzione del codice:

{
  "role": "assistant",
  "container": {
    "id": "container_011CPR5CNjB747bTd36fQLFk",
    "expires_at": "2025-05-23T21:13:31.749448Z"
  },
  "content": [
    {
      "type": "text",
      "text": "Calcolerò la media e la deviazione standard per te."
    },
    {
      "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\"Deviazione standard: {std}\")"
      }
    },
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_01A2B3C4D5E6F7G8H9I0J1K2",
      "content": {
        "type": "code_execution_result",
        "stdout": "Media: 5.5\nDeviazione standard: 2.8722813232690143\n",
        "stderr": "",
        "return_code": 0
      }
    },
    {
      "type": "text",
      "text": "La media del dataset è 5.5 e la deviazione standard è approssimativamente 2.87."
    }
  ],
  "id": "msg_01BqK2v4FnRs4xTjgL8EuZxz",
  "model": "claude-opus-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 187,
  }
}

​
Risultati

I risultati dell’esecuzione del codice includono:

  • stdout: Output dalle istruzioni print e dall’esecuzione riuscita
  • stderr: Messaggi di errore se l’esecuzione del codice fallisce
  • return_code (0 per successo, non-zero per fallimento)
{
  "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
  }
}

​
Errori

Se c’è un errore nell’uso dello strumento ci sarà 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"
  }
}

Gli errori possibili includono

  • unavailable: Lo strumento di esecuzione del codice non è disponibile
  • code_execution_exceeded: Il tempo di esecuzione ha superato il massimo consentito
  • container_expired: Il container è scaduto e non è disponibile

​
Motivo di stop pause_turn

La risposta può includere un motivo di stop pause_turn, che indica che l’API ha messo in pausa un turno di lunga durata. Puoi fornire la risposta così com’è in una richiesta successiva per permettere a Claude di continuare il suo turno, o modificare il contenuto se desideri interrompere la conversazione.

​
Lavorare con i File nell’Esecuzione del Codice

L’esecuzione del codice può analizzare file caricati tramite l’API Files, come file CSV, file Excel e altri formati di dati. Questo consente a Claude di leggere, elaborare e generare insights dai tuoi dati. Puoi passare più file per richiesta.

L’uso dell’API Files con l’Esecuzione del Codice richiede due header beta: "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"

​
Tipi di file supportati

L’ambiente Python è capace di lavorare con ma non limitato ai seguenti tipi di file

  • CSV
  • Excel (.xlsx, .xls)
  • JSON
  • XML
  • Immagini (JPEG, PNG, GIF, WebP)
  • File di testo (.txt, .md, .py, ecc)

​
Caricamento di file per l’esecuzione del codice

  1. Carica il tuo file usando l’API Files
  2. Fai riferimento al file nel tuo messaggio usando un blocco di contenuto container_upload
  3. Includi lo strumento di esecuzione del codice nella tua richiesta API
# Prima, carica un 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"' \

# Poi usa il file_id con l'esecuzione del codice
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": "Analizza questi dati CSV"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Recupero di file creati dall’esecuzione del codice

Quando Claude crea file durante l’esecuzione del codice (ad esempio, salvando grafici matplotlib, generando CSV), puoi recuperare questi file usando l’API Files:

from anthropic import Anthropic

# Inizializza il client
client = Anthropic()

# Richiedi l'esecuzione del codice che crea file
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 visualizzazione matplotlib e salvala come output.png"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

# Estrai gli ID dei file dalla risposta
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

# Scarica i file creati
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"Scaricato: {file_metadata.filename}")

​
Container

Lo strumento di esecuzione del codice funziona in un ambiente containerizzato sicuro progettato specificamente per l’esecuzione di codice Python.

​
Ambiente di runtime

  • Versione Python: 3.11.12
  • Sistema operativo: Container basato su Linux
  • Architettura: x86_64 (AMD64)

​
Limiti delle risorse

  • Memoria: 1GiB RAM
  • Spazio su disco: 5GiB di storage del workspace
  • CPU: 1 CPU

​
Networking e sicurezza

  • Accesso a Internet: Completamente disabilitato per sicurezza
  • Connessioni esterne: Nessuna richiesta di rete in uscita consentita
  • Isolamento sandbox: Isolamento completo dal sistema host e da altri container
  • Accesso ai file: Limitato solo alla directory del workspace
  • Scoping del workspace: Come i Files, i container sono limitati al workspace della chiave API
  • Scadenza: I container scadono 1 ora dopo la creazione

​
Librerie preinstallate

L’ambiente Python isolato include queste librerie comunemente usate:

  • Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
  • Visualizzazione: matplotlib
  • Elaborazione File: pyarrow, openpyxl, xlrd, pillow
  • Math & Computing: sympy, mpmath
  • Utilità: tqdm, python-dateutil, pytz, joblib

​
Riutilizzo del container

Puoi riutilizzare un container esistente attraverso più richieste API fornendo l’ID del container da una risposta precedente. Questo ti consente di mantenere i file creati tra le richieste.

​
Esempio

import os
from anthropic import Anthropic

# Inizializza il client
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Prima richiesta: Crea un file con un numero casuale
response1 = client.beta.messages.create(
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Scrivi un file con un numero casuale e salvalo in '/tmp/number.txt'"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

# Estrai l'ID del container dalla prima risposta
container_id = response1.container.id

# Seconda richiesta: Riutilizza il container per leggere il file
response2 = client.beta.messages.create(
    container=container_id,  # Riutilizza lo stesso container
    model="claude-opus-4-20250514",
    betas=["code-execution-2025-05-22"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Leggi il numero da '/tmp/number.txt' e calcola il suo quadrato"
    }],
    tools=[{
        "type": "code_execution_20250522",
        "name": "code_execution"
    }]
)

​
Streaming

Con lo streaming abilitato, riceverai eventi di esecuzione del codice mentre si verificano:

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

// Esecuzione del codice in streaming
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 mentre il codice viene eseguito

// Risultati dell'esecuzione in streaming
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": ""}}}

​
Richieste batch

Puoi includere lo strumento di esecuzione del codice nell’API Messages Batches. Le chiamate dello strumento di esecuzione del codice attraverso l’API Messages Batches hanno lo stesso prezzo di quelle nelle richieste API Messages regolari.

​
Utilizzo e prezzi

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.