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 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 sono inclusi 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 è un primitivo 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 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:

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"
        }]
    }'

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 "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"
        }]
    }'

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 "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"
        }]
    }'

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: 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"
        }]
    }'

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

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: 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"
        }]
    }'

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 successo, non zero per 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, o 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 spazio 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 di lavoro
• Ambito del workspace: Come Files, i contenitori sono limitati al workspace della chiave API
• Scadenza: I contenitori scadono 30 giorni dopo la creazione

Librerie pre-installate

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.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"}],
)

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
• Nessun cambiamento richiesto ai flussi di lavoro esistenti solo Python

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 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. Questo abilita 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.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 della 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 API di Agent Skills.