Odklepanje ogrodja Codex: kako smo zgradili App Server

OpenAI-jev agent za kodiranje Codex obstaja na številnih različnih platformah: spletna aplikacija⁠(odpre se v novem oknu), CLI⁠(odpre se v novem oknu), razširitev integriranega razvojnega okolja (IDE)⁠(odpre se v novem oknu) in nova aplikacija Codex za macOS. V ozadju jih vse poganja isto ogrodje Codex – agentska zanka in logika, ki sta temelj vseh izkušenj s Codexom. Kritična povezava med njimi? Codex App Server⁠(odpre se v novem oknu), odjemalcem prijazen, dvosmerni JSON-RPC¹ API.

V tem prispevku bomo predstavili Codex App Server; delili bomo dosedanja spoznanja o najboljših načinih, kako Codexove zmožnosti vključiti v vaš produkt, da bi uporabnikom pomagali okrepiti njihove delovne tokove. Obravnavali bomo arhitekturo in protokol App Serverja ter način, kako se integrira z različnimi okolji Codex, poleg tega pa tudi nasvete za izkoriščanje Codexa, ne glede na to, ali želite Codex spremeniti v pregledovalca kode, agenta SRE ali kodirnega asistenta.

Preden se poglobimo v arhitekturo, je koristno poznati ozadje App Serverja. Sprva je bil App Server praktičen način za ponovno uporabo ogrodja Codex v produktih, nato pa se je postopoma razvil v naš standardni protokol.

Codex CLI se je začel kot TUI (terminalni uporabniški vmesnik), kar pomeni, da se do Codexa dostopa prek terminala. Ko smo zgradili razširitev za VS Code, ki predstavlja boljši način interakcije z agenti Codex, prilagojen integriranemu razvojnemu okolju (IDE), smo potrebovali način, da uporabimo isto ogrodje, tako da lahko isto agentsko zanko poganjamo iz uporabniškega vmesnika IDE brez ponovne implementacije. To je pomenilo podporo bogatim vzorcem interakcije, ki presegajo model zahteva/odgovor, kot so raziskovanje delovnega prostora, pretakanje napredka, ko agent sklepa, in oddajanje diffov. Najprej smo eksperimentirali z izpostavitvijo Codexa kot strežnika protokola za modelni kontekst (MCP)⁠(odpre se v novem oknu), vendar se je vzdrževanje semantike MCP na način, ki bi imel smisel za VS Code, izkazalo za zahtevno. Namesto tega smo uvedli protokol JSON-RPC, ki je zrcalil zanko TUI, kar je postalo neuradna prva različica⁠(odpre se v novem oknu) strežnika aplikacij. Takrat nismo pričakovali, da se bodo drugi odjemalci zanašali na App Server, zato ni bil zasnovan kot stabilen API.

Ker se je uporaba Codexa v naslednjih mesecih povečala, so interne ekipe in zunanji partnerji želeli možnost, da isto ogrodje vdelajo v lastne produkte, da bi pospešili delovne tokove svojih uporabnikov pri razvoju programske opreme. JetBrains in Xcode sta na primer želela agentsko izkušnjo na ravni integriranega razvojnega okolja, medtem ko je namizna aplikacija Codex potrebovala možnost orkestriranja številnih agentov Codex vzporedno. Te zahteve so nas spodbudile k zasnovi platformne površine, na katero bi se lahko naši produkti in partnerske integracije dolgoročno varno zanašali. Ta je morala biti enostavna za integracijo in nazaj združljiva, kar pomeni, da lahko protokol razvijamo, ne da bi prekinili delovanje obstoječih odjemalcev.

V nadaljevanju bomo predstavili, kako smo zasnovali arhitekturo in protokol, tako da lahko različni odjemalci uporabljajo isto ogrodje.

Najprej si podrobneje oglejmo, kaj se nahaja v notranjosti ogrodja Codex in kako to Codex App Server izpostavlja odjemalcem. V našem zadnjem blogu o Codexu smo razčlenili osnovno agentsko zanko, ki orkestrira interakcijo med uporabnikom, modelom in orodji. To predstavlja osnovno logiko ogrodja Codex, vendar celotna agentska izkušnja vključuje še več:

1. Življenjski cikel niti in trajnost Nit je pogovor Codex med uporabnikom in agentom. Codex niti ustvarja, nadaljuje, osami in arhivira ter trajno hrani zgodovino dogodkov, da se lahko odjemalci znova povežejo in izrišejo dosledno časovnico.

2. Konfiguracija in avtentikacija Codex nalaga konfiguracijo, upravlja privzete nastavitve in izvaja avtentikacijske tokove, kot je »Prijavite se s ChatGPT«, vključno s stanjem poverilnic.

3. Izvajanje orodja in razširitve. Codex izvaja lupinska in datotečna orodja v peskovniškem okolju ter povezuje integracije, kot so strežniki protokola za modelni kontekst (MCP) in veščine, tako da lahko v okviru doslednega modela pravil sodelujejo v agentski zanki.

Vsa agentska logika, ki smo jo tukaj omenili, vključno z osnovno agentsko zanko, se nahaja v delu kodne baze Codex CLI, imenovanem »Codex core⁠(odpre se v novem oknu)«. Codex core je hkrati knjižnica, v kateri se nahaja vsa agentska koda, in izvajalno okolje, ki ga je mogoče zagnati za izvajanje agentske zanke ter upravljanje trajnosti ene niti Codex (pogovora).

Da bi bilo ogrodje Codex uporabno, mora biti dostopno odjemalcem. Tu nastopi App Server.

App Server je hkrati protokol JSON-RPC med odjemalcem in strežnikom ter dolgotrajen proces, ki gosti niti Codex core. Kot je razvidno iz zgornjega diagrama, ima proces App Server štiri glavne komponente: bralnik stdio, obdelovalnik sporočil Codex, upravljalnik niti in niti Codex core. Upravljalnik niti za vsako nit zažene eno osnovno sejo, obdelovalnik sporočil Codex pa nato z vsako osnovno sejo neposredno komunicira, da posreduje zahteve odjemalca in prejema posodobitve.

Ena zahteva odjemalca lahko povzroči številne posodobitve dogodkov, prav ti podrobni dogodki pa omogočajo gradnjo bogatega uporabniškega vmesnika nad App Serverjem. Poleg tega bralnik stdio in obdelovalnik sporočil Codex delujeta kot prevajalska plast med odjemalcem in nitmi Codex core. Zahteve odjemalca JSON-RPC prevajata v operacije Codex core, poslušata notranji tok dogodkov Codex core in nato te nizkonivojske dogodke pretvarjata v majhen nabor stabilnih obvestil JSON-RPC, pripravljenih za uporabniški vmesnik.

Protokol JSON-RPC med odjemalcem in App Serverjem je v celoti dvosmeren. Tipična nit ima eno zahtevo odjemalca in številna obvestila strežnika. Poleg tega lahko strežnik sproži zahteve, kadar agent potrebuje vhod, na primer odobritev, in nato potezo začasno ustavi, dokler odjemalec ne odgovori.

V nadaljevanju bomo razčlenili osnovne gradnike pogovora, temeljne elemente protokola App Serverja. Zasnova API-ja za agentsko zanko je zahtevna, ker interakcija med uporabnikom in agentom ni preprosta zahteva/odgovor. Ena uporabniška zahteva se lahko razplete v strukturirano zaporedje dejanj, ki jih mora odjemalec zvesto predstaviti: uporabnikov vnos, postopni napredek agenta in artefakte, ki nastanejo sproti (npr. diffe). Da bi bil ta tok interakcij enostaven za integracijo in odporen v različnih uporabniških vmesnikih, smo se odločili za tri temeljne gradnike z jasnimi mejami in življenjskimi cikli:

1. Element: Element je atomska enota vhoda/izhoda v Codexu. Elementi so tipizirani (npr. uporabniško sporočilo, agentsko sporočilo, izvajanje orodja, zahteva za odobritev, diff) in vsak ima izrecen življenjski cikel:

• item/started ko se element zažene
• neobvezni dogodki item/*/delta, ko se vsebina pretaka (pri pretočnih tipih elementov)
• item/completed, ko se element zaključi s končnim paketom podatkov

Ta življenjski cikel omogoča strankam, da začnejo upodabljati takoj ob started, pretakajo postopne posodobitve ob delta in zaključijo ob completed.

2. Korak: Korak je ena enota agentskega dela, ki jo sproži uporabnikov vnos. Začne se, ko odjemalec pošlje vnos (na primer »zaženi teste in povzemaj napake«), in konča, ko agent zaključi ustvarjanje izhodov za ta vnos. Korak vsebuje zaporedje elementov, ki predstavljajo vmesne korake in izhode, ustvarjene sproti.

3. Niz: Niz je trajni vsebnik za tekočo sejo Codex med uporabnikom in agentom. Vsebuje več korakov. Nize je mogoče ustvariti, nadaljevati, osamiti in arhivirati. Zgodovina niza se trajno shrani, tako da se lahko odjemalci znova povežejo in izrišejo dosledno časovnico.

Zdaj si bomo ogledali poenostavljen pogovor med odjemalcem in agentom, kjer je pogovor predstavljen z gradniki:

Na začetku pogovora morata odjemalec in strežnik vzpostaviti rokovanje z initialize. Odjemalec mora poslati eno samo zahtevo initialize pred katero koli drugo metodo, strežnik pa jo potrdi z odgovorom. S tem strežnik dobi možnost, da objavi svoje zmožnosti, obe strani pa se lahko dogovorita o verzioniranju protokola, zastavicah funkcionalnosti in privzetih nastavitvah, še preden se začne dejansko delo. Tukaj je primer tovora iz razširitve OpenAI za VS Code:

To je odgovor strežnika:

Ko odjemalec pošlje novo zahtevo, bo najprej ustvaril nit in nato potezo. Strežnik bo poslal obvestila o napredku (thread/started in turn/started). Poslal bo tudi vhode, ki jih registrira kot elemente, na primer tukajšnje uporabniško sporočilo.

Priklici orodij so odjemalcu prav tako poslani kot elementi. Poleg tega lahko strežnik zahteva odobritev odjemalca, preden lahko izvede dejanje, tako da pošlje zahtevo strežnika. Odobritev začasno ustavi izvajanje koraka, dokler odjemalec ne odgovori z »allow« (Dovoli) ali »deny« (Zavrni). Tako je videti potek odobritve v razširitvi za VS Code:

Na koncu strežnik pošlje agentsko sporočilo in nato zaključi potezo z dogodkom turn/completed. Dogodki delta agentskega sporočila pretakajo dele sporočila nazaj, dokler se sporočilo ne zaključi z item/completed.

Sporočila v diagramu so poenostavljena zaradi berljivosti. Če želite videti JSON za celotni korak, lahko iz repozitorija Codex CLI zaženete testni odjemalec.

Zdaj si oglejmo, kako različna odjemalska okolja vdelajo Codex prek App Serverja. Obravnavali bomo tri vzorce: lokalne aplikacije in integrirana razvojna okolja (IDE), spletno izvajalno okolje Codex in TUI.

Pri vseh treh je prenos JSON-RPC prek stdio (JSONL). JSON-RPC omogoča enostavno gradnjo odjemalskih vezav v jeziku po vaši izbiri. Okolja Codex in partnerske integracije so implementirala odjemalce App Serverja v jezikih, vključno z Go, Python, TypeScript, Swift in Kotlin. Za TypeScript lahko definicije ustvarite neposredno iz protokola v jeziku Rust z zagonom:

Za druge jezike lahko ustvarite sveženj JSON Schema in ga posredujete izbranemu generatorju kode z zagonom:

Lokalni odjemalci običajno zapakirajo ali pridobijo binarno datoteko App Serverja, specifično za platformo, jo zaženejo kot dolgotrajen podproces in ohranijo odprt dvosmeren kanal stdio za JSON-RPC. V naši razširitvi za VS Code in namizni aplikaciji na primer distribuirani artefakt vključuje binarno datoteko Codex, specifično za platformo, in je pripet na preizkušeno različico, tako da odjemalec vedno izvaja točno tiste bite, ki smo jih validirali.

Ni vsaka integracija, ki lahko pogosto pošilja posodobitve odjemalca. Nekateri partnerji, kot je Xcode, ločijo cikle izdaj tako, da ohranijo odjemalca stabilnega in mu po potrebi omogočijo, da kaže na novejšo binarno datoteko strežnika aplikacij. Na ta način lahko prevzamejo izboljšave na strani strežnika (npr. boljše samodejno zgoščevanje v Codex core ali na novo podprte konfiguracijske ključe) in uvedejo popravke napak, ne da bi čakali na izdajo odjemalca. Površina JSON-RPC App Serverja je zasnovana kot nazaj združljiva, zato se lahko starejši odjemalci varno povezujejo z novejšimi strežniki.

Codex Web uporablja ogrodje Codex, vendar ga izvaja v vsebniškem okolju. Delavec zagotovi vsebnik s prevzetim delovnim prostorom, v njem zažene binarno datoteko App Serverja in vzdržuje dolgotrajen kanal JSON-RPC prek stdio². Spletna aplikacija (ki teče v uporabnikovem zavihku brskalnika) komunicira z zaledjem Codex prek HTTP in SSE, ki pretakata dogodke nalog, ki jih proizvaja delavec. S tem ostane uporabniški vmesnik na strani brskalnika lahek, hkrati pa je zagotovljeno dosledno izvajalno okolje na namizju in v spletu.

Ker so spletne seje kratkotrajne (zavihki se zaprejo, omrežja se prekinejo), spletna aplikacija ne more biti zanesljiv vir za dolgotrajne naloge. Ohranjanje stanja in napredka na strežniku pomeni, da delo teče naprej tudi, če zavihek izgine. Pretočni protokol in shranjene seje niti omogočajo, da se nova seja enostavno znova poveže, nadaljuje tam, kjer se je ustavila, in dohiti stanje brez ponovne vzpostavitve stanja v odjemalcu.

Zgodovinsko gledano je bil TUI »domorodni« odjemalec, ki je tekel v istem procesu kot agentska zanka in je komuniciral neposredno z osnovnimi tipi v jeziku Rust, namesto prek protokola App Serverja. To je omogočalo hitro zgodnje iteriranje, vendar je TUI hkrati postal poseben primer med okolji.

Zdaj, ko App Server obstaja, načrtujemo preoblikovanje TUI-ja⁠(odpre se v novem oknu), da ga bo uporabljal, tako da se bo obnašal kot vsak drug odjemalec: zagnal bo podproces App Serverja, komuniciral z JSON-RPC prek stdio ter izrisoval iste pretočne dogodke in odobritve. To odpira delovne tokove, v katerih se TUI lahko poveže s strežnikom Codex, ki teče na oddaljenem računalniku, pri čemer agent ostane blizu računskih virov in nadaljuje delo tudi, če prenosnik preide v stanje mirovanja ali se odklopi, hkrati pa se lokalno še vedno zagotavljajo sprotne posodobitve in nadzor.

Codex App Server bo metoda integracije prvega razreda, ki jo bomo v prihodnje vzdrževali, obstajajo pa tudi druge metode z bolj omejeno funkcionalnostjo. Privzeto priporočamo, da odjemalci za integracijo s Codexom uporabijo Codex App Server, vendar se je smiselno seznaniti tudi z različnimi metodami integracije ter razumeti njihove prednosti in slabosti. Spodaj so navedeni najpogostejši načini upravljanja Codexa in primeri, kdaj je vsak primeren.

Zaženite codex mcp-server⁠(odpre se v novem oknu) in se povežite iz katerega koli odjemalca MCP, ki podpira strežnike stdio (npr. OpenAI Agents SDK⁠(odpre se v novem oknu)). Ta pristop je primeren, če že uporabljate delovni tok, ki temelji na MCP, in želite Codex priklicati kot klicljivo orodje. Slaba stran je, da dobite le tisto, kar izpostavlja MCP, zato se interakcije, specifične za Codex, ki temeljijo na bogatejši semantiki sej (npr. posodobitve diffov), morda ne preslikajo čisto skozi končne točke MCP.

Nekateri ekosistemi ponujajo prenosljiv vmesnik, ki lahko cilja na več ponudnikov modelov in izvajalnih okolij. To je lahko dobra izbira, če želite eno abstrakcijo, ki usklajuje več agentov. Kompromis je v tem, da se ti protokoli pogosto zbližajo na skupni podmnožici zmožnosti, kar lahko oteži predstavitev bogatejših interakcij, zlasti kadar so pomembne semantike orodij in sej, ki so specifične za posameznega ponudnika. To področje se hitro razvija, in pričakujemo, da se bodo pojavili bolj razširjeni skupni standardi, ko bomo ugotavljali, kateri so najboljši osnovni gradniki za predstavitev delovnih tokov agentov v resničnem svetu (skills⁠(odpre se v novem oknu) je dober primer tega).

App Server izberite, ko želite, da je celotni Codex harness izpostavljen kot stabilen tok dogodkov, prilagojen uporabniškemu vmesniku. Dobite tako celotno funkcionalnost zanke agenta kot tudi druge podporne funkcionalnosti, kot so prijava s ChatGPT, odkrivanje modelov in upravljanje konfiguracije. Glavni strošek predstavlja integracijsko delo, saj morate v svojem jeziku zgraditi vezavo JSON-RPC na strani odjemalca. V praksi pa Codex lahko opravi velik del zahtevnega dela, če mu posredujete shemo JSON in dokumentacijo. Številne ekipe, s katerimi smo sodelovali, so s pomočjo Codex hitro vzpostavile delujočo integracijo.

Način CLI z enostavnim skaliranjem za enkratna opravila in CI zagone. Primeren je za avtomatizacijo in cevovode, kjer želite en sam ukaz, ki se brez interakcije izvede do konca, pretaka strukturirane izhode za dnevnike in se konča z jasnim signalom o uspehu ali neuspehu.

Knjižnica TypeScript za programsko nadziranje lokalnih agentov Codex znotraj lastne aplikacije. Najprimernejša je, kadar želite domorodni knjižnični vmesnik za orodja in delovne tokove na strani strežnika, ne da bi zgradili ločenega odjemalca JSON-RPC. Ker je bila izdana prej kot App Server, trenutno podpira manj jezikov in manjši nabor funkcionalnosti. Če bo med razvijalci dovolj zanimanja, bomo morda dodali dodatne SDK-je, ki ovijejo protokol App Server, tako da bodo ekipe lahko pokrile večji del površine harnessa brez pisanja vezav JSON-RPC.

V tej objavi smo predstavili, kako pristopamo k zasnovi novega standarda za interakcijo z agenti in kako Codex harness pretvoriti v stabilen, odjemalcem prijazen protokol. Opisali smo, kako App Server izpostavlja jedro Codex, omogoča odjemalcem upravljanje celotne zanke agenta ter poganja širok nabor površin, vključno s TUI, lokalnimi integracijami IDE in spletnim izvajalnim okoljem.

Če je to spodbudilo ideje za integracijo Codex v vaše lastne delovne tokove, je smiselno preizkusiti App Server. Vsa izvorna koda je v odprtokodnem repozitorij⁠(odpre se v novem oknu) Codex CLI. Brez zadržkov delite povratne informacije in zahteve za funkcionalnosti. Veselimo se vašega odziva in tega, da bomo agente še naprej približevali vsem.