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.

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)

​
Guida rapida

Ecco un semplice esempio 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": "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"
        }]
    }'

​
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, calcoli o analisi generati

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

​
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, diverso da 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 si verifica un errore nell’utilizzo 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"
  }
}

I possibili errori 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 arresto pause_turn

La risposta può includere un motivo di arresto 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.

​
Container

Lo strumento di esecuzione del codice viene eseguito 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 di risorse

  • Memoria: 1GiB RAM
  • Spazio su disco: 5GiB di spazio di lavoro
  • CPU: 1 CPU
  • Timeout di esecuzione: L’esecuzione è limitata per richiesta di messaggi e può essere controllata con il parametro max_execution_duration
  • Scadenza del container: Dopo 1 ora di inattività, il container non può più essere accessibile

​
Rete 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 di lavoro

​
Librerie preinstallate

L’ambiente Python sandbox include queste librerie comunemente utilizzate:

  • Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
  • Visualizzazione: matplotlib, seaborn
  • Elaborazione file: pyarrow, openpyxl, xlrd, pillow
  • Matematica e calcolo: sympy, mpmath
  • Utilità: tqdm, python-dateutil, pytz, joblib

​
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 permette a Claude di leggere, elaborare e generare approfondimenti dai tuoi dati.

L’utilizzo 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 è in grado 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)

​
Esempio

  1. Carica il tuo file utilizzando l’API Files
  2. Fai riferimento al file nel tuo messaggio utilizzando 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": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250522",
            "name": "code_execution"
        }]
    }'

​
Streaming

Con lo streaming abilitato, riceverai gli 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 allo strumento di esecuzione del codice attraverso l’API Messages Batches hanno lo stesso prezzo di quelle nelle normali richieste dell’API Messages.

​
Utilizzo e prezzi

L’utilizzo dello strumento di esecuzione del codice viene tracciato separatamente dall’utilizzo dei token. Il tempo di esecuzione è di minimo 5 minuti. Se i file sono inclusi nella richiesta, il tempo di esecuzione viene addebitato anche se lo strumento non viene utilizzato a causa del precaricamento dei file sul container.

Prezzo: $0.05 per ora di sessione.