OpenAI Agents API: che cosa gestisce l'harness di Codex
OpenAI ospita il ciclo di Codex per la tua applicazione. Spiego le differenze rispetto all'SDK, la persistenza delle sessioni e i costi che rimangono.
L’Agents API di OpenAI, lanciata in beta pubblica il 10 settembre 2026, permette di usare l’infrastruttura gestita di Codex nelle proprie applicazioni. OpenAI esegue il ciclo dell’agente, mentre l’applicazione assegna lavoro e riceve risultati. Il vantaggio è costruire meno infrastruttura attorno al modello, mantenendo la responsabilità delle decisioni su strumenti e accessi. [1] [2]
Che differenza c’è rispetto a Responses e all’Agents SDK?
La differenza principale è chi esegue l’agente. Con l’Agents API, OpenAI ospita l’harness. Con l’Agents SDK, il tuo codice esegue un framework che gestisce il ciclo. Usando direttamente la Responses API, l’applicazione assume più responsabilità sulle fasi tra le risposte del modello. La documentazione di architettura e quella dell’SDK di OpenAI distinguono esplicitamente queste opzioni. [2] [9]
L’harness è il software attorno al modello che fa avanzare un compito: fornisce contesto, richiama strumenti e stabilisce quando serve un’altra chiamata al modello. Una singola chiamata è soltanto una parte di questo lavoro. L’annuncio di OpenAI include nell’offerta gestita la gestione delle sessioni, la compattazione del contesto e la delega parallela. Compattare significa ridurre il contesto accumulato per consentire all’agente di continuare mentre la conversazione cresce. [1]
| Responsabilità | Responses API | Agents SDK | Agents API |
|---|---|---|---|
| Ciclo dell'agente | La tua applicazione | SDK nel tuo ambiente | Ospitato da OpenAI |
| Motivo abituale della scelta | Controllare ogni passaggio | Usare un framework per agenti | Usare un harness gestito |
| Regole dell'applicazione | Le definisci tu | Le definisci tu | Le definisci tu |
La considero una scelta operativa. Se mantenere il ciclo sta rallentando il prodotto, affidarlo a OpenAI può essere utile. Se controllare ogni transizione è ciò che fa funzionare la tua applicazione, valuta questo compromesso prima di migrare. Una nuova API non rende obsoleta un’applicazione costruita con l’SDK.
Una discussione su r/artificial, il 10 settembre, mostrava entrambe le reazioni: interesse per gli agenti come infrastruttura e domande sui confini dell’ambiente sandbox. È un punto di partenza più utile che chiedersi se un altro framework sia di moda. La domanda pratica è quali responsabilità vuoi delegare. [8]
Una sessione persistente conserva tutti i file dell’agente?
Una sessione persistente conserva la conversazione e il lavoro salvato dell’agente, ma l’ambiente di esecuzione ha un proprio ciclo di vita. L’architettura di OpenAI separa applicazione, harness ospitato e ambiente. Trattarli come un unico computer permanente sarebbe un errore. [2] [3]
L’ambiente è il luogo in cui gli strumenti eseguono codice e accedono allo spazio di lavoro. Può essere ospitato da OpenAI o fornito dallo sviluppatore. Un agente può anche funzionare senza: l’opzione documentata none non include Bash, lo strumento apply-patch o un filesystem di lavoro, ma permette strumenti MCP remoti via HTTP. MCP è il protocollo che collega l’agente a strumenti esterni. [2]
La documentazione delle sessioni indica di riutilizzare l’identificatore della sessione per il lavoro successivo. Distingue inoltre gli elementi salvati dagli eventi in diretta: uno stream disconnesso non riproduce tutti gli eventi persi, quindi l’applicazione deve recuperare gli elementi salvati quando si ricollega. Questo dettaglio tecnico ha una conseguenza diretta sul prodotto. L’interfaccia deve recuperare lo stato reale del compito, senza interpretare il silenzio come assenza di attività. [3]
Per i file definirei la consegna in modo esplicito: che cosa deve produrre l’agente, dove lo copierà l’applicazione e quale risultato indica che il lavoro è concluso. È un requisito di progettazione anche quando il fornitore gestisce la sessione. Una conversazione riuscita non è ancora un risultato consegnato in modo affidabile.
I sottoagenti paralleli hanno permessi indipendenti?
I sottoagenti documentati condividono filesystem e ambiente del coordinatore ed ereditano gli accessi configurati agli strumenti. Li tratterei come agenti che condividono lo stesso perimetro di sicurezza. OpenAI documenta anche una restrizione specifica della beta: i sottoagenti non supportano gli strumenti di funzione. [4]
La distinzione conta nel progettare l’applicazione. Uno strumento di funzione espone funzionalità personalizzate della tua applicazione; gli strumenti MCP remoti sono un altro percorso di integrazione. Se il compito dipende da una funzione personalizzata, non presumere che delegarlo dia al sottoagente le stesse capacità del coordinatore. Verifica il percorso supportato prima di affidargli l’intero risultato.
Comincerei con compiti indipendenti e risultati chiari, come esaminare moduli diversi, lasciando l’integrazione finale al coordinatore. I file condivisi rendono possibile la collaborazione, ma anche modifiche sovrapposte. Il parallelismo è utile quando i risultati si combinano senza dover annullare il lavoro degli altri.
Cambia anche il calcolo dei costi. OpenAI avverte che aggiungere sottoagenti può aumentare il consumo di token. Un’esecuzione più breve può comportare più lavoro complessivo: «finito prima» e «costato meno» vanno quindi misurati separatamente. [4]
Quali decisioni su sicurezza e dati restano tue?
I permessi dell’ambiente contano ancora perché il codice eseguito dall’agente può raggiungere file, credenziali e risorse di rete disponibili al suo interno. La guida alla sicurezza di OpenAI raccomanda di limitare l’accesso in uscita e tenere la chiave API dell’applicazione fuori dall’ambiente di esecuzione. Ospitare il ciclo non stabilisce quali sistemi aziendali l’agente possa modificare. [5]
Per un assistente di revisione del codice, comincerei con l’accesso al repository e un canale in cui restituire i finding. Consentire deploy o modifiche ai dati dei clienti richiederebbe una decisione di prodotto separata. Il confine importante è l’azione consentita dall’applicazione, non quanto prudente si descriva l’agente.
Un servizio con stato può essere adatto a un utente che ritorna o a un lavoro continuativo. L’applicazione deve però definire consapevolmente il ciclo di vita di quello stato. Deciderei quando conservare o eliminare le sessioni durante la progettazione della funzione, prima di lasciarle accumulare senza limiti.
Quanto costa l’Agents API?
OpenAI dichiara che l’Agents API non aggiunge una tariffa propria: gli sviluppatori pagano token e strumenti utilizzati. Il budget rilevante comprende quindi l’intero compito, incluse le chiamate ripetute al modello e il lavoro delegato. Un agente che continua a lavorare per ore non diventa gratuito per questo. [1]
La pagina dei prezzi separa i costi dei token da quelli degli strumenti. I container di esecuzione ospitati sono fatturati in base a risorse e tempo, mentre strumenti come la ricerca web possono aggiungere costi per chiamata. Una stima deve includere l’ambiente scelto, non soltanto i token di output. [10]
La documentazione sull’osservabilità precisa una limitazione dei contatori visibili nell’applicazione. L’utilizzo per sessione e turno può essere incompleto o cambiare, e OpenAI afferma espressamente che quei dati non sono una fattura definitiva. Servono a capire l’esecuzione, mentre la spesa effettiva va riconciliata con i dati di fatturazione. [7]
La mia prima valutazione sarebbe quindi un carico piccolo e ripetibile, con una condizione di completamento chiara. Registrerei se il risultato supera la revisione, quali azioni esterne sono avvenute e quanto è costato completare il compito. Poi lo confronterei con l’applicazione esistente, includendo il lavoro necessario per mantenerla.
L’Agents API merita attenzione quando gestire l’infrastruttura dell’agente diventa un peso per il prodotto. La prima domanda è concreta: quali responsabilità su ciclo, stato ed esecuzione può gestire OpenAI senza togliere il controllo di cui l’applicazione ha bisogno?