Codex harness felszabadítása: hogyan építettük az App szervert

Az OpenAI kódoló ügynöke, a Codex, számos különböző felületen érhető el: a webalkalmazásban⁠(új ablakban nyílik meg), a CLI-ben⁠(új ablakban nyílik meg), az IDE-bővítményben⁠(új ablakban nyílik meg), és az új Codex macOS-alkalmazásban. A háttérben mindegyiket ugyanaz a Codex keretrendszer hajtja meg—az ügynökciklus és a logika, amely minden Codex-élmény alapját képezi. Mi a kritikus kapcsolat köztük? A Codex App Server⁠(új ablakban nyílik meg) egy ügyfélbarát, kétirányú JSON-RPC¹ API.

Ebben a bejegyzésben a Codex App Servert mutatjuk be; megosztjuk eddigi tapasztalatainkat arról, hogyan érdemes a Codex képességeit a termékedbe integrálni, hogy a felhasználóid hatékonyabban dolgozhassanak. Áttekintjük az App Server architektúráját és protokollját, és azt, hogyan integrálódik a különböző Codex-felületekkel. Tippeket adunk a Codex hasznosításához, akár kódellenőrré, SRE ügynökké vagy kódolási asszisztenssé szeretnéd alakítani.

Mielőtt belemerülnénk az architektúrába, érdemes megismerni az App Server előzményeit. Kezdetben az App Server praktikus módot kínált a Codex harness újrafelhasználására a termékek között, ami fokozatosan a standard protokollunkká vált.

A Codex CLI kezdetben TUI-ként (terminálos felhasználói felületként) indult, ami azt jelenti, hogy a Codex a terminálon keresztül érhető el. Amikor megépítettük a VS Code-bővítményt (egy IDE-barátabb módot a Codex ügynökökkel való interakcióra), olyan megoldásra volt szükségünk, amely lehetővé teszi ugyanannak a harness-nek a használatát, így az agent-ciklus egy IDE UI-ból is vezérelhető, újraimplementálás nélkül. Ez azt jelentette, hogy a kérés/válasz mintán túlmutató gazdag interakciós mintákat kellett támogatni, úgymint a munkaterület felfedezése, az előrehaladás közvetítése, miközben az ügynök érvel, valamint a különbségek kibocsátása. Először azzal kísérleteztünk, hogy a Codexet MCP szerverként⁠(új ablakban nyílik meg) tegyük elérhetővé, de az MCP szemantikájának fenntartása a VS Code számára érthető módon nehéznek bizonyult. Ehelyett bevezettünk egy JSON-RPC protokollt, amely tükrözte a TUI ciklust, és ez lett az App Server nem hivatalos első verziója⁠(új ablakban nyílik meg). Akkoriban nem feltételeztük, hogy más kliensek is függni fognak az App Servertől, így az nem stabil API-ként került kialakításra.

Ahogy a Codex egyre inkább elterjedt a következő hónapokban, a belső csapatok és a külső partnerek is szerették volna beágyazni ugyanazt a keretrendszert a saját termékeikbe, hogy felgyorsítsák felhasználóik szoftverfejlesztési munkafolyamatait. Például a JetBrains és az Xcode IDE-szintű ügynökélményt szerettek volna, míg a Codex asztali alkalmazásnak több Codex ügynököt kellett párhuzamosan koordinálnia. Ezek a követelmények egy olyan platformfelület kialakításához vezettek, amelyre a belső termékeink és a partneri integrációk is időtálló módon építhetnek. Fontos volt, hogy könnyen integrálható és visszafelé kompatibilis legyen, azaz úgy tudtuk fejleszteni a protokollt, hogy közben ne okozzunk problémát a meglévő klienseknek.

Ezután végigvezetünk azon, hogyan terveztük meg az architektúrát és a protokollt oly módon, hogy a különböző kliensek ugyanazt a keretrendszert használhassák.

Először nézzük meg közelebbről, mi található a Codex harness belsejében, és hogyan teszi azt a Codex App Server elérhetővé a kliensek számára. A legutóbbi Codex blogbejegyzésünkben részletesen bemutattuk az alapvető ügynökciklust, amely a felhasználó, a modell és az eszközök közötti interakciót irányítja. Ez a Codex keretrendszer alapvető logikája, de a teljes ügynökélmény ennél még többet nyújt:

1. Témaszál életciklus és tartósság. Egy témaszál egy Codex-beszélgetés egy felhasználó és egy ügynök között. A Codex létrehozza, folytatja, elágazásokat hoz létre és archiválja a szálakat, és megőrzi az eseménytörténetet, hogy a kliensek újracsatlakozhassanak, és egyetlen idővonalként láthassák a témát.

2. Konfiguráció és hitelesítés. A Codex betölti a konfigurációt, kezeli az alapértelmezéseket, és hitelesítési folyamatokat futtat, mint például a „Bejelentkezés a ChatGPT‑vel”, beleértve a hitelesítő adatok állapotát.

3. Eszközök végrehajtása és bővítmények. A Codex egy sandboxban futtatja a shell- és fájleszközöket, és összekapcsolja az integrációkat, úgymint az MCP-szervereket és a skilleket, hogy egységes házirend-modell alatt részt vehessenek az ügynök ciklusában.

Az itt említett összes ügynöklogika, beleértve az alapvető ügynökciklust is, a Codex CLI kódbázisának egy „Codex core⁠(új ablakban nyílik meg)” nevű részében található. A Codex core egyszerre szolgál könyvtárként, ahol az összes ügynökkód található, és futtatókörnyezetként, amely képes elindítani az ügynök-ciklust, valamint kezelni egy Codex szál (beszélgetés) állandóságát.

Ahhoz, hogy hasznos legyen, a Codex keretrendszernek elérhetőnek kell lennie az ügyfelek számára. Itt lép be a képbe az App Server.

Az App Server kettős szerepet tölt be: egyrészt a kliens–szerver közti JSON-RPC protokollt valósítja meg, másrészt egy hosszú életű folyamatként a Codex központi szálainak ad otthont. Ahogy a fenti ábrán láthatjuk, egy App Server folyamatnak négy fő része van: a stdio olvasó, a Codex üzenetfeldolgozó, a szálkezelő és a központi szálak. A szálkezelő minden témaszálhoz elindít egy alap munkamenetet, majd a Codex üzenetfeldolgozó közvetlenül kommunikál az egyes alap munkamenetekkel az ügyfélkérések beküldésére és a frissítések fogadására.

Egy klienskérés számos eseményfrissítést eredményezhet, és ezek a részletes események teszik lehetővé, hogy gazdag felhasználói felületet építsünk az App Serverre. Továbbá a stdio-olvasó és a Codex üzenetfeldolgozó tölti be a kliens és a Codex központi szálai közötti köztes, fordító réteg szerepét. A kliens JSON-RPC kéréseit Codex core műveletekké fordítják, figyelik a Codex core belső eseményfolyamát, majd ezeket az alacsony szintű eseményeket egy kis számú, stabil, felhasználói felületre kész JSON-RPC értesítéssé alakítják.

A kliens és az App Server közötti JSON-RPC protokoll teljes mértékben kétirányú. Egy tipikus szál tartalmaz egy klienskérést és több szerverértesítést. Ezenkívül a szerver kéréseket kezdeményez, amikor az ügynöknek inputra van szüksége, például jóváhagyásra, majd szüneteltetheti a folyamatot, amíg az ügyfél válaszol.

A következőkben részletezzük a beszélgetési primitíveket, az App Server protokoll alapvető elemeit. Egy ügynökciklushoz API-t tervezni bonyolult, mert a felhasználó és az ügynök közötti interakció nem egyszerű kérés-választ jelent. Egy felhasználói kérés egy strukturált műveletsorozattá alakulhat át, amelyet a kliensnek hűen kell megjelenítenie: a felhasználó bemenetét, az ügynök fokozatos előrehaladását, valamint a közben létrejövő artefaktumokat (pl. diffeket). Annak érdekében, hogy ez az interakciós adatfolyam könnyen integrálható és minden UI-n ellenálló legyen, három alapvető primitívet választottunk, egyértelmű határokkal és életciklusokkal:

1. Elem: Az elem a Codex bemenetének/kimenetének atomi egysége. Az elemek típusosak (pl. felhasználói üzenet, ügynöküzenet, eszközvégrehajtás, jóváhagyási kérelem, diff), mindegyik egy egyértelmű életciklussal:

• item/started amikor a tétel elindul
• opcionális item/*/delta események tartalomfolyamként (streamelhető elemtípusok esetén)
• item/completed, amikor az elem a végső payloaddal befejeződik

Ez az életciklus lehetővé teszi, hogy az ügyfelek azonnal megkezdjék a renderelést a started eseménynél, a delta eseménynél folyamatosan közvetítsék a növekményes frissítéseket, és a completed eseménynél véglegesítsenek.

2. Kör: A kör a felhasználói bemenet által kezdeményezett ügynök által végzett munka egysége. A folyamat akkor kezdődik, amikor az ügyfél beküld egy bemenetet (például: „futtasd a teszteket, és foglald össze a hibákat”), és akkor ér véget, amikor az ügynök befejezi az adott bemenethez tartozó kimenetek előállítását. Egy kör olyan elemek sorozatát tartalmazza, amelyek a köztes lépéseket és kimeneteket jelentenek, amelyek a folyamat során jönnek létre.

3. Témaszál: A témaszál egy tartós tároló a felhasználó és az ügynök közötti folyamatban lévő Codex-munkamenet számára. Több kört foglal magában. A szálak létrehozhatók, újraindíthatók, elágaztathatók és archiválhatók. A szál előzményei megmaradnak, így a felhasználók újracsatlakozhatnak hozzá, és egy egységes idővonalat jeleníthetnek meg.

Most egy leegyszerűsített beszélgetést nézünk meg egy ügyfél és egy ügynök között, ahol a beszélgetést primitívek ábrázolják:

A beszélgetés kezdetén a kliensnek és a szervernek meg kell állapodnia az initialize kézfogásról. Az ügyfélnek egyetlen initialize kérést kell küldenie bármely más metódus előtt, és a szerver ezt egy válasszal nyugtázza. Ez lehetőséget ad arra, hogy a szerver bemutathassa képességeit, és mindkét fél egyeztethesse a protokollverziót, a funkciókat és az alapértelmezett értékeket, még mielőtt a tényleges munka megkezdődne. Íme egy példa a payloadra az OpenAI VS Code-bővítményéből:

Ezt adja vissza a szerver:

Amikor egy kliens új kérést indít, először létrehoz egy szálat, majd egy kört. A szerver értesítéseket küld az előrehaladásról (thread/started és turn/started). Azokat a bemeneteket is visszaküldi, amelyeket elemként regisztrál, mint például ezt a felhasználói üzenetet itt.

Az eszközhívások elemekként is visszaküldésre kerülnek a kliensnek. Ezenkívül a szerver kérheti a kliens jóváhagyását egy szerverkérés elküldésével, mielőtt végrehajtaná a műveletet. A jóváhagyás addig szünetelteti a kört, amíg az ügyfél nem válaszol „engedélyez” vagy „elutasít” szavakkal. Így néz ki a jóváhagyási folyamat a VS Code bővítményben:

Végül a szerver egy ügynöküzenetet küld, majd a kört a turn/completed paranccsal zárja le. Az ügynök üzenet-delta eseményei visszaküldik az üzenet részeit, amíg az üzenet a item/completed eseménnyel véglegesítésre kerül.

Az ábrán lévő üzeneteket az olvashatóság érdekében egyszerűsítettük. Ha szeretnéd látni a teljes kör JSON-ját, futtasd a tesztklienst a Codex CLI repóból:

Most nézzük meg, hogyan ágyazzák be a különböző kliensfelületek a Codexet az App Serveren keresztül. Három mintát fogunk áttekinteni, melyek: helyi alkalmazások és IDE-k, a Codex webes futtatókörnyezet, valamint a TUI.

Mindhárom esetben a szállítás JSON-RPC stdio-n keresztül történik (JSONL). A JSON-RPC megkönnyíti az ügyféloldali kötéseket az általad választott nyelven. A Codex felületek és partneri integrációk különböző nyelveken, köztük Go, Python, TypeScript, Swift és Kotlin nyelven valósították meg az App Server klienseket. TypeScript esetén a definíciókat közvetlenül a Rust protokollból generálhatod a következő parancs futtatásával:

Más nyelvekhez JSON séma csomagot generálhatsz, és betáplálhatod a preferált kódgenerátorodba a következő parancs futtatásával:

A helyi kliensek jellemzően vagy tartalmazzák, vagy letöltik a platformhoz megfelelő App Server binárist, hosszú életű alfolyamatként indítják, és fenntartanak egy kétirányú stdio csatornát a JSON-RPC kommunikációhoz. A VS Code-bővítményünkben és az asztali alkalmazásunkban például a kiadott artefaktum tartalmazza a platform-specifikus Codex binárist, egy tesztelt verzióhoz van rögzítve, így a kliens mindig pontosan azokat a biteket futtatja, amelyeket validáltunk.

Nem minden integráció képes gyakori kliensfrissítéseket kiadni. Néhány partner, mint például az Xcode, leválasztja a kiadási ciklusokat azáltal, hogy stabilan tartja a klienst, és lehetővé teszi, hogy szükség esetén egy újabb App Server binárisra mutasson. Így át tudják venni a szerveroldali fejlesztéseket (például a Codex mag jobb automatikus tömörítését vagy az újonnan támogatott konfigurációs kulcsokat), és a hibajavításokat is bevezethetik anélkül, hogy meg kellene várniuk egy klienskiadást. Az App Server JSON-RPC felülete visszamenőleges kompatibilitásra lett tervezve, így a régebbi kliensek biztonságosan kommunikálhatnak az újabb szerverekkel.

A Codex Web a Codex harness-t használja, de konténerben futtatja. A worker előkészít egy konténert a kicsomagolt munkaterülettel, elindítja benne az App Server binárist, és fenntart egy hosszú életű JSON-RPC csatornát stdio-n keresztül². A webalkalmazás (a felhasználó böngészőfülén futva) HTTP-n és SSE-n keresztül kommunikál a Codex háttérrendszerével, amely a worker által előállított feladateseményeket továbbítja. Ez könnyűvé teszi a böngészőoldali felhasználói felületet, ugyanakkor az asztali és webes környezetben is egységes futtatókörnyezetet kapunk.

A webes munkamenetek átmeneti jellege miatt (lapok bezáródása, hálózati megszakadások) a webalkalmazás nem szolgálhat megbízható forrásként a hosszú ideig futó feladatokhoz. Az állapot és a folyamat szerveren való megőrzése azt jelenti, hogy a munka akkor is folytatódik, ha a böngészőfül eltűnik. A streaming protokoll és a mentett témaszál munkamenetek lehetővé teszik, hogy egy új munkamenet könnyedén újracsatlakozzon, ott folytassa, ahol abbahagyta, és felzárkózzon anélkül, hogy az állapotot újra kellene építeni a kliensben.

Korábban a TUI egy natív kliensként működött: ugyanabban a folyamatban futott, mint az ügynök-ciklus, és közvetlenül a Rust magtípusokkal kommunikált az App Server protokoll használata helyett. Ez gyors korai iterációt tett lehetővé, de a TUI-t is egy speciális esetű felületté tette.

Most, hogy az App Server rendelkezésre áll, a TUI-t úgy tervezzük átalakítani⁠(új ablakban nyílik meg), hogy azt használja. Így ugyanúgy működik majd, mint bármely más kliens: elindít egy App Server alfolyamatot, stdio-n keresztül JSON-RPC-t használ, és rendereli ugyanazokat a streaming eseményeket és jóváhagyásokat. Ez lehetővé teszi azokat a munkafolyamatokat, ahol a TUI csatlakozhat egy távoli gépen futó Codex szerverhez, az ügynököt közel tartva a számítási kapacitáshoz, és a munka akkor is folytatódik, ha a laptop alvó módba kerül vagy a kapcsolat megszakad, miközben továbbra is helyben biztosítja az élő frissítéseket és vezérléseket.

A Codex App Server lesz az elsődleges integrációs megoldás, amelyet továbbra is támogatunk, ugyanakkor vannak más módszerek is, amelyek csak korlátozott funkcionalitást kínálnak. Alapértelmezés szerint azt javasoljuk, hogy az ügyfelek a Codex App Servert használják a Codexszel való integrációhoz, de érdemes megvizsgálni más integrációs módszereket is, és megérteni azok előnyeit és hátrányait. Az alábbiakban a Codex használatának leggyakoribb módjai találhatók, és hogy melyik mikor lehet megfelelő választás.

Futtasd a codex mcp-server⁠(új ablakban nyílik meg) parancsot, és csatlakozz bármely MCP klienshez, amely támogatja a stdio szervereket (például OpenAI Agents SDK⁠(új ablakban nyílik meg)). Ez akkor jó választás, ha már van egy MCP-alapú munkafolyamatod, és a Codexet hívható eszközként szeretnéd használni. Az a hátrány, hogy csak az MCP által kitettségeket érhetjük el, ezért a Codex-specifikus interakciók, amelyek gazdagabb munkamenet-szemantikát igényelnek (pl. diff frissítések), nem mindig kezelhetők zökkenőmentesen az MCP végpontokon keresztül.

Néhány ökoszisztéma hordozható interfészt kínál, amely több modell-szolgáltatót és futtatókörnyezetet célozhat meg. Ez akkor lehet jó választás, ha olyan absztrakcióra van szükséged, amely több ügynököt koordinál. A kompromisszum az, hogy ezek a protokollok gyakran a képességek közös részhalmazára konvergálnak, ami megnehezítheti a gazdagabb interakciók megjelenítését, különösen akkor, amikor a szolgáltatóspecifikus eszköz- és munkamenet-szemantika fontos. A terület gyorsan fejlődik, és arra számítunk, hogy egyre több közös szabvány fog kialakulni, ahogy megtaláljuk a legjobb alapvető elemeket a valós ügynöki munkafolyamatok ábrázolására (készségek⁠(új ablakban nyílik meg) jó példa erre).

Válaszd az App Servert, ha a teljes Codex harness-t stabil, felhasználóbarát eseményfolyamként szeretnéd elérni. Ez lehetővé teszi az ügynök-ciklus teljes funkcionalitásának kihasználását, emellett pedig olyan kiegészítő szolgáltatásokat is, mint a ChatGPT‑vel való bejelentkezés, a modellek felfedezése és a konfiguráció kezelése. A fő költség az integrációs munka, mivel a nyelveden kell megépítened a kliensoldali JSON-RPC kötést. A gyakorlatban azonban a Codex képes elvégezni a munka oroszlánrészét, ha megadod neki a JSON sémát és a dokumentációt. Sok csapat, akikkel együtt dolgoztunk, rövid idő alatt működő integrációt tudott készíteni a Codex használatával.

Egy könnyű, szkriptelhető CLI mód egyszeri feladatok és CI futtatások számára. Ideális automatizálási feladatokhoz és folyamatláncokhoz, ahol egy parancsot kell teljesen, interakció nélkül futtatni, strukturált kimenetet streamelni a naplókhoz, és világos siker- vagy hibaállapotot jelezni a kilépéskor.

TypeScript könyvtár, amely lehetővé teszi a helyi Codex-ügynökök programozott vezérlését a saját alkalmazásodon belül. Akkor a legjobb választás, ha szerveroldali eszközökhöz és munkafolyamatokhoz natív könyvtári felületet szeretnél, anélkül hogy külön JSON-RPC klienst kellene építened. Mivel korábban került kiadásra, mint az App Server, jelenleg kevesebb nyelvet és kisebb felületet támogat. Ha van rá fejlesztői érdeklődés, további SDK-kat is hozzáadhatunk, amelyek az App Server protokollt csomagolják, így a csapatok a harness felületének nagyobb részét fedhetik le JSON-RPC kötés írása nélkül.

Ebben a bejegyzésben bemutattuk, hogyan közelítjük meg az ügynökökkel való interakció új szabványának kialakítását, és hogyan alakítható a Codex harness stabil, kliensbarát protokollá. Áttekintettük, miként teszi elérhetővé az App Server a Codex magját, hogyan engedi a kliensnek a teljes ügynökciklus irányítását, és hogyan támogatja a felületek széles skáláját, beleértve a TUI-t, a helyi IDE-integrációkat és a webes futtatókörnyezetet.

Ha ez ötleteket adott arra, hogyan integrálhatod a Codexet a saját munkafolyamataidba, érdemes kipróbálni az App Servert. Az összes forráskód a Codex CLI nyílt forráskódú repo⁠(új ablakban nyílik meg)-ban található. Nyugodtan oszd meg visszajelzéseidet és funkciókéréseidet. Alig várjuk, hogy halljunk felőled, és folytatjuk azon munkát, hogy az ügynököket mindenki számára könnyen elérhetővé tegyük.