Zrození Codexu: jak jsme postavili App Server

Kódovací agent OpenAI Codex je dostupný na mnoha různých platformách: webová aplikace⁠(otevře se v novém okně), CLI⁠(otevře se v novém okně), rozšíření IDE⁠(otevře se v novém okně) a nová aplikace Codex pro macOS. Pod kapotou jsou všechny poháněny stejným rámcem Codexu – agentní smyčkou a logikou, která je základem všech zážitků Codexu. Kritické spojení mezi nimi? Codex App Server⁠(otevře se v novém okně), uživatelsky přívětivé a obousměrné JSON-RPC¹ API.

V tomto příspěvku představíme Codex App Server; podělíme se o dosavadní poznatky o nejlepších způsobech, jak přenést schopnosti Codex do vašeho produktu, aby vaši uživatelé mohli výrazně zefektivnit své pracovní postupy. Probereme architekturu a protokol App Serveru a to, jak se integruje s různými rozhraními Codexu, a také tipy, jak Codex využít – ať už z něj chceš udělat code reviewera, SRE agenta nebo kódovacího asistenta.

Než se ponoříme do architektury, je dobré znát příběh App Serveru. Zpočátku byl App Server praktickým způsobem, jak opětovně využívat Codex harness napříč produkty, ze který se postupně stal náš standardní protokol.

Codex CLI začal jako TUI (terminálové uživatelské rozhraní), což znamená, že se k Codexu přistupuje přes terminál. Když jsme vytvářeli rozšíření pro VS Code (přátelštější způsob práce s agenty Codex prostřednictvím IDE), potřebovali jsme způsob, jak použít stejný harness, abychom mohli řídit stejnou agentní smyčku z uživatelského rozhraní IDE bez nutnosti nové implementace. To vyžadovalo podporu bohatých vzorců interakcí přesahujících požadavek/odpověď, jako je prozkoumávání pracovního prostoru, streamování průběhu agentova uvažování a generování diffů. Nejprve jsme experimentovali s vystavením Codexu jako serveru MCP⁠(otevře se v novém okně), ale udržení sémantiky MCP způsobem, který by dával smysl pro VS Code, se ukázalo jako obtížné. Místo toho jsme zavedli protokol JSON-RPC, který zrcadlil TUI loop, což se stalo neoficiální první verzí⁠(otevře se v novém okně) App Serveru. V té době jsme nepředpokládali, že by na App Serveru byli závislí další klienti, takže nebyl navržen jako stabilní API.

Jak se v následujících několika měsících začal Codex šířeji nasazovat, chtěli mít interní týmy i externí partneři možnost vložit stejný nástroj do svých vlastních produktů, aby urychlili pracovní postupy vývoje softwaru pro své uživatele. Například JetBrains a Xcode chtěly agentní zkušenost na úrovni IDE, desktopová aplikace Codex zase vyžadovala paralelní orchestraci mnoha agentů Codex. Tyto požadavky nás přiměly navrhnout platformní rozhraní, na které se do budoucna mohly bezpečně spoléhat jak naše produkty, tak integrace partnerů. Muselo být snadno integrovatelné a zpětně kompatibilní, abychom mohli vyvíjet protokol, aniž bychom rozbili stávající klienty.

Dále si ukážeme, jak jsme navrhli architekturu a protokol, aby různí klienti mohli používat stejný harness.

Nejprve se podívejme zblízka na to, co je uvnitř harnessu Codex a jak ho Codex App Server zpřístupňuje klientům. V našem posledním blogu o Codexu jsme rozebírali základní smyčku agenta, která orchestruje interakci mezi uživatelem, modelem a nástroji. Toto je základní harnessu Codexu, ale k plnohodnotnému agentnímu zážitku je toho potřeba víc:

1. Životní cyklus vlákna a perzistence. Vlákno je konverzace v Codexu mezi uživatelem a agentem. Codex vytváří, obnovuje, větví a archivuje vlákna a uchovává historii událostí, aby se klient mohl znovu připojit a vykreslit konzistentní časovou osu.

2. Konfigurace a ověřování. Codex načítá konfiguraci, spravuje výchozí nastavení a spouští ověřovací toky jako „Přihlásit se pomocí ChatGPT“, včetně stavu ověření.

3. Spouštění nástrojů a rozšíření. Codex spouští nástroje shellu/souborů v sandboxu a propojuje integrace, jako jsou servery MCP a dovednosti, aby se mohly účastnit smyčky agenta v rámci konzistentního modelu zásad.

Veškerá agentní logika agenta, o které jsme se zde zmínili, včetně základní agentní smyčky, se nachází v části kódové báze Codex CLI s názvem „Codex core⁠(otevře se v novém okně)”. Jádro Codexu je jak knihovna, kde je uložen veškerý kód agenta, tak runtime, který lze spustit pro běh smyčky agenta a správu perzistence jednoho vlákna Codexu (konverzace).

Aby byl harness Codex užitečný, musí být přístupný klientům. A právě tady přichází ke slovu App Server.

App Server je jak protokol JSON-RPC mezi klientem a serverem, tak dlouhodobý proces, který hostuje základní vlákna Codexu. Jak můžeme vidět z diagramu výše, proces App Serveru má čtyři hlavní komponenty: čtečku stdio, procesor zpráv Codex, správce vláken a základní vlákna. Správce vláken spouští jednu základní relaci pro každé vlákno a procesor zpráv Codex pak komunikuje s každou základní relací přímo, aby odesílal klientské požadavky a dostával aktualizace.

Jeden klientský požadavek může vést k mnoha aktualizacím událostí a právě tyto podrobné události nám umožňují postavit nad App Serverem bohaté uživatelské rozhraní. Čtečka stdio a procesor zpráv Codex navíc slouží jako překladová vrstva mezi klientem a základními vlákny Codexu. Překládají klientské požadavky JSON-RPC na základní operace Codex, sledují základní interní stream událostí v Codexu a poté z těchto nízkoúrovňových událostí vytvářejí malé sady stabilních notifikací JSON-RPC připravených pro uživatelské rozhraní.

Protokol JSON-RPC mezi klientem a App Serverem je plně obousměrný. Typické vlákno obsahuje požadavek klienta a mnoho notifikací serveru. Navíc server může zahájit požadavky, když agent potřebuje vstup, jako je schválení, a pak pozastavit tah a čekat, dokud klient neodpoví.

Dále si rozebereme primitiva konverzace, základní stavební kameny protokolu App Serveru. Navrhování API pro agentní smyčku je složité, protože interakce mezi uživatelem a agentem není jen jednoduchá žádost–odpověď. Jeden uživatelský požadavek se může rozvinout do strukturované posloupnosti akcí, které klient musí věrně reprezentovat: vstup uživatele, postupně se rozvíjející proces agenta, průběžně vznikající artefakty (např. diffy). Aby bylo možné tento stream interakcí snadno integrovat a zajistit jeho odolnost v různých uživatelských rozhraních, zvolili jsme tři základní primitiva s jasně definovanými hranicemi a životními cykly:

1. Položka: Položka je v Codexu základní jednotkou vstupu/výstupu. Jsou různé typy položek (např. uživatelská zpráva, zpráva agenta, spuštění nástroje, žádost o schválení, diff) a každá má explicitní životní cyklus:

• item/started když položka začíná
• volitelné události item/*/delta jako obsahové streamy (pro streamované typy položek)
• item/completed když se položka dokončí se svým koncovým obsahem

Tento životní cyklus umožňuje klientům začít vykreslovat okamžitě při started, streamovat průběžné aktualizace při delta a ukončit při completed.

2. Tah: Tah je jedna jednotka práce agenta zahájená vstupem uživatele. Začíná, když klient odešle vstup (například „spusť testy a shrň selhání“), a končí, když agent dokončí vytváření výstupů pro tento vstup. Tah obsahuje sekvenci položek, které představují mezilehlé kroky a v průběhu vytvořené výstupy.

3. Vlákno: Vlákno je trvalý kontejner pro probíhající relaci Codexu mezi uživatelem a agentem. Obsahuje několik tahů. Vlákna lze vytvářet, obnovovat, rozvětvovat a archivovat. Historie vláken se uchovává, aby se klienti mohli znovu připojit a vykreslit konzistentní časovou osu.

Teď se podíváme na zjednodušenou konverzaci mezi klientem a agentem, kde konverzaci reprezentují primitiva:

Na začátku konverzace musí klient a server provést handshake initialize. Klient musí odeslat jediný požadavek initialize před jakoukoli jinou metodou a server to potvrdí odpovědí. To dává serveru možnost oznámit své schopnosti a oběma stranám umožňuje dohodnout se na verzích protokolu, příznacích funkcí a výchozích nastaveních ještě před zahájením skutečné práce. Tady je příklad payloadu z rozšíření VS Code od OpenAI:

Tohle vrací server:

Když klient vytvoří nový požadavek, nejprve vytvoří vlákno a poté tah. Server vrátí notifikaci provedených kroků (thread/started a turn/started). Také pošle zpět vstupy, které zaregistruje jako položky, jako je například zde zpráva uživatele.

I volání nástrojů jsou vracena klientovi jako položky. Server může před spuštěním akce požádat klienta o schválení odesláním požadavku na server. Schválení pozastaví tah, dokud klient neodpoví buď „povolit“, nebo „zamítnout“. Takto vypadá schvalovací tok v rozšíření do VS Code:

Nakonec server odešle zprávu agenta a poté ukončí tah pomocí turn/completed. Události delta zpráv agenta streamují části zprávy zpět, dokud není zpráva dokončena pomocí item/completed.

Zprávy v diagramu jsou zjednodušené pro lepší čitelnost. JSON celého tahu je možné prohlédnout spuštěním testovacího klienta z repozitáře Codex CLI:

Teď se podívejme, jak různé klientské platformy integrují Codex prostřednictvím App Serveru. Podíváme se na tři vzorce: lokální aplikace a IDE, webový runtime Codex a TUI.

Ve všech třech případech se pro přenos používá JSON-RPC přes stdio (JSONL). JSON-RPC usnadňuje vytváření klientských vazeb ve tebou vybraném jazyce. Prostředí Codexu a partnerské integrace implementovaly klienty App Serveru v jazycích jako Go, Python, TypeScript, Swift a Kotlin. Pro TypeScript můžeš generovat definice přímo z protokolu Rust spuštěním:

Pro ostatní jazyky se dá vygenerovat svazek schématu JSON a vložit jej do preferovaného generátoru kódu spuštěním:

Lokální klienti obvykle přibalí nebo načtou binární soubor App Serveru specifický pro danou platformu, spustí ho jako dlouhodobě běžící podřízený proces a udržují otevřený obousměrný kanál stdio pro JSON-RPC. V našem rozšíření pro VS Code a desktopové aplikaci například dodávaný artefakt obsahuje binární soubor Codex specifický pro danou platformu a je připnutý k testované verzi, takže klient vždy spustí přesně ty bity, které jsme validovali.

Ne každá integrace je schopná často produkovat aktualizace klienta. Někteří partneři, jako Xcode, oddělují cykly vydávání tím, že udržují klienta stabilního a umožňují mu v případě potřeby odkazovat na novější binární soubor App Serveru. Tímto způsobem mohou zavádět vylepšení na straně serveru (například lepší automatickou kompakci v jádru Codexu nebo nově podporované konfigurační klíče) a vydávat opravy chyb, aniž by museli čekat na vydání klienta. Rozhraní aplikačního serveru JSON-RPC je navrženo tak, aby bylo zpětně kompatibilní, takže starší klienti mohou bezpečně komunikovat s novějšími servery.

Codex Web používá Codex harness, ale spouští ho v kontejnerovém prostředí. Pracovník zřídí kontejner s vybraným pracovním prostorem, spustí v něm binární soubor App Serveru a udržuje dlouhodobé JSON-RPC přes kanál stdio². Webová aplikace (běžící v kartě prohlížeče uživatele) komunikuje s backendem Codexu přes HTTP a SSE, které streamují události úloh vytvářené pracovníkem. Díky tomu je uživatelské rozhraní na straně prohlížeče odlehčené, ale přitom poskytuje konzistentní běhové prostředí pro desktop i web.

Protože webové relace jsou pomíjivé (karta prohlížeče se může zavřít, síť může spadnout), nemůže být zdrojem pravdy pro dlouhotrvající úkoly webová aplikace. Udržování stavu a průběhu na serveru znamená, že práce pokračuje, i když se karta zavře. Streamovací protokol a uložené relace vláken usnadňují nové relaci znovu se připojit, pokračovat tam, kde skončila, a dohnat zameškané bez nutnosti znovu vybudovat stav v klientovi.

Historicky byl TUI „nativní“ klient, který běžel ve stejném procesu jako agentní smyčka a komunikoval přímo se základními typy v Rustu, ne v protokolu aplikačního serveru. To umožňovalo rychlé rané iterace, ale zároveň to z z prostředí TUI dělalo speciální případ.

Teď, když existuje App Server, máme v plánu refaktorovat TUI⁠(otevře se v novém okně) a používat ho, aby a chovalo se jako jakýkoli jiný klient: spouštělo podřízený proces App Serveru, komunikovalo pomocí JSON-RPC přes stdio a vykreslovalo stejné streamované události a schválení. Tím se umožní pracovní postupy, kdy se TUI může připojit k serveru Codex běžícímu na vzdáleném počítači, čímž zůstává agent v blízkosti výpočtů a pokračuje v práci i v případě, že notebook usne nebo se odpojí, přičemž bude i nadále poskytovat živé aktualizace a ovládací prvky.

Codex App Server bude do budoucna hlavní integrační metodou, kterou budeme udržovat, ale existují i další metody s omezenější funkčností. Klientům bychom nejobecněji doporučili, aby k integraci s Codexem používali Codex App Server, ale stojí za to podívat se i na další metody integrace s jejich výhodami a nevýhodami. Následují nejběžnější způsoby ovládání Codexu a případy, kdy se hodí.

Spusť codex mcp-server⁠(otevře se v novém okně) a připoj se z libovolného MCP klienta, který podporuje stdio servery (např. OpenAI Agents SDK⁠(otevře se v novém okně)). To se hodí, pokud už máš pracovní postup založený na MCP a chceš volat Codex jako volatelný nástroj. Nevýhodou je, že dostaneš jen to, k čemu MCP dává přístup – takže interakce specifické pro Codex, které používají bohatší sémantiku relace (např. aktualizace diffů), se přes koncové body MCP ne vždycky čistě namapují.

Některé ekosystémy nabízejí přenosné rozhraní, které může cílit na více poskytovatelů modelů a runtime prostředí. To se může hodit, pokud chceš, aby jedna abstrakce koordinovala více agentů. Nevýhodou je, že tyto protokoly se často sejdou na společné podmnožině schopností, což může ztížit reprezentaci bohatších interakcí, zejména když záleží na sémantice nástrojů a relací specifických pro konkrétního poskytovatele. Tato oblast se rychle vyvíjí a očekáváme, že se vznikne více společných standardů, až přijdeme s primitivy, která nejlépe reprezentují pracovní postupy agentů v reálném světě (dobrým příkladem jsou dovednosti⁠(otevře se v novém okně)).

App Server si vyber, pokud chceš, aby byl celý Codex harness přístupný jako stabilní stream událostí vhodný pro uživatelské rozhraní. Získáš plnou funkčnost agentní smyčky a další podpůrné funkce, jako je Přihlásit se pomocí ChatGPT, objevování modelů a správa konfigurace. Hlavní náklad představuje práce s integrací, protože si ve svém jazyce musíš vytvořit JSON-RPC binding na straně klienta. V praxi ale Codex většinu dřiny zvládne sám, když mu dodáš JSON schéma a dokumentaci. Mnoha týmům, se kterými jsme spolupracovali, se pomocí Codexu podařilo vytvořit funkční integraci velice rychle.

Odlehčený, skriptovatelný režim CLI pro jednorázové úlohy a běhy CI. Hodí se pro automatizaci a pipelines, pokud potřebuješ neinteraktivní spouštění jediného příkazu až do konce, streamování strukturovaného výstupu protokolování a ukončení s jasným signálem úspěchu nebo selhání.

Knihovna TypeScript pro programové ovládání lokálních agentů Codex přímo z tvojí vlastní aplikace. Nejvíc se hodí, když potřebuješ nativní rozhraní knihovny pro serverové nástroje a pracovní postupy, aniž bys musel vytvářet samostatného klienta JSON-RPC. Protože byl vydán dříve než App Server, podporuje v současnosti méně jazyků a menší rozsah funkcí. V případě zájmu vývojářů přidáme další sady SDK, které obalí protokol App Serveru, aby týmy mohly pokrýt větší část plochy harnessu bez nutnosti programovat vazby JSON-RPC.

V tomto příspěvku jsme se podělili o to, jak přistupujeme k navrhování nového standardu pro interakci s agenty a jak proměnit Codex ve stabilní a uživatelsky přívětivý protokol. Probrali jsme, jak App Server zpřístupňuje jádro Codexu, umožňuje klientům řídit celou agentní smyčku a pohání širokou škálu rozhraní včetně TUI, lokálních integrací do IDE a webového runtime.

Pokud ti při čtení naskočily nápady, jak integrovat Codex do tvých vlastních pracovních postupů, stojí App Server za vyzkoušení. Celý zdrojový kód žije v open-source repozitáři Codex CLI repo⁠(otevře se v novém okně). Klidně nám pošli připomínky nebo požadavky na funkce. Budeme se těšit, že se nám ozveš – a rádi budeme dál zpřístupňovat agenty pro všechny.