Tutorial sull'Agents API di OpenAI: crea un agente che scrive ed esegue codice nel cloud

La maggior parte delle app basate su LLM segue uno schema semplice: invii un prompt, ottieni una risposta e usi quella risposta nella tua applicazione.

Questo funziona bene per attività semplici, ma le cose si complicano quando il modello deve scrivere codice, eseguirlo, controllare il risultato, lavorare con i file, correggere gli errori e continuare finché il compito non è davvero finito.

È qui che l'Agents API di OpenAI diventa davvero utile.

Invece di costruire tu ogni passaggio, puoi dare all'agente il compito, i file di cui ha bisogno e un ambiente in cui lavorare, e lasciare che gestisca il resto.

In questo tutorial manterrò l'esempio semplice. Creeremo un piccolo dataset fittizio di vendite di un bar e lo daremo all'agente. L'agente scriverà ed eseguirà l'analisi, verificherà i risultati e creerà tre file di output per noi.

Una volta visto tutto il processo dietro le quinte, inizierai a capire quanta parte del normale flusso di lavoro di coding viene automatizzata per te. 

Se sei alle prime armi con gli agenti AI, ti consiglio di dare un'occhiata al nostro percorso di competenze AI Agents Fundamentals. 

Cos'è l'Agents API di OpenAI?

L'Agents API di OpenAI ti consente di dare a un agente un compito, i file di cui ha bisogno e l'ambiente in cui deve lavorare, per poi lasciare che gestisca il resto.

Invece di creare manualmente una sandbox, avviare una sessione, caricare i file, eseguire il codice, controllare gli errori e gestire ogni singolo passaggio, puoi inviare una sola richiesta API con il compito, la configurazione, l'ambiente e i file di input.

Dopo di che, gran parte del lavoro viene gestita dall'Agents API.

Sotto il cofano, OpenAI gestisce il Codex harness, inclusi orchestrazione, contesto, uso degli strumenti, esecuzione e sessioni di lunga durata. Puoi pensarla quasi come avere OpenAI Codex in esecuzione nel cloud per la tua applicazione. 

Non devi più preoccuparti troppo di configurare le risorse di calcolo, gestire l'ambiente di lavoro, tenere traccia della sessione o costruire da zero l'intero loop dell'agente.

Questo è particolarmente utile per attività più complesse e di lunga durata in cui l'agente deve effettivamente svolgere il lavoro, non solo restituire una risposta.

Per questo tutorial, useremo una sandbox ospitata da OpenAI:

Inviamo una richiesta con il file CSV, il compito e la configurazione dell'agente. 

L'Agents API quindi crea e gestisce per noi la sessione e la sandbox.

All'interno della sandbox, l'agente può esaminare il file, capire come impostare l'analisi, generare codice Python, eseguirlo, controllare i risultati e correggere eventuali problemi.

Una volta terminato tutto, gli output vengono salvati come artifacts di sessione. 

Possono essere grafici, dataset ripuliti, report o qualsiasi altro file creato dall'agente. Possiamo poi recuperare questi file e permettere all'utente di scaricarli e consultarli.

Quindi l'idea principale è semplice: inviamo una volta il compito e da lì l'agente si occupa del lavoro vero e proprio.

OpenAI Responses API vs Agents SDK vs Agents API: quale dovresti usare?

La differenza principale tra questi tre strumenti è quanto del flusso di lavoro vuoi gestire tu stesso.

Usa la Responses API quando ti serve che il modello completi un compito mirato, come riassunto, estrazione, classificazione, question answering, output strutturati o poche chiamate a strumenti.

Usa l'Agents SDK quando stai costruendo tu un'applicazione con agenti e vuoi più controllo su agenti, strumenti, handoff, guardrail e workflow multi-agente.

Usa l'Agents API quando il compito è più complesso e richiede un proprio ambiente di lavoro. È utile quando l'agente deve lavorare con file, eseguire codice, ispezionare i risultati, correggere gli errori e proseguire su più passaggi.

Guida passo passo: costruire un agente di analisi dati con OpenAI

Per questo tutorial, usiamo l'Agents API perché l'agente deve lavorare con un file, ragionare sull'analisi, eseguire codice, ispezionare i risultati e salvare gli artefatti finali per l'utente.

Iniziamo

1. Configura il tuo ambiente Python per l'Agents API

Per questo tutorial useremo un Jupyter Notebook per testare l'Agents API passo dopo passo e capire come funziona ogni parte. 

Inizieremo installando il pacchetto OpenAI e importando le librerie necessarie per il resto del tutorial.

Per prima cosa, installa o aggiorna il pacchetto OpenAI per Python:

%pip install -q --upgrade openai

Poi importa le librerie che useremo:

import base64
import csv
import io
import os
import random
from datetime import date, timedelta
from pathlib import Path

from IPython.display import Markdown, display
from openai import OpenAI

Ora crea il client OpenAI:

client = OpenAI()

Assicurati che la tua OPENAI_API_KEY sia già impostata nel tuo ambiente. Il client OpenAI la rileverà automaticamente.

2. Genera dati di esempio per l'agente AI

Creeremo un piccolo dataset di vendite fittizie così da avere qualcosa di semplice da dare all'agente.

random.seed(42)

products = {
    "Latte": 4.50,
    "Tea": 3.00,
    "Cookie": 2.50,
    "Sandwich": 7.00
}

locations = ["Downtown", "Airport", "Campus"]
first_day = date(2026, 1, 1)
orders = []

for order_id in range(1, 51):
    product = random.choice(list(products))

    orders.append(
        {
            "order_id": order_id,
            "date": first_day + timedelta(days=random.randint(0, 89)),
            "location": random.choice(locations),
            "product": product,
            "units": random.randint(1, 5),
            "unit_price": products[product],
            "discount_rate": random.choice([0, 0, 0, 0.10]),
        }
    )

Questo crea 50 ordini fittizi del bar su diversi prodotti, sedi, date e sconti. Usiamo un seed casuale fisso così da generare lo stesso dataset ogni volta che eseguiamo il notebook.

3. Crea e codifica il file CSV per la sandbox dell'agente

Successivamente, trasformeremo i dati generati in un file CSV che può essere passato all'agente.

csv_buffer = io.StringIO()

writer = csv.DictWriter(
    csv_buffer,
    fieldnames=orders[0].keys()
)

writer.writeheader()
writer.writerows(orders)

csv_text = csv_buffer.getvalue()

csv_base64 = base64.b64encode(
    csv_text.encode()
).decode()

print("Preview:")
print("\n".join(csv_text.splitlines()[:6]))

Output:

Preview:
order_id,date,location,product,units,unit_price,discount_rate
1,2026-01-04,Campus,Latte,3,4.5,0
2,2026-01-18,Campus,Tea,1,3.0,0
3,2026-01-05,Downtown,Sandwich,1,7.0,0
4,2026-03-06,Campus,Tea,1,3.0,0
5,2026-01-29,Airport,Sandwich,5,7.0,0

Codifichiamo anche il CSV in Base64 perché invieremo il file direttamente con la richiesta all'agente.

4. Definisci il compito dell'agente e gli output attesi

Ora descriveremo cosa vogliamo che l'agente faccia con il file CSV.

task = """
Analyze /workspace/cafe_sales.csv. Write /workspace/analyze_sales.py and run it.

Your job:
1. Check that the required columns exist and numeric values are valid.
2. Calculate gross_sales = units * unit_price.
3. Calculate net_sales = gross_sales * (1 - discount_rate).
4. Summarize net sales by location, product, and month.
5. Find the best-selling location and product by net sales.
6. Write these files:
   - /workspace/outputs/summary.json
   - /workspace/outputs/location_sales.csv
   - /workspace/outputs/morning_brief.md
7. Make the Morning Brief friendly and include three evidence-based insights.
8. Read the files back and verify that location totals equal total net sales.
9. Finish by reporting the verified total and the three output filenames.

Use only Python's standard library. Do not invent or silently change data.
""".strip()

La parte importante è che descriviamo l'obiettivo e gli output attesi, invece di scrivere noi stessi il codice dell'analisi.

L'agente può decidere come svolgere il lavoro, eseguire il codice e verificare i risultati prima di concludere.

5. Esegui l'agente nella sandbox ospitata da OpenAI

Ora invieremo tutto all'Agents API con una sola richiesta e lasceremo che l'agente svolga il lavoro effettivo nel cloud.

session_id = None
turn_id = None
response_parts = []

live_output = display(
    Markdown(""),
    display_id=True
)

with client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "You are a careful data analyst. "
            "Write simple code, run it, and verify the results."
        ),
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/cafe_sales.csv",
                "data": csv_base64,
            }
        ],
    },
    input=task,
    stream=True,
) as events:

    for event in events:

        if hasattr(event, "session_id"):
            session_id = event.session_id

        if event.type == "agent.session.turn.output_text.delta":
            response_parts.append(event.delta)

            live_output.update(
                Markdown("".join(response_parts))
            )

        elif event.type == "agent.session.turn.completed":
            turn_id = event.turn.id

        elif event.type.endswith(("failed", "cancelled")):
            raise RuntimeError(
                event.model_dump_json(indent=2)
            )

assert session_id and turn_id

live_output.update(
    Markdown("".join(response_parts))
)

print("✅ Analysis complete")
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")

È qui che avviene la maggior parte del lavoro.

Facciamo una richiesta che contiene configurazione dell'agente, ambiente ospitato, file CSV e compito. 

OpenAI crea la sessione gestita ed esegue l'agente all'interno della sandbox ospitata. L'agente può quindi ispezionare il file, scrivere analyze_sales.py, eseguirlo, controllare i risultati, correggere ciò che non va e creare i file finali di output. 

L'endpoint di creazione della sessione supporta sia l'ambiente sia l'input iniziale nella stessa richiesta.

Ci sono tre parti principali nella richiesta:

• agent indica a OpenAI quale modello usare e come deve comportarsi l'agente.
• environment fornisce all'agente il suo spazio di lavoro ospitato e inserisce il nostro file CSV al suo interno.
• input fornisce all'agente il compito che abbiamo definito nella sezione precedente.

Impostiamo anche stream=True. 

Questo non cambia come viene completato il compito. Ci permette semplicemente di ricevere eventi mentre l'agente lavora, invece di aspettare che l'intero turno finisca prima di vedere qualcosa.

In questo esempio ascoltiamo gli eventi agent.session.turn.output_text.delta e aggiorniamo continuamente il notebook con il testo più recente.

Quindi il testo che vediamo comparire sopra è il resoconto dei progressi dell'agente e la sua risposta finale. 

Il compito vero e proprio continua a essere eseguito nell'ambiente ospitato finché non riceviamo l'evento agent.session.turn.completed.

Nella mia esecuzione, l'agente ha creato ed eseguito analyze_sales.py, ha controllato i file generati e ha verificato vendite nette totali pari a 600,55.

La cosa importante è che il modello non si è limitato a dirci quale codice Python eseguire. L'agente ha effettivamente scritto il codice, lo ha eseguito, ha ispezionato il risultato e ha verificato l'output in autonomia.

6. Recupera e scarica gli artifacts di file dell'agente

Ora che l'agente ha finito, possiamo scaricare i file che ha creato durante quel turno.

download_dir = Path("cloud_bean_results")
download_dir.mkdir(exist_ok=True)

downloaded = []

for artifact in client.beta.agents.sessions.artifacts.list(
    session_id
):
    if artifact.turn_id == turn_id:

        destination = (
            download_dir / Path(artifact.path).name
        )

        with (
            client.beta.agents.sessions.artifacts
            .with_streaming_response
            .content(
                artifact.id,
                session_id=session_id
            )
        ) as response:
            response.stream_to_file(destination)

        downloaded.append(destination)

assert downloaded

print("Downloaded:")

for path in downloaded:
    print(f"- {path}")

Output:

Downloaded:
- cloud_bean_results/summary.json
- cloud_bean_results/morning_brief.md
- cloud_bean_results/location_sales.csv

Qui elenchiamo gli artifacts della sessione, teniamo quelli creati dal turno completato e li scarichiamo nella nostra cartella locale cloud_bean_results.

7. Elimina la sessione per risparmiare sui costi di calcolo della sandbox

Una volta terminato con i file, dovremmo eliminare la sessione per non mantenere l'ambiente gestito più a lungo del necessario.

result = client.beta.agents.sessions.delete(
    session_id
)

print(f"Session deleted: {result.deleted}")

Output:

Session deleted: True

Questo rimuove la sessione gestita dall'API. 

OpenAI segnala che la pulizia fisica delle risorse sottostanti può proseguire in modo asincrono dopo che la richiesta di eliminazione è stata completata.

Questo passaggio è particolarmente importante quando si utilizza una sandbox ospitata da OpenAI. 

La sandbox è l'ambiente di calcolo in cui l'agente esegue il codice e lavora con i file, e le sandbox ospitate usano risorse containerizzate fatturate separatamente dall'uso del modello. 

Quindi, se mantieni sessioni e ambienti attivi più a lungo del necessario, potresti accumulare costi di calcolo.

Considerazioni finali: l'Agents API di OpenAI vale il costo?

Ciò che mi ha colpito dell'Agents API è quanto riesca a fare con una semplice chiamata API.

Le abbiamo dato il file, il compito, la configurazione del modello e l'ambiente ospitato. 

Da lì, ha gestito il resto: ha creato lo spazio di lavoro, ha ispezionato i dati, ha scritto il codice Python, lo ha eseguito, ha controllato gli output, ha corretto il necessario e ha prodotto gli artefatti finali.

Sembra davvero di avere Codex in esecuzione nel cloud per la tua applicazione. 

Non ho dovuto preoccuparmi di impostare le risorse di calcolo, gestire il loop di esecuzione, trattare i file intermedi o tenere traccia di ogni passaggio. Ho dovuto soprattutto definire bene il compito e poi guardare il risultato.

L'esecuzione in sé ha impiegato circa due minuti, ma in quel tempo l'agente stava facendo parecchio dietro le quinte.

Ed è questo che la differenzia da una normale richiesta API. 

Non stai solo aspettando che un modello generi testo. Stai aspettando che un agente completi effettivamente un pezzo di lavoro.

Nei miei test, tre esecuzioni di questo esempio sono costate in totale circa $1,52, includendo l'uso del modello e dell'ambiente ospitato. 

Per un compito così piccolo, non è economico, quindi in produzione testerei sicuramente prima modelli più piccoli o economici.

Ma per lavori più complessi che implicano coding, debugging, file, ragionamento e più passaggi dipendenti, il costo extra può avere molto più senso.