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 sandbox sicuro.

L'esecuzione del codice è gratuita quando utilizzata con la ricerca web o il recupero web. Quando web_search_20260209 o web_fetch_20260209 è incluso nella tua richiesta, non ci sono costi aggiuntivi per le chiamate dello strumento di esecuzione del codice oltre ai costi standard dei token di input e output. Gli addebiti standard per l'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. Abilita il filtraggio dinamico negli strumenti di ricerca web e recupero web, consentendo a Claude di elaborare i risultati prima che raggiungano la finestra di contesto, migliorando l'accuratezza riducendo il consumo di token.

Compatibilità dei modelli

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

Disponibilità della piattaforma

L'esecuzione del codice è disponibile su:

• Claude API (Anthropic)
• Microsoft Azure AI Foundry

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

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-7",
    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 aiuterebbe 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 su 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 risultati con eventuali grafici generati, calcoli o analisi

Utilizzo dell'esecuzione del codice con altri strumenti di esecuzione

Quando fornisci l'esecuzione del codice insieme a strumenti forniti dal client che eseguono anche codice (come uno strumento bash o un REPL personalizzato), Claude sta operando in un ambiente multi-computer. Lo strumento di esecuzione del codice viene eseguito nel contenitore sandbox di Anthropic, mentre i tuoi strumenti forniti dal client vengono eseguiti in un ambiente separato che controlli. Claude a volte può confondere questi ambienti, tentando di utilizzare lo strumento sbagliato o assumendo che lo stato sia condiviso tra loro.

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 l'esecuzione del codice automaticamente. 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 (CSV, Excel, immagini, ecc.), caricali tramite l'API Files e fai riferimento ad essi nella tua richiesta:

L'ambiente Python può elaborare vari tipi di file caricati tramite l'API Files, inclusi:

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

Carica e analizza file

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

client = anthropic.Anthropic()

# Upload a file
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# Use the file_id with code execution
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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 file generati

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

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-opus-4-7",
    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"}],
)


# Extract file IDs from the response
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":
                # concrete-typed list: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Download the created files
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 su 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 dell'esecuzione includono:

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

Campi aggiuntivi per le operazioni su 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 permettere a Claude di continuare il suo turno, oppure modificare il contenuto se desideri interrompere la conversazione.

Contenitori

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

Ambiente di runtime

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

Limiti di risorse

• Memoria: 5GiB RAM
• Spazio su disco: 5GiB di archiviazione dell'area di lavoro
• CPU: 1 CPU

Rete e sicurezza

• Accesso a Internet: Completamente disabilitato per motivi di sicurezza
• Connessioni esterne: Nessuna richiesta di rete in uscita consentita
• Isolamento sandbox: Isolamento completo dal sistema host e da altri contenitori
• Accesso ai file: Limitato solo alla directory dell'area di lavoro
• Ambito dell'area di lavoro: Come Files, i contenitori sono limitati all'area di lavoro della chiave API
• Scadenza: I contenitori scadono 30 giorni dopo la creazione

Librerie pre-installate

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

Riutilizzo del contenitore

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

Esempio

# First request: Create a file with a random number
response1 = client.messages.create(
    model="claude-opus-4-7",
    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"}],
)

# Extract the container ID from the first response
container_id = response1.container.id

# Second request: Reuse the container to read the file
response2 = client.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-opus-4-7",
    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 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"}}

// 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 nell'API Messages Batches. Le chiamate dello strumento di esecuzione del codice tramite l'API Messages Batches hanno lo stesso prezzo di quelle nelle richieste API Messages regolari.

Utilizzo e prezzi

Code execution is free when used with web search or web fetch. When web_search_20260209 or web_fetch_20260209 is included in your API request, there are no additional charges for code execution tool calls beyond the standard input and output token costs.

When used without these tools, code execution is billed by execution time, tracked separately from token usage:

• Execution time has a minimum of 5 minutes
• Each organization receives 1,550 free hours of usage per month
• Additional usage beyond 1,550 hours is billed at $0.05 per hour, per container
• If files are included in the request, execution time is billed even if the tool is not invoked, due to files being preloaded onto the container

Code execution usage is tracked in the response:

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

Aggiorna alla versione più recente dello strumento

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

Cosa è cambiato

Compatibilità all'indietro

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

Passaggi di aggiornamento

Per aggiornare, 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 su file (vedi sezione Formato della risposta)

Chiamata dello strumento a livello di programmazione

Per eseguire strumenti all'interno del contenitore di esecuzione del codice, vedi Chiamata dello strumento a livello di programmazione.

Conservazione dei dati

L'esecuzione del codice viene eseguita in contenitori sandbox lato server. I dati del contenitore, 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 nell'ambiente del contenitore. I file che l'esecuzione del codice crea nell'API Files (recuperabili tramite client.beta.files.download()) persistono fino a quando non vengono eliminati esplicitamente.

Per l'idoneità ZDR in tutte le funzionalità, vedi Conservazione API e dati.

Utilizzo dell'esecuzione del codice con Agent Skills

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

Scopri di più nella documentazione di Agent Skills e nella guida API di Agent Skills.