Strumento di esecuzione del codice

Claude può analizzare dati, creare visualizzazioni, eseguire calcoli complessi, eseguire comandi di sistema, creare e modificare file ed elaborare file caricati direttamente all'interno della conversazione API. Lo strumento di esecuzione del codice consente a Claude di eseguire comandi Bash e manipolare file, inclusa la scrittura di codice, in un ambiente sicuro e isolato (sandbox).

L'esecuzione del codice è gratuita quando utilizzata con la ricerca web o il recupero web (web_search_20260209, web_fetch_20260209 o versioni successive). Quando uno di questi strumenti è presente nella tua richiesta, non ci sono costi aggiuntivi per l'esecuzione del codice in quella richiesta oltre ai costi standard dei token. Questo copre sia l'esecuzione del codice alla base del filtraggio dinamico sia qualsiasi codice che Claude esegue direttamente. I prezzi standard per l'esecuzione del codice si applicano quando questi strumenti non sono inclusi.

L'esecuzione del codice alimenta anche il filtraggio dinamico negli strumenti di ricerca web e recupero web: Claude filtra i risultati all'interno dell'ambiente di esecuzione del codice prima che raggiungano la finestra di contesto. Quando il filtraggio dinamico viene eseguito, l'API predispone automaticamente l'esecuzione del codice necessaria per la richiesta, quindi non devi aggiungere lo strumento di esecuzione del codice alla tua richiesta per questo scopo.



Compatibilità dei modelli

Lo strumento di esecuzione del codice è disponibile sui seguenti modelli:

Ogni versione dello strumento si basa sulla precedente:

• code_execution_20250825 supporta comandi Bash e operazioni sui file.
• code_execution_20260120 aggiunge la persistenza dello stato REPL e la chiamata programmatica degli strumenti dall'interno della sandbox. Claude Haiku 4.5 accetta i tipi di strumento code_execution_20260120 e code_execution_20260521, ma la chiamata programmatica degli strumenti e la persistenza dello stato REPL che ne dipende non sono disponibili su di esso, quindi le versioni più recenti si comportano come code_execution_20250825 in quel caso.
• code_execution_20260521 è lo stesso runtime di code_execution_20260120. La differenza è che la descrizione dello strumento informa Claude del limite di 90 secondi di tempo reale su ogni cella Python nella chiamata programmatica degli strumenti, così Claude può pianificare le celle a lunga esecuzione. Una cella che supera il limite restituisce un normale risultato di esecuzione del codice con un return_code diverso da zero e un messaggio di stato detection_timeout nel suo output. Questo è separato dal codice di errore execution_time_exceeded, che l'API restituisce quando un'intera invocazione dello strumento supera il tempo massimo di esecuzione.

Tutte e tre le versioni dello strumento sono generalmente disponibili e non richiedono un header anthropic-beta. Gli header beta legacy per l'esecuzione del codice rimangono validi come opt-in.

Gli esempi in questa pagina utilizzano code_execution_20250825, che copre le operazioni Bash e sui file che dimostrano e si comporta allo stesso modo su ogni modello nella tabella; usa code_execution_20260120 o versioni successive quando hai bisogno della chiamata programmatica degli strumenti o della persistenza dello stato REPL. Gli strumenti attuali di ricerca web e recupero web (web_search_20260209, web_fetch_20260209 e versioni successive) richiedono code_execution_20260120 o versioni successive come versione di esecuzione del codice.



Disponibilità sulle piattaforme

L'esecuzione del codice è disponibile su:

• Claude API (Anthropic)
• Claude Platform on AWS
• Microsoft Foundry (richiede un deployment Hosted on Anthropic)

L'esecuzione del codice non è attualmente disponibile su Amazon Bedrock o Google Cloud.



Avvio rapido

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Use the code execution tool to 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.to_json())

La risposta alterna blocchi server_tool_use (i comandi eseguiti da Claude) con i relativi blocchi di risultato dello strumento, seguiti dal testo di Claude. Il livello superiore include anche un oggetto container il cui id puoi riutilizzare tra le richieste. Consulta Formato della risposta per le forme dei blocchi.



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 potrebbe aiutare a rispondere alla tua domanda
2. Lo strumento fornisce automaticamente a Claude le seguenti capacità:
   • Comandi Bash: Esegui comandi shell per operazioni di sistema
   • Operazioni sui file: Crea, visualizza e modifica file direttamente, inclusa la scrittura di codice
3. Claude può utilizzare qualsiasi combinazione di queste capacità in una singola richiesta
4. Tutte le operazioni vengono eseguite in un container sicuro e isolato. Il container non ha accesso a internet, quindi Claude non può scaricare pacchetti a runtime: sono disponibili solo le librerie preinstallate
5. L'API esegue ogni comando lato server e restituisce i risultati a Claude all'interno della stessa richiesta, quindi non devi mai eseguire codice o inviare blocchi tool_result tu stesso. Un'eccezione è quando Claude chiama uno dei tuoi strumenti client insieme all'esecuzione del codice: l'API restituisce la chiamata di esecuzione del codice senza il suo risultato. Il risultato arriva in una risposta successiva, dopo che hai inviato i blocchi tool_result per i tuoi strumenti client
6. Ogni richiesta viene eseguita in un nuovo container a meno che tu non passi l'ID del container di una risposta precedente (consulta Riutilizzo del container)
7. Claude fornisce i risultati con eventuali grafici, calcoli o analisi generati

Il container ha Python preinstallato. Claude scrive codice Python con il sotto-strumento per le operazioni sui file e lo esegue con un comando Bash. Con code_execution_20260120 o versioni successive e la chiamata programmatica degli strumenti, anche lo stato dell'interprete Python (come i binding delle variabili) persiste tra le richieste che riutilizzano il container.



Quando Claude esegue codice

Claude esegue codice quando la richiesta trae vantaggio dal calcolo o dalla gestione dei file:

• Matematica non banale (numeri grandi, molti passaggi, risultati sensibili alla precisione)
• Analisi dei dati, parsing di file o visualizzazione
• Esecuzione di algoritmi o simulazione
• Richieste esplicite di "eseguire", "calcolare" o "elaborare"

Claude risponde direttamente senza eseguire codice per:

• Aritmetica semplice e fatti matematici ben noti
• Richieste fattuali, conversazionali o creative
• Semplici conversioni di unità o traduzioni

Se vuoi che Claude esegua codice per una richiesta al limite, chiedilo esplicitamente (ad esempio, "esegui del codice per verificare questo").



Lavorare con i file



Carica e analizza i tuoi file

Per analizzare i tuoi file di dati (come CSV, Excel o immagini), caricali tramite la Files API e fai riferimento a essi nella tua richiesta:

L'ambiente Python può elaborare vari tipi di file caricati tramite la Files API, tra cui:

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



Carica e analizza i file

1. Carica il tuo file utilizzando la Files API
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

client = anthropic.Anthropic()

# Carica un file
file_object = client.beta.files.upload(file=Path("data.csv"))

# Usa il file_id con l'esecuzione del codice
response = client.beta.messages.create(
    model="claude-opus-5",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response.to_json())



Recupera i file generati

Quando Claude crea file durante l'esecuzione del codice, l'ID di ogni file creato appare nel risultato dello strumento di esecuzione del codice e puoi scaricarlo con la Files API:

client = Anthropic()

# Richiedi l'esecuzione di codice che crea file
response = client.beta.messages.create(
    model="claude-opus-5",
    betas=["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"}],
)


# Estrai gli ID dei file dalla risposta
def extract_file_ids(response: BetaMessage) -> list[str]:
    file_ids: list[str] = []
    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 output_block in content_item.content:
                    file_ids.append(output_block.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"Downloaded: {file_metadata.filename}")



Definizione dello strumento

Lo strumento di esecuzione del codice non richiede parametri aggiuntivi:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

Entrambi i campi sono fissi: type seleziona la versione dello strumento e name deve essere code_execution.

Quando fornisci questo strumento, Claude ottiene automaticamente accesso a due sotto-strumenti:

• bash_code_execution: Esegui comandi shell
• text_editor_code_execution: Visualizza, crea e modifica file, inclusa la scrittura di codice

Quando Claude esegue codice, la risposta include anche un oggetto container di livello superiore con l'id del container e il timestamp expires_at. Passa quell'ID nel parametro di richiesta container di livello superiore per continuare a utilizzare lo stesso container. Consulta Riutilizzo del container.



Formato della risposta

Lo strumento di esecuzione del codice può restituire due tipi di risultati a seconda dell'operazione:



Risposta del 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,
    "content": []
  }
}



Risposte delle operazioni sui file

Visualizza file:

{
  "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_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 4
  }
}

Crea file:

{
  "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_create_result",
    "is_file_update": false
  }
}

Modifica file (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_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Risultati

I risultati dei comandi Bash (bash_code_execution_result) includono:

• stdout: Output dall'esecuzione riuscita
• stderr: Messaggi di errore se l'esecuzione fallisce
• return_code: 0 per successo, diverso da zero per fallimento
• content: Un elenco con una voce per ogni file creato dal comando. Ogni voce contiene il file_id per recuperare il file con la Files API

I risultati delle operazioni sui file hanno i propri campi:

• View (text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_lines
• Create (text_editor_code_execution_create_result): is_file_update (se il file esisteva già)
• Edit (text_editor_code_execution_str_replace_result): old_start, old_lines, new_start, new_lines, lines (formato diff)



Errori

Ogni tipo di strumento può restituire errori specifici:

Errori comuni (tutti gli strumenti):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

Codici di errore per tipo di strumento:

Un container scaduto non può essere riutilizzato: le richieste che vi fanno riferimento restituiscono un errore invece di ripristinarlo. Invia nuovamente la richiesta senza il parametro container per ottenere un nuovo container.



Stop reason pause_turn

La risposta potrebbe includere uno stop reason pause_turn, che indica che l'API ha messo in pausa un turno a lunga esecuzione. Puoi fornire la risposta così com'è in una richiesta successiva per consentire a Claude di continuare il suo turno, oppure modificare il contenuto se vuoi interrompere la conversazione.



Container

Lo strumento di esecuzione del codice viene eseguito in un ambiente sicuro e containerizzato progettato specificamente per l'esecuzione del codice, con un focus maggiore su Python.



Ambiente di runtime

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



Limiti delle risorse

• Memoria: 5 GiB di RAM
• Spazio su disco: 5 GiB di storage per il workspace
• CPU: 1 CPU
• Tempo di esecuzione: Un'invocazione dello strumento che supera il tempo massimo di esecuzione restituisce un errore execution_time_exceeded. Con la chiamata programmatica degli strumenti, ogni cella REPL ha anche un limite di 90 secondi di tempo reale



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 del workspace
• Ambito del workspace: Come la Files API, i container sono limitati al workspace della chiave API
• Scadenza: I container scadono 30 giorni dopo la creazione



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, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab[pycairo], Img2pdf
• Matematica e calcolo: sympy, mpmath
• Utilità: tqdm, python-dateutil, pytz, joblib

Il container include anche strumenti da riga di comando come unzip, unrar, 7zip, bc, rg (ripgrep), fd e sqlite.

Il container non ha accesso a internet, quindi Claude non può scaricare o installare pacchetti aggiuntivi a runtime: sono disponibili solo le librerie preinstallate.



Riutilizzo del container

Puoi riutilizzare un container esistente tra più richieste API fornendo l'ID del container da una risposta precedente. Questo ti consente di mantenere i file creati tra le richieste. Con code_execution_20260120 o versioni successive e la chiamata programmatica degli strumenti, anche lo stato dell'interprete Python persiste.

I container scadono 30 giorni dopo la creazione. Dopo circa 5 minuti di inattività un container viene salvato come checkpoint, e l'invio di una richiesta con il suo ID entro la finestra di 30 giorni lo ripristina. Il timestamp expires_at nell'oggetto container della risposta è un valore progressivo più breve e non riporta il limite di 30 giorni. Un container scaduto non può essere riutilizzato. Invia nuovamente la richiesta senza il parametro container per ottenere un nuovo container.



Esempio

client = anthropic.Anthropic()

# Prima richiesta: crea un file con un numero casuale in un nuovo container
response1 = client.messages.create(
    model="claude-opus-5",
    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"}],
)

# Seconda richiesta: passa nuovamente l'ID del container così Claude riutilizza lo stesso container
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5",
    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"}],
)

print(response2.to_json())



Utilizzo dell'esecuzione del codice con altri strumenti di esecuzione

Quando fornisci l'esecuzione del codice insieme a strumenti forniti dal client che eseguono anch'essi codice (come uno strumento Bash o un REPL personalizzato), Claude opera in un ambiente multicomputer. Lo strumento di esecuzione del codice viene eseguito nel container sandbox di Anthropic, mentre i tuoi strumenti forniti dal client vengono eseguiti in un ambiente separato che controlli tu. Claude può talvolta confondere questi ambienti, tentando di utilizzare lo strumento sbagliato o assumendo che lo stato sia condiviso tra di essi.

Per evitare questo, aggiungi istruzioni al tuo prompt di sistema che chiariscano la distinzione:

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

Questo è particolarmente importante quando si combina l'esecuzione del codice con la ricerca web o il recupero web, che abilitano automaticamente l'esecuzione del codice. Se la tua applicazione fornisce già uno strumento shell lato client, l'esecuzione automatica del codice crea un secondo ambiente di esecuzione che Claude deve distinguere.

Quando Claude chiama uno dei tuoi strumenti client insieme all'esecuzione del codice, l'API restituisce la chiamata di esecuzione del codice senza il suo risultato. Il risultato arriva in una risposta successiva, dopo che hai inviato i blocchi tool_result per i tuoi strumenti client.



Streaming

Con lo streaming abilitato ("stream": true), riceverai gli eventi di esecuzione del codice man mano che si verificano. L'input del sotto-strumento viene trasmesso in streaming come eventi input_json_delta, e ogni blocco di risultato arriva intero in un singolo evento content_block_start:

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

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}



Richieste batch

Puoi includere lo strumento di esecuzione del codice nella Messages Batches API. Le chiamate allo strumento di esecuzione del codice tramite la Messages Batches API hanno lo stesso prezzo di quelle nelle normali richieste della Messages API.



Utilizzo e prezzi

L'esecuzione di codice è gratuita quando viene utilizzata con la ricerca web o il recupero web. Quando web_search_20260209 (o versioni successive) o web_fetch_20260209 (o versioni successive) è incluso nella tua richiesta API, non ci sono costi aggiuntivi per le chiamate allo strumento di esecuzione del codice oltre ai costi standard dei token di input e output.

Quando viene utilizzata senza questi strumenti, l'esecuzione di codice viene fatturata in base al tempo di esecuzione, tracciato separatamente dall'utilizzo dei token:

• Il tempo di esecuzione ha un minimo di 5 minuti
• Ogni organizzazione riceve 1.550 ore gratuite di utilizzo al mese
• L'utilizzo aggiuntivo oltre le 1.550 ore viene fatturato a $0,05 USD all'ora, per container
• Se nella richiesta sono inclusi dei file, il tempo di esecuzione viene fatturato anche se lo strumento non viene chiamato, perché i file vengono precaricati nel container

L'utilizzo dell'esecuzione di codice viene tracciato nella risposta:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}



Aggiornamento alla versione più recente dello strumento

La versione più recente dello strumento è code_execution_20260521. Per passare tra le tre versioni attuali, aggiorna la stringa type nella tua richiesta: tutte e tre restituiscono i blocchi di risposta documentati in Formato della risposta. Consulta Compatibilità dei modelli per sapere cosa aggiunge ogni versione e quali modelli la supportano.

Il resto di questa sezione tratta la migrazione dalla versione legacy solo Python code_execution_20250522 alle versioni attuali dello strumento.



Cosa è cambiato



Retrocompatibilità

• Tutta l'esecuzione di codice Python esistente continua a funzionare esattamente come prima
• Nessuna modifica richiesta ai flussi di lavoro esistenti solo Python



Passaggi per l'aggiornamento

Per eseguire l'aggiornamento, aggiorna il tipo di strumento nelle tue richieste API:

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

Rivedi la gestione delle risposte (se analizzi le risposte programmaticamente):

• L'API non invia più i blocchi precedenti per le risposte di esecuzione Python
• Invece, l'API invia nuovi tipi di risposta per Bash e operazioni sui file (consulta Formato della risposta)



Conservazione dei dati

L'esecuzione del codice viene eseguita in container sandbox lato server. I dati del container, inclusi gli artefatti di esecuzione, i file caricati e gli output, vengono conservati per un massimo di 30 giorni. Questa conservazione si applica a tutti i dati elaborati all'interno dell'ambiente del container. I file che l'esecuzione del codice crea nella Files API (recuperabili con client.beta.files.download()) persistono fino a quando non vengono eliminati esplicitamente.

Per l'idoneità ZDR su tutte le funzionalità, consulta API e conservazione dei dati.



Passaggi successivi