OpenAIs kodeagent Codex finnes på mange forskjellige plattformer: webappen(åpnes i et nytt vindu), CLI-en(åpnes i et nytt vindu), IDE-utvidelsen(åpnes i et nytt vindu) og den nye Codex macOS-appen. Under panseret drives de alle av den samme Codex-selen – agentsløyfen og logikken som ligger til grunn for alle Codex-opplevelser. Den kritiske koblingen mellom dem? Codex App Server(åpnes i et nytt vindu), en brukervennlig, toveis JSON-RPC1 API.
I dette innlegget skal vi introdusere Codex App Server. Vi deler erfaringene våre så langt om de beste måtene å integrere Codex sine funksjoner i produktet ditt for å hjelpe brukerne med å forbedre arbeidsflytene sine. Vi vil dekke App Server sin arkitektur og protokoll og hvordan den integreres med forskjellige Codex-overflater, samt tips om hvordan du kan utnytte Codex, enten du vil gjøre Codex om til en kodegjennomgangsperson, en SRE-agent eller en kodeassistent.
Før du dykker ned i arkitekturen, er det nyttig å kjenne til bakhistorien til App Server. I utgangspunktet var App Server en praktisk måte å gjenbruke Codex-selen på tvers av produkter, som gradvis utviklet seg til vår standardprotokoll.
Codex CLI startet som et TUI (terminalbrukergrensesnitt), noe som betyr at Codex kan nås via terminalen. Da vi bygde VS Code-utvidelsen (en mer IDE-vennlig måte å samhandle med Codex-agenter på), trengte vi en måte å bruke samme sele for å drive den samme agentløkken fra et IDE-grensesnitt uten å implementere den på nytt. Det betydde å støtte rike interaksjonsmønstre utover forespørsel/svar, som å utforske arbeidsområdet, strømme fremdrift mens agenten resonnerer, og sende ut differanser. Vi eksperimenterte først med å eksponere Codex som en MCP-server(åpnes i et nytt vindu), men det viste seg å være vanskelig å opprettholde MCP-semantikk på en måte som ga mening for VS Code. I stedet introduserte vi en JSON-RPC-protokoll som speilet TUI-løkken, som ble den uoffisielle første versjon(åpnes i et nytt vindu) av App Server. På den tiden forventet vi ikke at andre klienter ville være avhengige av App Server, så den ble ikke utviklet som et stabilt API.
Etter hvert som adopsjonen av Codex økte i løpet av de neste månedene, ønsket interne team og eksterne partnere muligheten til å integrere den samme løsningen i sine egne produkter for å fremskynde brukernes arbeidsflyter for programvareutvikling. For eksempel ønsket JetBrains og Xcode en agentopplevelse på IDE-nivå, mens Codex-skrivebordsappen måtte orkestrere mange Codex-agenter parallelt. Disse kravene presset oss til å designe en plattformoverflate som både produktene våre og partnerintegrasjoner trygt kunne stole på over tid. Det måtte være enkelt å integrere og bakoverkompatibelt, noe som betydde at vi kunne videreutvikle protokollen uten å ødelegge eksisterende klienter.
Deretter skal vi gå gjennom hvordan vi designet arkitekturen og protokollen slik at forskjellige klienter kan bruke den samme selen.
La oss først se nærmere på hva som er inni Codex-selen og hvordan Codex App Server eksponerer den for klienter. I vår siste Codex-blogg forklarte vi kjernen i agentløkken som orkestrerer samspillet mellom brukeren, modellen og verktøyene. Dette er kjernelogikken i Codex-selen, men det er mer ved den komplette agentopplevelsen:
1. Trådens livssyklus og persistens. En tråd er en Codex-samtale mellom en bruker og en agent. Codex oppretter, gjenopptar, kopierer og arkiverer tråder, og lagrer hendelseshistorikken slik at klienter kan koble til på nytt og gjengi en konsistent tidslinje.
2. Konfigurasjon og autentisering. Codex laster inn konfigurasjon, administrerer standardinnstillinger og kjører autentiseringsflyter som «Logg på med ChatGPT», inkludert legitimasjonsstatus.
3. Verktøyutførelse og utvidelser. Codex kjører skall-/filverktøy i en sandkasse og kobler til integrasjoner som MCP-servere og ferdigheter, slik at de kan delta i agentløkken under en konsistent policymodell.
All agentlogikken vi nevnte her, inkludert kjerneagentløkken, ligger i en del av Codex CLI-kodebasen kalt «Codex-kjerne(åpnes i et nytt vindu)». Codex-kjernen er både et bibliotek der all agentkoden ligger og en kjøretid som kan startes for å kjøre agentløkken og administrere vedvarigheten til én Codex-tråd (samtale).
For å være nyttig, må Codex-selen være tilgjengelig for klienter. Det er der App Server kommer inn i bildet.
App Server er både JSON-RPC-protokollen mellom klienten og serveren og en langvarig prosess som er vert for Codex-kjernetrådene. Som vi kan se i diagrammet ovenfor, har en App Server-prosess fire hovedkomponenter: stdio-leseren, Codex-meldingsprosessoren, trådbehandleren og kjernetråder. Trådbehandleren starter én kjerneøkt for hver tråd, og Codex-meldingsprosessoren kommuniserer deretter direkte med hver kjerneøkt for å sende inn klientforespørsler og motta oppdateringer.
Én klientforespørsel kan resultere i mange hendelsesoppdateringer, og det er disse detaljerte hendelsene som lar oss bygge et rikt brukergrensesnitt oppå App Server. Videre fungerer stdio-leseren og Codex-meldingsprosessoren som oversettelseslaget mellom klienten og Codex-kjernetrådene. De oversetter klientens JSON-RPC-forespørsler til Codex-kjerneoperasjoner, lytter til Codex-kjernens interne hendelsesstrøm og transformerer deretter disse lavnivåhendelsene til et lite sett med stabile, brukergrensesnittklare JSON-RPC-varsler.
JSON-RPC-protokollen mellom klienten og App Server er helt toveis. En typisk tråd har en klientforespørsel og mange servervarsler. I tillegg kan serveren starte forespørsler når agenten trenger inndata, som en godkjenning, og deretter sette turen på pause til klienten svarer.
Deretter skal vi forklare samtaleprimitivene, byggeklossene i App Server-protokollen. Det er vanskelig å designe et API for en agentløkke fordi bruker/agent-interaksjonen ikke er en enkel forespørsel/svar. Én brukerforespørsel kan utfolde seg til en strukturert sekvens av handlinger som klienten må representere trofast: brukerens inndata, agentens trinnvise fremgang, artefakter som produseres underveis (f.eks. differanser). For å gjøre den interaksjonsstrømmen enkel å integrere og robust på tvers av brukergrensesnitt, kom vi frem til tre kjerneprimitiver med klare grenser og livssykluser:
1. Element: Et element er den atomære enheten for inndata/utdata i Codex. Elementer er kategorisert (f.eks. brukermelding, agentmelding, verktøyutførelse, godkjenningsforespørsel, forskjeller) og hver har en eksplisitt livssyklus:
element/startetnår elementet begynner- valgfrie
element/*/delta-hendelser som innholdsstrømmer i (for strømmeelementtyper) element/fullførtnår elementet fullføres med sin terminalnyttelast
Denne livssyklusen lar klienter starte gjengivelse umiddelbart ved startet, strømme trinnvise oppdateringer ved delta og fullføre når fullført.
2. Runde: En tur er én enhet med agentarbeid initiert av brukerinndata. Det begynner når klienten sender inn en inndata (for eksempel «kjør tester og oppsummer feil») og slutter når agenten er ferdig med å produsere utdata for den inndataen. En tur inneholder en sekvens av elementer som representerer mellomtrinnene og resultatene som produseres underveis.
3. Tråd: En tråd er en varig beholder for en pågående Codex-økt mellom en bruker og en agent. Den inneholder flere turer. Tråder kan opprettes, gjenopptas, kopieres og arkiveres. Trådhistorikken lagres slik at klienter kan koble til igjen og gjengi en konsistent tidslinje.
Nå skal vi se på en forenklet samtale mellom en klient og en agent, der samtalen er representert av primitiver:
I begynnelsen av samtalen må klienten og serveren etablere initialiser-håndtrykket. Klienten må sende en enkelt initialiser-forespørsel før noen annen metode, og serveren bekrefter med et svar. Dette gir serveren en sjanse til å annonsere muligheter og lar begge sider bli enige om protokollversjonering, funksjonsflagg og standardinnstillinger før det virkelige arbeidet begynner. Her er et eksempel på en nyttelast fra OpenAIs VS Code-utvidelse:
Dette er hva serveren returnerer:
Når en klient lager en ny forespørsel, vil den først opprette en tråd og deretter en tur. Serveren vil sende tilbake varsler om fremdrift (tråd/startet og tur/startet). Den vil også sende tilbake inndata den registrerer som elementer, som brukermeldingen her.
Verktøykall sendes også tilbake til klienten som elementer. I tillegg kan serveren be om godkjenning fra klienten før den kan utføre en handling ved å sende en serverforespørsel. Godkjenningen vil sette runden på pause inntil klienten svarer med enten «tillat» eller «avslå». Slik ser godkjenningsflyten ut i VS Code-utvidelsen:
Til slutt sender serveren en agent melding og avslutter deretter turen med tur/fullført. Agentmeldingens deltahendelser strømmer deler av meldingen tilbake til meldingen er ferdigstilt med element/fullført.
Meldingene i diagrammet er forenklet for å være lesbare. Hvis du vil se JSON for en hel runde, kan du kjøre testklienten fra Codex CLI repo:
Nå skal vi se på hvordan forskjellige klientflater integrerer Codex via App Server. Vi skal dekke tre mønstre: lokale apper og IDE-er, Codex web-runtime, og TUI-en.
På tvers av alle tre er transporten JSON-RPC over stdio (JSONL). JSON-RPC gjør det enkelt å bygge klientbindinger på det språket du ønsker. Codex-grensesnitt og partnerintegrasjoner har implementert App Server-klienter på språk som Go, Python, TypeScript, Swift og Kotlin. For TypeScript kan du generere definisjoner direkte fra Rust-protokollen ved å kjøre:
For andre språk kan du generere en JSON-skjemapakke og mate den inn i din foretrukne kodegenerator ved å kjøre:
Lokale klienter pakker eller henter vanligvis en plattformspesifikk App Server-binærfil, starter den som en langvarig underordnet prosess og holder en toveis stdio-kanal åpen for JSON-RPC. I VS Code-utvidelsen og skrivebordsappen vår, for eksempel, inkluderer den leverte artefakten den plattformspesifikke Codex-binærfilen og er festet til en testet versjon, slik at klienten alltid kjører nøyaktig de bitene vi validerte.
Ikke alle integrasjoner kan sende klientoppdateringer ofte. Noen partnere som Xcode frikobler utgivelsessykluser ved å holde klienten stabil og la den peke til en nyere App Server-binærfil ved behov. På den måten kan de ta i bruk forbedringer på serversiden (for eksempel bedre automatisk komprimering i Codex-kjernen eller nylig støttede konfigurasjonsnøkler) og rulle ut feilrettinger uten å vente på en klientutgivelse. App Servers JSON-RPC-overflate er utformet for å være bakoverkompatibel, slik at eldre klienter kan kommunisere med nyere servere på en trygg måte.
Codex Web bruker Codex-selen, men kjører det i et beholdermiljø. En arbeider klargjør en beholder med det utsjekkede arbeidsområdet, starter App Server-binærfilen inni den og vedlikeholder en langvarig JSON-RPC over stdio2-kanalen. Nettappen (som kjører i brukerens nettleserfane) kommuniserer med Codex-backend via HTTP og SSE, som strømmer oppgavehendelser produsert av arbeideren. Dette holder brukergrensesnittet på nettlesersiden lett, samtidig som det fortsatt gir oss en konsistent kjøretid på tvers av skrivebord og nett.
Fordi nettøkter er flyktige (faner lukkes, nettverk kobles fra), kan ikke nettappen være den pålitelige kilden for langvarige oppgaver. Det å holde status og fremdrift på serveren betyr at arbeidet fortsetter selv om fanen forsvinner. Strømmeprotokollen og lagrede trådøkter gjør det enkelt for en ny økt å koble til igjen, fortsette der den slapp og ta igjen det tapte uten å gjenoppbygge tilstanden i klienten.
Historisk sett var TUI en «nativ» klient som kjørte i samme prosess som agentløkken og kommuniserte direkte med Rust-kjernetyper i stedet for app-server-protokollen. Det gjorde tidlig iterasjon rask, men det gjorde også TUI-en til en spesialtilfelle-overflate.
Nå som App Server finnes, planlegger vi å omstrukturere TUI-(åpnes i et nytt vindu) en slik at den oppfører seg som en hvilken som helst annen klient: starte en underordnet App Server-prosess, kommunisere JSON-RPC over stdio og gjengi de samme strømmehendelsene og godkjenningene. Dette åpner for arbeidsflyter der TUI-en kan koble seg til en Codex-server som kjører på en ekstern maskin, slik at agenten holder seg nær datamaskinen og kan fortsette arbeidet selv om den bærbare datamaskinen sover eller kobles fra, samtidig som den leverer liveoppdateringer og kontroller lokalt.
Codex App Server vil være den førsteklasses integrasjonsmetoden vi vedlikeholder fremover, men det finnes også andre metoder med mer begrenset funksjonalitet. Som standard anbefaler vi at kundene bruker Codex App Server for å integrere med Codex, men det er verdt å se på ulike integrasjonsmetoder og forstå deres fordeler og ulemper. Nedenfor er de vanligste måtene å drive Codex på, og når hver av dem kan være en god løsning.
Kjør codex mcp-server(åpnes i et nytt vindu) og koble til fra hvilken som helst MCP-klient som støtter stdio-servere (f.eks. OpenAI Agents SDK(åpnes i et nytt vindu)). Dette passer godt hvis du allerede har en MCP-basert arbeidsflyt og ønsker å bruke Codex som et kallbart verktøy. Ulempen er at du bare får det MCP eksponerer, så Codex-spesifikke interaksjoner som er avhengige av rikere øktsemantikk (f.eks. diff-oppdateringer) kanskje ikke kan kartlegges tydelige gjennom MCP-endepunkter.
Noen økosystemer tilbyr et portabelt grensesnitt som kan målrettes mot flere modelleverandører og kjøretider. Dette kan være en god løsning hvis du ønsker én abstraksjon som koordinerer flere agenter. Kompromisset er at disse protokollene ofte konvergerer mot det felles delsettet av funksjoner, noe som kan gjøre det vanskeligere å representere rikere interaksjoner, spesielt når leverandørspesifikke verktøy- og øktsemantikker er viktige. Dette området utvikler seg raskt, og vi forventer at flere felles standarder vil dukke opp etter hvert som vi finner ut de beste primitivene for å representere virkelige agentarbeidsflyter (ferdigheter(åpnes i et nytt vindu) er et godt eksempel på dette).
Velg App Server når du vil at hele Codex-selen skal eksponeres som en stabil, UI-vennlig hendelsesstrøm. Du får både full funksjonalitet til agentløkken og andre støttefunksjoner som Logg på med ChatGPT, modelloppdagelse og konfigurasjonsadministrasjon. Hovedkostnaden er integrasjonsarbeid, siden du må bygge JSON-RPC-bindingen på klientsiden på språket ditt. I praksis kan Codex imidlertid gjøre mye av det tunge arbeidet hvis du gir den JSON-skjemaet og dokumentasjonen. Mange team vi jobbet med klarte raskt å få til en fungerende integrasjon ved hjelp av Codex.
En lett, skriptbar CLI-modus for engangsoppgaver og CI-kjøringer. Det passer godt for automatisering og pipelines der du vil at én enkelt kommando skal kjøres til fullføring ikke-interaktivt, strømme strukturert utdata for logger og avslutte med et tydelig signal om suksess eller feil.
Et TypeScript-bibliotek for programmatisk kontroll av lokale Codex-agenter fra din egen applikasjon. Det er best når du ønsker et innebygd bibliotekgrensesnitt for verktøy og arbeidsflyter på serversiden uten å bygge en separat JSON-RPC-klient. Siden den ble levert tidligere enn App Server, støtter den for øyeblikket færre språk og et mindre overflateareal. Hvis det er interesse fra utviklerne, kan vi legge til flere SDK-er som omslutter App Server-protokollen, slik at team kan dekke mer av seleflaten uten å skrive JSON-RPC-bindinger.
I dette innlegget delte vi hvordan vi går frem for å designe en ny standard for samhandling med agenter og hvordan vi kan gjøre Codex-selen om til en stabil og klientvennlig protokoll. Vi dekket hvordan App Server eksponerer Codex-kjernen, lar klienter kjøre hele agentløkken og driver et bredt spekter av overflater, inkludert TUI, lokale IDE-integrasjoner og webkjøringstiden.
Hvis dette ga deg ideer til å integrere Codex i dine egne arbeidsflyter, er det verdt å prøve App Server. Hele kildekoden ligger i Codex CLIs åpen kildekode repo(åpnes i et nytt vindu). Del gjerne tilbakemeldinger og funksjonsforespørsler. Vi gleder oss til å høre fra deg og til å fortsette å gjøre agenter mer tilgjengelige for alle.
Forfatter
Anerkjennelser
Spesiell takk til Michael Bolin, Owen Lin, Eric Traut og Rasmus Rygaard, som bidro til dette innlegget, og til hele Codex-teamet som jobbet med App Server.
Fotnoter
- 1
Vi bruker en «JSON-RPC lite»-variant: den beholder forespørsel/svar/varslingsform, men utelater
«jsonrpc»: «2.0»header og er innrammet som JSONL over stdio i stedet for streng JSON‑RPC 2.0. - 2
«stdio» refererer til app-serverens stdin/stdout inne i beholderen. I vertsbaserte oppsett blir disse strømmene ofte tunnelert over en vedvarende nettverkstilkobling (f.eks. WebSocket-lignende) til beholderens kjøretidspunkt – slik at den oppfører seg som stdio selv om det ikke er en bokstavelig lokal pipe.
