Code Interpreter: esegui codice nell'API
In questa pagina
Aggiornato il 2 novembre 2026 sulla base della guida ufficiale di Code Interpreter e dell’SDK
openai: lo strumento richiede un parametrocontainer(mancante in tutti gli esempi precedenti, che avrebbero fallito), i file generati appaiono nelle annotazionicontainer_file_citatione vengono scaricati tramite le API dei Container (nonclient.files.content), e gli output delle chiamate sono denominatioutputs(nonresults). Le parti di testo in input usano il tipoinput_text. I file allegati a un messaggio vengono caricati con lo scopouser_data, raccomandato da OpenAI per gli input del modello (File inputs). Fonti: Code Interpreter · File inputs.
Code Interpreter: esegui codice nell’API
Un modello linguistico prevede testo; non esegue calcoli. Chiedigli la radice quadrata di 1764 e produrrà il risultato più probabile basato sul suo addestramento: spesso corretto, a volte errato, senza modo di distinguere le due casistiche. Code Interpreter elimina questa incertezza fornendo al modello un interprete Python: scrive il calcolo, lo esegue e restituisce un risultato ottenuto, non un’ipotesi.
Il cambiamento è più profondo di quanto sembri. Il modello vede l’output del proprio codice, inclusi gli errori, quindi può correggersi e riprovare. Su un file dati di cui nessuno conosce la struttura esatta, questo ciclo batte qualsiasi istruzione pre-scritta.
Abilita Code Interpreter
Lo abiliti aggiungendo lo strumento all’array tools: nulla da installare, nessun ambiente da provisioningare. Il modello decide quando scrivere codice: risponde direttamente alle domande fattuali, ma passa all’esecuzione per calcoli o manipolazione dei dati.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Calcola la sequenza di Fibonacci fino al 20° termine",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
print(response.output_text)
Il modello scrive il codice Python, lo esegue in una sandbox e integra i risultati nella sua risposta.
Ispeziona il codice eseguito
Prendi l’abitudine di leggere questo codice, almeno durante lo sviluppo. È l’unico modo per distinguere un buon risultato da uno giusto per caso: una media calcolata ignorando silenziosamente i valori mancanti è numericamente corretta ma analiticamente falsa. La risposta non te lo dirà; il codice sì.
La risposta contiene il codice generato e i suoi risultati:
response = client.responses.create(
model="gpt-5.6-terra",
input="Qual è la radice quadrata di 1764? Verifica elevando il risultato al quadrato.",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
include=["code_interpreter_call.outputs"], # per ricevere log e immagini prodotti
)
for item in response.output:
if item.type == "code_interpreter_call":
print("--- Codice Eseguito ---")
print(item.code)
print("--- Output ---")
for output in item.outputs or []:
print(output.logs if output.type == "logs" else output.url)
Fornisci file come input
Lo strumento offre il suo massimo valore quando lavora con i file. Carichi il file, lo riferisci nella chiamata e il modello lo apre effettivamente: legge le colonne reali, i tipi reali e gli outlier reali, invece di ragionare su una descrizione che potresti aver fornito.
# Carica il file
with open("sales_2025.csv", "rb") as f:
file_obj = client.files.create(file=f, purpose="user_data")
# Usa Code Interpreter con il file
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "Analizza questo file di vendite. "
"Dammi il totale per categoria e il mese con le migliori prestazioni."},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
print(response.output_text)
Recupera i file generati
Funziona anche il percorso inverso: il codice produce un CSV pulito, un grafico o una cartella di lavoro Excel, e questi file ti vengono restituiti. Rimangono nel container e il messaggio di risposta li cita nelle sue annotazioni di tipo container_file_citation, includendo l’ID del container, l’ID del file e il nome del file. Puoi quindi scaricarli tramite le API dei Container. Due piccole funzioni, riutilizzate nelle lezioni successive, incapsulano questo flusso:
def generated_files(response):
"""File creati da Code Interpreter, citati nelle annotazioni dei messaggi."""
for item in response.output:
if item.type == "message":
for part in item.content:
for ann in getattr(part, "annotations", None) or []:
if ann.type == "container_file_citation":
yield ann
def download(client, ann, path):
"""Scarica un file dal container e restituisce il suo percorso locale."""
content = client.containers.files.content.retrieve(ann.file_id, container_id=ann.container_id)
with open(path, "wb") as out:
out.write(content.read())
return path
I file che fornisci come input (input_file) vengono copiati automaticamente nel container: non devi caricare nient’altro.
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "Crea un grafico delle vendite per mese "
"ed esporta i dati puliti come CSV."},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
# Recupera i file generati
for ann in generated_files(response):
print(f"File generato: {ann.filename}")
download(client, ann, ann.filename)
Container e ambiente
Conoscere le regole del container ti fa risparmiare tempo nel debug di ciò che non può funzionare. Secondo la documentazione di OpenAI:
- è una macchina virtuale completamente isolata (sandbox) in cui il modello esegue Python;
- lo strumento richiede un parametro
container:{"type": "auto"}crea un container (o ne riutilizza uno da una chiamata precedente presente nel contesto), mentre un ID ottenuto tramiteclient.containers.create(...)forza un container specifico; - la memoria è impostata con
memory_limit:1g(default),4g,16go64g, con livelli superiori fatturati alle tariffe degli strumenti integrati; - un container scade dopo 20 minuti di inattività; i suoi dati vengono quindi persi, quindi scarica eventuali file che vuoi conservare mentre è attivo.
Non contare sull’accesso alla rete dal codice: fornisci i dati come input o delega la ricerca allo strumento Web Search.
# Esempio: il modello può usare pandas direttamente
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": "Carica questo CSV con pandas, "
"calcola le statistiche descrittive e identifica gli outlier."},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
Catena più esecuzioni
Le esecuzioni successive condividono la stessa sessione: variabili, DataFrame e importazioni dal primo blocco rimangono disponibili nel successivo, esattamente come in un notebook. Il modello ne sfrutta naturalmente le potenzialità: carica, ispeziona, poi elabora, rendendo possibile un’analisi multi-step senza ricaricare tutto a ogni fase.
response = client.responses.create(
model="gpt-5.6-terra",
input="1. Genera 1000 punti casuali da una distribuzione normale. "
"2. Calcola media e deviazione standard. "
"3. Crea un istogramma. "
"4. Esegui un test di normalità di Shapiro-Wilk.",
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)
# Il modello esegue 4 blocchi di codice in sequenza
# Ogni blocco ha accesso alle variabili di quelli precedenti
Combina con altri strumenti
La combinazione più utile abbina una fonte dati alla capacità di elaborarla: File Search trova il passaggio rilevante nei tuoi documenti, Web Search porta dati di mercato e Code Interpreter confronta i due in una tabella o in un grafico. Nessuno di questi strumenti può svolgere il lavoro degli altri.
response = client.responses.create(
model="gpt-5.6-terra",
input="Cerca sul web i dati del PIL francese degli ultimi 10 anni, "
"poi crea un grafico di tendenza con una regressione lineare.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter", "container": {"type": "auto"}}
]
)
Pattern: pipeline di analisi completa
L’esempio finale concatena tutto quanto sopra in un caso realistico: un file di input, un’analisi multi-step e deliverable in output. Concentrati soprattutto sul formato del prompt: numerato, esplicito sull’output atteso, perché è quello, ben più del codice Python che lo accompagna, a determinare la qualità del risultato.
def analyze_data(file_path: str, questions: list[str]) -> dict:
"""Pipeline di analisi dati con Code Interpreter."""
# Caricamento
with open(file_path, "rb") as f:
file_obj = client.files.create(file=f, purpose="user_data")
results = {}
for question in questions:
response = client.responses.create(
model="gpt-5.6-terra",
input=[
{
"role": "user",
"content": [
{"type": "input_text", "text": question},
{"type": "input_file", "file_id": file_obj.id}
]
}
],
tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
instructions="Scrivi codice Python pulito e commentato. "
"Mostra i risultati intermedi."
)
results[question] = response.output_text
return results
# Utilizzo
results = analyze_data("sales.csv", [
"Fornisci le statistiche descrittive per ogni colonna numerica",
"Quali sono i 5 prodotti più venduti?",
"C'è stagionalità nelle vendite?"
])
Punti chiave
- Code Interpreter esegue Python in un container isolato; il parametro
containerè obbligatorio ({"type": "auto"}o un ID) - I file forniti come
input_filevengono copiati automaticamente nel container - I file generati sono citati come
container_file_citatione scaricati tramiteclient.containers.files.content.retrieve - Un container scade dopo 20 minuti di inattività: scarica ciò che vuoi conservare
- Combinalo con Web Search e File Search per un’analisi arricchita