Strumento di esecuzione 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 codice consente a Claude di eseguire comandi Bash e manipolare file, inclusa la scrittura di codice, in un ambiente sicuro e sandboxed.

Lo strumento di esecuzione codice è attualmente in beta pubblica.

Per utilizzare questa funzionalità, aggiungi l’header beta "code-execution-2025-08-25" alle tue richieste API.

Abbiamo recentemente aggiornato lo strumento di esecuzione codice per supportare comandi Bash e manipolazione diretta dei file. Per istruzioni sull’aggiornamento alla versione più recente dello strumento, vedi Aggiorna alla versione più recente dello strumento.

Modelli supportati

Lo strumento di esecuzione codice è disponibile su:

Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
Claude Haiku 3.5 (claude-3-5-haiku-latest)

Avvio rapido

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Calcola la media e la deviazione standard di [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Come funziona l’esecuzione del codice

Quando aggiungi lo strumento di esecuzione codice alla tua richiesta API:

Claude valuta se l’esecuzione del codice aiuterebbe a rispondere alla tua domanda
Lo strumento fornisce automaticamente a Claude le seguenti capacità:
- Comandi Bash: Eseguire comandi shell per operazioni di sistema e gestione pacchetti
- Operazioni sui file: Creare, visualizzare e modificare file direttamente, inclusa la scrittura di codice
Claude può utilizzare qualsiasi combinazione di queste capacità in una singola richiesta
Tutte le operazioni vengono eseguite in un ambiente sandbox sicuro
Claude fornisce risultati con eventuali grafici generati, calcoli o analisi

Come utilizzare lo strumento

Eseguire comandi Bash

Chiedi a Claude di controllare le informazioni di sistema e installare pacchetti:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Controlla la versione di Python e elenca i pacchetti installati"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Creare e modificare file direttamente

Claude può creare, visualizzare e modificare file direttamente nel sandbox utilizzando le capacità di manipolazione dei file:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Crea un file config.yaml con impostazioni del database, poi aggiorna la porta da 5432 a 3306"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

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’utilizzo dell’API Files con l’Esecuzione Codice richiede due header beta: "anthropic-beta": "code-execution-2025-08-25,files-api-2025-04-14"

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

Carica il tuo file utilizzando l’API Files
Fai riferimento al file nel tuo messaggio utilizzando un blocco di contenuto container_upload
Includi lo strumento di esecuzione codice nella tua richiesta API

# Prima, carica un 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"' \

# Poi usa il file_id con l'esecuzione codice
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analizza questi dati CSV"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Recupera file generati

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

from anthropic import Anthropic

# Inizializza il client
client = Anthropic()

# Richiedi l'esecuzione codice che crea file
response = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25", "files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Crea una visualizzazione matplotlib e salvala come 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.get('type') == 'code_execution_result':
                for file in content_item.get('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"Scaricato: {file_metadata.filename}")

Combinare operazioni

Un flusso di lavoro complesso che utilizza tutte le capacità:

# Prima, carica un 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

# Estrai file_id (usando jq)
FILE_ID=$(jq -r '.id' file_response.json)

# Poi usalo con l'esecuzione codice
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Analizza questi dati CSV: crea un report riassuntivo, salva le visualizzazioni e crea un README con i risultati"
                },
                {
                    "type": "container_upload", 
                    "file_id": "'$FILE_ID'"
                }
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Definizione dello strumento

Lo strumento di esecuzione codice non richiede parametri aggiuntivi:

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

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

Formato della risposta

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

Risposta 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 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 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:

Strumento	Codice Errore	Descrizione
Tutti gli strumenti	`unavailable`	Lo strumento è temporaneamente non disponibile
Tutti gli strumenti	`execution_time_exceeded`	L’esecuzione ha superato il limite massimo di tempo
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 velocità superato per l’utilizzo dello strumento
text_editor	`file_not_found`	Il file non esiste (per operazioni view/edit)
text_editor	`string_not_found`	L’`old_str` non trovato nel file (per str_replace)

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, o modificare il contenuto se desideri interrompere la conversazione.

Container

Lo strumento di esecuzione codice viene eseguito in un ambiente containerizzato sicuro 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: 1GiB RAM
Spazio disco: 5GiB di storage workspace
CPU: 1 CPU

Networking e sicurezza

Accesso Internet: Completamente disabilitato per sicurezza
Connessioni esterne: Nessuna richiesta di rete in uscita consentita
Isolamento sandbox: Isolamento completo dal sistema host e altri container
Accesso ai file: Limitato solo alla directory workspace
Scoping workspace: Come Files, i container sono limitati al workspace della chiave API
Scadenza: I container scadono 1 ora dopo la creazione

Librerie pre-installate

L’ambiente Python sandboxed include queste librerie comunemente utilizzate:

Data Science: pandas, numpy, scipy, scikit-learn, statsmodels
Visualizzazione: matplotlib, seaborn
Elaborazione File: pyarrow, openpyxl, 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 attraverso più richieste API fornendo l’ID del container da una risposta precedente. Questo ti consente di mantenere i file creati tra le richieste.

Esempio

import os
from anthropic import Anthropic

# Inizializza il client
client = Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Prima richiesta: Crea un file con un numero casuale
response1 = client.beta.messages.create(
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Scrivi un file con un numero casuale e salvalo in '/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.beta.messages.create(
    container=container_id,  # Riutilizza lo stesso container
    model="claude-opus-4-1-20250805",
    betas=["code-execution-2025-08-25"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Leggi il numero da '/tmp/number.txt' e calcola il suo quadrato"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

Streaming

Con lo streaming abilitato, riceverai eventi di esecuzione 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"}}

// Esecuzione codice in streaming
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())\"}"}}

// Pausa mentre il codice viene eseguito

// Risultati di esecuzione in streaming
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 codice nell’API Messages Batches. Le chiamate dello strumento di esecuzione codice attraverso l’API Messages Batches hanno lo stesso prezzo di quelle nelle richieste API Messages regolari.

Utilizzo e prezzi

The code execution tool usage is tracked separately from token usage. Execution time is a minimum of 5 minutes. If files are included in the request, execution time is billed even if the tool is not used due to files being preloaded onto the container.

Pricing: $0.05 per session-hour.

Aggiorna 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

Componente	Legacy	Attuale
Header beta	`code-execution-2025-05-22`	`code-execution-2025-08-25`
Tipo 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`

Compatibilità all’indietro

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

Passaggi di aggiornamento

Per aggiornare, devi apportare le seguenti modifiche nelle tue richieste API:

Aggiorna l’header beta:

- "anthropic-beta": "code-execution-2025-05-22"
+ "anthropic-beta": "code-execution-2025-08-25"

Aggiorna il tipo di strumento:

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

Rivedi la gestione delle risposte (se analizzi le risposte programmaticamente):
- 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 sezione Formato Risposta)

Strumento bash Strumento di utilizzo del computer

On this page

Modelli supportati
Avvio rapido
Come funziona l’esecuzione del codice
Come utilizzare lo strumento
Eseguire comandi Bash
Creare e modificare file direttamente
Carica e analizza i tuoi file
Carica e analizza file
Recupera file generati
Combinare operazioni
Definizione dello strumento
Formato della risposta
Risposta comando Bash
Risposte operazioni sui file
Risultati
Errori
Motivo di arresto pause_turn
Container
Ambiente di runtime
Limiti delle risorse
Networking e sicurezza
Librerie pre-installate
Riutilizzo del container
Esempio
Streaming
Richieste batch
Utilizzo e prezzi
Aggiorna alla versione più recente dello strumento
Cosa è cambiato
Compatibilità all’indietro
Passaggi di aggiornamento

Primi passi

Modelli e prezzi

Scopri Claude

Funzionalità

Strumenti

Model Context Protocol (MCP)

Casi d'uso

Ingegneria dei prompt

Testa e valuta

Rafforza le protezioni

Centro legale

​Modelli supportati

​Avvio rapido

​Come funziona l’esecuzione del codice

​Come utilizzare lo strumento

​Eseguire comandi Bash

​Creare e modificare file direttamente

​Carica e analizza i tuoi file

​Carica e analizza file

​Recupera file generati

​Combinare operazioni

​Definizione dello strumento

​Formato della risposta

​Risposta comando Bash

​Risposte operazioni sui file

​Risultati

​Errori

​Motivo di arresto pause_turn

​Container

​Ambiente di runtime

​Limiti delle risorse

​Networking e sicurezza

​Librerie pre-installate

​Riutilizzo del container

​Esempio

​Streaming

​Richieste batch

​Utilizzo e prezzi

​Aggiorna alla versione più recente dello strumento

​Cosa è cambiato

​Compatibilità all’indietro

​Passaggi di aggiornamento

Modelli supportati

Avvio rapido

Come funziona l’esecuzione del codice

Come utilizzare lo strumento

Eseguire comandi Bash

Creare e modificare file direttamente

Carica e analizza i tuoi file

Carica e analizza file

Recupera file generati

Combinare operazioni

Definizione dello strumento

Formato della risposta

Risposta comando Bash

Risposte operazioni sui file

Risultati

Errori

Motivo di arresto `pause_turn`

Container

Ambiente di runtime

Limiti delle risorse

Networking e sicurezza

Librerie pre-installate

Riutilizzo del container

Esempio

Streaming

Richieste batch

Utilizzo e prezzi

Aggiorna alla versione più recente dello strumento

Cosa è cambiato

Compatibilità all’indietro

Passaggi di aggiornamento