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.

Compatibilità del modello

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

Avvio rapido

Ecco un semplice esempio 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-sonnet-4-5",
        "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"
        }]
    }'

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

Come utilizzare lo strumento

Esegui 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-sonnet-4-5",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Check the Python version and list installed packages"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'

Crea e modifica file direttamente

Claude può creare, visualizzare e modificare file direttamente nella 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-sonnet-4-5",
        "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"
        }]
    }'

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

# 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: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

Recupera file generati

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

from anthropic import Anthropic

# Initialize the client
client = Anthropic()

# Request code execution that creates files
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25", "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}")

Combina operazioni

Un flusso di lavoro complesso utilizzando tutte le capacità:

# 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: code-execution-2025-08-25,files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5",
        "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"
        }]
    }'

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 consentire 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 maggiore 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 preinstallate

L'ambiente Python in 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

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.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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.beta.messages.create(
    container=container_id,  # Reuse the same container
    model="claude-sonnet-4-5",
    betas=["code-execution-2025-08-25"],
    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"
    }]
)

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 tool usage is tracked separately from token usage. Execution time has 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.

Each organization receives 1,550 free hours of usage with the code execution tool per month. Additional usage beyond the first 1,550 hours is billed at $0.05 per hour, per container.

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

Compatibilità all'indietro

• Tutto il codice Python di esecuzione esistente continua a funzionare esattamente come prima
• Nessun cambiamento richiesto ai flussi di lavoro esistenti solo Python

Passaggi di aggiornamento

Per eseguire l'aggiornamento, devi apportare le seguenti modifiche alle tue richieste API:

1. Aggiorna l'intestazione beta:

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

2. Aggiorna il tipo di strumento:

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

3. Rivedi la gestione della risposta (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 operazioni Bash e file (vedi sezione Formato della risposta)

Chiamata dello strumento a livello di programmazione

Lo strumento di esecuzione del codice alimenta la chiamata dello strumento a livello di programmazione, che consente a Claude di scrivere codice che chiama i tuoi strumenti personalizzati a livello di programmazione all'interno del contenitore di esecuzione. Ciò consente flussi di lavoro multi-strumento efficienti, filtraggio dei dati prima di raggiungere il contesto di Claude e logica condizionale complessa.

# Enable programmatic calling for your tools
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["advanced-tool-use-2025-11-20"],
    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 dello strumento a livello di programmazione.

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 all'API di Agent Skills.