Zhbllokimi i Codex harness: si e ndërtuam serverin e aplikacionit

Agjenti i kodimit i OpenAI, Codex, është i disponueshëm në shumë platforma të ndryshme: aplikacioni në ueb⁠(hapet në një dritare të re), CLI⁠(hapet në një dritare të re), zgjerimi i IDE⁠(hapet në një dritare të re) dhe aplikacioni i ri Codex për macOS. Nën kapak, të gjitha fuqizohen nga i njëjti Codex harness — cikël agjenti dhe logjika që qëndron në themel të të gjitha përvojave të Codex. Cila është lidhja kritike midis tyre? Codex App Server⁠(hapet në një dritare të re), një API JSON-RPC¹ miqësore për klientët, me komunikim të ndërsjellë.

Në këtë postim, do të prezantojmë Codex App Server; do të ndajmë mësimet tona deri tani mbi mënyrat më të mira për të sjellë aftësitë e Codex në produktin tënd për t'i ndihmuar përdoruesit e tu të përmirësojnë ndjeshëm rrjedhat e tyre të punës. Do të mbulojmë arkitekturën dhe protokollin e App Server dhe mënyrën se si integrohet me sipërfaqet e ndryshme të Codex, si dhe këshilla për të shfrytëzuar Codex, pavarësisht nëse dëshiron ta kthesh Codex në një shqyrtues kodi, një agjent SRE, ose një asistent kodimi.

Para se të zhytemi në arkitekturë, është e dobishme të dimë historinë e App Server. Fillimisht, App Server ishte një mënyrë praktike për të ripërdorur Codex harness nëpër produkte, që gradualisht evoluoi në protokollin tonë standard.

Codex CLI filloi si një TUI (ndërfaqe përdoruesi e terminalit), që do të thotë se Codex aksesohet përmes terminalit. Kur ndërtuam zgjerimin e VS Code (një mënyrë më miqësore për IDE për të bashkëvepruar me agjentët Codex), na duhej një mënyrë për të përdorur të njëjtin mekanizëm në mënyrë që të drejtonim të njëjtin cikël të agjentit nga një ndërfaqe përdoruesi e IDE pa e riimplementuar atë. Kjo nënkuptonte mbështetjen e modeleve të pasura të ndërveprimit përtej kërkesë/përgjigje, si eksplorimi i hapësirë pune, transmetimi i progresit ndërsa agjenti arsyeton, dhe gjenerimi i ndryshimeve. Fillimisht eksperimentuam me ekspozimin e Codex si një server MCP⁠(hapet në një dritare të re), por mirëmbajtja e semantikës MCP në një mënyrë që kishte kuptim për VS Code u tregua e vështirë. Në vend të kësaj, ne prezantuam një protokoll JSON-RPC që pasqyronte ciklin TUI, i cili u bë versioni i parë jozyrtar⁠(hapet në një dritare të re) i App Server. Në atë kohë, nuk prisnim që klientë të tjerë të vareshin nga App Server, kështu që nuk ishte projektuar si një API e qëndrueshme.

Ndërsa adoptimi i Codex u rrit gjatë muajve të ardhshëm, ekipet e brendshme dhe partnerët e jashtëm dëshironin mundësinë për të integruar të njëjtin mjet në produktet e tyre për të përshpejtuar rrjedhat e punës së zhvillimit të softuerit për përdoruesit e tyre. Për shembull, JetBrains dhe Xcode donin një përvojë agjenti të nivelit IDE, ndërsa aplikacioni desktop Codex duhej të orkestronte shumë agjentë Codex në të njëjtën kohë. Këto kërkesa na shtynë të projektonim një sipërfaqe platforme mbi të cilën si produktet tona ashtu edhe integrimet e partnerëve mund të mbështeteshin në mënyrë të sigurtë me kalimin e kohës. Duhej të ishte e lehtë për t'u integruar dhe e përputhshme me versionet e mëparshme, që do të thotë se mund ta zhvillonim protokollin pa prishur klientët ekzistues.

Më pas, do të shpjegojmë se si e dizajnuam arkitekturën dhe protokollin në mënyrë që klientë të ndryshëm të mund të përdorin të njëjtin sistem.

Së pari, le të zmadhojmë se çfarë ndodhet brenda Codex harness dhe si Codex App Server e ekspozon atë për klientët. Në blogun tonë të fundit të Codex, ne zbërthyem ciklin bazë të agjentit që orkestron ndërveprimin midis përdoruesit, modelit dhe mjeteve. Kjo është logjika bazë e sistemit Codex, por ka më shumë për përvojën e plotë të agjentit:

1. Cikli jetik i temës dhe qëndrueshmëria. Tema është një bisedë Codex midis një përdoruesi dhe një agjenti. Codex krijon, rifillon, bën bigëzime dhe arkivon tema, duke ruajtur historikun e ngjarjeve që klientët të mund të rilidhen dhe të shfaqin një kronologji të qëndrueshme.

2. Konfig dhe autentikim. Codex ngarkon konfigurimin, menaxhon parazgjedhjet dhe ekzekuton flukse autentikimi si “Identifikohu me ChatGPT”, duke përfshirë gjendjen e kredencialeve.

3. Ekzekutimi i mjetit dhe zgjerimet. Codex ekzekuton mjetet shell/file në një sandbox dhe lidh integrime si serverët MCP dhe aftësitë që të mund të marrin pjesë në ciklin e agjentit nën një model të qëndrueshëm politikash.

E gjithë logjika e agjentit që përmendëm këtu, duke përfshirë ciklin bazë të agjentit, gjendet në një pjesë të bazës së kodit të Codex CLI të quajtur “Codex core⁠(hapet në një dritare të re).” Codex core është një bibliotekë ku ndodhet i gjithë kodi i agjentit dhe një mjedis ekzekutimi që mund të aktivizohet për të drejtuar ciklin e agjentit dhe për të menaxhuar ruajtjen e një bisede Codex.

Që të jetë i dobishëm, Codex harness duhet të jetë i aksesueshëm për klientët. Këtu hyn në lojë Serveri i Aplikacioneve.

App Server është njëkohësisht protokolli JSON-RPC midis klientit dhe serverit dhe një proces afatgjatë që hoston temat bazë të Codex. Siç mund ta shohim nga diagrami më sipër, një proces i App Server ka katër komponentë kryesorë: lexuesin stdio, përpunuesin e mesazheve Codex, menaxherin e fijeve dhe temat bazë. Menaxheri i temave krijon një sesion bazë për çdo temë, dhe përpunuesi i mesazheve të Codex pastaj komunikon drejtpërdrejt me secilin sesion bazë për të dorëzuar kërkesat e klientit dhe për të marrë përditësime.

Një kërkesë e vetme e klientit mund të rezultojë në shumë përditësime ngjarjesh, dhe këto ngjarje të detajuara janë ato që na lejojnë të ndërtojmë një UI të pasur mbi Serverin e Aplikacionit. Për më tepër, lexuesi stdio dhe procesori i mesazheve Codex shërbejnë si shtresa e përkthimit midis klientit dhe temave bazë të Codex. Ato përkthejnë kërkesat JSON-RPC të klientit në operacione bazë të Codex, dëgjojnë rrjedhën e brendshme të ngjarjeve të bërthamës së Codex dhe më pas i shndërrojnë ato ngjarje të nivelit të ulët në një grup të vogël njoftimesh JSON-RPC të qëndrueshme, të gatshme për UI.

Protokolli JSON-RPC midis klientit dhe App Server është plotësisht dykahësh. Një temë tipike ka një kërkesë nga klienti dhe shumë njoftime nga serveri. Përveç kësaj, serveri mund të nisë kërkesa kur agjenti ka nevojë për input, si një miratim, dhe pastaj të ndalojë radhën derisa klienti të përgjigjet.

Më pas, do të zbërthejmë primitivët e bisedës, blloqet ndërtuese të protokollit App Server. Projektimi i një API për një cikël agjenti është i ndërlikuar sepse ndërveprimi mes përdoruesit dhe agjentit nuk është një kërkesë/përgjigje e thjeshtë. Një kërkesë përdoruesi mund të shpaloset në një sekuencë të strukturuar veprimesh që klienti duhet ta përfaqësojë me besnikëri: inputi i përdoruesit, progresi gradual i agjentit, artefaktet e prodhuara gjatë rrugës (p.sh., diffs). Për ta bërë atë rrjedhë ndërveprimi të lehtë për t'u integruar dhe të qëndrueshme në të gjitha ndërfaqet e përdoruesit, u përqendruam te tre primitivë kryesorë me kufij dhe cikle jetësore të qarta:

1. Artikull: Një artikull është njësia themelore e hyrje/daljes në Codex. Artikujt janë të tipizuar (p.sh., mesazh përdoruesi, mesazh agjent, ekzekutim mjeti, kërkesë miratimi, ndryshim) dhe secili ka një cikël jete të qartë:

• item/started kur fillon artikulli
• ngjarje opsionale item/*/delta si rrjedha përmbajtjeje (për llojet e artikujve me transmetim)
• item/completed kur artikulli përfundon me ngarkesën e tij përfundimtare

Ky cikël jetësor u lejon klientëve të fillojnë renderimin menjëherë në started, të transmetojnë përditësime inkrementale në delta dhe të përfundojnë në completed.

2. Radha: Radha është një njësi pune e agjentit që fillon me hyrjen e përdoruesit. Fillon kur klienti dorëzon një input (për shembull, “ekzekuto testet dhe përmblidh dështimet”) dhe përfundon kur agjent mbaron së prodhuari outpute për atë input. Një kthesë përmban një sekuencë elementesh që përfaqësojnë hapat ndërmjetës dhe rezultatet e prodhuara gjatë procesit.

3. Bashkëbisedim: Një bashkëbisedim është kontejneri i qëndrueshëm për një sesion të vazhdueshëm Codex midis një përdoruesi dhe një agjenti. Përmban disa radhë. Temat mund të krijohen, rifillohen, degëzohen dhe arkivohen. Historiku i temës ruhet që klientët të mund të rilidhen dhe të shfaqin një kronologji të qëndrueshme.

Tani, do të shohim një bisedë të thjeshtuar midis një klienti dhe një agjenti, ku biseda përfaqësohet nga primitivë:

Në fillim të bisedës, klienti dhe serveri duhet të vendosin dorë-shtrëngimin initialize. Klienti duhet të dërgojë një kërkesë të vetme initialize përpara çdo metode tjetër dhe serveri e konfirmon me një përgjigje. Kjo i jep serverit një mundësi për të reklamuar aftësitë dhe u lejon të dyja palëve të bien dakord për versionimin e protokollit, flamujt e veçorive dhe parazgjedhjet përpara se të fillojë puna e vërtetë. Ja një shembull payload nga zgjerimi i OpenAI për VS Code:

Kjo është ajo që serveri kthen:

Kur një klient bën një kërkesë të re, fillimisht do të krijojë një thread dhe pastaj një radhë. Serveri do të dërgojë njoftime për ecurinë (thread/started dhe turn/started). Do të dërgojë gjithashtu mbrapsht hyrjet që i regjistron si artikuj, siç është mesazhi i përdoruesit këtu.

Thirrjet e mjeteve dërgohen gjithashtu te klienti si elemente. Përveç kësaj, serveri mund të kërkojë miratimin e klientit përpara se të ekzekutojë një veprim duke dërguar një kërkesë serveri. Miratimi do të ndalojë radhën derisa klienti të përgjigjet me “lejo” ose “refuzo.” Ja si duket cikli i miratimit në modulin e VS Code:

Në fund, serveri dërgon një mesazh agjent dhe pastaj përfundon radhën me turn/completed. Ngjarjet delta të mesazhit të agjentit transmetojnë pjesë të mesazhit derisa mesazhi të finalizohet me item/completed.

Mesazhet në diagram janë thjeshtuar për të qenë të lexueshme. Nëse dëshiron të shohësh JSON për një radhë të plotë, mund të ekzekutosh klientin e testimit nga depoja e Codex CLI:

Tani, le të shohim se si sipërfaqet e ndryshme të klientit e futin Codex përmes App Server. Do të mbulojmë tre modele: aplikacione lokale dhe IDE, runtime i Codex në web, dhe TUI.

Në të treja, transporti është JSON-RPC mbi stdio (JSONL). JSON-RPC e bën të thjeshtë krijimin e lidhjeve të klientit në gjuhën që zgjedh. Sipërfaqet e Codex dhe integrimet e partnerëve kanë zbatuar klientë të Serverit të Aplikacionit në gjuhë si Go, Python, TypeScript, Swift dhe Kotlin. Për TypeScript, mund të gjenerosh përkufizime drejtpërdrejt nga protokolli Rust duke ekzekutuar:

Për gjuhë të tjera, mund të gjenerosh një paketë skeme JSON dhe ta futësh në gjeneratorin tënd të preferuar të kodit duke e ekzekutuar:

Klientët lokalë zakonisht paketojnë ose marrin një binar specifik për platformën të App Server, e nisin atë si një proces fëmijë afatgjatë dhe mbajnë të hapur një kanal dykahësh stdio për JSON-RPC. Në zgjerimin tonë për VS Code dhe aplikacionin për desktop, për shembull, artefakti i dërguar përfshin binarin Codex specifik për platformën dhe është i fiksuar në një version të testuar, në mënyrë që klienti të ekzekutojë gjithmonë saktësisht bitët që kemi validuar.

Jo çdo integrim mund të dërgojë shpesh përditësime për klientët. Disa partnerë si Xcode i ndajnë ciklet e lëshimit duke mbajtur klientin të qëndrueshëm dhe duke e lejuar atë të lidhet me një binar më të ri të App Server kur është e nevojshme. Në këtë mënyrë ata mund të adoptojnë përmirësime në anën e serverit (p.sh., auto-kompaktim më të mirë në bërthamën e Codex ose çelësa të rinj konfigurimi të mbështetur) dhe të shpërndajnë rregullime të gabimeve pa pritur për një version të klientit. Sipërfaqja JSON-RPC e App Server është projektuar të jetë e pajtueshme me versionet e mëparshme, kështu që klientët më të vjetër mund të komunikojnë në mënyrë të sigurt me serverët më të rinj.

Codex Web përdor Codex harness, por e ekzekuton në një mjedis kontejneri. Një punonjës furnizon një kontejner me hapësirën pune të nxjerrë, nis binarin e serverit të aplikacionit brenda tij dhe mban një kanal JSON-RPC afatgjatë mbi stdio². Aplikacioni web (që ekzekutohet në skedën e shfletuesit të përdoruesit) komunikon me backend-in e Codex përmes HTTP dhe SSE, të cilat transmetojnë ngjarje të detyrave të prodhuara nga punëtori. Kjo e mban ndërfaqen e përdoruesit në anën e shfletuesit të lehtë, ndërsa ende na ofron një mjedis ekzekutimi të qëndrueshëm si në desktop ashtu edhe në ueb.

Meqenëse sesionet në ueb janë të përkohshme (skedat mbyllen, rrjetet ndërpriten), aplikacioni në ueb nuk mund të jetë burimi i besueshëm për detyra që zgjasin gjatë. Mbajtja e gjendjes dhe përparimit në server do të thotë që puna vazhdon edhe nëse skeda zhduket. Protokolli i transmetimit dhe sesionet e ruajtura të temave e bëjnë të lehtë që një sesion i ri të rilidhet, të vazhdojë aty ku e la dhe të kapë ritmin pa rindërtuar gjendjen në klient.

Historikisht, TUI ishte një klient “native” që ekzekutohej në të njëjtin proces si cikli i agjentit dhe komunikonte drejtpërdrejt me tipat bazë të Rust, në vend të protokollit të serverit të aplikacionit. Kjo e bëri iterimin e hershëm të shpejtë, por gjithashtu e bëri TUI një sipërfaqe të veçantë.

Tani që ekziston App Server, planifikojmë të rifaktorizojmë TUI⁠(hapet në një dritare të re) për ta përdorur atë, në mënyrë që të sillet si çdo klient tjetër: të nisë një proces fëmijë të App Server, të komunikojë JSON-RPC përmes stdio dhe të shfaqë të njëjtat ngjarje të transmetuara dhe miratime. Kjo zhbllokon flukse pune ku TUI mund të lidhet me një server Codex që ekzekutohet në një makinë të largët, duke e mbajtur agjentin afër llogaritjes dhe duke vazhduar punën edhe nëse laptopi fle ose shkëputet, ndërsa ende ofron përditësime dhe kontrolle të drejtpërdrejta në vend.

Codex App Server do të jetë metoda e integrimit e klasit të parë që do të mirëmbajmë në të ardhmen, por ka edhe metoda të tjera me funksionalitet të kufizuar. Si parazgjedhje, do t’u rekomandonim klientëve të përdorin Codex App Server për t’u integruar me Codex, por ia vlen të shikohen metoda të ndryshme integrimi dhe të kuptohen avantazhet dhe disavantazhet e tyre. Më poshtë janë mënyrat më të zakonshme për të drejtuar Codex dhe kur secila mund të jetë një përshtatje e mirë.

Ekzekuto codex mcp-server⁠(hapet në një dritare të re) dhe lidhu nga çdo klient MCP që mbështet serverë stdio (p.sh. OpenAI Agents SDK⁠(hapet në një dritare të re)). Kjo është një përshtatje e mirë nëse tashmë ke një fluks pune të bazuar në MCP dhe dëshiron të përdorësh Codex si një mjet të thirrshëm. E meta është se ti merr vetëm atë që ekspozon MCP, kështu që ndërveprimet specifike të Codex që mbështeten në semantikë më të pasur të sesionit (p.sh., përditësimet e ndryshimeve) mund të mos përshtaten qartë përmes pikave fundore të MCP.

Disa ekosisteme ofrojnë një ndërfaqe të lëvizshme që mund të synojë disa ofrues modelesh dhe mjedise ekzekutimi. Kjo mund të jetë një përshtatje e mirë nëse dëshiron një abstraksion që koordinon disa agjentë. Kompromisi është se këto protokolle shpesh konvergojnë te grupi i përbashkët i aftësive, gjë që mund t'i bëjë ndërveprimet më të pasura më të vështira për t'u përfaqësuar, veçanërisht kur semantika e mjeteve dhe sesionit specifike për ofruesin ka rëndësi. Kjo hapësirë po evoluon shpejt dhe presim që të shfaqen standarde më të zakonshme ndërsa zbulojmë primitivët më të mirë për të përfaqësuar rrjedhat e punës së agjentëve në botën reale (aftësitë⁠(hapet në një dritare të re) janë një shembull i mirë i kësaj).

Zgjidh App Server kur dëshiron që i gjithë Codex harness të shfaqet si një rrjedhë ngjarjesh e qëndrueshme dhe miqësore për UI. Ti merr si funksionalitetin e plotë të ciklit të agjentit ashtu edhe veçori të tjera mbështetëse si Hyrja me ChatGPT, zbulimi i modelit dhe menaxhimi i konfigurimit. Kostoja kryesore është puna e integrimit, pasi duhet të ndërtosh lidhjen JSON-RPC në anën e klientit në gjuhën tënde. Në praktikë, megjithatë, Codex mund të kryejë shumë nga detyrat e vështira nëse i jep skemën JSON dhe dokumentacionin. Shumë ekipe me të cilat kemi punuar arritën të bëjnë një integrim funksional shpejt duke përdorur Codex.

Një modalitet i lehtë dhe i skriptueshëm CLI për detyra të njëhershme dhe ekzekutime CI. Është një zgjedhje e mirë për automatizim dhe procese ku dëshiron që një komandë e vetme të ekzekutohet deri në përfundim në mënyrë jointeraktive, të transmetojë outpute të strukturuara për regjistrat dhe të përfundojë me një sinjal të qartë suksesi ose dështimi.

Një bibliotekë TypeScript për të kontrolluar në mënyrë programatike agjentët lokalë Codex nga brenda aplikacionit tënd. Është më mirë kur dëshiron një ndërfaqe të bibliotekës vendase për mjetet dhe flukset e punës në anën e serverit, pa ndërtuar një klient të veçantë JSON-RPC. Meqenëse u dërgua më herët se App Server, aktualisht mbështet më pak gjuhë dhe ka një sipërfaqe më të vogël. Nëse ka interes nga zhvilluesit, mund të shtojmë SDK shtesë që mbështjellin protokollin e App Server, në mënyrë që ekipet të mbulojnë më shumë nga sipërfaqja e sistemit pa shkruar lidhje JSON-RPC.

Në këtë postim, ndamë se si i qasemi dizajnimit të një standardi të ri për ndërveprimin me agjentët dhe si ta kthejmë Codex harness në një protokoll të qëndrueshëm dhe miqësor për klientët. Ne mbuluam se si App Server ekspozon bërthamën e Codex, u lejon klientëve të drejtojnë ciklin e plotë të agjentit dhe fuqizon një gamë të gjerë sipërfaqesh, duke përfshirë TUI, integrimet lokale me IDE dhe ekzekutimin në ueb.

Nëse kjo të frymëzoi për të integruar Codex në flukset e tua të punës, ia vlen të provosh App Server. I gjithë kodi burimor ndodhet në repo-n me burim të hapur Codex CLI repo⁠(hapet në një dritare të re). Mos hezito të ndash përshtypjet dhe kërkesat e tua për veçori. Jemi të ngazëllyer të dëgjojmë nga ti dhe të vazhdojmë t’i bëjmë agjentët më të arritshëm për të gjithë.