Migracija sa OpenAI Agents SDK na Agents API: Šta se zapravo menja arhitektonski?

Migracija sa OpenAI Agents SDK na Agents API nije samo preimenovanje importa. Menja se osnovna arhitektonska granica: SDK pokreće agent petlju unutar vaše aplikacije, dok Agents API pokreće upravljani Codex harness i trajnu sesiju na OpenAI strani. Pitanje migracije stoga nije „Koje klase se mapiraju na koje endpoint-e?” već „Koje odgovornosti runtime-a prelaze granicu, koje ostaju u našoj aplikaciji i koje treba redizajnirati?”

Migracija je sa petlje koju poseduje aplikacija na upravljani harness

U Agents SDK, jedno pokretanje je potez na nivou aplikacije. SDK runner poziva model, pregleda izlaz, izvršava alate, prati handoff-ove i nastavlja dok ne dođe do tačke zaustavljanja. Vaš proces hostuje tu petlju i stoga poseduje njen životni ciklus.

U Agents API, OpenAI pokreće harness. Sesija je trajna instanca konfiguracije agenta koja prihvata zadatke, proizvodi događaje, može da se pauzira radi potrebnih radnji i može da se nastavi tokom vremena. OpenAI upravlja sesijama, orkestracijom, sažimanjem konteksta i oporavkom; vaša aplikacija šalje posao, obrađuje function alate, prima događaje i opciono upravlja self-hosted okruženjem za izvršavanje.

Taj prelaz vlasništva je migracija. Sve ostalo — API sintaksa, šeme alata, obrada događaja, ID-ovi sesija — proizlazi iz toga.

Mapa migracije runtime granice

Šta može konceptualno da se migrira bez promene vlasništva

Nekoliko koncepata aplikacije čisto preživi migraciju iako se njihova reprezentacija menja. Modeli, instrukcije, JSON-schema definicije funkcija, MCP pristup, opisi alata i zahtevi za strukturisanim izlazom i dalje su stvar konfiguracije agenta.

OpenAI model konfiguracije Agents API-ja eksplicitno definiše agenta kroz model, instrukcije, alate, rezonovanje i ponašanje izlaza. Function alati ostaju kod aplikacije: harness zahteva poziv funkcije, a vaš handler vraća rezultat. OpenAI takođe napominje da implementacije funkcija koje se koriste sa Responses API-jem mogu da se ponovo koriste sa tokom Agents API sesije.

Šta ne treba migrirati jedan-na-jedan

Opasan obrazac migracije je ponovno stvaranje svake SDK runtime apstrakcije unutar Agents API-ja. To može da dovede do toga da plaćate za upravljani harness dok i dalje vodite senoviti harness u svojoj aplikaciji.

Korak 1 — Razdvojite stanje domena od stanja sesije agenta

Pre nego što dirnete API pozive, klasifikujte stanje koje vaša SDK aplikacija trenutno nosi. Neka stanja postoje samo da bi se razgovor agenta odvijao. Druga stanja su poslovna istina: korisničke dozvole, status projekta, podaci o porudžbini, odobrenje radnog toka, evidencija klijenata, verzije dokumenata, stanje politike ili konfiguracija aplikacije.

Druga kategorija ne bi trebalo da postane zavisna od sesije Agents API-ja. Trajna sesija je korisna za kontinuitet agenta; ona nije zamena za izvor istine vašeg proizvoda. Ako sesija nestane, istekne, bude ponovo izgrađena ili promeni implementaciju, vaša aplikacija i dalje mora da zna šta je istina.

Korak 2 — Pretvorite način razmišljanja pokretača u način razmišljanja sesije i događaja

SDK aplikacije često razmišljaju u smislu pozivanja run i primanja rezultata. Agents API razmišlja u smislu trajne sesije čiji potezi mogu da se izvršavaju asinhrono. Poruka sesiji koja miruje pokreće rad; poruka tokom aktivnog poteza može da ga usmeri. Napredak stiže putem strimovanja ili webhook-ova.

Ovo utiče na arhitekturu aplikacije. Dugotrajni produkcioni rad ne bi trebalo da zavisi od toga da jedan HTTP zahtev ostane živ. Vaš proizvod zahteva stabilne identifikatore sesije, trajnost životnog ciklusa, verifikaciju webhook-ova, idempotentne rukovaoce i način da se uskladi trenutno stanje sesije nakon ponovnog pokretanja procesa.

Korak 3 — Redizajnirajte funkcijske alate oko potrebnih radnji

Funkcijski alati ostaju važna granica aplikacije. Funkciju i njenu JSON šemu definišete u konfiguraciji agenta. Kada harness-u zatreba funkcija, sesija može da uđe u stanje koje zahteva radnju. Vaša aplikacija preuzima potrebnu radnju, izvršava poslovnu logiku i vraća rezultat.

To znači da implementacija funkcije treba da bude bezbedna za nastavljanje. Webhook može biti isporučen dok drugi radnik obrađuje. Mrežni kvar može nastati nakon spoljnog efekta, ali pre nego što se rezultat vrati. Migracija je stoga dobar trenutak da se konsekventnim alatima dodaju ID-ovi poziva, idempotentni ključevi, eksplicitna autorizacija, politike tajm-auta i revizorski zapisi.

Korak 4 — Odlučite gde treba da se odvija izvršavanje

Agents API razdvaja upravljani harness od okruženja za izvršavanje. Agent može da radi bez namenskog okruženja, u OpenAI sandbox-u koji je hostovan, ili putem samostalno hostovanog okruženja povezanog sa sesijom.

Ovo stvara odluku o migraciji koju SDK aplikacije možda nikada nisu eksplicitno donele: koji kod treba da se izvršava kao funkcija aplikacije, koji kod pripada sandbox-u i koji radni zadaci zahtevaju infrastrukturu koju kontrolišete?

Korak 5 — Zamenite implicitni oporavak eksplicitnim upravljanjem životnim ciklusom

Upravljani harness obezbeđuje oporavak na nivou sesije, ali vaša aplikacija i dalje poseduje svaku spoljnu zavisnost oko nje. Samostalno hostovana okruženja zahtevaju pripremu, ponovno povezivanje i gašenje. Rukovaoci funkcija mogu da ne uspeju. Webhook-ovi mogu biti ponovo pokušani. Stanje na strani proizvoda može se promeniti dok agent miruje.

Migracija stoga zahteva dva modela oporavka: oporavak izvršnog okruženja agenta i oporavak poslovne operacije. Prvi sve više upravlja Agents API. Drugi ostaje vaša odgovornost.

Korak 6 — Ponovo izgradite observabilnost oko nove granice traga

Sesije Agents API-ja izlažu događaje, sačuvanu istoriju, turnove, pozive alata, podagente i potrošnju tokena. OpenAI takođe pruža dnevnike sesija na platformi i izvoz tragova.

Ne odbacujte observabilnost svoje aplikacije samo zato što su se tragovi platforme poboljšali. Dnevnici proizvoda i dalje moraju da povežu sesiju agenta sa identitetom korisnika, odlukom o autorizaciji, domenskim objektom, nuspojavom alata, zapisom o odobrenju i konačnim prihvaćenim rezultatom. Koristan trag u produkciji je spoj između dokaza iz okruženja agenta i dokaza iz poslovnog okruženja.

Korak 7 — Sačuvajte evaluacije pre promene okruženja

Migracija može izgledati uspešno jer novi sistem i dalje daje verodostojne odgovore, dok tiho menja izbor alata, kontinuitet sesije, ponašanje pri predaji, latenciju ili oporavak od grešaka. Izgradite bihevioralnu osnovu pre prelaska na novo okruženje.

Osnova treba da uključi reprezentativne zadatke, očekivane pozive alata, zabranjene radnje, tačke odobrenja, kontinuitet stanja, scenarije oporavka i kriterijume prihvatanja konačnog izlaza. Pokrenite staru i novu arhitekturu na istim slučajevima gde god je to moguće.

Test dokaza migracije

Šta meriti tokom migracije

Kada još ne treba migrirati

Postojeća aplikacija sa Agents SDK-om ne postaje loša arhitektura samo zato što se smer platforme promenio. OpenAI nastavlja održavanje, bezbednosne ispravke, ispravke kritičnih grešaka i rad na kompatibilnosti. Ako je aplikacija stabilna, dobro evaluirana i nema blokiran zahtev na planu razvoja, trenutna migracija okruženja možda nije opravdana.

• Potrebna mogućnost SDK-a još nije dostupna u Agents API-ju.
• Migracija bi poremetila kritični produkcijski period bez donošenja kratkoročne vrednosti.
• Aplikacija zavisi od prilagođene semantike orkestracije koja nije validirana na upravljanom okviru.
• Prenosivost između provajdera je čvrst zahtev i trenutna apstrakcija SDK-a je materijalno vredna.
• Vaš tim još nije razdvojio poslovno stanje od stanja okruženja agenta, što prelazak čini nesigurnim.
• Novo ponašanje Agents API-ja nije testirano na reprezentativnim produkcijskim opterećenjima.

Kada migracija postaje strateški važna

Migracija postaje privlačnija kada se zahtevi proizvoda usklade sa upravljanim okvirom: trajni dugotrajni rad, upravljanje sažimanjem i oporavkom konteksta od strane platforme, novije mogućnosti okruženja agenata, izvršavanje u sandbox-u, bogatije hostovano upravljanje životnim ciklusom ili želja da se smanji količina koda za orkestraciju koji vaša aplikacija održava.

Najjači signal nije „stari SDK je funkcionalno kompletan“. To je „naš plan razvoja sada zavisi od mogućnosti čiji je prirodni dom upravljano Agents API okruženje“.

Šta bi promenilo ovaj odgovor?

Strategija migracije bi se promenila ako OpenAI objavi automatizovane alate za migraciju, uvede eksplicitne slojeve kompatibilnosti, promeni semantiku sesija Agents API-ja, proširi ili suzi podršku za samostalno hostovana okruženja ili promeni politiku podrške za Agents SDK.

Promenila bi se i ako se promene zahtevi vašeg proizvoda. Jednostavan asistent za zahtev-odgovor možda uopšte ne zahteva trajni upravljani harness. Dugotrajni agent za kodiranje, istraživanje ili operacije može imati mnogo više koristi od modela vlasništva Agents API-ja.

Ograničenja

Ne postoji univerzalna mapa migracije jedan-na-jedan sa SDK-a na API jer aplikacije koriste Agents SDK na različite načine. Neke se u velikoj meri oslanjaju na sesije i predaje; druge ga koriste kao tanak runner oko funkcijskih alata. Ispravna migracija zavisi od toga koje odgovornosti vaša aplikacija zapravo poseduje danas.

Agents API je takođe u javnoj beta verziji, tako da se detalji implementacije mogu menjati. Smatrajte principe vlasništva u ovom članku trajnijim od bilo kog pojedinačnog oblika endpointa.

Zaključak

Migraciju sa Agents SDK na Agents API najbolje je razumeti kao pomeranje granice agent-runtime-a. Upravljani harness preuzima veći deo petlje, kontinuiteta sesije, kompakcije i oporavka. Vaša aplikacija treba da postane eksplicitnija u pogledu odgovornosti koje ostaju vaše: istinitost domena, autorizacija, nuspojave funkcija, artefakti, revizibilnost i životni ciklus proizvoda.

Ako migracija ostavi svu staru mašineriju orkestracije na mestu i samo zameni pozive SDK-a pozivima Agents API-ja, verovatno je propustila arhitektonsku priliku. Cilj nije da se stari runtime reprodukuje na vrhu novog. Cilj je da se odluči koje odgovornosti runtime-a više ne pripadaju vašoj aplikaciji.

Često postavljana pitanja

Pojmovnik

Primarni izvori i dodatno čitanje

Migracija sa OpenAI Agents SDK na Agents API nije preimenovanje importa. Menja se osnovna arhitektonska granica: SDK pokreće petlju agenta unutar vaše aplikacije, dok Agents API pokreće upravljani Codex okvir i trajnu sesiju na OpenAI strani. Pitanje migracije stoga nije „Koje klase se mapiraju na koje krajnje tačke?“ već „Koje odgovornosti izvršavanja prelaze granicu, koje ostaju u našoj aplikaciji i koje treba redizajnirati?“

Migracija je sa petlje koju poseduje aplikacija na upravljani okvir

U Agents SDK, jedno pokretanje je ciklus na nivou aplikacije. SDK pokretač poziva model, pregleda izlaz, izvršava alate, prati predaje i nastavlja dok ne dođe do tačke zaustavljanja. Vaš proces hostuje tu petlju i stoga poseduje njen životni ciklus.

U Agents API, OpenAI pokreće okvir. Sesija je trajna instanca konfiguracije agenta koja prihvata zadatke, proizvodi događaje, može da se pauzira radi potrebnih radnji i može da se nastavi tokom vremena. OpenAI upravlja sesijama, orkestracijom, sažimanjem konteksta i oporavkom; vaša aplikacija šalje posao, rukuje funkcijskim alatima, prima događaje i opciono upravlja samostalno hostovanim izvršnim okruženjem.

Taj prelaz vlasništva je migracija. Sve ostalo — sintaksa API-ja, šeme alata, rukovanje događajima, ID-ovi sesija — proizlazi iz toga.

Mapa migracije granica izvršavanja

Šta može konceptualno da se migrira bez promene vlasništva

Nekoliko koncepata aplikacije preživi migraciju čisto iako se njihova reprezentacija menja. Modeli, instrukcije, JSON-šema definicije funkcija, MCP pristup, opisi alata i zahtevi za strukturisanim izlazom su i dalje pitanja konfiguracije agenta.

OpenAI model konfiguracije Agents API eksplicitno definiše agenta kroz model, instrukcije, alate, rezonovanje i ponašanje izlaza. Funkcijski alati ostaju kod aplikacije: okvir zahteva poziv funkcije, a vaš rukovalac vraća rezultat. OpenAI takođe napominje da se implementacije funkcija koje se koriste sa Responses API mogu ponovo koristiti sa tokom Agents API sesije.

Šta ne treba migrirati jedan-na-jedan

Opasan obrazac migracije je ponovno stvaranje svake SDK runtime apstrakcije unutar Agents API-ja. To može dovesti do toga da plaćate za upravljani harness dok i dalje upravljate senovitim harness-om u svojoj aplikaciji.

Korak 1 — Odvojite domensko stanje od stanja sesije agenta

Pre nego što dodirnete API pozive, klasifikujte stanje koje vaša SDK aplikacija trenutno nosi. Neko stanje postoji samo da bi održalo razgovor agenta u pokretu. Drugo stanje je poslovna istina: korisničke dozvole, status projekta, podaci o porudžbini, odobrenje radnog toka, zapisi o klijentima, verzije dokumenata, stanje politike ili konfiguracija aplikacije.

Druga kategorija ne bi trebalo da postane zavisna od Agents API sesije. Trajna sesija je koristan kontinuitet za agenta; ona nije zamena za izvor istine vašeg proizvoda. Ako sesija nestane, istekne, bude ponovo izgrađena ili promeni implementaciju, vaša aplikacija i dalje mora da zna šta je istina.

Korak 2 — Pretvorite mentalni sklop runner-a u mentalni sklop sesije i događaja

SDK aplikacije često razmišljaju u smislu pozivanja run i primanja rezultata. Agents API razmišlja u smislu trajne sesije čiji potezi mogu da se izvršavaju asinhrono. Poruka neaktivnoj sesiji započinje rad; poruka tokom aktivnog poteza može da ga usmeri. Napredak stiže putem streaming-a ili webhook-ova.

Ovo utiče na arhitekturu aplikacije. Dugotrajni produkcioni rad ne bi trebalo da zavisi od toga da jedan HTTP zahtev ostane živ. Vaš proizvod zahteva stabilne identifikatore sesije, trajnost životnog ciklusa, verifikaciju webhook-ova, idempotentne handlere i način da se uskladi trenutno stanje sesije nakon ponovnog pokretanja procesa.

Korak 3 — Redizajnirajte function alate oko potrebnih radnji

Function alati ostaju važna granica aplikacije. Vi definišete funkciju i njenu JSON šemu u konfiguraciji agenta. Kada harness-u zatreba funkcija, sesija može da uđe u stanje koje zahteva radnju. Vaša aplikacija preuzima potrebnu radnju, izvršava poslovnu logiku i vraća rezultat.

To znači da implementacija funkcije treba da bude bezbedna za nastavljanje. Webhook može biti dostavljen dok drugi worker obrađuje. Mrežni kvar može nastupiti nakon spoljnog efekta, ali pre nego što se rezultat vrati. Migracija je stoga dobar trenutak da se konsekventnim alatima dodaju ID-ovi poziva, ključevi idempotentnosti, eksplicitna autorizacija, politike tajm-auta i zapisi za reviziju.

Korak 4 — Odlučite gde treba da se odvija izvršavanje

Agents API razdvaja upravljani harness od okruženja za izvršavanje. Agent može da radi bez namenskog okruženja, u OpenAI-hostovanoj sandbox-u ili putem self-hosted okruženja povezanog sa sesijom.

Ovo stvara odluku o migraciji koju SDK aplikacije možda nikada nisu eksplicitno donele: koji kod treba da se izvršava kao aplikaciona funkcija, koji kod pripada sandbox-u i koji radni zadaci zahtevaju infrastrukturu koju kontrolišete?

Korak 5 — Zamenite implicitni oporavak eksplicitnim upravljanjem životnim ciklusom

Upravljani harness obezbeđuje oporavak na nivou sesije, ali vaša aplikacija i dalje poseduje svaku spoljnu zavisnost oko njega. Samostalno hostovana okruženja zahtevaju provisioniranje, ponovno povezivanje i gašenje. Funkcijski rukovaoci mogu da zakažu. Webhook-ovi mogu biti ponovljeni. Stanje na strani proizvoda može se promeniti dok je agent neaktivan.

Migracija stoga zahteva dva modela oporavka: oporavak agent-runtime-a i oporavak poslovnih operacija. Prvim sve više upravlja Agents API. Drugi ostaje vaša odgovornost.

Korak 6 — Ponovo izgradite observabilnost oko nove granice traga

Sesije Agents API-ja izlažu događaje, sačuvanu istoriju, turn-ove, pozive alata, pod-agente i potrošnju tokena. OpenAI takođe obezbeđuje logove sesija na platformi i izvoz tragova.

Ne odbacujte observabilnost svoje aplikacije samo zato što su se tragovi platforme poboljšali. Logovi proizvoda i dalje moraju da povežu sesiju agenta sa identitetom korisnika, odlukom o autorizaciji, domenskim objektom, sporednim efektom alata, zapisom o odobrenju i konačnim prihvaćenim rezultatom. Koristan produkcijski trag je spoj između dokaza agent-runtime-a i dokaza poslovnog runtime-a.

Korak 7 — Sačuvajte evaluacije pre promene runtime-a

Migracija može izgledati uspešno jer novi sistem i dalje daje verodostojne odgovore dok tiho menja izbor alata, kontinuitet sesije, ponašanje pri predaji, latenciju ili oporavak od greške. Izgradite bihevioralnu osnovu pre prebacivanja runtime-a.

Osnova treba da uključi reprezentativne zadatke, očekivane pozive alata, zabranjene radnje, tačke odobrenja, kontinuitet stanja, scenarije oporavka i kriterijume prihvatanja konačnog izlaza. Pokrenite staru i novu arhitekturu na istim slučajevima gde god je to moguće.

Test dokaza migracije

Šta meriti tokom migracije

Kada još ne treba migrirati

Postojeća aplikacija sa Agents SDK ne postaje loša arhitektura samo zato što se smer platforme promenio. OpenAI nastavlja održavanje, bezbednosne ispravke, ispravke kritičnih grešaka i rad na kompatibilnosti. Ako je aplikacija stabilna, dobro evaluirana i nema blokiranu potrebu na mapi puta, trenutna migracija runtime-a možda nije opravdana.

• Potrebna sposobnost SDK-a još nije dostupna u Agents API-ju.
• Migracija bi poremetila kritični produkcijski period bez donošenja kratkoročne vrednosti.
• Aplikacija zavisi od prilagođene semantike orkestracije koja nije validirana na upravljanom harness-u.
• Prenosivost između provajdera je čvrst zahtev i trenutna apstrakcija SDK-a je materijalno vredna.
• Vaš tim još nije razdvojio poslovno stanje od stanja agent-runtime-a, što prelazak čini nesigurnim.
• Novo ponašanje Agents API-ja nije testirano na reprezentativnim produkcijskim radnim opterećenjima.

Kada migracija postaje strateški važna

Migracija postaje uverljivija kada se zahtevi proizvoda usklade sa upravljanim okvirom: trajni dugotrajni rad, upravljanje kompresijom i oporavkom konteksta na nivou platforme, novije mogućnosti agent-runtime-a, izvršavanje u sandbox-u, bogatije upravljanje životnim ciklusom na hostingu ili želja da se smanji količina koda za orkestraciju koji vaša aplikacija održava.

Najjači signal nije „stari SDK je funkcionalno kompletan“. To je „naš plan razvoja sada zavisi od mogućnosti čiji je prirodni dom managed Agents API runtime“.

Šta bi promenilo ovaj odgovor?

Strategija migracije bi se promenila ako OpenAI objavi automatizovane alate za migraciju, uvede eksplicitne slojeve kompatibilnosti, promeni semantiku Agents API sesija, proširi ili suzi podršku za self-hosted okruženja ili promeni politiku podrške za Agents SDK.

Takođe bi se promenilo ako se promene zahtevi vašeg proizvoda. Jednostavan asistent za zahtev-odgovor možda uopšte neće imati potrebu za trajnim upravljanim okvirom. Dugotrajni agent za kodiranje, istraživanje ili operacije može mnogo više da iskoristi model vlasništva Agents API-ja.

Ograničenja

Ne postoji univerzalna mapa migracije jedan-na-jedan sa SDK-a na API jer aplikacije koriste Agents SDK na različite načine. Neke se u velikoj meri oslanjaju na sesije i predaje; druge ga koriste kao tanak pokretač oko funkcijskih alata. Ispravna migracija zavisi od toga koje odgovornosti vaša aplikacija zapravo trenutno poseduje.

Agents API je takođe u javnoj beta verziji, tako da se detalji implementacije mogu menjati. Smatrajte principe vlasništva u ovom članku trajnijim od bilo kog pojedinačnog oblika endpoint-a.

Zaključak

Migraciju sa Agents SDK na Agents API najbolje je razumeti kao pomeranje granice agent-runtime-a. Upravljani okvir preuzima više petlje, kontinuiteta sesije, kompresije i oporavka. Vaša aplikacija treba da postane eksplicitnija u pogledu odgovornosti koje ostaju vaše: istinitost domena, autorizacija, nuspojave funkcija, artefakti, revizibilnost i životni ciklus proizvoda.

Ako migracija ostavi svu staru mašineriju za orkestraciju na mestu i samo zameni pozive SDK-a pozivima Agents API-ja, verovatno je propustila arhitektonsku priliku. Cilj nije da se stari runtime reprodukuje na vrhu novog. Cilj je da se odluči koje odgovornosti runtime-a više ne pripadaju vašoj aplikaciji.

Često postavljana pitanja

Pojmovnik

Primarni izvori i dodatno čitanje