OpenAI Agents API vs Agents SDK vs Responses API: Su cosa dovresti sviluppare nel 2026?

Lo stack per agenti di OpenAI è cambiato radicalmente a settembre 2026. La nuova Agents API ha introdotto un harness Codex gestito per agenti cloud duraturi, mentre il precedente Agents SDK è passato a una fase di manutenzione feature-complete. La Responses API rimane la superficie di livello inferiore per le applicazioni che necessitano di chiamate dirette al modello o che desiderano gestire autonomamente l'agent loop. Non si tratta di tre wrapper intercambiabili per la stessa cosa: definiscono il perimetro di runtime in punti diversi.

L'architettura è cambiata: scegli un perimetro di runtime, non una libreria

La decisione cruciale non è più semplicemente «Quale SDK dovrei installare?» Riguarda chi gestisce l'harness, l'agent loop, lo stato duraturo della sessione, la compattazione del contesto, il ripristino, l'ambiente di esecuzione e il ciclo di vita dell'applicazione.

L'attuale panoramica di OpenAI sugli agenti rende esplicito questo confine. La Agents API esegue un harness Codex ospitato e gestisce l'orchestrazione insieme allo stato duraturo della sessione. La Responses API fornisce risposte del modello e funzionalità ospitate mentre la tua applicazione gestisce l'agent loop circostante. L'Agents SDK esegue il loop nella tua applicazione ed è ora completo dal punto di vista delle funzionalità, non rappresentando più la strada principale per lo sviluppo di nuove funzionalità per gli agenti.

Il confronto in sintesi

1. Agents API: harness gestito, agente cloud duraturo

La Agents API espone l'harness Codex attraverso un servizio gestito da OpenAI. OpenAI gestisce le sessioni, l'orchestrazione, la compattazione del contesto e il ripristino. La tua applicazione continua a fornire gli strumenti e a selezionare l'ambiente di esecuzione.

Quest'ultima distinzione è importante. «Agente gestito» non significa necessariamente «tutta l'elaborazione viene eseguita all'interno di OpenAI». L'architettura della Agents API supporta l'assenza di ambiente, un ambiente ospitato da OpenAI oppure un ambiente self-hosted collegato all'harness gestito. Con un ambiente self-hosted, la tua applicazione gestisce provisioning, riconnessione, arresto e file persistenti, mentre l'harness rimane gestito.

La Agents API è quindi un servizio di runtime, non un semplice formato di richiesta. Le sessioni possono persistere, inviare lo stato di avanzamento in streaming, ricevere task aggiuntivi, usare strumenti, manipolare file e ripristinarsi nel corso di attività prolungate.

Cosa ottieni con la Agents API

• Un harness Codex gestito invece di dover costruire e gestire autonomamente l'agent loop principale.
• Sessioni durature per attività che si estendono su più turni e operazioni di lunga durata.
• Orchestrazione, compattazione del contesto e ripristino gestiti.
• Ambienti di esecuzione ospitati da OpenAI o self-hosted, a seconda dei requisiti del carico di lavoro.
• Streaming e webhook per gli avanzamenti e gli eventi del ciclo di vita.
• Una direzione di piattaforma che OpenAI raccomanda esplicitamente per le nuove applicazioni basate su agenti.

Cosa rimane sotto la tua gestione

• Il tuo prodotto e il server dell'applicazione.
• Le implementazioni dei function tool e la logica di business.
• Le decisioni relative ad autorizzazioni e policy per i tuoi sistemi.
• Il ciclo di vita dell'ambiente di esecuzione quando scegli un'infrastruttura di calcolo self-hosted.
• La valutazione, i criteri di accettazione, i guardrail specifici di dominio e la decisione su cosa l'agente è autorizzato a fare.

2. Responses API: gestisci il ciclo, usa le primitive della piattaforma

L'API Responses è la scelta di livello inferiore quando desideri le funzionalità dei modelli e degli strumenti di OpenAI senza delegare l'intero runtime dell'agente. OpenAI descrive Responses come la primitiva API consigliata per i nuovi progetti e come un'evoluzione di Chat Completions dotata di strumenti integrati, opzioni di stato multi-turn, input multimodale e uso agentico degli strumenti.

Una richiesta Responses può a sua volta invocare strumenti, ma la tua applicazione rimane responsabile del flusso di lavoro complessivo quando costruisci un agente attorno ad essa. Ciò significa che il tuo codice decide come mantenere lo stato dell'applicazione, quando proseguire, come gestire il ripristino, come coordinare gli specialisti, come compattare le cronologie estese e come rappresentare il lavoro ripristinabile.

Questo approccio non è intrinsecamente inferiore. È il confine ideale quando il comportamento dell'agente deve essere profondamente integrato nella logica applicativa esistente, quando è necessario un modello di stato personalizzato o quando un harness gestito nasconderebbe un livello di controllo di cui hai effettivamente bisogno.

3. Agents SDK: supportato, ma non più il percorso predefinito per il futuro

L'Agents SDK rimane un framework open source per l'esecuzione di flussi di lavoro di agenti all'interno della tua applicazione. Fornisce definizioni di agenti, strumenti, passaggi di consegne (handoff), guardrail, tracciamento, sessioni e il ciclo di esecuzione (runner loop) in TypeScript e Python.

Tuttavia, il suo ruolo strategico è cambiato. OpenAI ora etichetta l'Agents SDK come completo nelle funzionalità (feature complete): la manutenzione, le correzioni di sicurezza, le risoluzioni di bug critici e gli aggiornamenti di compatibilità continuano, ma non sono previste nuove funzionalità principali. OpenAI consiglia l'Agents API per le nuove applicazioni.

Ciò non significa che un'applicazione SDK esistente debba essere riscritta immediatamente. Significa piuttosto che l'architettura non dovrebbe più dare per scontato che l'SDK sia la sede in cui approderanno le prossime importanti funzionalità del runtime degli agenti.

Dove si colloca il Codex SDK

La scelta attuale non è una semplice suddivisione a tre vie. La panoramica del runtime di OpenAI include il Codex SDK come opzione per eseguire l'harness di Codex nell'infrastruttura che gestisci direttamente. Questa impostazione è architettonicamente diversa sia dall'Agents API ospitata sia dall'Agents SDK.

Se la tua effettiva esigenza è “Desidero l'harness di Codex, ma devo gestirlo autonomamente”, il Codex SDK è la superficie da valutare. Se la tua esigenza è “Voglio avere il pieno controllo del ciclo attorno alle chiamate del modello”, valuta Responses. Se la tua esigenza è “Ho già un'applicazione funzionante basata sull'Agents SDK”, l'SDK esistente può rimanere valido mentre pianifichi le prossime mosse in base al suo stato di manutenzione.

Il test sul controllo del runtime

Una decisione architetturale efficace inizia stabilendo quali aspetti il tuo team deve controllare direttamente. Assegna a ciascun requisito una classificazione tra controllo obbligatorio, preferenza per il controllo o preferenza per la gestione delegata.

Un albero decisionale per i nuovi sistemi

Cosa non dovrebbe guidare la decisione

La migrazione è un cambiamento architetturale, non la ridenominazione di una import

Il passaggio dall'Agents SDK all'Agents API cambia la proprietà dei componenti. Nell'SDK, il ciclo viene eseguito all'interno dell'applicazione. Nell'Agents API, OpenAI gestisce l'harness e la sessione, mentre l'applicazione si integra tramite attività, eventi, strumenti e confini dell'ambiente.

Un piano di migrazione concreto deve quindi mappare lo stato della sessione, l'orchestrazione personalizzata, gli handoff, l'esecuzione dei tool, le approvazioni, lo storage, il tracing, i tentativi di retry, il ripristino dai guasti, il ciclo di vita dell'ambiente e qualsiasi astrazione specifica del provider. Il volume di codice potrebbe ridursi, mentre cambiano i presupposti operativi.

L'inventario per la migrazione

• Definizioni degli agenti e titolarità delle istruzioni.
• Definizioni dei tool e dove ciascun tool viene eseguito.
• Handoff, pattern manager/specialist e comportamento dei sotto-agenti.
• Identificatori di sessione, stato della conversazione, capacità di ripresa e conservazione della cronologia.
• Approvazioni umane e semantica di interruzione.
• Logica personalizzata di trimming o compattazione del contesto.
• Tracing, valutazioni, osservabilità e debugging in produzione.
• File self-hosted, container, accesso a reti private o altre dipendenze di esecuzione.
• Astrazione del provider o dipendenze da modelli non-OpenAI.
• Presupposti su tentativi di retry, timeout, idempotenza, ripristino e ciclo di vita.

La beta pubblica cambia il modello di rischio

L'Agents API è la direzione consigliata per le nuove applicazioni basate su agenti, ma è anche in versione beta pubblica. Questi elementi non sono in contraddizione. La direzione strategica risponde a "dove sta andando la piattaforma?". Lo stato di beta risponde a "quante modifiche a livello di interfaccia e operative devo preventivare?"

Per i sistemi di produzione, isola l'integrazione dietro un perimetro applicativo. Mantieni lo stato del dominio, i permessi, i dati di audit e le regole di business all'esterno degli oggetti di sessione specifici del vendor, ove possibile. In questo modo è più facile assorbire l'evoluzione delle API senza trasformare il runtime dell'agente nell'unica fonte di verità per l'intero prodotto.

Un'architettura predefinita pratica

Per molte nuove applicazioni native per OpenAI, una configurazione predefinita ragionevole per il 2026 è: Agents API per l'harness gestito e la sessione persistente, servizi di dominio e autorizzazione di proprietà dell'applicazione, tool funzionali espliciti per le azioni di business ed esecuzione gestita da OpenAI o self-hosted a seconda dei requisiti di dati e calcolo.

Ciò mantiene potente il runtime dell'agente senza renderlo il titolare delle verità di business. L'applicazione decide comunque cosa può fare un utente, quali dati sono autorevoli, quali azioni richiedono approvazione e come vengono convalidati i risultati.

Cosa potrebbe cambiare questa risposta?

La raccomandazione cambia se l'Agents API aggiunge o rimuove funzionalità, esce dalla beta con contratti diversi, modifica i limiti di ambiente o di prezzo, oppure introduce strumenti di migrazione che riducono le differenze di gestione. Cambia anche se la tua applicazione dipende dalla portabilità del provider, da semantiche di orchestrazione personalizzate, da un'esecuzione esclusivamente locale o da una capacità che l'harness hosted non può supportare.

Per un'applicazione esistente basata su Agents SDK, la risposta cambia anche in funzione del costo di migrazione. Se il sistema è stabile, ben valutato e non limitato dallo stato feature-complete dell'SDK, una migrazione immediata potrebbe comportare più rischi che benefici. Se la roadmap del prodotto dipende da capacità introdotte solo nell'Agents API, ritardare la migrazione può generare un debito tecnico differente.

Limitazioni

Questo confronto si concentra sulla titolarità del runtime e sulla direzione dichiarata della piattaforma OpenAI. Non fornisce benchmark di latenza, qualità o costo totale per un carico di lavoro specifico. Tali proprietà dipendono dalla scelta del modello, dall'uso dei tool, dall'ambiente, dalla lunghezza dell'attività, dal caching, dall'uso di sandbox e dall'architettura complessiva dell'applicazione.

L'Agents API è inoltre abbastanza recente da far sì che l'esperienza in produzione si stia ancora consolidando. Un'architettura dovrebbe quindi essere convalidata con carichi di lavoro rappresentativi piuttosto che scelta unicamente in base al posizionamento del prodotto.

Conclusione

La scelta del runtime degli agenti OpenAI nel 2026 riguarda fondamentalmente la proprietà del runtime. L'Agents API implica che OpenAI gestisca gran parte dell'harness e dei meccanismi per le sessioni persistenti. Responses significa che la tua applicazione gestisce il ciclo attorno alle primitive della piattaforma. L'Agents SDK rimane valido per i sistemi esistenti, ma non è più la destinazione predefinita per le nuove funzionalità principali del runtime degli agenti.

Per una nuova applicazione, segui la direzione della piattaforma a meno che un requisito concreto non richieda di scendere a un livello inferiore dello stack. Inizia con l'Agents API, passa a Responses quando hai bisogno di gestire direttamente il ciclo, valuta il Codex SDK quando hai bisogno dell'harness nella tua infrastruttura e mantieni l'Agents SDK dove gli investimenti esistenti o temporanee lacune di funzionalità lo giustificano.

FAQ

Glossario

Fonti primarie e approfondimenti