Was this page helpful?
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 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 costruzione 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 la precisione e riducendo il consumo di token.
Contattaci tramite il nostro modulo di feedback per condividere il tuo feedback su questa funzionalità.
This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.
Lo strumento di esecuzione del codice è disponibile sui seguenti modelli:
| Modello | Versione dello strumento |
|---|---|
Claude Opus 4.6 (claude-opus-4-6) | code_execution_20250825 |
Claude Sonnet 4.6 (claude-sonnet-4-6) | code_execution_20250825 |
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929) | code_execution_20250825 |
Claude Opus 4.5 (claude-opus-4-5-20251101) | code_execution_20250825 |
Claude Opus 4.1 (claude-opus-4-1-20250805) | code_execution_20250825 |
Claude Opus 4 (claude-opus-4-20250514) | code_execution_20250825 |
Claude Sonnet 4 (claude-sonnet-4-20250514) | code_execution_20250825 |
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219) (deprecato) | code_execution_20250825 |
Claude Haiku 4.5 (claude-haiku-4-5-20251001) | code_execution_20250825 |
Claude Haiku 3.5 (claude-3-5-haiku-latest) (deprecato) | code_execution_20250825 |
La versione corrente code_execution_20250825 supporta i comandi Bash e le operazioni sui file. È disponibile anche una versione legacy code_execution_20250522 (solo Python). Consulta Aggiornamento all'ultima versione dello strumento per i dettagli sulla migrazione.
Non è garantita la compatibilità con le versioni precedenti delle versioni più vecchie degli strumenti con i modelli più recenti. Usa sempre la versione dello strumento che corrisponde alla versione del tuo modello.
L'esecuzione del codice è disponibile su:
L'esecuzione del codice non è attualmente disponibile su Amazon Bedrock o Google Vertex AI.
Ecco un semplice esempio che chiede a Claude di eseguire un calcolo:
Quando aggiungi lo strumento di esecuzione del codice alla tua richiesta API:
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 opera in un ambiente multi-computer. Lo strumento di esecuzione del codice viene eseguito nel container sandbox di Anthropic, mentre gli strumenti forniti dal client vengono eseguiti in un ambiente separato che controlli tu. Claude a volte può confondere questi ambienti, tentando di utilizzare lo strumento sbagliato o assumendo che lo stato sia condiviso tra di essi.
Per evitare ciò, 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 stateQuesto è 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.
Chiedi a Claude di controllare le informazioni di sistema e installare pacchetti:
Claude può creare, visualizzare e modificare file direttamente nella sandbox utilizzando le capacità di manipolazione dei file:
Per analizzare i propri file di dati (CSV, Excel, immagini, ecc.), caricali tramite l'API Files e fai riferimento ad essi nella tua richiesta:
L'utilizzo dell'API Files con l'esecuzione del codice richiede l'intestazione beta dell'API Files: "anthropic-beta": "files-api-2025-04-14"
L'ambiente Python può elaborare vari tipi di file caricati tramite l'API Files, tra cui:
container_uploadQuando Claude crea file durante l'esecuzione del codice, puoi recuperare questi file utilizzando l'API Files:
Un flusso di lavoro complesso che utilizza tutte le capacità:
Lo strumento di esecuzione del codice non richiede parametri aggiuntivi:
{
"type": "code_execution_20250825",
"name": "code_execution"
}Quando viene fornito questo strumento, Claude ottiene automaticamente accesso a due sotto-strumenti:
bash_code_execution: Esegui comandi shelltext_editor_code_execution: Visualizza, crea e modifica file, inclusa la scrittura di codiceLo strumento di esecuzione del codice può restituire due tipi di risultati a seconda dell'operazione:
{
"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
}
}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"]
}
}Tutti i risultati di esecuzione includono:
stdout: Output dall'esecuzione riuscitastderr: Messaggi di errore se l'esecuzione falliscereturn_code: 0 per successo, diverso da zero per fallimentoCampi aggiuntivi per le operazioni sui file:
file_type, content, numLines, startLine, totalLinesis_file_update (se il file esisteva già)oldStart, oldLines, newStart, newLines, lines (formato diff)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:
| Strumento | Codice di errore | Descrizione |
|---|---|---|
| Tutti gli strumenti | unavailable | Lo strumento è temporaneamente non disponibile |
| Tutti gli strumenti | execution_time_exceeded | L'esecuzione ha superato il limite di tempo massimo |
| Tutti gli strumenti | container_expired | Il container è scaduto e non è più disponibile |
| Tutti gli strumenti | invalid_tool_input | Parametri non validi forniti allo strumento |
| Tutti gli strumenti | too_many_requests | Limite di frequenza superato per l'utilizzo dello strumento |
| text_editor | file_not_found |
pause_turnLa risposta può includere un motivo di stop 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.
Lo strumento di esecuzione del codice viene eseguito in un ambiente containerizzato sicuro progettato specificamente per l'esecuzione del codice, con un focus maggiore su Python.
L'ambiente Python sandbox include queste librerie comunemente utilizzate:
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.
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": ""}}}Puoi includere lo strumento di esecuzione del codice nell'API Messages Batches. Le chiamate allo strumento di esecuzione del codice tramite l'API Messages Batches hanno lo stesso prezzo di quelle nelle normali richieste API Messages.
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:
Code execution usage is tracked in the response:
"usage": {
"input_tokens": 105,
"output_tokens": 239,
"server_tool_use": {
"code_execution_requests": 1
}
}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.
| Componente | Legacy | Corrente |
|---|---|---|
| Intestazione beta | code-execution-2025-05-22 | code-execution-2025-08-25 |
| Tipo di strumento | code_execution_20250522 | code_execution_20250825 |
| Capacità | Solo Python | Comandi Bash, operazioni sui file |
| Tipi di risposta | code_execution_result | bash_code_execution_result, text_editor_code_execution_result |
Per aggiornare, modifica il tipo di strumento nelle tue richieste API:
- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"Rivedi la gestione delle risposte (se si analizzano le risposte in modo programmatico):
Lo strumento di esecuzione del codice alimenta la chiamata programmatica degli strumenti, che consente a Claude di scrivere codice che chiama i tuoi strumenti personalizzati in modo programmatico all'interno del container di esecuzione. Ciò consente flussi di lavoro multi-strumento efficienti, il filtraggio dei dati prima che raggiungano il contesto di Claude e una logica condizionale complessa.
# Enable programmatic calling for your tools
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
messages=[
{"role": "user", "content": "Get weather for 5 cities and find the warmest"}
],
tools=[
{"type": "code_execution_20250825", "name": "code_execution"},
{
"name": "get_weather",
"description": "Get weather for a city",
"input_schema": {...},
"allowed_callers": [
"code_execution_20250825"
], # Enable programmatic calling
},
],
)Scopri di più nella documentazione sulla chiamata programmatica degli strumenti.
L'esecuzione del codice avviene 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 container.
Per l'idoneità ZDR su tutte le funzionalità, vedere API e conservazione dei dati.
Lo strumento di esecuzione del codice consente a Claude di utilizzare Agent Skills. Le Skills sono funzionalità modulari composte da istruzioni, script e risorse che estendono le funzionalità di Claude.
Per ulteriori informazioni, consulta la documentazione di Agent Skills e la guida all'API di Agent Skills.
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"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"
}]
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Check the Python version and list installed packages"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": "Create a config.yaml file with database settings, then update the port from 5432 to 3306"
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'# First, upload a 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"' \
# Then use the file_id with code execution
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: files-api-2025-04-14" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"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_20250825",
"name": "code_execution"
}]
}'from anthropic import Anthropic
# Initialize the client
client = Anthropic()
# Request code execution that creates files
response = client.beta.messages.create(
model="claude-opus-4-6",
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":
for file in content_item.content:
if hasattr(file, "file_id"):
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}")# First, upload a 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"' \
> file_response.json
# Extract file_id (using jq)
FILE_ID=$(jq -r '.id' file_response.json)
# Then use it with code execution
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: files-api-2025-04-14" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-4-6",
"max_tokens": 4096,
"messages": [{
"role": "user",
"content": [
{
"type": "text",
"text": "Analyze this CSV data: create a summary report, save visualizations, and create a README with the findings"
},
{
"type": "container_upload",
"file_id": "'$FILE_ID'"
}
]
}],
"tools": [{
"type": "code_execution_20250825",
"name": "code_execution"
}]
}'| Il file non esiste (per operazioni di visualizzazione/modifica) |
| text_editor | string_not_found | Il old_str non trovato nel file (per str_replace) |
import os
from anthropic import Anthropic
# Initialize the client
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
# First request: Create a file with a random number
response1 = client.messages.create(
model="claude-opus-4-6",
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-6",
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"}],
)