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. Quando web_search_20260209 (o versioni successive) o web_fetch_20260209 (o versioni successive) è incluso nella tua richiesta, non ci sono costi aggiuntivi per le chiamate allo strumento di esecuzione del codice oltre ai costi standard dei token di input e output. I costi standard di esecuzione del codice si applicano quando questi strumenti non sono inclusi.

L'esecuzione del codice è una primitiva fondamentale per la creazione di agenti ad alte prestazioni. Consente il filtraggio dinamico negli strumenti di ricerca web e recupero web, permettendo a Claude di elaborare i risultati prima che raggiungano la "context window" (finestra di contesto), migliorando l'accuratezza e riducendo al contempo il consumo di token.



Compatibilità dei modelli

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



Disponibilità sulle piattaforme

L'esecuzione del codice è disponibile su:

• API Claude (Anthropic)
• Claude Platform su AWS
• Microsoft Foundry (richiede una distribuzione Hosted on Anthropic)

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



Avvio rapido

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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_20250825", "name": "code_execution"}],
)

print(response)



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 può 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 e gestione dei pacchetti
   • 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 ambiente sandbox sicuro
5. Claude fornisce i risultati con eventuali grafici, calcoli o analisi generati



Quando Claude esegue il codice

Claude esegue il 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 il codice per una richiesta al limite, chiedilo esplicitamente (ad esempio, "esegui il codice per verificare questo").



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 multi-computer. 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 presumendo 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.



Come utilizzare lo strumento



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 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=open("data.csv", "rb"),
)

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



Recupera i file generati

Quando Claude crea file durante l'esecuzione del codice, puoi recuperare questi file utilizzando la Files API:

# Inizializza il client
client = Anthropic()

# Richiedi l'esecuzione di codice che crea file
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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):
    file_ids = []
    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":
                # lista con tipo concreto: List[BashCodeExecutionOutputBlock]
                for file in content_item.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"Downloaded: {file_metadata.filename}")



Definizione dello strumento

Lo strumento di esecuzione del codice non richiede parametri aggiuntivi:

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

Quando questo strumento viene fornito, 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



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
  }
}



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_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "numLines": 4,
    "startLine": 1,
    "totalLines": 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_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_result",
    "oldStart": 3,
    "oldLines": 1,
    "newStart": 3,
    "newLines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}



Risultati

Tutti i risultati di esecuzione includono:

• stdout: Output dall'esecuzione riuscita
• stderr: Messaggi di errore se l'esecuzione fallisce
• return_code: 0 per successo, diverso da zero per fallimento

Campi aggiuntivi per le operazioni sui file:

• Visualizza: file_type, content, numLines, startLine, totalLines
• Crea: is_file_update (se il file esisteva già)
• Modifica: oldStart, oldLines, newStart, newLines, 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:



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 consentire a Claude di continuare il suo turno, oppure modificare il contenuto se desideri 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.12
• Sistema operativo: Container basato su Linux
• Architettura: x86_64 (AMD64)



Limiti delle risorse

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



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 i File, 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 di uso comune:

• 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, unzip, unrar, 7zip, bc, rg (ripgrep), fd, sqlite



Riutilizzo del container

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



Esempio

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

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

# Seconda richiesta: riutilizza il container per leggere il file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-8",
    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)



Streaming

Con lo streaming abilitato, riceverai gli eventi di esecuzione del codice man mano che 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"}}

// Code execution streamed
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())\"}"}}

// Pause while code executes

// Execution results streamed
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 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 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 di codice oltre ai costi standard dei token di input e output.

Quando 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 all'ora, per container
• Se nella richiesta sono inclusi dei file, il tempo di esecuzione viene fatturato anche se lo strumento non viene invocato, poiché 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

Aggiornando a code-execution-2025-08-25, ottieni accesso alla manipolazione dei file e alle capacità Bash, incluso il codice in più linguaggi. Non c'è differenza di prezzo.



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 a livello di programmazione):

• I blocchi precedenti per le risposte di esecuzione Python non verranno più inviati
• Invece, verranno inviati nuovi tipi di risposta per Bash e operazioni sui file (vedi la sezione Formato della risposta)



Chiamata programmatica degli strumenti

Per eseguire strumenti all'interno del container di esecuzione del codice, consulta Chiamata programmatica degli strumenti.



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 tramite 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.



Utilizzo dell'esecuzione del codice con le Agent Skills

Lo strumento di esecuzione del codice consente a Claude di utilizzare le Agent Skills. Le Skills sono capacità modulari costituite da istruzioni, script e risorse che estendono le funzionalità di Claude.

Scopri di più in Agent Skills e Utilizzo delle Agent Skills con l'API.