Claude Platform Docs
MessaggiStrumenti

Strumento di esecuzione del codice

Esegui codice Python e Bash in un container isolato (sandbox) per analizzare dati, generare file e iterare sulle soluzioni.

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 viene utilizzata con la ricerca web o il recupero web (web_search_20260209, web_fetch_20260209 o successivi). 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. Ciò copre sia l’esecuzione del codice alla base del “dynamic filtering” (filtraggio dinamico) sia qualsiasi codice che Claude esegue direttamente. Quando questi strumenti non sono inclusi, si applicano i prezzi standard dell’esecuzione del codice.

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 “context window” (finestra di contesto). Quando viene eseguito il filtraggio dinamico, l’API fornisce automaticamente l’esecuzione del codice di cui ha bisogno per la richiesta, quindi non è necessario aggiungere lo strumento di esecuzione del codice alla tua richiesta a tale scopo.

Versioni dello strumento

Lo strumento di esecuzione del codice ha tre versioni attuali, e ogni modello supportato le accetta tutte e tre. Ogni versione si basa sulla precedente:

  • code_execution_20250825 supporta comandi Bash e operazioni sui file.
  • code_execution_20260120 aggiunge la persistenza dello stato della 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 della REPL che da essa dipende non sono disponibili su di esso, quindi le versioni più recenti si comportano lì come code_execution_20250825.
  • 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 è distinto dal codice di errore execution_time_exceeded, che l’API restituisce quando un’intera chiamata allo strumento supera il tempo massimo di esecuzione.

Per Claude Mythos Preview, l’esecuzione del codice è supportata sulla Claude API e su Microsoft Foundry.

Nessuna delle tre versioni dello strumento richiede un header anthropic-beta. Gli header beta legacy dell’esecuzione del codice rimangono opt-in validi.

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 supportato; usa code_execution_20260120 o successivo quando hai bisogno della chiamata programmatica degli strumenti o della persistenza dello stato della REPL. Gli strumenti attuali di ricerca web e recupero web (web_search_20260209, web_fetch_20260209 e successivi) richiedono code_execution_20260120 o successivo come versione di esecuzione del codice.

Non è garantito che le versioni precedenti dello strumento rimangano compatibili con i modelli più recenti. Quando adotti un nuovo modello, controlla Versioni dello strumento e Supporto API, e preferisci la versione dello strumento più recente supportata dalla tua integrazione.

Per verificare se un modello accetta lo strumento di esecuzione del codice prima di inviare una richiesta, leggi il suo valore capabilities.server_tools.code_execution.supported dalla Models API. Non usare a questo scopo il valore di primo livello capabilities.code_execution. Esso indica se il codice eseguito in questo strumento può chiamare gli altri strumenti della tua richiesta, come nella chiamata programmatica degli strumenti. Utilizzo della Models API descrive entrambi i campi.

Avvio rapido

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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 la struttura 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 aiuterebbe a rispondere alla tua domanda.
  2. Lo strumento fornisce automaticamente a Claude le seguenti capacità:
    • Comandi Bash: Eseguire comandi shell per operazioni di sistema
    • Operazioni sui file: Creare, visualizzare e modificare 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 durante l’esecuzione: 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 né rinviare tu stesso blocchi tool_result. Un’eccezione si verifica 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 rinviato i blocchi tool_result per i tuoi strumenti client.
  6. Ogni richiesta viene eseguita in un nuovo container a meno che tu non rinvii 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 successivo 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 di file:

  • Matematica non banale (numeri grandi, molti passaggi, risultati sensibili alla precisione)
  • Analisi di dati, parsing di file o visualizzazione
  • Esecuzione di algoritmi o simulazioni
  • Richieste esplicite di “eseguire”, “calcolare” o “lanciare”

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 codice per verificarlo”).

Lavorare con i file

Caricare e analizzare i tuoi file

Per analizzare i tuoi file di dati (come CSV, Excel o immagini), caricali tramite la Files API e fai riferimento ad 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)

Caricare e analizzare 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.files.upload(file=Path("data.csv"))

# Usa il file_id con l'esecuzione del codice
response = client.messages.create(
    model="claude-opus-5-5",
    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())

Recuperare i file generati

Quando Claude salva file nella sua directory di output durante l’esecuzione del codice (consulta Come vengono acquisiti i file generati), l’ID di ciascun file appare nel risultato dello strumento di esecuzione del codice, e puoi scaricarlo con la Files API:

client = Anthropic()

# Richiedi un'esecuzione di codice che crea file
response = client.messages.create(
    model="claude-opus-5-5",
    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: Message) -> 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.files.retrieve_metadata(file_id)
    file_content = client.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Come vengono acquisiti i file generati

Ogni chiamata bash_code_execution riceve una nuova directory vuota, disponibile al comando come $OUTPUT_DIR. Al termine del comando, i file al livello superiore di quella directory vengono acquisiti e restituiti come voci file_id nell’elenco content del risultato. I file scritti in qualsiasi altro punto rimangono nel container e non vengono restituiti.

La descrizione dello strumento indica a Claude di condividere i file copiandoli in $OUTPUT_DIR. Se la tua applicazione dipende dalla ricezione di un file, chiedi a Claude di copiarlo in $OUTPUT_DIR e di elencare il contenuto della directory nello stesso comando, in modo che l’output di ls confermi l’acquisizione (Claude non riceve l’elenco content):

python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"

Un file che Claude ha scritto altrove si trova ancora nel container, quindi puoi riutilizzare il container e chiedere a Claude di copiarlo in $OUTPUT_DIR.

Content Credentials sui file generati

Sulla Claude API, i file immagine, video e audio supportati che Claude produce nella sandbox di esecuzione del codice includono le Content Credentials C2PA quando li scarichi tramite la Files API. I formati supportati includono PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC e M4A. La credenziale è un manifest firmato crittograficamente e incorporato nei metadati del file. Identifica Anthropic come emittente, include un timestamp e registra la descrizione dell’azione “Claude provided this file at the request of a user and may have created or modified the file contents.”

La firma non richiede modifiche alle tue richieste o alla gestione delle risposte, e il manifest non registra nulla su di te, sulla tua organizzazione o sulla tua richiesta. Il contenuto visibile del file rimane invariato. Il manifest aggiunge alcuni kilobyte, quindi la dimensione e il checksum del file scaricato differiscono da quelli del file così come esiste all’interno del container. I file di testo, i PDF e i documenti d’ufficio non vengono firmati perché non sono formati supportati per la firma. I file che carichi vengono archiviati così come sono, incluse eventuali Content Credentials che già contengono.

Per verificare una credenziale, ispeziona il file con qualsiasi strumento compatibile con C2PA, come l’utility a riga di comando c2patool open source. La ricodifica, la conversione di formato, gli screenshot e gli strumenti che rimuovono i metadati eliminano la credenziale, quindi l’assenza di una credenziale non significa che un file non sia stato prodotto con Claude. Per maggiori informazioni sul motivo per cui una credenziale può mancare, consulta Come Claude contrassegna i contenuti generati dall’IA.

Definizione dello strumento

Lo strumento di esecuzione del codice non richiede parametri aggiuntivi:

JSON
{
  "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 l’accesso a due sotto-strumenti:

  • bash_code_execution: Eseguire comandi shell
  • text_editor_code_execution: Visualizzare, creare e modificare file, inclusa la scrittura di codice

Quando Claude esegue codice, la risposta include anche un oggetto container di primo livello con l’id del container e il timestamp expires_at. Rinvia quell’ID nel parametro di richiesta container di primo livello 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 di un comando Bash

Output
{
  "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

Visualizzare un file:

Output
{
  "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
  }
}

Creare un file:

Output
{
  "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
  }
}

Modificare un file (str_replace):

Output
{
  "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 dell’esecuzione riuscita
  • stderr: Messaggi di errore se l’esecuzione fallisce
  • return_code: 0 in caso di successo, diverso da zero in caso di errore
  • content: Un elenco con una voce per ogni file che il comando ha lasciato in $OUTPUT_DIR (consulta Come vengono acquisiti i file generati). Ogni voce contiene il file_id per recuperare il file con la Files API

I risultati delle operazioni sui file hanno i propri campi:

  • Visualizzazione (text_editor_code_execution_view_result): file_type, content, num_lines, start_line, total_lines
  • Creazione (text_editor_code_execution_create_result): is_file_update (se il file esisteva già)
  • Modifica (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):

Output
{
  "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:

StrumentoCodice di erroreDescrizione
Tutti gli strumentiunavailableLo strumento è temporaneamente non disponibile
Tutti gli strumentiexecution_time_exceededLa chiamata allo strumento ha superato il tempo massimo di esecuzione
Tutti gli strumentiinvalid_tool_inputParametri non validi forniti allo strumento
Tutti gli strumentitoo_many_requestsLimite di velocità superato per l’utilizzo dello strumento
bashoutput_file_too_largeL’output del comando ha superato la dimensione massima
text_editorfile_not_foundIl file non esiste (per le operazioni di visualizzazione/modifica)

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

Motivo di arresto pause_turn

La risposta potrebbe 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 consentire a Claude di continuare il suo turno, oppure modificare il contenuto se vuoi interrompere la conversazione.

Invia con quella richiesta l’ID del container restituito dalla risposta (vedi Riutilizzo del container). Senza di esso, la richiesta viene eseguita in un nuovo container e i file creati in precedenza nel turno vanno persi.

Container

Lo strumento di esecuzione del codice viene eseguito in un ambiente sicuro e containerizzato progettato specificamente per l’esecuzione del codice, con una maggiore attenzione a Python.

Ambiente di runtime

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

Limiti delle risorse

  • Memoria: Il container dispone di 5 GiB di RAM.
  • Spazio su disco: Il container dispone di 5 GiB di spazio di archiviazione per l’area di lavoro.
  • CPU: Il container dispone di 1 CPU.
  • Tempo di esecuzione: Una chiamata allo strumento che supera il tempo massimo di esecuzione restituisce un errore execution_time_exceeded. Con la chiamata programmatica degli strumenti, ogni cella della REPL ha anche un limite di 90 secondi di tempo reale.

Rete e sicurezza

  • Accesso a internet: Completamente disabilitato per motivi di sicurezza
  • Connessioni esterne: Nessuna richiesta di rete in uscita consentita
  • Isolamento della sandbox: Isolamento completo dal sistema host e dagli altri container
  • Accesso ai file: Limitato alla sola directory dell’area di lavoro
  • Ambito del workspace: Limitato al workspace della richiesta, come la Files API
  • Scadenza: 30 giorni dopo la creazione

Librerie preinstallate

L’ambiente Python isolato include queste librerie di uso comune:

  • Data science: pandas, numpy, scipy, scikit-learn, statsmodels
  • Visualizzazione: matplotlib, seaborn
  • Elaborazione di 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 a 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 durante l’esecuzione: sono disponibili solo le librerie preinstallate.

Riutilizzo del container

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

I container scadono 30 giorni dopo la creazione. Dopo circa 5 minuti di inattività viene creato un checkpoint del container, 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 mobile più breve e non riporta il limite di 30 giorni. Un container scaduto non può essere riutilizzato. Invia di nuovo 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-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: ripassa l'ID del container affinché Claude riutilizzi lo stesso container
response2 = client.messages.create(
    container=response1.container.id,
    model="claude-opus-5-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 una REPL personalizzata), Claude opera in un ambiente multi-computer. Lo strumento di esecuzione del codice viene eseguito nel container isolato di Anthropic, mentre i tuoi strumenti forniti dal client vengono eseguiti in un ambiente separato che controlli tu. A volte Claude può utilizzare lo strumento sbagliato o comportarsi come se lo stato fosse condiviso tra questi ambienti.

Per evitarlo, 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

Ciò è 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 dal primo.

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 rinviato 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 come eventi input_json_delta, e ogni blocco di risultato arriva per 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 del codice è gratuita quando utilizzata con ricerca web o web fetch. Quando web_search_20260209 (o successivo) o web_fetch_20260209 (o successivo) è 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 utilizzata senza questi strumenti, l’esecuzione del 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 del codice viene tracciato nella risposta:

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

Aggiornamento all’ultima versione dello strumento

L’ultima versione dello strumento è code_execution_20260521. Per passare da una all’altra delle tre versioni attuali, aggiorna la stringa type nella tua richiesta: tutte e tre restituiscono i blocchi di risposta documentati in Formato della risposta. Consulta Versioni dello strumento per sapere cosa aggiunge ciascuna versione e Supporto API per i modelli che le supportano.

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

Cosa è cambiato

ComponenteLegacyAttuale
Header betacode-execution-2025-05-22Nessuno richiesto
Tipo di strumentocode_execution_20250522code_execution_20250825 o successivo
CapacitàSolo PythonComandi Bash, operazioni sui file
Tipi di rispostacode_execution_resultbash_code_execution_result, text_editor_code_execution_*_result

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 in modo programmatico):

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

Conservazione dei dati

L’esecuzione del codice avviene in container sandbox lato server. I dati del container, inclusi artefatti di esecuzione, file caricati e 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.files.download()) persistono finché non vengono eliminati esplicitamente.

Passaggi successivi

Abbina un modello esecutore più veloce a un modello advisor di maggiore intelligenza che fornisce indicazioni strategiche durante la generazione.

Chiama i tuoi strumenti dal codice eseguito all’interno del container di esecuzione del codice.

Carica file per l’analisi e scarica i file creati dall’esecuzione del codice.

Scopri come utilizzare gli Agent Skills per estendere le capacità di Claude tramite l’API.

Disponibilità

Strumento di esecuzione del codice
I requisiti di disponibilità per Strumento di esecuzione del codice sono gli stessi su tutte le piattaforme supportate.
API
  • Messages API
Modelli
  • Tutti i modelli

Endpoint applicabili

  • /v1/messages con lo strumento code_execution
Conservazione zero dei datiNon idoneo

Dati del container conservati fino a 30 giorni. Scopri di più

HIPAANon idoneo

Questa pagina ti è stata utile?