Odomykanie systému Codex: ako sme vytvorili server aplikácií

Kódovací agent OpenAI Codex je dostupný na mnohých rôznych platformách: webová aplikácia⁠(otvorí sa v novom okne), CLI⁠(otvorí sa v novom okne), rozšírenie IDE⁠(otvorí sa v novom okne) a nová aplikácia Codex pre macOS. Pod kapotou sú všetky poháňané tým istým Codex harnessom – slučkou agenta a logikou, ktorá je základom všetkých skúseností s Codexom. Kritické spojenie medzi nimi? Codex App Server⁠(otvorí sa v novom okne), klientsky prívetivé, obojsmerné JSON-RPC API.

V tomto príspevku predstavíme Codex App Server a podelíme sa o naše doterajšie poznatky o najlepších spôsoboch, ako integrovať možnosti Codex do tvojho produktu, aby sme ti pomohli tvojim používateľom výrazne zefektívniť ich pracovné postupy. Budeme sa zaoberať architektúrou a protokolom App Servera a tým, ako sa integruje s rôznymi rozhraniami Codexu, a poskytneme tipy, ako využiť Codex, či už chceš z Codexu urobiť kontrolóra kódu, agenta SRE alebo asistenta pri kódovaní.

Predtým, než sa ponoríme do architektúry, je užitočné poznať príbeh servera App Server. Spočiatku bol App Server praktickým spôsobom, ako opätovne používať Codex harness naprieč produktmi, čo sa postupne vyvinulo do nášho štandardného protokolu.

Codex CLI začal ako TUI (terminálové používateľské rozhranie), čo znamená, že ku Codexu sa pristupuje cez terminál. Keď sme vytvárali rozšírenie VS Code (spôsob, ktorý je viac priateľský k IDE na interakciu s agentmi Codex), potrebovali sme spôsob, ako použiť ten istý rámec, aby sme mohli z IDE UI riadiť tú istú slučku agenta bez toho, aby sme ju museli znovu implementovať. To znamenalo podporu bohatých vzorcov interakcie nad rámec request/response, ako napríklad preskúmavanie pracovného priestoru, streamovanie priebehu, keď agent uvažuje a emitovanie rozdielov. Najprv sme experimentovali so sprístupnením Codex ako server MCP⁠(otvorí sa v novom okne), ale udržiavanie sémantiky MCP spôsobom, ktorý dával zmysel pre VS Code, sa ukázalo ako náročné. Namiesto toho sme zaviedli protokol JSON-RPC, ktorý zrkadlil slučku TUI a stal sa neoficiálnou prvou verziou⁠(otvorí sa v novom okne) App Servera. V tom čase sme neočakávali, že iní klienti budú závisieť od App Servera, takže nebol navrhnutý ako stabilné rozhranie API.

Ako sa v priebehu nasledujúcich mesiacov zvyšovalo osvojenie Codexu, interné tímy a externí partneri chceli mať možnosť integrovať rovnaký nástroj do svojich produktov, aby urýchlili vývojové procesy softvéru pre svojich používateľov. Napríklad JetBrains a Xcode chceli prostredie agenta na úrovni IDE, zatiaľ čo desktopová aplikácia Codex potrebovala orchestráciu viacerých agentov Codex súčasne. Tieto požiadavky nás podnietili navrhnúť povrch platformy, na ktorý sa môžu naše produkty aj partnerské integrácie bezpečne spoliehať v priebehu času. Muselo byť ľahko integrované a spätne kompatibilné, čo znamená, že sme mohli vyvíjať protokol bez narušenia existujúcich klientov.

Ďalej si ukážeme, ako sme navrhli architektúru a protokol, aby rôzni klienti mohli používať ten istý nástroj.

Najprv sa pozrime na to, čo sa nachádza vo vnútri postroja Codex a ako ho Codex App Server sprístupňuje klientom. V našom poslednom Codex blogu sme podrobne rozobrali základnú slučku agenta, ktorá orchestruje interakciu medzi používateľom, modelom a nástrojmi. Toto je základná logika nástroja Codex, ale úplný zážitok s agentom ponúka viac:

1. Životný cyklus vlákna a perzistencia. Vlákno je konverzácia medzi používateľom a agentom Codex. Codex vytvára, obnovuje, vykonáva rozvetvenie a archivuje vlákna, a uchováva históriu udalostí, aby sa klienti mohli znova pripojiť a zobraziť konzistentnú časovú os.

2. Konfigurácia a autentifikácia. Codex načítava konfiguráciu, spravuje predvolené nastavenia a spúšťa autentifikačné toky, ako je „Prihlásenie s ChatGPT“ vrátane stavu prihlasovacích údajov.

3. Spustenie nástrojov a rozšírenia. Codex spúšťa nástroje shell/súbor v sandboxe a prepája integrácie, ako sú servery MCP a zručnosti, aby sa mohli zúčastňovať na slučkách agenta v rámci konzistentného modelu politík.

Všetka logika agenta, ktorú sme tu spomenuli, vrátane základnej slučky agenta, sa nachádza v časti kódovej základne Codex CLI s názvom „Codex core⁠(otvorí sa v novom okne).” Codex core je knižnica, kde sa nachádza všetok kód agenta a zároveň runtime, ktorý možno spustiť na vykonávanie slučky agenta a na správu perzistencie jedného vlákna Codex (konverzácia).

Aby bol užitočný, Codex harness musí byť dostupný klientom. Tam prichádza na rad App Server.

Aplikačný server je nielen protokolom JSON-RPC medzi klientom a serverom, ale aj dlhotrvajúcim procesom, ktorý hostuje vlákna jadra Codex. Ako vidíme z diagramu vyššie, proces App Servera má štyri hlavné komponenty: stdio reader, Codex procesor správ, manažér vlákien a hlavné vlákna. Správca vlákien spustí jednu jadrovú reláciu pre každé vlákno a procesor správ Codex potom priamo komunikuje s každou jadrovou reláciou, aby odoslal požiadavky klienta a prijal aktualizácie.

Jedna požiadavka klienta môže viesť k mnohým aktualizáciám udalostí, a práve tieto podrobné udalosti nám umožňujú vytvoriť bohaté používateľské rozhranie na aplikačnom serveri. Okrem toho čítačka stdio a procesor správ Codex slúžia ako prekladová vrstva medzi klientom a jadrovými vláknami Codexu. Prekladajú klientské požiadavky JSON-RPC na základné operácie jadra Codex, sledujú interný tok udalostí jadra Codex a potom transformujú tieto nízkoúrovňové udalosti na malú sadu stabilných, pre používateľské rozhranie pripravených oznámení JSON-RPC.

Protokol JSON-RPC medzi klientom a aplikačným serverom je plne obojsmerný. Typické vlákno obsahuje požiadavku klienta a mnoho notifikácií zo servera. Okrem toho môže server iniciovať požiadavky, keď agent potrebuje vstup, ako je schválenie, a potom pozastaviť činnosť, kým klient neodpovie.

Ďalej si rozoberieme základné prvky konverzácie, ktoré tvoria stavebné bloky protokolu App Server. Navrhnúť API pre agentovú slučku je náročné, pretože interakcia medzi používateľom a agentom nie je jednoduchá požiadavka/odpoveď. Jedna požiadavka používateľa sa môže rozvinúť do štruktúrovanej postupnosti akcií, ktoré musí klient verne reprezentovať: vstup používateľa, postupný pokrok agenta, artefakty vytvorené po ceste (napr. rozdiely). Aby bolo možné tento prúd interakcií jednoducho integrovať a zabezpečiť jeho odolnosť naprieč používateľskými rozhraniami, zvolili sme tri základné prvky s jasne definovanými hranicami a životnými cyklami:

1. Položka: Položka je základná jednotka vstupu/výstupu v Codexe. Položky sú typované (napr. používateľská správa, správa agenta, vykonanie nástroja, žiadosť o schválenie, rozdiel) a každá má explicitný životný cyklus:

• item/started keď sa položka začne
• voliteľné udalosti item/*/delta ako toky obsahu (pre typy položiek so streamovaním)
• item/completed keď sa položka dokončí so svojím konečným payloadom

Tento životný cyklus umožňuje klientom okamžite začať vykresľovať pri started, streamovať prírastkové aktualizácie pri delta a dokončiť pri completed.

2. Turnus: Turnus je jedna jednotka práce agenta, ktorú iniciuje vstup používateľa. Proces začína, keď klient odošle vstup (napríklad „spustiť testy a zhrnúť zlyhania“) a končí, keď agent dokončí produkciu výstupov pre tento vstup. Ťah obsahuje sekvenciu položiek, ktoré predstavujú medzikroky a výstupy vytvorené počas procesu.

3. Vlákno: Vlákno je odolný kontajner pre prebiehajúcu reláciu Codex medzi používateľom a agentom. Obsahuje viacero ťahov. Vlákna sa môžu vytvárať, obnovovať, vetviť a archivovať. História vlákna sa uchováva, aby sa klienti mohli znova pripojiť a zobraziť konzistentnú časovú os.

Teraz sa pozrieme na zjednodušenú konverzáciu medzi klientom a agentom, kde je konverzácia reprezentovaná primitívmi:

Na začiatku konverzácie musia klient a server nadviazať initialize handshake. Klient musí odoslať jednu požiadavku initialize pred akoukoľvek inou metódou a server to potvrdí odpoveďou. Toto dáva serveru príležitosť propagovať svoje schopnosti a umožňuje obom stranám dohodnúť sa na verziách protokolu, príznakoch funkcií a predvolených nastaveniach ešte predtým, než sa začne skutočná práca. Tu je príklad dátového balíka z rozšírenia OpenAI pre VS Code.

Toto je to, čo server vracia:

Keď klient vytvorí novú požiadavku, najprv sa vytvorí vlákno a potom ťah. Server pošle späť oznámenia o priebehu (thread/started a turn/started). Taktiež odošle späť vstupy, ktoré zaregistruje ako položky, napríklad správu používateľa.

Volania nástrojov sú tiež odosielané späť klientovi ako položky. Okrem toho server môže požiadať klienta o schválenie predtým, ako môže spustiť akciu, a to odoslaním požiadavky na server. Schválenie pozastaví ťah, kým klient neodpovie buď „povoliť“, alebo „zamietnuť“. Takto vyzerá schvaľovací proces v rozšírení VS Code:

Nakoniec server odošle správu agenta a potom ukončí ťah s turn/completed. Delta udalosti prúdu správ agenta posielajú časti správy späť, až kým sa správa nefinalizuje s item/completed.

Správy v diagrame sú zjednodušené pre lepšiu čitateľnosť. Ak chceš zobraziť JSON pre celý ťah, môžeš spustiť testovacieho klienta z repozitára Codex CLI.

Teraz sa pozrime na to, ako rôzne klientske rozhrania integrujú Codex cez App Server. Preberieme tri vzory: lokálne aplikácie a IDE, Codex web runtime a TUI.

Vo všetkých troch je prenos JSON-RPC cez stdio (JSONL). JSON-RPC umožňuje jednoducho vytvárať klientske väzby v jazyku podľa tvojho výberu. Povrchy Codex a integrácie partnerov implementovali klientov aplikačného servera v jazykoch ako Go, Python, TypeScript, Swift a Kotlin. Pre TypeScript môžete generovať definície priamo z protokolu Rust spustením:

Pre iné jazyky môžete vygenerovať balík schémy JSON a vložiť ho do vášho preferovaného generátora kódu spustením:

Lokálni klienti zvyčajne pribalia alebo načítajú binárny súbor App Server špecifický pre danú platformu, spustia ho ako dlho bežiaci podriadený proces a ponechajú otvorený obojsmerný stdio kanál pre JSON-RPC. V našom rozšírení VS Code a desktopovej aplikácii je napríklad dodaný artefakt, ktorý obsahuje platformovo špecifický binárny súbor Codex a je priradený k otestovanej verzii, takže klient vždy spúšťa presne tie bity, ktoré sme overili.

Nie každá integrácia môže často dodávať aktualizácie klienta. Niektorí partneri, ako Xcode, oddeľujú cykly vydávania tým, že udržiavajú klienta stabilného a umožňujú mu v prípade potreby odkazovať na novšiu binárku App Servera. Takto môžu implementovať vylepšenia na strane servera (napríklad lepšiu automatickú kompakciu v jadre Codex alebo novo podporované konfiguračné kľúče) a nasadzovať opravy chýb bez čakania na vydanie klienta. Rozhranie JSON-RPC servera aplikácie je navrhnuté tak, aby bolo spätne kompatibilné, takže starší klienti môžu bezpečne komunikovať s novšími servermi.

Codex Web používa Codex harness, ale spúšťa ho v kontajnerovom prostredí. Pracovník zriaďuje kontajner s odhláseným pracovným priestorom, spúšťa v ňom binárny súbor App Server a udržiava dlhodobo aktívny kanál JSON-RPC cez stdio². Webová aplikácia (bežiaca v karte prehliadača používateľa) komunikuje s backendom Codex cez HTTP a SSE, ktoré streamujú udalosti úloh vytvorené pracovníkom. Tým sa zachová ľahké používateľské rozhranie na strane prehliadača, pričom nám to stále poskytuje konzistentné prostredie na spúšťanie aplikácií naprieč počítačmi a webom.

Keďže webové relácie sú prechodné (karty sa zatvárajú, siete vypadávajú), webová aplikácia nemôže byť spoľahlivým zdrojom pre dlhodobé úlohy. Udržiavanie stavu a priebehu na serveri znamená, že práca pokračuje, aj keď karta zmizne. Protokol streamovania a uložené relácie vlákna uľahčujú novej relácii opätovné pripojenie, pokračovanie tam, kde skončila, a dobehnutie bez nutnosti znovu vytvárať stav na strane klienta.

Historicky bol TUI „natívnym“ klientom, ktorý bežal v tom istom procese ako slučka agenta a komunikoval priamo s jadrovými typmi Rustu, namiesto protokolu aplikačného servera. To umožnilo rýchlu skorú iteráciu, ale zároveň to z TUI urobilo povrch pre špeciálne prípady.

Teraz, keď existuje App Server, plánujeme refaktorovať TUI⁠(otvorí sa v novom okne) tak, aby ho používal, a správal sa ako každý iný klient: spustí podriadený proces App Servera, bude komunikovať cez JSON-RPC cez stdio a vykreslí tie isté streamované udalosti a schválenia. Toto umožňuje pracovné postupy, kde sa TUI môže pripojiť k serveru Codex na vzdialenom počítači, pričom agent zostáva blízko výpočtových zdrojov a pokračuje v práci aj v prípade, že sa laptop uspí alebo odpojí, pričom lokálne stále poskytuje živé aktualizácie a ovládacie prvky.

Codex App Server bude do budúcna hlavnou integračnou metódou, ktorú budeme udržiavať, ale existujú aj iné metódy s obmedzenejšou funkčnosťou. Predvolene by sme klientom odporúčali používať Codex App Server na integráciu s Codexom, ale oplatí sa preskúmať aj rôzne metódy integrácie a pochopiť ich výhody a nevýhody. Nižšie sú uvedené najbežnejšie spôsoby, ako používať Codex, a kedy môže byť každý z nich vhodný.

Spusti codex mcp-server⁠(otvorí sa v novom okne) a pripoj sa z akéhokoľvek klienta MCP, ktorý podporuje stdio servery (napríklad OpenAI Agents SDK⁠(otvorí sa v novom okne)). Toto je dobrá voľba, ak už máš pracovný postup založený na MCP a chceš použiť Codex ako volateľný nástroj. Nevýhodou je, že získaš iba to, čo MCP sprístupňuje, takže interakcie špecifické pre Codex, ktoré sa spoliehajú na bohatšiu sémantiku relácie (napr. aktualizácie diff), sa nemusia dať čisto mapovať cez koncové body MCP.

Niektoré ekosystémy ponúkajú prenosné rozhranie, ktoré môže cieliť na viacerých poskytovateľov modelov a runtime prostredí. Toto môže byť dobrá voľba, ak chceš jednu abstrakciu, ktorá koordinuje viacerých agentov. Nevýhodou je, že tieto protokoly sa často zbiehajú na spoločnej podmnožine schopností, čo môže sťažovať reprezentáciu zložitejších interakcií, najmä keď záleží na sémantike nástrojov a relácií špecifických pre poskytovateľa. Tento priestor sa rýchlo vyvíja a očakávame, že sa objavia bežnejšie štandardy, keď zistíme, ktoré základné prvky najlepšie reprezentujú pracovné postupy agentov v reálnom svete (zručnosti⁠(otvorí sa v novom okne) sú dobrým príkladom).

Vyberte App Server, keď chceš, aby bol celý Codex harness sprístupnený ako stabilný tok udalostí vhodný pre používateľské rozhranie. Získaš plnú funkcionalitu slučky agenta a ďalšie podporné funkcie, ako napríklad prihlásenie cez ChatGPT, objavovanie modelov a správu konfigurácie. Hlavným nákladom je integračná práca, keďže si vo svojom jazyku musíš vytvoriť client-side JSON-RPC väzbu. V praxi však Codex dokáže urobiť veľkú časť ťažkej práce, ak mu poskytnete schému JSON a dokumentáciu. Mnohé tímy, s ktorými sme spolupracovali, dokázali rýchlo vytvoriť funkčnú integráciu pomocou Codexu.

Odľahčený skriptovateľný režim CLI na jednorazové úlohy a spúšťanie v CI. Je vhodný pre automatizáciu a pipeline, kde chceš, aby sa jeden príkaz spustil až do dokončenia neinteraktívne, streamoval štruktúrované výstupy pre logy a ukončil sa s jasným signálom úspechu alebo zlyhania.

Knižnica TypeScript na programové ovládanie lokálnych agentov Codex z tvojej aplikácie. To je najlepšie, keď potrebuješ natívne rozhranie knižnice pre serverové nástroje a pracovné postupy bez nutnosti vytvárať samostatného klienta JSON-RPC. Keďže bol dodaný skôr ako App Server, v súčasnosti podporuje menej jazykov a menší rozsah. Ak bude záujem zo strany vývojárov, môžeme pridať ďalšie SDK, ktoré obalia protokol App Server, aby tímy mohli pokryť väčšiu časť povrchu harnessu bez písania väzieb JSON-RPC.

V tomto príspevku sme sa podelili o to, ako pristupujeme k navrhovaniu nového štandardu pre interakciu s agentmi, a ako premeniť vybavenie Codexu na stabilný, pre klientov priateľský protokol. Prebrali sme, ako App Server sprístupňuje jadro Codex, umožňuje klientom riadiť celú slučku agenta a poháňa širokú škálu rozhraní vrátane TUI, lokálnych integrácií do IDE a webového runtime.

Ak ťa to inšpirovalo k nápadom, ako integrovať Codex do vlastných pracovných postupov, stojí za to vyskúšať App Server. Celý zdrojový kód sa nachádza v open-source repozitári Codex CLI repo⁠(otvorí sa v novom okne). Podeľ sa o svoju spätnú väzbu a žiadosti o funkcie. Budeme radi, ak sa nám ozveš, a budeme naďalej sprístupňovať agentov pre všetkých.