Odkrywanie środowiska testowego Codex: jak powstał App Server

Agent kodowania Codex firmy OpenAI jest dostępny na wielu różnych platformach: w aplikacji internetowej⁠(otwiera nowe okno), w interfejsie CLI⁠(otwiera nowe okno), w rozszerzeniu IDE⁠(otwiera nowe okno) oraz w nowej aplikacji Codex dla systemu macOS. W praktyce wszystkie działają na tym samym środowisku testowym Codex – pętli agenta i logice, które stanowią podstawę wszystkich funkcji Codex. Na czym polega kluczowy związek między nimi? Codex App Server⁠(otwiera nowe okno), przyjazny dla użytkownika, dwukierunkowy interfejs API JSON-RPC¹.

W tym artykule przedstawimy serwer aplikacji Codex. Przedstawimy nasze dotychczasowe doświadczenia dotyczące najlepszych sposobów wykorzystania możliwości Codex w twoim produkcie, aby pomóc Twoim użytkownikom usprawnić ich procesy robocze. Omówimy architekturę i protokół App Server oraz sposób jego integracji z różnymi środowiskami Codex, a także podamy wskazówki dotyczące wykorzystania Codex, niezależnie od tego, czy chcesz przekształcić Codex w narzędzie do przeglądania kodu, agenta SRE czy asystenta kodowania.

Przed zagłębieniem się w architekturę warto poznać historię powstania rozwiązania App Server. Początkowo App Server był praktycznym sposobem ponownego wykorzystania środowiska testowego Codex w różnych produktach, który stopniowo przekształcił się w wasz standardowy protokół.

Codex CLI powstał jako TUI (terminalowy interfejs użytkownika), co oznacza, że dostęp do Codex odbywa się za pośrednictwem terminala. Przy tworzeniu rozszerzenia VS Code (bardziej przyjaznego dla IDE sposobu interakcji z agentami Codex) potrzebowaliśmy sposobu na wykorzystanie tego samego środowiska testowego, aby uruchamiać tę samą pętlę agenta z poziomu interfejsu użytkownika IDE bez konieczności ponownej implementacji. Oznaczało to obsługę rozbudowanych wzorców interakcji wykraczających poza model żądanie/odpowiedź, takich jak eksploracja przestrzeni roboczej, strumieniowe przesyłanie postępów pracy agenta oraz generowanie różnic. Na początku próbowaliśmy udostępnić Codex jako serwer MCP⁠(otwiera nowe okno), ale utrzymanie semantyki MCP w sposób, który miałby sens dla VS Code, okazało się bardzo trudne. Zamiast tego wprowadziliśmy protokół JSON-RPC, który odzwierciedlał pętlę TUI i stał się nieoficjalną pierwszą wersją⁠(otwiera nowe okno) App Server. W tamtym czasie nie przewidywaliśmy, że inne klienty będą korzystać z App Server, więc nie został on zaprojektowany jako stabilny interfejs API.

Wraz z rosnącą popularnością Codex w ciągu kolejnych miesięcy zespoły wewnętrzne i partnerzy zewnętrzni wyrażali zainteresowanie możliwością wbudowania tego samego zestawu narzędzi w swoje produkty, aby przyspieszyć proces tworzenia oprogramowania przez swoich użytkowników. Na przykład firmy JetBrains i Xcode chciały mieć agenta na poziomie IDE, podczas gdy aplikacja Codex na komputery musiała koordynować pracę wielu agentów Codex jednocześnie. Wymagania te skłoniły nas do zaprojektowania platformy, na której zarówno nasze produkty, jak i integracje naszych partnerów mogłyby bezpiecznie funkcjonować przez długi czas. Musiała być łatwa do zintegrowania i kompatybilna wstecznie, co pozwoliłoby nam rozwijać protokół bez zakłócania działania istniejących klientów.

Następnie omówimy, w jaki sposób zaprojektowaliśmy architekturę i protokół, aby inne klienty mogły korzystać z tego samego środowiska testowego.

Najpierw przyjrzyjmy się bliżej zawartości środowiska testowego Codex i sposobowi, w jaki Codex App Server udostępnia je klientom. W naszym ostatnim wpisie na blogu Codex przeanalizowaliśmy podstawową pętlę agenta, która koordynuje interakcję między użytkownikiem, modelem i narzędziami. To podstawowa logika działania środowiska testowego Codex, ale pełne doświadczenie agenta obejmuje znacznie więcej:

1. Cykl życia wątku i trwałość. Wątek stanowi rozmowę między użytkownikiem a agentem w modelu Codex. Codex tworzy, wznawia, rozgałęzia i archiwizuje wątki oraz przechowuje historię zdarzeń, dzięki czemu klienty mogą połączyć się ponownie i wyświetlić spójną oś czasu.

2. Konfiguracja i autoryzacja. Codex ładuje konfigurację, zarządza ustawieniami domyślnymi i uruchamia procesy uwierzytelniania, takie jak „Zaloguj się za pomocą ChatGPT”, w tym stan poświadczeń.

3. Uruchamianie narzędzi i rozszerzenia. Codex uruchamia narzędzia powłoki/plików w trybie piaskownicy i łączy integracje, takie jak serwery MCP i umiejętności, aby mogły uczestniczyć w pętli agenta w ramach spójnego modelu polityki.

Cała logika agenta, o której tu wspomnieliśmy, w tym pętla rdzenia agenta, znajduje się w części kodu źródłowego Codex CLI o nazwie „Codex Core⁠(otwiera nowe okno)”. Codex Core to zarówno biblioteka, w której przechowywany jest cały kod agenta, jak i środowisko uruchomieniowe, które można uruchomić w celu uruchomienia pętli agenta i zarządzania trwałością jednego wątku Codex (rozmowy).

Środowisko testowe Codex musi być dostępne dla klientów, aby było przydatne. W tym miejscu do akcji wkracza App Server.

App Server to zarówno protokół JSON-RPC między klientem a serwerem, jak i długotrwały proces, który obsługuje główne wątki Codex. Jak widać na powyższym diagramie, proces App Server składa się z czterech głównych komponentów: czytnika stdio, procesora komunikatów Codex, menedżera wątków oraz wątków podstawowych. Menedżer wątków uruchamia jedną sesję rdzenia dla każdego wątku, a procesor komunikatów Codex komunikuje się bezpośrednio z każdą sesją rdzenia w celu przesyłania żądań klientów i odbierania aktualizacji.

Jedno żądanie klienta może spowodować wiele aktualizacji zdarzeń, a te szczegółowe zdarzenia pozwalają wam zbudować bogaty interfejs użytkownika na serwerze aplikacji. Ponadto czytnik stdio i procesor komunikatów Codex pełnią funkcję warstwy translacyjnej między wami a wątkami rdzenia Codex. Przekształcają one żądania JSON-RPC klientów na operacje Codex Core, nasłuchują wewnętrznego strumienia zdarzeń rdzenia Codex, a następnie przekształcają te zdarzenia niskiego poziomu w niewielki zestaw stabilnych powiadomień JSON-RPC gotowych do użycia w interfejsie użytkownika.

Protokół JSON-RPC między klientem a serwerem aplikacji jest w pełni dwukierunkowy. Typowy wątek zawiera żądanie klienta i wiele powiadomień serwera. Ponadto serwer może inicjować żądania, gdy agent potrzebuje danych wejściowych takich jak zatwierdzenie, a następnie wstrzymać kolejkę do momentu uzyskania odpowiedzi od klienta.

Następnie przeanalizujemy elementy podstawowe komunikacji, czyli części składowe protokołu App Server. Projektowanie interfejsu API dla pętli agenta to trudne zadanie, ponieważ interakcja między tobą a agentem nie jest prostym procesem typu żądanie/odpowiedź. Jedno żądanie użytkownika może spowodować szereg działań, które klient musi wiernie odwzorować: dane wprowadzone przez użytkownika, postępy agenta, artefakty powstałe w trakcie realizacji (np. różnice w kodzie). Aby ułatwić integrację tego strumienia interakcji i zapewnić jego odporność w różnych interfejsach użytkownika, opracowaliśmy trzy podstawowe elementy o jasno określonych granicach i cyklach życia:

1. Element: Element jest podstawową jednostką wejścia/wyjścia w Codex. Elementy mają przypisany typ (np. wiadomość użytkownika, wiadomość agenta, uruchomienie narzędzia, żądanie zatwierdzenia, różnica w kodzie) i każdy z nich ma określony cykl życia:

• item/started, gdy element się zaczyna
• opcjonalne zdarzenia item/*/delta jako strumienie treści (dla typów elementów obsługujących przesyłanie strumieniowe)
• item/completed, gdy element sfinalizuje swój ładunek końcowy

Ten cykl życia pozwala wam rozpocząć renderowanie natychmiast po komendzie started, przesyłać strumieniowo aktualizacje przyrostowe przy delta i finalizować po completed.

2. Tura: jednostka pracy agenta zainicjowana przez wprowadzenie danych przez użytkownika. Rozpoczyna się w momencie, gdy klient wprowadzi dane wejściowe (na przykład „uruchom testy i podsumuj awarie”) i kończy się, gdy agent zakończy generowanie danych wyjściowych dla tych danych wejściowych. Tura zawiera sekwencję elementów, które reprezentują pośrednie etapy i wyniki uzyskane w trakcie jej trwania.

3. Wątek: trwały kontener sesji Codex trwającej między użytkownikiem a agentem. Zawiera wiele tur. Wątki można tworzyć, wznawiać, rozgałęziać i archiwizować. Historia wątków jest zachowywana, dzięki czemu klienty mogą ponownie nawiązać połączenie i wyświetlić spójną oś czasu.

Teraz spojrzymy na uproszczoną rozmowę między klientem a agentem, gdzie rozmowa jest reprezentowana przez elementy podstawowe:

Na początku rozmowy klient i serwer musicie nawiązać uzgodnienie initialize. Klient musi wysłać pojedyncze żądanie initialize przed użyciem jakiejkolwiek innej metody, a serwer potwierdza je odpowiedzią. Daje to serwerowi możliwość zaprezentowania swoich możliwości i pozwala obu stronom uzgodnić wersję protokołu, flagi funkcji i ustawienia domyślne przed rozpoczęciem rzeczywistej pracy. Oto przykładowy ładunek z rozszerzenia VS Code firmy OpenAI:

Oto co zwraca serwer:

Kiedy klient wysyła nowe żądanie, najpierw tworzy wątek, a następnie kolejkę. Serwer będzie wysyłał powiadomienia o postępie (thread/started i turn/started). Wyśle również z powrotem dane wejściowe, które zarejestruje jako elementy, takie jak wiadomość użytkownika w tym przypadku.

Wywołania narzędzi są również wysyłane z powrotem do użytkownika jako elementy. Ponadto serwer może prosić klienta o zgodę przed wykonaniem działania, wysyłając żądanie serwera. Zatwierdzenie spowoduje wstrzymanie tury do momentu, aż klient odpowie „zezwól” lub „odmów”. Proces zatwierdzania w rozszerzeniu VS Code wygląda następująco:

Na koniec serwer wysyła komunikat agenta, a następnie kończy turę zdarzeniem turn/completed. Zdarzenia delta wiadomości agenta przesyłają fragmenty wiadomości z powrotem, aż wiadomość zostanie sfinalizowana zdarzeniem item/completed.

Wiadomości na diagramie zostały uproszczone w celu poprawy czytelności. Aby wyświetlić plik JSON dla pełnej tury, uruchom klienta testowego z repozytorium Codex CLI:

Przyjrzyjmy się teraz, w jaki sposób różne środowiska klientów osadzają Codex za pośrednictwem App Server. Omówimy trzy wzorce: aplikacje lokalne i środowiska IDE, środowisko uruchomieniowe Codex w sieci Web oraz TUI.

We wszystkich trzech przypadkach transport odbywa się za pomocą JSON-RPC przez stdio (JSONL). JSON-RPC ułatwia tworzenie powiązań klienckich w wybranym przez ciebie języku. Środowiska Codex i integracje partnerskie zaimplementowały klientów App Server w językach takich jak Go, Python, TypeScript, Swift i Kotlin. W przypadku TypeScript definicje można wygenerować bezpośrednio z protokołu Rust, uruchamiając:

W przypadku innych języków możesz wygenerować pakiet schematu JSON i wprowadzić go do preferowanego generatora kodu, uruchamiając:

W przypadku klientów lokalnych plik binarny App Server specyficzny dla platformy jest zazwyczaj dołączany lub pobierany, uruchamiany jako długotrwały proces podrzędny i utrzymywany jako dwukierunkowy kanał stdio otwarty dla JSON-RPC. Na przykład w naszym rozszerzeniu VS Code i aplikacji na komputery dostarczany artefakt zawiera plik binarny Codex specyficzny dla platformy i jest przypisany do przetestowanej wersji, dzięki czemu klient zawsze uruchamia dokładnie te bity, które zweryfikowaliśmy.

Nie każda integracja może często dostarczać aktualizacje dla klientów. Niektórzy partnerzy, tacy jak Xcode, oddzielają cykle wydań nowych wersji, utrzymując stabilność klienta i umożliwiając mu wskazanie nowszego pliku binarnego App Server w razie potrzeby. W ten sposób mogą korzystać z usprawnień po stronie serwera (np. lepszej automatycznej kompaktacji w Codex Core lub nowych obsługiwanych kluczy konfiguracyjnych) oraz wprowadzać poprawki błędów bez czekania na nową wersję klienta. Interfejs JSON-RPC w App Server został zaprojektowany z myślą o kompatybilności wstecznej, dzięki czemu starsze klienty mogą bezpiecznie komunikować się z nowszymi serwerami.

Codex Web korzysta ze środowiska testowego Codex, ale działa w środowisku kontenerowym. Pracownik przygotowuje kontener ze sprawdzoną przestrzenią roboczą, uruchamia w nim pliki binarne App Server i utrzymuje długotrwały kanał JSON-RPC przez stdio². Aplikacja internetowa (działająca w karcie przeglądarki użytkownika) komunikuje się z zapleczem Codex za pośrednictwem protokołów HTTP i SSE, które przesyłają strumieniowo zdarzenia związane z zadaniami generowane przez moduł roboczy. Dzięki temu interfejs użytkownika po stronie przeglądarki pozostaje lekki, a jednocześnie zapewnia nam spójne środowisko uruchomieniowe zarówno na komputerach stacjonarnych, jak i w Internecie.

Ponieważ sesje internetowe są krótkotrwałe (karty są zamykane, połączenia sieciowe ulegają rozłączeniu), aplikacja internetowa nie może być źródłem wiarygodnych informacji dla długotrwałych zadań. Przechowywanie stanu i postępów na serwerze oznacza, że praca jest kontynuowana nawet w przypadku zamknięcia karty. Protokół przesyłania strumieniowego i zapisane sesje wątków ułatwiają ponowne połączenie nowej sesji, wznowienie pracy od miejsca, w którym została przerwana, oraz nadrobienie zaległości bez konieczności odbudowywania stanu w kliencie.

Historycznie rzecz biorąc, TUI był „natywnym” klientem, który działał w tym samym procesie co pętla agenta i komunikował się bezpośrednio z typami rdzenia Rust, a nie z protokołem serwera aplikacji. Dzięki temu wczesne iteracje przebiegały szybko, ale sprawiło to również, że TUI stał się interfejsem specjalnego rodzaju.

Teraz, gdy App Server już istnieje, planujemy refaktoryzować TUI⁠(otwiera nowe okno), aby korzystał z niego tak samo jak każdy inny klient: uruchamiał proces podrzędny App Server, komunikował się za pomocą JSON-RPC przez stdio i renderował te same zdarzenia strumieniowe i zatwierdzenia. Umożliwia to uruchomienie procesów, w których TUI może połączyć się z serwerem Codex działającym na zdalnym komputerze, utrzymując agenta w pobliżu obliczeń i kontynuując pracę nawet wtedy, gdy laptop przechodzi w stan uśpienia lub traci połączenie, jednocześnie nadal zapewniając na bieżąco aktualizacje i lokalną kontrolę.

Serwer aplikacji Codex będzie najlepszą metodą integracji, którą będziemy stosować w przyszłości, ale istnieją również inne metody o bardziej ograniczonej funkcjonalności. Domyślnie zalecamy klientom korzystanie z Codex App Server do integracji z Codex, ale warto zapoznać się z różnymi metodami integracji oraz zrozumieć ich zalety i wady. Poniżej przedstawiono najpopularniejsze sposoby korzystania z Codex oraz sytuacje, w których każdy z nich może być dobrym rozwiązaniem.

Wystarczy uruchomić codex mcp-server⁠(otwiera nowe okno) i połączyć się z dowolnym klientem MCP obsługującym serwery stdio (np. OpenAI Agents SDK⁠(otwiera nowe okno)). Jest to dobre rozwiązanie, jeśli posiadasz już proces roboczy oparty na MCP i chcesz wywoływać Codex jako narzędzie wywoływalne. Wadą tego rozwiązania jest to, że otrzymujesz tylko to, co udostępnia MCP, więc interakcje specyficzne dla Codex, które opierają się na bogatszej semantyce sesji (np. aktualizacje różnic w kodzie), mogą nie być poprawnie mapowane przez punkty końcowe MCP.

Niektóre ekosystemy zapewniają przenośny interfejs, który może obsługiwać wielu dostawców modeli i środowisk uruchomieniowych. Może to być dobre rozwiązanie, jeśli potrzebujesz jednej abstrakcji koordynującej wiele agentów. Minusem tego rozwiązania to, że protokoły te często skupiają się na wspólnym podzbiorze funkcji, co może utrudniać przedstawienie bogatszych interakcji, zwłaszcza gdy istotne znaczenie mają narzędzia i semantyka sesji specyficzne dla danego dostawcy. W tej dziedzinie następuje dynamiczny rozwój oraz przewidujemy, że wraz z ustaleniem najlepszych elementów podstawowych do reprezentowania rzeczywistych procesów pracy agentów (dobrym przykładem są tu umiejętności⁠(otwiera nowe okno)) pojawią się bardziej powszechne standardy.

Wybierz serwer aplikacji, gdy chcesz mieć pełny dostęp do środowiska testowego Codex w postaci stabilnego, przyjaznego dla UI strumienia zdarzeń. Otrzymujesz zarówno pełną funkcjonalność pętli agenta, jak i inne funkcje wspierające, takie jak logowanie przez ChatGPT, wykrywanie modeli oraz zarządzanie konfiguracją. Głównym kosztem są prace integracyjne, ponieważ trzeba zbudować powiązanie JSON-RPC po stronie klienta w swoim języku. W praktyce jednak Codex jest w stanie wykonać większość żmudnej pracy, jeśli dostarczysz mu schemat JSON i dokumentację. Wiele zespołów, z którymi współpracowaliśmy, było w stanie szybko przeprowadzić integrację przy użyciu Codex.

Lekki tryb CLI z obsługą skryptów do jednorazowych zadań i uruchomień CI. Doskonale sprawdza się w przypadku automatyzacji i potoków, jeśli chcesz, aby pojedyncze polecenie było wykonywane do końca w trybie nieinteraktywnym, przesyłało ustrukturyzowane dane wyjściowe do logów i kończyło się wyraźnym sygnałem powodzenia lub niepowodzenia.

Biblioteka TypeScript do programowego sterowania lokalnymi agentami Codex z poziomu twojej aplikacji. Najlepiej sprawdza się, gdy potrzebujesz natywnego interfejsu biblioteki dla narzędzi i przepływów pracy po stronie serwera bez konieczności tworzenia oddzielnego klienta JSON-RPC. Ponieważ została wprowadzona na rynek wcześniej niż App Server, obecnie obsługuje mniej języków i ma mniejszy zakres. Jeśli programiści będą tym zainteresowani, możemy dodać dodatkowe zestawy SDK, które obejmują protokół App Server, dzięki czemu zespoły będą mogły objąć większy zakres środowiska testowego bez konieczności pisania powiązań JSON-RPC.

W tym poście przedstawiliśmy nasze podejście do projektowania nowego standardu interakcji z agentami oraz sposoby przekształcenia środowiska testowego Codex w stabilny, przyjazny dla klientów protokół. Omówiliśmy, w jaki sposób App Server udostępnia rdzeń Codex Core, pozwala wam sterować pełną pętlą agenta i obsługuje szeroki zakres interfejsów, w tym TUI, lokalne integracje IDE i środowisko uruchomieniowe sieci Web.

Jeśli zainspirowało cię to do wdrożenia Codex w swoich procesach roboczych, warto wypróbować App Server. Cały kod źródłowy znajduje się w repozytorium⁠(otwiera nowe okno) open source Codex CLI. Zachęcamy do dzieleniu się opiniami i sugestiami dotyczącymi nowych funkcji. Cieszymy się, mogąc poznać Wasze opinię i nieustannie rozwijać agentów, aby były bardziej dostępne dla wszystkich.