OpenAI Agents SDK o Agents API: quale runtime scegliere

Il confronto tra OpenAI Agents SDK e OpenAI Agents API si gioca soprattutto su controllo e gestione operativa. OpenAI ha lanciato l’Agents API gestita il 10 settembre 2026: conviene quando lo stato delle sessioni, la compattazione e il ripristino rappresentano il vero costo operativo; l’Agents SDK è più adatto quando l’applicazione deve governare runtime, deployment e percorso dei dati. La scelta dipende da controllo e operatività, perché il servizio gestito non applica un costo separato per l’harness.

OpenAI Agents SDK o Agents API: quale scegliere?

L’OpenAI Agents API è la scelta predefinita più sensata per un piccolo team di piattaforma che deve portare in produzione agenti di lunga durata. OpenAI esegue l’harness di Codex, conserva la sessione e il lavoro salvato, compatta il contesto, coordina i subagenti e permette di riprendere l’esecuzione tra turni asincroni. In questo modo scompare una categoria di lavoro infrastrutturale che raramente differenzia il prodotto. OpenAI l’ha resa disponibile in beta pubblica il 10 settembre 2026 e dichiara che è accessibile a tutti gli sviluppatori.

Per un founder finanziato, affiancato da un piccolo team backend e con un agente di revisione documentale che può attendere approvazioni per ore, il valore della sessione gestita supera quello del controllo diretto sul loop. Il tempo limitato del team di prodotto va investito in policy, tool, valutazioni ed esperienza utente.

L’OpenAI Agents SDK è invece la scelta migliore quando il controllo del runtime è un requisito, non una preferenza. Funziona all’interno dell’applicazione, che mantiene la responsabilità di deployment, storage, logica di approvazione, implementazione dei tool e strategia per lo stato. Oggi un CTO di un’azienda mid-market con una policy Zero Data Retention obbligatoria dovrebbe scegliere questa strada, perché la beta pubblica dell’Agents API non supporta ZDR.

Per uno sviluppatore senior che dispone già di una flotta di worker, telemetria personalizzata e un percorso di ripristino collaudato, migrare soltanto per evitare la manutenzione di un loop modesto è uno scambio poco conveniente. L’SDK preserva quel controllo e fornisce comunque agenti, tool, handoff, guardrail, sessioni, revisione umana e tracing.

OpenAI Agents API e Agents SDK a confronto

La distinzione ufficiale riguarda il luogo in cui gira l’orchestrazione e chi possiede lo stato tra un’attività e l’altra. Entrambe le soluzioni possono chiamare modelli e tool di OpenAI; nessuna rende gratuiti i token dei modelli.

In pratica, il discrimine è semplice. Se l’agente completa una richiesta breve all’interno di un servizio esistente, il carico legato alla proprietà nell’SDK può essere minimo. Se invece modifica file, attende un’approvazione, sopravvive alle disconnessioni, delega attività e riprende il giorno successivo, ogni nuovo stato del ciclo di vita aumenta il valore dell’API gestita.

Harness e sandbox sono due decisioni distinte

L’Agents API gestisce il loop decisionale, ma non obbliga a eseguire ogni tool sull’infrastruttura OpenAI. OpenAI chiama questo loop gestito harness Codex: coordina chiamate ai modelli, uso dei tool, contesto, sessioni e subagenti. L’ambiente di esecuzione è una risorsa separata, nella quale vengono eseguiti i comandi e risiedono i file.

L’ambiente può essere assente, ospitato da OpenAI oppure self-hosted. Senza un ambiente, l’harness può comunque chiamare server MCP remoti e inviare chiamate di funzione all’applicazione, ma non dispone di Bash integrato, del tool apply-patch o dei file del workspace. Con una sandbox ospitata, OpenAI predispone il workspace Linux. Con un ambiente self-hosted, è l’executor dell’applicazione a eseguire comandi e operazioni sui file richiesti dall’harness gestito. La guida all’architettura esplicita questa separazione.

Comprendere questa differenza evita due errori costosi. Primo: scegliere l’Agents SDK solo perché il codice deve girare nella propria VPC è prematuro, dato che l’Agents API può collegarsi a un ambiente self-hosted. Secondo: scegliere l’Agents API affinché OpenAI esegua tutto è altrettanto prematuro, perché i gestori di funzioni dell’applicazione continuano a girare nel codice proprietario e, con un executor self-hosted, provisioning, riconnessione, arresto e persistenza dei file restano a carico dell’applicazione.

Per un flusso privato di analisi dati, l’harness gestito potrebbe inviare chiamate di funzione SQL a un servizio applicativo senza ricevere accesso a una shell generica. Per un agente di coding potrebbe usare una sandbox ospitata da OpenAI. Per un sistema di build proprietario potrebbe collegarsi a un worker isolato dell’azienda. Sono tre modalità di esecuzione sotto un’unica superficie di orchestrazione gestita.

Sessioni di lunga durata: qui vince l’Agents API

L’Agents API è favorita quando il ciclo di vita di un’attività supera la durata di una singola richiesta applicativa. Una sessione conserva la configurazione dell’agente, la conversazione e il lavoro salvato. Un nuovo input avvia un turno asincrono se la sessione è inattiva, oppure orienta il turno in corso mentre l’agente lavora. L’applicazione può seguire uno stream o ricevere i cambiamenti di stato tramite webhook.

OpenAI gestisce anche la compattazione del contesto quando la sessione si avvicina al limite disponibile. Compattare significa sostituire i dettagli meno recenti con una rappresentazione più piccola, così che l’agente possa continuare a lavorare attraversando più finestre di contesto. È un concetto semplice da spiegare ma difficile da gestire bene: il riepilogo conservato deve mantenere decisioni, risultati dei tool e attività incomplete, senza trascinarsi per sempre ogni token precedente.

Il ripristino è il vantaggio meno evidente. Gli stream di eventi non riproducono gli eventi persi. Dopo una disconnessione, l’applicazione recupera la sessione e gli elementi salvati, quindi prosegue dal record persistente invece di ricostruire un turno dell’agente dalla memoria del processo. La guida alle sessioni documenta la differenza tra un turno completato, uno fallito, una cancellazione e una sessione semplicemente inattiva.

Si consideri l’agente di revisione contratti di un founder finanziato: legge un documento, chiede a un subagente specializzato di confrontare le clausole, attende l’approvazione legale, riceve in seguito una correzione e produce un artefatto. Il valore del prodotto è nella revisione. Replay della sessione, compattazione, stream interrotti e ripristino dei turni sono costi operativi. È il tipo di carico che l’API gestita nasce per assorbire.

Il limite da dichiarare con chiarezza riguarda la precisione contabile. Gli agenti possono effettuare più chiamate ai modelli; agente root, subagenti, tentativi ripetuti, tool e sandbox contribuiscono tutti al costo. OpenAI specifica che i campi di utilizzo dell’Agents API sono best effort, possono essere null o cambiare in seguito e non costituiscono la fattura definitiva. I token di reasoning contano come token di output, mentre l’input memorizzato nella cache resta fatturabile. La guida all’utilizzo serve per il debug; per i controlli finanziari, i dati vanno poi riconciliati con quelli di fatturazione.

Anche la dashboard rientra nei confini dell’osservabilità. Il recupero dettagliato delle trace e gli exporter esterni non sono disponibili tramite l’API cliente della beta pubblica. Se la pipeline di telemetria richiede l’esportazione programmatica di ogni trace, questa lacuna pesa più di una dashboard gestita ben rifinita.

Controllo di runtime e deployment: qui vince l’Agents SDK

L’Agents SDK è favorito quando l’applicazione deve stabilire con precisione come un’esecuzione inizia, si interrompe, riparte, conserva lo stato, smista i tool e gestisce gli errori. Il runner esegue il loop dell’agente e gli handoff, ma il loop vive nel servizio applicativo. Il codice di prodotto può quindi racchiudere ogni transizione nelle proprie transazioni, code, limiti di frequenza, registri di approvazione e sistemi di telemetria.

L’SDK è disponibile per TypeScript e Python, e il repository Python adotta la licenza MIT. Il pacchetto non comporta quindi alcun costo per postazione. Chiamate ai modelli OpenAI, tool ospitati, provider di sandbox e capacità di calcolo dell’applicazione restano costi separati. La guida all’SDK lo presenta come soluzione per applicazioni code-first che gestiscono direttamente deployment, storage, approvazioni e integrazione del runtime.

Lo stato è flessibile, non automatico. Un’applicazione SDK può riprodurre result.history, salvare una sessione SDK nel proprio storage, collegare un ID di OpenAI Conversations oppure concatenare l’esecuzione dall’ID di una response precedente della Responses API. Ogni opzione ha un’utilità, ma la guida all’esecuzione degli agenti avverte che mescolare replay locale e stato gestito dal server può duplicare il contesto se i livelli non vengono riconciliati intenzionalmente.

Questa flessibilità ripaga in un servizio interno regolamentato. È possibile includere un’approvazione e la prosecuzione dell’agente nella stessa transazione di database, collocare lo stato in una regione autorizzata, eseguire i tool dietro controlli di rete privati e integrare l’agente in un sistema di job già esistente. Il livello dei modelli dell’SDK consente inoltre di integrare modelli o provider diversi, senza trasformare l’harness Codex gestito nel confine permanente dell’orchestrazione.

Il rovescio della medaglia è la responsabilità operativa. Un crash di processo diventa un problema di ripristino dell’applicazione. Una consegna duplicata nella coda diventa un problema di idempotenza. Crescita della cronologia, policy di compattazione, tentativi ripetuti dei tool, migrazioni dello stato e rollback del deployment ricadono tutti sul team. L’SDK offre controllo su ciascuno di questi aspetti, ma quel controllo ha valore solo se l’applicazione lo utilizza davvero.

Confronto dei costi: nessun sovrapprezzo per l’harness

Il conto per token e tool ospitati è identico quando i due runtime usano lo stesso modello OpenAI, lo stesso mix di token e le stesse chiamate ai tool. I prezzi sono stati verificati sulle pagine pubblicate da OpenAI l’11 settembre 2026. Con il listino standard per il contesto breve, GPT-6 Astra costa $10.00 per 1 milione di token di input e $50.00 per 1 milione di token di output. La ricerca web costa $10.00 ogni 1,000 chiamate, più i token dei contenuti di ricerca alla tariffa del modello scelto. L’Agents API gestita non aggiunge alcun costo separato.

Ecco un carico di lavoro normalizzato. Sono ipotesi, non dati osservati in produzione:

• 1,000 job dell’agente al mese.
• Ogni job usa complessivamente 10,000 token di input non memorizzati nella cache e 2,000 token di output su GPT-6 Astra. Il contenuto restituito dalla ricerca è incluso nella quota di input.
• Ogni job effettua una chiamata di ricerca web.
• Nel caso Agents API ospitato, ogni job apre una nuova sessione di fatturazione in un container da 1 GB al prezzo pubblicato di $0.03. Riutilizzare una sandbox ridurrebbe questa voce.
• Nel caso SDK si ipotizza un unico worker condiviso da $40 al mese, con capacità sufficiente. Storage, rete e lavoro umano sono esclusi.

La componente modello è composta da $0.10 per l’input e $0.10 per l’output, quindi $0.20 per job. Sul mix ipotizzato di 12,000 token, equivale a $0.0167 ogni 1,000 token combinati del modello. Una chiamata di ricerca web aggiunge $0.01, portando la spesa OpenAI comune a $0.21 per job.

Con 1,000 job, l’Agents API con un nuovo container ospitato da 1 GB per ogni job costa $240: $210 per l’utilizzo comune di modello e ricerca, più $30 per i container. Il caso SDK costa $250: gli stessi $210 di utilizzo OpenAI, più i $40 ipotizzati per il worker. A questo volume ridotto, i container ospitati vincono sul costo diretto.

Con 10,000 job, il caso gestito e ospitato arriva a $2,400: $2,100 di spesa comune più $300 di container. Il caso SDK raggiunge $2,140 con il worker condiviso ipotizzato. Il punto di pareggio del costo diretto di calcolo è a 1,334 nuove sessioni container al mese: è il primo numero intero di sessioni per cui $0.03 a sessione supera $40.

La riga più importante è quella dell’Agents API self-hosted. Se usa lo stesso worker ipotizzato da $40, anche il totale per 10,000 job è $2,140. L’harness Codex resta gestito, mentre il costo di esecuzione coincide con lo scenario SDK perché OpenAI non applica un sovrapprezzo per l’harness.

Il conto in denaro ignora comunque la variabile principale: il tempo degli ingegneri. Sopra il punto di pareggio, risparmiare $260 al mese in capacità di calcolo è irrilevante se l’SDK assorbe diverse ore di lavoro della piattaforma. Sotto quel punto, mantenere un sistema SDK maturo può costare quasi nulla.

Per applicare limiti di budget rigorosi a entrambe le architetture, le stime del carico vanno affiancate alle misure di sicurezza a livello di progetto descritte in Controlli di budget per le API degli agenti AI nel 2026. Una stima è uno strumento di pianificazione, non un meccanismo di applicazione dei limiti.

Migrare all’Agents API: quanto costa lasciare l’SDK

Passare dall’Agents SDK all’Agents API è una migrazione del runtime, non un semplice cambio di pacchetto. Definizioni degli agenti e schemi dei tool possono risultare familiari, ma ID di sessione, sessioni SDK, conversazioni della Responses API, sessioni dell’Agents API e sandbox sono risorse diverse. Lo stato va trattato come dato che attraversa un confine, non come identificatore trasferibile senza modifiche.

1. 1

   Fissare il contratto di comportamento

   Documentare le istruzioni attuali dell’agente, gli schemi dei tool, i punti di approvazione, il formato dell’output, il budget di token e la policy per gli errori. Durante il confronto, modello e tool devono restare invariati, così una variazione di qualità non verrà scambiata per un miglioramento del runtime.

2. 2

   Mappare configurazione di agente e tool

   Trasferire modello, istruzioni, connessioni MCP e definizioni delle funzioni nella configurazione dell’Agents API. I gestori delle funzioni dell’applicazione richiedono ancora un servizio che riceva le chiamate e restituisca i risultati: non diventano ospitati solo perché l’orchestrazione è stata spostata.

3. 3

   Definire il confine dello stato

   Avviare le nuove conversazioni come sessioni dell’Agents API e archiviarne gli ID accanto ai record delle conversazioni dell’applicazione. Durante la transizione, mantenere leggibili le cronologie legacy dell’SDK. Se il vecchio contesto deve proseguire, trasformare soltanto lo stato di business necessario in un input esplicito, senza fingere che una sessione SDK sia una sessione dell’Agents API.

4. 4

   Sostituire la gestione del ciclo di vita

   Sostituire l’entry point del runner in-process con creazione della sessione, eventi, elementi salvati, azioni richieste, webhook, cancellazione ed eliminazione. Aggiungere idempotenza intorno a ogni webhook e risultato di funzione, perché lo stato gestito non elimina il rischio di consegne duplicate ai confini dell’applicazione.

5. 5

   Eseguire shadow test e regressione

   Eseguire lo stesso set di valutazione su entrambi i percorsi. Confrontare riuscita delle attività, token totali di input e output, chiamate ai tool, tempo trascorso, comportamento del ripristino e intervento umano. Spostare il traffico solo dopo che il nuovo percorso soddisfa il contratto precedente.

Un budget di migrazione esemplificativo rende concreto lo scambio. Si ipotizzi un flusso esistente con tre tool basati su funzioni, sessioni persistenti e approvazione umana. Si assegnano 24 ore di lavoro tecnico a $150 l’ora: 6 ore per configurazione e mappatura dei tool, 8 per sessioni e ciclo di vita, 6 per webhook, ripristino e idempotenza e 4 per regressione e verifiche dei costi. Il costo una tantum è $3,600.

Se compattazione, ripristino, sessioni e orchestrazione gestiti fanno risparmiare le 6 ore mensili di lavoro tecnico ipotizzate, il risparmio è $900 al mese e l’investimento si ripaga in quattro mesi. Se il percorso SDK attuale richiede solo interventi occasionali, il ritorno può scomparire. Sono proprio le ipotesi a contare: la migrazione si giustifica con il lavoro operativo eliminato, non con token più economici.

Quando non conviene passare all’Agents API

Non bisogna migrare se i controlli sui dati della beta pubblica non superano la verifica del procurement. L’attuale panoramica dell’Agents API specifica che la residenza dei dati è limitata agli Stati Uniti e che Zero Data Retention non è supportato. Una sandbox self-hosted non cambia questa policy, perché harness e sessione continuano a risiedere nel servizio gestito.

È preferibile restare sull’Agents SDK quando si verifica una di queste condizioni:

• Il runtime deve funzionare sotto uno scheduler personalizzato, un confine transazionale o vincoli di latenza controllati direttamente dall’applicazione.
• Le policy su storage, esportazione delle trace o residenza dei dati non sono compatibili con la beta pubblica gestita.
• L’agente richiede flessibilità nella scelta del provider o un’astrazione dei modelli che non debba dipendere dall’harness Codex.
• Il sistema SDK dispone già di compattazione, ripristino, osservabilità e deployment affidabili, con poca manutenzione continuativa.
• La maggior parte delle attività è breve e senza stato, quindi una sessione gestita persistente elimina poca infrastruttura.

La beta pubblica implica anche una decisione sulla maturità della release. OpenAI dichiara che continuerà a iterare rapidamente prima della disponibilità generale. Un team con un calendario rigido di change management può preferire una valutazione immediata e rimandare la migrazione fino alla stabilizzazione del contratto.

Anche l’SDK ha un caso in cui va evitato. Una startup snella non dovrebbe sceglierlo solo per scongiurare un lock-in teorico, mentre ricostruisce in silenzio sessioni, ripristino, ciclo di vita della sandbox e orchestrazione. Il controllo che il prodotto non usa diventa debito di manutenzione.

Per gli agenti che devono eseguire codice, il livello dell’ambiente va confrontato separatamente in Le migliori sandbox di codice per agenti AI nel 2026. La scelta della sandbox non stabilisce chi debba possedere lo stato dell’orchestrazione.

I risultati dei clienti sono indicativi, non trasferibili

I primi numeri favoriscono il percorso gestito, ma sono dichiarazioni di clienti pubblicate nel post di lancio OpenAI del 10 settembre, non un benchmark indipendente e controllato. SafetyKit ha segnalato una riduzione del 60% del costo per caso. Hypha ha indicato una riduzione dell’86% nelle risposte fallite degli agenti dopo aver separato l’harness gestito dalla propria sandbox. Ciridae ha riportato un aumento del punteggio di valutazione da 0.71 a 0.85 e una riduzione della latenza di 4x.

Questi risultati dimostrano che il confine del runtime può fare la differenza. Non permettono però di stimare il risparmio di una specifica migrazione, perché il post non normalizza architettura precedente, mix di modelli, volume di token, difficoltà delle attività o lavoro tecnico dei clienti. Sono un motivo per avviare una valutazione shadow, non una base per fare previsioni.

FAQ su OpenAI Agents API e Agents SDK

Perché usare OpenAI Agents SDK?

OpenAI Agents SDK è indicato quando l’applicazione deve possedere direttamente deployment, storage, decisioni di approvazione, implementazione dei tool e loop del runtime. Offre le primitive per agenti di OpenAI senza trasferire l’orchestrazione nell’Agents API gestita.

Meglio OpenAI Agents SDK o PydanticAI?

È un confronto distinto tra framework. Prima occorre decidere se affidare a OpenAI la gestione dell’harness Codex tramite Agents API oppure mantenere nell’applicazione un runtime SDK; soltanto dopo ha senso confrontare i framework SDK all’interno della seconda opzione.

Qual è il miglior SDK per agenti AI?

Non esiste un SDK migliore per ogni architettura. OpenAI Agents SDK è una scelta solida quando il suo loop TypeScript o Python, i tool, gli handoff, i guardrail, le sessioni e le integrazioni OpenAI corrispondono alle esigenze dell’applicazione e si vuole mantenere il controllo del deployment.

OpenAI Agents SDK è gratuito?

L’Agents SDK per Python ha licenza MIT, quindi il pacchetto non ha costi di licenza. Restano a pagamento chiamate ai modelli, tool a pagamento, servizi di sandbox e infrastruttura che esegue l’applicazione.

Come si usa OpenAI Agents SDK?

Si installa il pacchetto ufficiale TypeScript o Python, si definisce un agente con istruzioni e tool, si sceglie un’unica strategia per lo stato e lo si esegue nell’applicazione. Approvazioni, persistenza, tracing e sandboxing vanno aggiunti soltanto dove il flusso li richiede.

Quanto costa un agente OpenAI?

Il calcolo deve includere input del modello, input memorizzato nella cache, output, chiamate ai tool, sandbox o capacità di calcolo dell’applicazione, servizi di terze parti e lavoro operativo. Non c’è alcun costo separato per l’harness dell’Agents API; secondo le ipotesi di questo articolo, il costo diretto dell’ambiente cambia convenienza a 1,334 nuove sessioni mensili in container da 1 GB rispetto a un worker condiviso da $40.

L’API OpenAI è gratuita o a pagamento?

L’utilizzo dei modelli e dei tool a pagamento dell’API OpenAI viene conteggiato secondo i prezzi dell’API. Un piano ChatGPT è un contratto di prodotto separato e non copre l’utilizzo API di un’applicazione basata su Agents API o Agents SDK.

Perché pagare $20 per ChatGPT?

È una decisione sull’abbonamento ChatGPT, non una scelta tra Agents API e SDK. L’abbonamento ChatGPT acquista l’accesso al prodotto ChatGPT secondo le condizioni del piano; l’utilizzo dell’API OpenAI viene fatturato separatamente.

OpenAI Agent Builder è gratuito o a pagamento?

Agent Builder era incluso nei prezzi standard dei modelli API, ma non coincide con nessuno dei due runtime confrontati qui. OpenAI dichiara che ne sta riducendo progressivamente l’operatività e che la chiusura è prevista per il 30 novembre 2026.

La mossa da fare lunedì

La prossima settimana, occorre scegliere un flusso di lunga durata e avviare un confronto shadow. Modello, istruzioni, budget di token, tool e set di valutazione devono restare costanti. Le nuove conversazioni di test vanno instradate sull’Agents API, mantenendo le cronologie utente esistenti sul percorso SDK; per isolare il valore dell’harness gestito, si può scegliere lo stesso ambiente di esecuzione su entrambi i lati.

Registrare riuscita delle attività, token complessivi, chiamate ai tool a pagamento, sessioni di fatturazione della sandbox, incidenti di ripristino, intervento umano e tempo tecnico. L’Agents API è la scelta giusta se il lavoro eliminato su sessioni e ripristino vale più del controllo ceduto. Conviene mantenere l’Agents SDK se il servizio gestito non soddisfa un requisito sui dati o se il tempo operativo risparmiato è insufficiente a recuperare il costo della migrazione.

Prima di cambiare il runtime di un agente, scarica la checklist di audit dei flussi di lavoro AI per le aziende.