Отклучување на системот Codex: како изградивме аплкациски сервер

Агентот за кодирање на OpenAI, Codex, е достапен на многу различни платформи: веб апликацијата⁠(се отвора во нов прозорец), CLI⁠(се отвора во нов прозорец), IDE екстензијата⁠(се отвора во нов прозорец) и новата Codex macOS апликација. Под површината, сите се овозможени од истиот Codex систем - агентскиот циклус и логиката што е основа на сите Codex искуства. Која е критичната врска помеѓу нив? Codex App Server⁠(се отвора во нов прозорец), погоден за клиенти и двонасочен JSON-RPC¹ API.

Во оваа објава, ќе го претставиме серверот за апликации Codex; ќе ги споделиме нашите досегашни сознанија за најдобрите начини да ги внесеш можностите на Codex во твојот производ за да им помогнеш на твоите корисници да ги унапредат своите работни текови. Ќе ја опфатиме архитектурата и протоколот на App Server и како се интегрира со различни површини на Codex, како и совети за искористување на Codex, без разлика дали сакаш да го претвориш Codex во рецензент на код, SRE агент или асистент за кодирање.

Пред да навлезеш во архитектурата, корисно е да ја знаеш позадинската приказна на App Server-от. Првично, App Server беше практичен начин за повторна употреба на Codex хернес низ производите, што постепено се разви во наш стандард протокол.

Codex CLI започна како TUI (терминален кориснички интерфејс), што значи дека до Codex се пристапува преку терминал. Кога ја изградивме екстензијата за VS Code (попогоден начин за IDE за интеракција со Codex агенти), ни требаше начин да го користиме истиот механизам за да го придвижуваме истиот циклус на агентот од корисничкиот интерфејс на IDE без повторно да го имплементираме. Тоа значеше поддршка на богати обрасци на интеракција надвор од барање/одговор, како што се истражување на работен простор, стримување на напредокот додека агентот размислува и емитување на разлики. Прво експериментиравме со изложување на Codex како MCP сервер⁠(се отвора во нов прозорец), но одржувањето на семантиката на MCP на начин што има смисла за VS Code се покажа како тешко. Наместо тоа, воведовме JSON-RPC протокол што ја пресликуваше TUI јамката, кој стана неофицијална прва верзија⁠(се отвора во нов прозорец) на апликацискиот сервер. Во тоа време, не очекувавме други клиенти да зависат од апликацискиот сервер, па затоа не го дизајниравме како стабилен API.

Како што усвојувањето на Codex растеше во текот на следните неколку месеци, внатрешните тимови и надворешните партнери сакаа да можат да го вградат истиот „harness“ во своите производи за да ги забрзаат работните текови за развој на софтвер на своите корисници. На пример, JetBrains и Xcode сакаа искуство со агент на ниво на IDE, додека десктоп апликацијата Codex требаше да оркестрира многу агенти на Codex паралелно. Тие барања нè поттикнаа да дизајнираме платформа на која и нашите производи и интеграциите на партнерите можат безбедно да се потпираат со текот на времето. Требаше да биде лесно за интегрирање и компатибилно наназад, што значи дека можевме да го развиваме протоколот без да ги нарушиме постојните клиенти.

Следно, ќе објасниме како ја дизајниравме архитектурата и протоколот за да можат различни клиенти да го користат истиот систем.

Прво, да се фокусираме на тоа што се наоѓа внатре во Codex системот и како Codex апликацискиот сервер го претставува на клиентите. Во нашиот последен Codex блог, го објаснивме основниот циклус на агентот што ја организира интеракцијата помеѓу корисникот, моделот и алатките. Ова е основната логика на Codex системот, но има повеќе во целосното искуство со агентот:

1. Циклус и перзистентност на нишката. Нишка е разговор во Codex помеѓу корисник и агент. Codex креира, продолжува, разгранување и архивира нишки, и ја зачувува историјата на настани за клиентите да можат повторно да се поврзат и да прикажат доследна временска линија.

2. Конфигурирање и автентикација. Codex вчитува конфигурации, управува со стандардни поставки и извршува текови за автентикација како „Sign in with ChatGPT“, вклучувајќи ја состојбата на акредитивите.

3. Извршување на алатките и нивните продолженија. Codex извршува shell/file алатки во изолирана средина и ги поврзува интеграциите како MCP сервери и вештини за да можат да учествуваат во циклусот на агентот под доследен модел на политики.

Целата логика на агентот што ја спомнавме тука, вклучувајќи го и основниот циклус на агентот, се наоѓа во дел од кодната база на Codex CLI наречен „Codex core⁠(се отвора во нов прозорец)“. Codex core е и библиотека каде што се наоѓа целиот код на агентот и извршна средина што може да се стартува за да го извршува циклусот на агентот и да управува со перзистентноста на една Codex нишка (разговор).

За да биде корисен, Codex системот треба да биде достапен за клиентите. Тука влегува во игра апликацискиот сервер.

Апликацискиот сервер е и JSON-RPC протокол помеѓу клиентот и серверот и долготраен процес што ги хостира основните нишки на Codex. Како што можеме да видиме од дијаграмот погоре, процесот на апликацискиот сервер има четири главни компоненти: читачот на stdio, процесорот на пораки на Codex, менаџерот на нишки и основните нишки. Менаџерот на нишки активира една основна сесија за секоја нишка, а потоа процесорот за пораки на Codex директно комуницира со секоја основна сесија за да поднесува барања од клиенти и да прима ажурирања.

Едно барање од клиент може да резултира со многу ажурирања на настани, а овие детални настани ни овозможуваат да изградиме богат кориснички интерфејс врз серверот за апликации. Понатаму, stdio читачот и процесорот за пораки на Codex служат како слој за превод помеѓу клиентот и основните нишки на Codex. Тие ги преведуваат барањата од клиенти JSON-RPC во основни операции на Codex, го слушаат внатрешниот тек на настани на Codex core, а потоа ги трансформираат тие настани на ниско ниво во мала група стабилни, подготвени за кориснички интерфејс JSON-RPC известувања.

Протоколот JSON-RPC помеѓу клиентот и апликацискиот сервер е целосно двонасочен. Типична нишка содржи барање од клиент и многу известувања од сервер. Дополнително, серверот може да иницира барања кога на агентот му е потребен внес, како на пример одобрување, и потоа да ја паузира акцијата додека клиентот не одговори.

Следно, ќе ги објасниме примитивите на разговорот, основните елементи на протоколот на апликацискиот сервер. Дизајнирањето на API за циклус на агент е сложено бидејќи интеракцијата помеѓу корисникот и агентот не е едноставна како барање и одговор. Едно барање од корисникот може да се развие во структурирана низа дејства што клиентот треба верно да ги претстави: внесот на корисникот, постепениот напредок на агентот, артефактите создадени по патот (на пр., разлики). За да го направиме тој тек на интеракција лесен за интегрирање и отпорен низ корисничките интерфејси, се одлучивме на три основни примитиви со јасни граници и животни циклуси:

1. Ставка: Ставката е основната единица на внесување/излез во Codex. Ставките се категоризирани (на пр., порака од корисник, порака од агент, извршување на алатка, барање за одобрување, разлика) и секоја има јасно дефиниран циклус:

• item/started кога започнува предметот
• опционални настани item/*/delta како текови на содржина (за типови на ставки за стриминг)
• item/completed кога ставката се завршува со нејзиниот краен товар

Овој животен циклус им овозможува на клиентите веднаш да започнат со рендерирање на started, да пренесуваат инкрементални ажурирања на delta и да завршат на completed.

2. Потег: Круг претставува една единица на работа на агент што се иницира од кориснички внес. Започнува кога клиентот поднесува внес (на пр., „изврши тестови и сумирај ги неуспесите“) и завршува кога агентот ќе заврши со создавање излези за тој внес. Еден круг содржи низа од елементи кои ги претставуваат посредните чекори и резултатите што се создаваат по патот.

3. Нишка: Нишката е издржлив контејнер за тековна Codex сесија помеѓу корисник и агент. Содржи повеќе кругови. Нишките може да се создадат, продолжат, разгранат и архивираат. Историјата на нишката се зачувува за клиентите да можат повторно да се поврзат и да прикажат доследна временска линија.

Сега ќе разгледаме поедноставен разговор помеѓу клиент и агент, каде што разговорот е претставен со примитиви:

На почетокот на разговорот, клиентот и серверот треба да воспостават initialize ракување. Клиентот мора да испрати единствено барање initialize пред кој било друг метод, а серверот го потврдува со одговор. Ова му дава можност на серверот да ги рекламира своите способности и им овозможува на двете страни да се договорат за верзионирање на протоколот, ознаки за функции и стандардни поставки пред да започне вистинската работа. Еве пример за payload од екстензијата на VS Code на OpenAI:

Ова е што враќа серверот:

Кога клиентот ќе направи ново барање, прво ќе креира нишка, а потоа ќе креира чекор. Серверот ќе испраќа известувања за напредок (thread/started и turn/started). Исто така, ќе ги врати внесувањата што ги регистрира како ставки, како што е корисничката порака тука.

Повици на алатки исто така се враќаат до клиентот како ставки. Дополнително, серверот може да побара одобрување од клиентот пред да може да изврши дејство со испраќање барање до серверот. Одобрувањето ќе го паузира кругот додека клиентот не одговори со „дозволи“ или „одбиј“. Еве како изгледа текот на одобрување во екстензијата за VS Code:

На крајот, серверот испраќа порака од агент и потоа го завршува кругот со turn/completed. Делта-настаните на агентот ги пренесуваат деловите од пораката назад додека пораката не се заврши со item/completed.

Пораките во дијаграмот се поедноставени за подобра читливост. Ако сакаш да го видиш JSON-от за целосен круг, можеш да го стартуваш тест клиентот од Codex CLI репо:

Сега, да разгледаме како различни клиентски површини го вметнуваат Codex преку апликацискиот сервер. Ќе опфатиме три обрасци: локални апликации и IDE-и, Codex веб-извршна околина и TUI.

Во сите три случаи, транспортот е JSON-RPC преку stdio (JSONL). JSON-RPC го олеснува создавањето на клиентски врски на јазикот што го избирате. Codex површините и партнерските интеграции имаат имплементирано клиенти за App Server на програмски јазици како што се Go, Python, TypeScript, Swift и Kotlin. За TypeScript, можеш да генерираш дефиниции директно од Rust протоколот со извршување:

За други јазици, можеш да генерираш JSON шема пакет и да го внесеш во твојот омилен генератор на код со извршување:

Локалните клиенти обично пакуваат или преземаат бинарна датотека на сервер за апликации специфична за платформата, ја лансираат како долготраен потпроцес и држат отворен двонасочен stdio канал за JSON-RPC. Во нашата VS Code екстензија и десктоп-апликација, на пример, испорачаниот артефакт го вклучува платформски-специфичната Codex бинарна датотека и е фиксиран на тестирана верзија за клиентот секогаш да ги извршува точните делови што ги валидиравме.

Не секоја интеграција може често да испорачува ажурирања за клиенти. Некои партнери како Xcode ги раздвојуваат циклусите на издавање со тоа што го одржуваат клиентот стабилен и му дозволуваат да се насочи кон понова верзија на App Server кога е потребно. На тој начин можат да усвојат подобрувања на серверската страна (на пример, подобра автоматска компакција во Codex јадрото или новоподдржани конфигурациски клучеви) и да воведуваат поправки на грешки без да чекаат клиентско издание. JSON-RPC површината на App Server е дизајнирана да биде наназад компатибилна, така што постарите клиенти можат безбедно да комуницираат со понови сервери.

Codex веб го користи Codex хернесот, но го извршува во контејнерска средина. Работник обезбедува контејнер со проверениот работен простор, ја стартува бинарната датотека на апликацискиот сервер во него и одржува долготраен JSON-RPC преку stdio² канал. Веб-апликацијата (што работи во јазичето на прелистувачот на корисникот) комуницира со Codex бекендот преку HTTP и SSE, кои пренесуваат настани за задачи што ги произведува работникот. Ова го одржува корисничкиот интерфејс на страната на прелистувачот лесен, додека сè уште ни обезбедува доследно извршување на десктоп и веб.

Бидејќи веб-сесиите се краткотрајни (јазичињата се затвораат, мрежите се прекинуваат), веб-апликацијата не може да биде извор на вистина за долготрајни задачи. Чувањето на состојбата и напредокот на серверот значи дека работата продолжува дури и ако табот исчезне. Протоколот за стриминг и зачуваните сесии на нишки овозможуваат лесно повторно поврзување на нова сесија, продолжување од каде што застанала и надоместување без повторно градење на состојбата во клиентот.

Историски, TUI беше „нативен“ клиент кој работеше во истиот процес како и циклусот на агентот и комуницираше директно со основните типови на Rust, наместо со протоколот на апликацискиот сервер. Тоа ја направи раната итерација брза, но исто така го направи TUI површина за посебни случаи.

Сега кога постои апликацискиот сервер, планираме да го рефакторираме TUI⁠(се отвора во нов прозорец) за да го користи, така што ќе се однесува како и секој друг клиент: да лансира потпроцес на апликацискиот сервер, да комуницира преку JSON-RPC преку stdio и да ги прикажува истите стриминг настани и одобрувања. Ова овозможува работни текови каде што TUI може да се поврзе со серверот Codex што работи на оддалечена машина, задржувајќи го агентот блиску до пресметувањето и продолжувајќи со работа дури и ако лаптопот заспие или се исклучи, додека сепак испорачува ажурирања во живо и контроли локално.

Codex апликацискиот сервер ќе биде првокласен метод за интеграција што ќе го одржуваме понатаму, но постојат и други методи со ограничена функционалност. По правило, препорачуваме клиентите да го користат Codex апликацискиот сервер за интеграција со Codex, но вреди да се разгледаат и други методи на интеграција и да се разберат нивните предности и недостатоци. Подолу се најчестите начини за управување со Codex и кога секој од нив може да биде добар избор.

Изврши codex mcp-server⁠(се отвора во нов прозорец) и поврзи се од кој било MCP клиент што поддржува stdio сервери (на пр., OpenAI Agents SDK⁠(се отвора во нов прозорец)). Ова е добар избор ако веќе имаш работен тек базиран на MCP и сакаш да го повикаш Codex како алатка што може да се повика. Недостатокот е што добиваш само она што го изложува MCP, па специфичните интеракции на Codex кои се потпираат на побогата семантика на сесијата (на пр., ажурирања на diff) можеби нема да се мапираат чисто преку крајни точки на MCP.

Некои екосистеми нудат пренослив интерфејс што може да насочи повеќе провајдери на модели и извршни околини. Ова може да биде добар избор ако сакаш една апстракција што координира повеќе агенти. Компромисот е што овие протоколи често се усогласуваат со заедничкото подмножество на способности, што може да ги направи побогатите интеракции потешки за претставување, особено кога се важни семантиката на алатките и сесиите специфични за давателот. Овој простор брзо се развива и очекуваме дека ќе се појават повеќе заеднички стандарди додека ги утврдуваме најдобрите примитиви за претставување на работните текови на агенти во реалниот свет (вештини⁠(се отвора во нов прозорец) е добар пример за ова).

Изберете го App Server кога сакате целосниот Codex harness да биде изложен како стабилен тек на настани прилагоден за корисничкиот интерфејс. Ќе ја добиеш целосната функционалност на циклусот на агентот и други поддржувачки функции како што се Најави се со ChatGPT, откривање на модели и управување со конфигурацијата. Главниот трошок е работата за интеграција, бидејќи треба да го изградите клиентската страна на JSON-RPC поврзувањето на вашиот јазик. Во пракса, сепак, Codex може да направи голем дел од тешката работа ако му ја дадете JSON шемата и документацијата. Многу тимови со кои работевме успеаја брзо да направат работна интеграција користејќи Codex.

Лесен, скриптабилен CLI режим за еднократни задачи и CI извршувања. Тоа е добро прилагодено за автоматизација и процеси каде што сакаш една команда да се изврши до крај неинтерактивно, да пренесува структурирани резултати за логови и да заврши со јасен сигнал за успех или неуспех.

Библиотека на TypeScript за програмско контролирање на локални агенти на Codex од вашата сопствена апликација. Најдобро е кога сакате интерфејс на изворна библиотека за алатки и работни текови на серверската страна без да изградите посебен JSON-RPC клиент. Бидејќи беше испорачано порано од App Server, моментално поддржува помалку јазици и помал обем на функционалност. Ако има интерес од развивачите, можеме да додадеме дополнителни SDK-ови што го обвиткуваат протоколот на App Server, за тимовите да можат да покријат поголем дел од површината на harness без да пишуваат JSON-RPC врски.

Во оваа објава, споделивме како пристапуваме кон дизајнирање нов стандард за интеракција со агенти и како да го претвориме Codex harness во стабилен и клиентски пријателски протокол. Опфативме како App Server го изложува јадрото на Codex, им овозможува на клиентите да го водат целиот циклус на агентот и обезбедува поддршка за широк спектар на интерфејси, вклучувајќи ги TUI, локалните IDE интеграции и веб-извршувањето.

Ако ова ти даде идеи за интегрирање на Codex во твоите работни текови, вреди да го пробаш App Server. Целиот изворен код се наоѓа во отворениот репозиториум на Codex CLI repo⁠(се отвора во нов прозорец). Слободно споделете ги вашите повратни информации и барања за функции. Возбудени сме што ќе слушнеме од вас и што ќе продолжиме да ги правиме агентите подостапни за сите.