Migrare dall'SDK OpenAI Agents all'API Agents: cosa cambia effettivamente a livello architetturale?

Migrare dall'OpenAI Agents SDK all'Agents API non è una semplice rinomina di import. Il confine architetturale principale cambia: l'SDK esegue il loop dell'agente all'interno della tua applicazione, mentre l'Agents API esegue un harness Codex gestito e una sessione durevole sul lato di OpenAI. La domanda di migrazione non è quindi "Quali classi corrispondono a quali endpoint?" ma "Quali responsabilità di runtime attraversano il confine, quali rimangono nella nostra applicazione e quali devono essere riprogettate?"

La migrazione va da un loop di proprietà dell'applicazione a un harness gestito

Nell'Agents SDK, una esecuzione è un turno a livello di applicazione. Il runner dell'SDK chiama il modello, ispeziona l'output, esegue gli strumenti, segue i passaggi di consegne e continua fino a raggiungere un punto di arresto. Il tuo processo ospita quel loop e quindi ne possiede il ciclo di vita.

Nell'Agents API, OpenAI esegue l'harness. Una sessione è un'istanza durevole di una configurazione di agente che accetta attività, produce eventi, può mettersi in pausa per azioni richieste e può continuare nel tempo. OpenAI gestisce sessioni, orchestrazione, compattazione del contesto e ripristino; la tua applicazione invia lavoro, gestisce gli strumenti funzione, riceve eventi e opzionalmente gestisce un ambiente di esecuzione self-hosted.

Questo spostamento di titolarità è la migrazione. Tutto il resto — sintassi API, schemi degli strumenti, gestione degli eventi, ID di sessione — ne consegue.

La Mappa di Migrazione del Confine di Runtime

Cosa può migrare concettualmente senza cambiare titolarità

Diversi concetti dell'applicazione sopravvivono alla migrazione senza problemi anche se la loro rappresentazione cambia. Modelli, istruzioni, definizioni di funzioni con schema JSON, accesso MCP, descrizioni degli strumenti e requisiti di output strutturato rimangono aspetti della configurazione dell'agente.

Il modello di configurazione dell'Agents API di OpenAI definisce esplicitamente un agente tramite modello, istruzioni, strumenti, ragionamento e comportamento di output. Gli strumenti funzione rimangono codice dell'applicazione: l'harness richiede una chiamata di funzione e il tuo handler restituisce il risultato. OpenAI osserva inoltre che le implementazioni di funzioni usate con la Responses API possono essere riutilizzate con il flusso di sessione dell'Agents API.

Cosa non dovrebbe essere migrato uno-a-uno

Il modello di migrazione pericoloso è ricreare ogni astrazione di runtime dell'SDK all'interno dell'Agents API. Questo può portarti a pagare per un harness gestito mentre gestisci ancora un harness ombra nella tua applicazione.

Passo 1 — Separare lo stato del dominio dallo stato della sessione dell'agente

Prima di toccare le chiamate API, classifica lo stato che la tua applicazione SDK attualmente trasporta. Parte dello stato esiste solo per mantenere in movimento la conversazione dell'agente. Altro stato è verità di business: permessi utente, stato del progetto, dati dell'ordine, approvazione del flusso di lavoro, record dei clienti, versioni dei documenti, stato delle policy o configurazione dell'applicazione.

La seconda categoria non dovrebbe diventare dipendente da una sessione dell'API Agents. Una sessione durevole è una continuità utile per l'agente; non è un sostituto della fonte di verità del tuo prodotto. Se la sessione scompare, scade, viene ricostruita o cambia implementazione, la tua applicazione deve comunque sapere cosa è vero.

Passo 2 — Convertire la mentalità del runner in una mentalità di sessione ed eventi

Le applicazioni SDK spesso pensano in termini di chiamata a run e ricezione di un risultato. L'API Agents pensa in termini di una sessione durevole i cui turni possono essere eseguiti in modo asincrono. Un messaggio a una sessione inattiva avvia il lavoro; un messaggio durante un turno attivo può indirizzarlo. I progressi arrivano tramite streaming o webhook.

Ciò influisce sull'architettura dell'applicazione. Il lavoro di produzione a lunga esecuzione non dovrebbe dipendere dal fatto che una singola richiesta HTTP rimanga attiva. Il tuo prodotto necessita di identificatori di sessione stabili, persistenza del ciclo di vita, verifica dei webhook, gestori idempotenti e un modo per riconciliare lo stato corrente della sessione dopo il riavvio del processo.

Passo 3 — Riprogettare gli strumenti funzione attorno alle azioni richieste

Gli strumenti funzione rimangono un confine importante dell'applicazione. Definisci la funzione e il suo schema JSON nella configurazione dell'agente. Quando l'harness necessita della funzione, la sessione può entrare in uno stato di azione richiesta. La tua applicazione recupera l'azione richiesta, esegue la logica di business e restituisce il risultato.

Ciò significa che l'implementazione della funzione dovrebbe essere sicura da riprendere. Un webhook può essere consegnato mentre un altro worker sta elaborando. Un errore di rete può verificarsi dopo l'effetto collaterale esterno ma prima che il risultato venga restituito. La migrazione è quindi un buon momento per aggiungere ID di chiamata, chiavi di idempotenza, autorizzazione esplicita, politiche di timeout e record di audit agli strumenti consequenziali.

Passo 4 — Decidere dove deve avvenire l'esecuzione

L'API Agents separa l'harness gestito dall'ambiente di esecuzione. Un agente può operare senza un ambiente dedicato, in un sandbox ospitato da OpenAI o tramite un ambiente self-hosted connesso alla sessione.

Ciò crea una decisione di migrazione che le applicazioni SDK potrebbero non aver mai preso esplicitamente: quale codice dovrebbe essere eseguito come funzione dell'applicazione, quale codice appartiene a un sandbox e quali carichi di lavoro richiedono infrastrutture che controlli tu?

Passo 5 — Sostituire il recupero implicito con una gestione esplicita del ciclo di vita

L'harness gestito fornisce il recupero a livello di sessione, ma la tua applicazione possiede comunque ogni dipendenza esterna attorno ad esso. Gli ambienti self-hosted necessitano di provisioning, riconnessione e arresto. I gestori di funzioni possono fallire. I webhook possono essere ritentati. Lo stato lato prodotto può cambiare mentre un agente è inattivo.

La migrazione necessita quindi di due modelli di recupero: recupero del runtime dell'agente e recupero delle operazioni di business. Il primo è sempre più gestito dall'API Agents. Il secondo rimane una tua responsabilità.

Passo 6 — Ricostruire l'osservabilità attorno al nuovo confine di traccia

Le sessioni dell'API Agents espongono eventi, cronologia salvata, turni, chiamate agli strumenti, subagenti e utilizzo dei token. OpenAI fornisce anche i log di sessione nella piattaforma e l'esportazione delle tracce.

Non scartare l'osservabilità della tua applicazione solo perché le tracce della piattaforma sono migliorate. I log di prodotto devono comunque collegare la sessione dell'agente all'identità dell'utente, alla decisione di autorizzazione, all'oggetto di dominio, all'effetto collaterale dello strumento, al record di approvazione e al risultato finale accettato. La traccia di produzione utile è la congiunzione tra le evidenze dell'agent-runtime e le evidenze del business-runtime.

Passo 7 — Preservare le valutazioni prima di modificare il runtime

Una migrazione può sembrare riuscita perché il nuovo sistema produce ancora risposte plausibili mentre cambia silenziosamente la scelta degli strumenti, la continuità della sessione, il comportamento di handoff, la latenza o il recupero dagli errori. Costruisci la baseline comportamentale prima di cambiare runtime.

La baseline dovrebbe includere attività rappresentative, chiamate agli strumenti attese, azioni vietate, punti di approvazione, continuità dello stato, scenari di recupero e criteri di accettazione dell'output finale. Esegui le vecchie e le nuove architetture sugli stessi casi ove possibile.

Il test di prova della migrazione

Cosa misurare durante la migrazione

Quando non migrare ancora

Un'applicazione esistente basata su Agents SDK non diventa una cattiva architettura solo perché la direzione della piattaforma è cambiata. OpenAI continua la manutenzione, le correzioni di sicurezza, le correzioni di bug critici e il lavoro di compatibilità. Se l'applicazione è stabile, ben valutata e non ha requisiti di roadmap bloccati, una migrazione immediata del runtime potrebbe non essere giustificata.

• Una capacità richiesta dell'SDK non è ancora disponibile nell'API Agents.
• La migrazione interromperebbe un periodo di produzione critico senza fornire valore a breve termine.
• L'applicazione dipende da semantiche di orchestrazione personalizzate che non sono state validate sull'harness gestito.
• La portabilità del provider è un requisito rigido e l'attuale astrazione dell'SDK è materialmente preziosa.
• Il tuo team non ha ancora separato lo stato di business dallo stato del runtime dell'agente, rendendo il passaggio non sicuro.
• Il comportamento della nuova API Agents non è stato testato su carichi di lavoro di produzione rappresentativi.

Quando la migrazione diventa strategicamente importante

La migrazione diventa più convincente quando i requisiti di prodotto si allineano con l'harness gestito: lavoro durevole di lunga durata, compattazione e recupero del contesto gestiti dalla piattaforma, capacità più recenti dell'agent-runtime, esecuzione in sandbox, gestione del ciclo di vita ospitata più ricca o il desiderio di ridurre la quantità di codice di orchestrazione che la tua applicazione gestisce.

Il segnale più forte non è "il vecchio SDK è completo di funzionalità". È "la nostra roadmap ora dipende da capacità la cui sede naturale è il runtime gestito dell'API Agents".

Cosa cambierebbe questa risposta?

La strategia di migrazione cambierebbe se OpenAI pubblicasse strumenti di migrazione automatizzati, introducesse livelli di compatibilità espliciti, modificasse la semantica delle sessioni dell'API Agents, ampliasse o restringesse il supporto agli ambienti self-hosted, oppure cambiasse la politica di supporto per l'SDK Agents.

Cambierebbe anche se cambiassero i requisiti del tuo prodotto. Un semplice assistente richiesta-risposta potrebbe non aver bisogno affatto di un harness gestito e durevole. Un agente di coding, ricerca o operations a lunga esecuzione può trarre molto più vantaggio dal modello di ownership dell'API Agents.

Limitazioni

Non esiste una mappa di migrazione universale uno-a-uno da SDK ad API, perché le applicazioni usano l'SDK Agents in modi diversi. Alcune si affidano pesantemente a sessioni e handoff; altre lo usano come un sottile runner attorno a function tool. La migrazione corretta dipende da quali responsabilità la tua applicazione possiede effettivamente oggi.

L'API Agents è anche in beta pubblica, quindi i dettagli implementativi possono evolvere. Considera i principi di ownership in questo articolo come più durevoli di qualsiasi forma specifica di endpoint.

Conclusione

Migrare dall'SDK Agents all'API Agents si comprende meglio come lo spostamento del confine del runtime dell'agente. L'harness gestito si assume una parte maggiore del loop, della continuità di sessione, della compattazione e del ripristino. La tua applicazione dovrebbe diventare più esplicita riguardo alle responsabilità che rimangono tue: verità di dominio, autorizzazione, effetti collaterali delle funzioni, artefatti, auditabilità e ciclo di vita del prodotto.

Se una migrazione lascia in piedi tutta la vecchia macchina di orchestrazione e si limita a sostituire le chiamate SDK con chiamate all'API Agents, probabilmente ha mancato l'opportunità architetturale. L'obiettivo non è riprodurre il vecchio runtime sopra quello nuovo. L'obiettivo è decidere quali responsabilità del runtime non appartengono più alla tua applicazione.

FAQ

Glossario

Fonti primarie e approfondimenti

Migrare dall'SDK OpenAI Agents all'API Agents non è una semplice rinomina di import. Il confine architetturale principale cambia: l'SDK esegue il ciclo dell'agente all'interno della tua applicazione, mentre l'API Agents esegue un harness Codex gestito e una sessione durevole dal lato di OpenAI. La domanda di migrazione quindi non è "Quali classi corrispondono a quali endpoint?" ma "Quali responsabilità di runtime si spostano oltre il confine, quali rimangono nella nostra applicazione e quali necessitano di una riprogettazione?"

La migrazione va da un ciclo di proprietà dell'applicazione a un harness gestito

Nell'SDK Agents, una esecuzione è un turno a livello di applicazione. Il runner dell'SDK chiama il modello, ispeziona l'output, esegue gli strumenti, segue i passaggi di consegne e continua fino a raggiungere un punto di arresto. Il tuo processo ospita quel ciclo e quindi ne possiede il ciclo di vita.

Nell'API Agents, OpenAI esegue l'harness. Una sessione è un'istanza durevole di una configurazione di agente che accetta attività, produce eventi, può mettersi in pausa per azioni richieste e può continuare nel tempo. OpenAI gestisce sessioni, orchestrazione, compattazione del contesto e ripristino; la tua applicazione invia lavoro, gestisce gli strumenti funzione, riceve eventi e opzionalmente gestisce un ambiente di esecuzione self-hosted.

Questo spostamento di titolarità è la migrazione. Tutto il resto — sintassi API, schemi degli strumenti, gestione degli eventi, ID di sessione — ne consegue.

La Mappa di Migrazione del Confine di Runtime

Cosa può migrare concettualmente senza cambiare titolarità

Diversi concetti dell'applicazione sopravvivono alla migrazione in modo pulito anche se la loro rappresentazione cambia. Modelli, istruzioni, definizioni di funzioni JSON-schema, accesso MCP, descrizioni degli strumenti e requisiti di output strutturato rimangono aspetti della configurazione dell'agente.

Il modello di configurazione dell'API Agents di OpenAI definisce esplicitamente un agente attraverso modello, istruzioni, strumenti, ragionamento e comportamento di output. Gli strumenti funzione rimangono codice dell'applicazione: l'harness richiede una chiamata a funzione e il tuo gestore restituisce il risultato. OpenAI nota anche che le implementazioni di funzioni utilizzate con l'API Responses possono essere riutilizzate con il flusso di sessione dell'API Agents.

Cosa non dovrebbe essere migrato uno a uno

Il pattern di migrazione pericoloso è ricreare ogni astrazione runtime dell'SDK all'interno dell'Agents API. Questo può portarti a pagare per un harness gestito continuando comunque a gestire un harness ombra nella tua applicazione.

Passo 1 — Separare lo stato di dominio dallo stato della sessione dell'agente

Prima di toccare le chiamate API, classifica lo stato che la tua applicazione SDK attualmente trasporta. Parte dello stato esiste solo per mantenere in movimento la conversazione dell'agente. Altro stato è verità di business: permessi utente, stato del progetto, dati dell'ordine, approvazione del flusso di lavoro, record dei clienti, versioni dei documenti, stato delle policy o configurazione dell'applicazione.

La seconda categoria non dovrebbe diventare dipendente da una sessione dell'Agents API. Una sessione durevole è una continuità utile per l'agente; non è un sostituto della fonte di verità del tuo prodotto. Se la sessione scompare, scade, viene ricostruita o cambia implementazione, la tua applicazione deve comunque sapere cosa è vero.

Passo 2 — Convertire la mentalità del runner in una mentalità di sessione ed eventi

Le applicazioni SDK spesso ragionano in termini di chiamata a run e ricezione di un risultato. L'Agents API ragiona in termini di una sessione durevole i cui turni possono essere eseguiti in modo asincrono. Un messaggio a una sessione inattiva avvia il lavoro; un messaggio durante un turno attivo può orientarlo. L'avanzamento arriva tramite streaming o webhook.

Questo influisce sull'architettura dell'applicazione. Il lavoro di produzione di lunga durata non dovrebbe dipendere dal fatto che una singola richiesta HTTP rimanga attiva. Il tuo prodotto necessita di identificatori di sessione stabili, persistenza del ciclo di vita, verifica dei webhook, handler idempotenti e un modo per riconciliare lo stato corrente della sessione dopo i riavvii del processo.

Passo 3 — Riprogettare gli strumenti funzione attorno alle azioni richieste

Gli strumenti funzione rimangono un confine applicativo importante. Definisci la funzione e il suo schema JSON nella configurazione dell'agente. Quando l'harness necessita della funzione, la sessione può entrare in uno stato di azione richiesta. La tua applicazione recupera l'azione richiesta, esegue la logica di business e restituisce il risultato.

Ciò significa che l'implementazione della funzione dovrebbe essere sicura da riprendere. Un webhook può essere consegnato mentre un altro worker sta elaborando. Un errore di rete può verificarsi dopo l'effetto collaterale esterno ma prima che il risultato venga restituito. La migrazione è quindi un buon momento per aggiungere call ID, chiavi di idempotenza, autorizzazione esplicita, policy di timeout e record di audit agli strumenti consequenziali.

Passo 4 — Decidere dove deve avvenire l'esecuzione

L'Agents API separa l'harness gestito dall'ambiente di esecuzione. Un agente può operare senza un ambiente dedicato, in una sandbox ospitata da OpenAI o tramite un ambiente self-hosted connesso alla sessione.

Questo crea una decisione di migrazione che le applicazioni SDK potrebbero non aver mai preso esplicitamente: quale codice dovrebbe essere eseguito come funzione applicativa, quale codice appartiene a una sandbox e quali carichi di lavoro richiedono un'infrastruttura che controlli tu?

Passo 5 — Sostituire il recupero implicito con una gestione esplicita del ciclo di vita

Il harness gestito fornisce il recupero a livello di sessione, ma la tua applicazione possiede ancora ogni dipendenza esterna attorno ad esso. Gli ambienti self-hosted necessitano di provisioning, riconnessione e spegnimento. I gestori di funzioni possono fallire. I webhook possono essere ritentati. Lo stato lato prodotto può cambiare mentre un agente è inattivo.

La migrazione necessita quindi di due modelli di recupero: recupero del runtime dell'agente e recupero delle operazioni di business. Il primo è sempre più gestito dalle API Agents. Il secondo rimane una tua responsabilità.

Passo 6 — Ricostruire l'osservabilità attorno al nuovo confine di tracciamento

Le sessioni delle API Agents espongono eventi, cronologia salvata, turni, chiamate agli strumenti, subagenti e utilizzo dei token. OpenAI fornisce anche log di sessione nella piattaforma ed esportazione delle tracce.

Non scartare l'osservabilità della tua applicazione solo perché le tracce della piattaforma sono migliorate. I log di prodotto devono ancora collegare la sessione dell'agente all'identità dell'utente, alla decisione di autorizzazione, all'oggetto di dominio, all'effetto collaterale dello strumento, al record di approvazione e al risultato finale accettato. La traccia di produzione utile è l'unione tra le prove del runtime dell'agente e le prove del runtime di business.

Passo 7 — Preservare le valutazioni prima di cambiare il runtime

Una migrazione può sembrare riuscita perché il nuovo sistema produce ancora risposte plausibili mentre cambia silenziosamente la scelta degli strumenti, la continuità della sessione, il comportamento di handoff, la latenza o il recupero dagli errori. Costruisci la baseline comportamentale prima di cambiare runtime.

La baseline dovrebbe includere attività rappresentative, chiamate agli strumenti attese, azioni vietate, punti di approvazione, continuità dello stato, scenari di recupero e criteri di accettazione dell'output finale. Esegui la vecchia e la nuova architettura sugli stessi casi ove possibile.

Il test di prova della migrazione

Cosa misurare durante la migrazione

Quando non migrare ancora

Un'applicazione esistente basata su Agents SDK non diventa una cattiva architettura solo perché la direzione della piattaforma è cambiata. OpenAI continua la manutenzione, le correzioni di sicurezza, le correzioni di bug critici e il lavoro di compatibilità. Se l'applicazione è stabile, ben valutata e non ha requisiti di roadmap bloccati, una migrazione immediata del runtime potrebbe non essere giustificata.

• Una capacità SDK richiesta non è ancora disponibile nelle API Agents.
• La migrazione interromperebbe un periodo di produzione critico senza fornire valore a breve termine.
• L'applicazione dipende da semantiche di orchestrazione personalizzate che non sono state validate sul harness gestito.
• La portabilità del provider è un requisito rigido e l'attuale astrazione SDK è materialmente preziosa.
• Il tuo team non ha ancora separato lo stato di business dallo stato del runtime dell'agente, rendendo il passaggio non sicuro.
• Il comportamento delle nuove API Agents non è stato testato su carichi di lavoro di produzione rappresentativi.

Quando la migrazione diventa strategicamente importante

La migrazione diventa più convincente quando i requisiti di prodotto si allineano con l'harness gestito: lavoro durevole a lunga esecuzione, compattazione e ripristino del contesto gestiti dalla piattaforma, capacità più recenti dell'agent-runtime, esecuzione in sandbox, gestione del ciclo di vita ospitata più ricca, o il desiderio di ridurre la quantità di codice di orchestrazione che la tua applicazione gestisce.

Il segnale più forte non è "il vecchio SDK è completo di funzionalità". È "la nostra roadmap ora dipende da capacità la cui sede naturale è il runtime gestito dell'Agents API".

Cosa cambierebbe questa risposta?

La strategia di migrazione cambierebbe se OpenAI pubblicasse strumenti di migrazione automatizzati, introducesse livelli di compatibilità espliciti, modificasse la semantica delle sessioni dell'Agents API, ampliasse o riducesse il supporto agli ambienti self-hosted, o modificasse la politica di supporto per l'Agents SDK.

Cambierebbe anche se i requisiti del tuo prodotto cambiassero. Un semplice assistente richiesta-risposta potrebbe non aver bisogno affatto di un harness gestito durevole. Un agente di coding, ricerca o operations a lunga esecuzione può trarre molto più vantaggio dal modello di ownership dell'Agents API.

Limitazioni

Non esiste una mappa di migrazione universale uno-a-uno da SDK ad API perché le applicazioni usano l'Agents SDK in modi diversi. Alcune si affidano pesantemente a sessioni e handoff; altre lo usano come un sottile runner attorno a function tool. La migrazione corretta dipende da quali responsabilità la tua applicazione possiede effettivamente oggi.

L'Agents API è anche in beta pubblica, quindi i dettagli di implementazione possono evolvere. Considera i principi di ownership in questo articolo come più durevoli di qualsiasi forma di endpoint individuale.

Conclusione

Migrare dall'Agents SDK all'Agents API è meglio inteso come spostare il confine dell'agent-runtime. L'harness gestito assume il controllo di una parte maggiore del loop, della continuità della sessione, della compattazione e del ripristino. La tua applicazione dovrebbe diventare più esplicita riguardo alle responsabilità che rimangono tue: verità di dominio, autorizzazione, effetti collaterali delle funzioni, artefatti, auditabilità e ciclo di vita del prodotto.

Se una migrazione lascia in piedi tutta la vecchia macchina di orchestrazione e si limita a sostituire le chiamate SDK con chiamate Agents API, probabilmente ha perso l'opportunità architetturale. L'obiettivo non è riprodurre il vecchio runtime sopra quello nuovo. L'obiettivo è decidere quali responsabilità del runtime non appartengono più alla tua applicazione.

FAQ

Glossario

Fonti primarie e ulteriori letture