Codex donanımının kilidini açmak: App Server'ı nasıl oluşturduk

OpenAI'ın otonom ajanı Codex, birçok farklı platformda mevcuttur: web uygulaması⁠(yeni bir pencerede açılır), CLI⁠(yeni bir pencerede açılır), IDE uzantısı⁠(yeni bir pencerede açılır) ve yeni Codex macOS uygulaması. Perde arkasında, hepsi aynı Codex altyapısı tarafından çalıştırılır; tüm Codex deneyimlerinin temelini oluşturan otonom ajan döngüsü ve mantık. Aralarındaki kritik bağ nedir? Codex App Server⁠(yeni bir pencerede açılır), kullanıcı dostu, çift yönlü bir JSON-RPC¹ API'sidir.

Bu yazıda Codex Uygulama Sunucusu'nu tanıtacağız ve Codex'in yeteneklerini ürününüze entegre etmenin en iyi yolları hakkında şimdiye kadar edindiğimiz bilgileri paylaşacağız, böylece kullanıcılarınızın iş akışlarını güçlendirmelerine yardımcı olabilirsiniz. App Server'ın mimarisini ve protokolünü ve bunun farklı Codex yüzeyleriyle nasıl entegre olduğunu ele alacağız; ayrıca ister Codex’i bir kod gözden geçiriciye, ister bir SRE otonom ajanına, ister bir kodlama asistanına dönüştürmek isteyin; Codex’ten nasıl yararlanabileceğinize dair ipuçları da paylaşacağız.

Mimariye dalmadan önce, App Server'ın geçmişini bilmekte fayda var. Başlangıçta, App Server, Codex donanımını ürünler arasında yeniden kullanmanın pratik bir yoluydu ve bu, zamanla standart protokolümüz haline geldi.

Codex CLI, bir TUI (terminal kullanıcı arayüzü) olarak başladı, yani Codex'e terminalden erişilir. VS Code uzantısını (Codex ajanlarıyla etkileşim kurmak için IDE dostu bir yöntem) oluştururken, aynı ajanı yeniden uygulamaya gerek kalmadan IDE kullanıcı arayüzünden çalıştırmak için aynı donanımı kullanmanın bir yolunu bulmamız gerekiyordu. Bu, çalışma alanını keşfetmek, ajanın akıl yürütme sürecini aktarmak ve farklılıkları ortaya çıkarmak gibi istek/yanıtın ötesinde zengin etkileşim modellerini desteklemek anlamına geliyordu. Öncelikle Codex'i bir MCP sunucusu⁠(yeni bir pencerede açılır) olarak kullanıma sunmayı denedik, ancak VS Code için anlamlı olacak şekilde MCP semantiğini korumak zor oldu. Bunun yerine, TUI döngüsünü yansıtan bir JSON-RPC protokolü tanıttık; bu, App Server'ın resmî olmayan ilk sürümü⁠(yeni bir pencerede açılır) oldu. O dönemde, diğer müşterilerin App Server'a bağımlı olmasını beklemiyorduk; bu yüzden kararlı bir API olarak tasarlanmamıştı.

Codex'in benimsenmesi önümüzdeki birkaç ay içinde yaygınlaştıkça, iç ekipler ve dış ortaklar, kullanıcılarının yazılım geliştirme iş akışlarını hızlandırmak için aynı donanımı kendi ürünlerine entegre etme olanağına sahip olmak istediler. Örneğin, JetBrains ve Xcode IDE düzeyinde bir ajan deneyimi isterken, Codex masaüstü uygulaması birçok Codex ajanını paralel olarak koordine etmek zorundaydı. Bu talepler, hem ürünlerimizin hem de iş ortağı entegrasyonlarımızın zaman içinde güvenle dayanabileceği bir platform yüzeyi tasarlamamızı sağladı. Entegrasyonu kolay ve geriye dönük uyumlu olması gerekiyordu, yani mevcut istemcileri bozmadan protokolü geliştirebilmemiz gerekiyordu.

Sonraki adımda, farklı istemcilerin aynı donanımı kullanabilmesi için mimariyi ve protokolü nasıl tasarladığımızı inceleyeceğiz.

Öncelikle, Codex donanımının içeriğine ve Codex App Server'ın bunu istemcilere nasıl sunduğuna yakından bakalım. Son Codex blog yazımızda, kullanıcı, model ve araçlar arasındaki etkileşimi düzenleyen temel otonom ajan döngüsünü ayrıntılı olarak ele aldık. Bu, Codex donanımının temel mantığıdır, ancak tam otonom ajan deneyiminde daha fazlası var:

1. İş parçacığının yaşam döngüsü ve kalıcılığı. İş parçacığı, bir kullanıcı ile bir temsilci arasındaki Codex konuşmasıdır. Codex, iş parçacıklarını oluşturur, devam ettirir, çatallandırır ve arşivler; ayrıca olay geçmişini kalıcı hale getirir, böylece müşteriler yeniden bağlanıp tutarlı bir zaman çizelgesi oluşturabilir.

2. Yapılandırma ve kimlik doğrulama. Codex, yapılandırmayı yükler, varsayılanları yönetir ve kimlik bilgisi durumu da dahil olmak üzere "Sign in with ChatGPT" gibi kimlik doğrulama akışlarını çalıştırır.

3. Araçların çalıştırılması ve uzantılar. Codex, shell/dosya araçlarını bir sandbox ortamında çalıştırır ve MCP sunucuları ile beceriler gibi entegrasyonları bağlayarak bunların tutarlı bir politika modeli altında otonom ajan döngüsüne katılmalarını sağlar.

Burada bahsettiğimiz tüm otonom ajan mantığı, çekirdek otonom ajan döngüsü de dahil olmak üzere, Codex CLI kod tabanının "Codex core⁠(yeni bir pencerede açılır)" adlı bir bölümünde yer alır. Codex çekirdeği, tüm ajan kodlarının bulunduğu bir kütüphane ve ajan döngüsünü çalıştırmak ve bir Codex iş parçacığının (konuşma) kalıcılığını yönetmek için çalıştırılabilen bir çalışma zamanıdır.

Kullanışlı olması için Codex donanımının istemciler tarafından erişilebilir olması gerekir. İşte App Server bu noktada devreye giriyor.

App Server, istemci ile sunucu arasındaki JSON-RPC protokolünü ve Codex çekirdek iş parçacıklarını barındıran uzun ömürlü bir süreci içerir. Yukarıdaki diyagramdan da görebileceğimiz gibi, bir App Server süreci dört ana bileşenden oluşur: stdio okuyucu, Codex mesaj işleyici, iş parçacığı yöneticisi ve çekirdek iş parçacıkları. İş parçacığı yöneticisi, her iş parçacığı için bir çekirdek oturumu başlatır ve ardından Codex mesaj işleyicisi, istemci isteklerini göndermek ve güncellemeleri almak üzere her çekirdek oturumuyla doğrudan iletişim kurar.

Tek bir istemci isteği birçok olay güncellemesine yol açabilir ve bu ayrıntılı olaylar, App Server üzerinde zengin bir kullanıcı arayüzü oluşturmamıza olanak tanır. Ayrıca, stdio okuyucu ve Codex mesaj işleyici, istemci ile Codex çekirdek iş parçacıkları arasında bir çeviri katmanı olarak hizmet eder. İstemci JSON-RPC isteklerini Codex çekirdek işlemlerine dönüştürür, Codex çekirdeğinin dahili olay akışını dinler ve ardından bu düşük seviyeli olayları küçük bir dizi kararlı, kullanıcı arayüzüne hazır JSON-RPC bildirimine dönüştürür.

İstemci ile App Server arasındaki JSON-RPC protokolü tamamen çift yönlüdür. Tipik bir iş parçacığı, bir istemci isteği ve birçok sunucu bildirimi içerir. Ayrıca, sunucu, otonom ajan bir girdiye ihtiyaç duyduğunda, örneğin bir onay, istekleri başlatabilir ve ardından istemci yanıt verene kadar işlemi duraklatabilir.

Ardından, App Server protokolünün yapı taşları olan konuşma öğelerini inceleyeceğiz. Bir ajan döngüsü için API tasarlamak zordur çünkü kullanıcı/otonom ajan etkileşimi basit bir istek/yanıt ilişkisi değildir. Bir kullanıcı isteği, istemcinin sadakatle temsil etmesi gereken yapılandırılmış bir eylem dizisine dönüşebilir: kullanıcının girdisi, otonom ajanın kademeli ilerlemesi, yol boyunca üretilen belgeler (örneğin, farklar). Bu etkileşim akışını kullanıcı arayüzleri genelinde kolayca entegre edilebilir ve dayanıklı hale getirmek için, net sınırları ve yaşam döngüleri olan üç temel ilkeye karar verdik:

1. Öğe: Codex'te bir öğe, girdi/çıktının en temel birimidir. Öğeler türlerine göre sınıflandırılır (ör. kullanıcı mesajı, otonom ajan mesajı, araç çalıştırma, onay isteği, fark) ve her birinin belirgin bir yaşam döngüsü vardır:

• item/started öğe başladığında
• isteğe bağlı item/*/delta olayları içerik akışları olarak (akış öğe türleri için)
• Öğe terminal yüküyle tamamlandığında item/completed

Bu yaşam döngüsü, istemcilerin started aşamasında hemen render etmeye başlamasına, delta aşamasında artımlı güncellemeleri akış halinde almasına ve completed aşamasında sonlandırmasına olanak tanır.

2. Tur: Bir tur, kullanıcı girdisiyle başlatılan bir otonom ajan çalışma birimidir. İstemci bir girdi (örneğin, "run tests and summarize failures") gönderdiğinde süreç başlar ve otonom ajan bu girdi için çıktıları üretmeyi tamamladığında sona erer. Bir tur, süreç boyunca üretilen ara adımları ve çıktıları temsil eden bir dizi öğe içerir.

3. İş Parçacığı: İş parçacığı, bir kullanıcı ile bir otonom ajan arasında devam eden bir Codex oturumunun kalıcı kapsayıcısıdır. Birden fazla tur içerir. İş parçacıkları oluşturulabilir, devam ettirilebilir, çatallanabilir ve arşivlenebilir. İş parçacığı geçmişi kalıcı olarak saklanır, böylece istemciler yeniden bağlanıp tutarlı bir zaman çizelgesi görüntüleyebilir.

Şimdi, bir müşteri ile bir otonom ajan arasındaki basitleştirilmiş bir konuşmaya bakacağız; burada konuşma, temel unsurlarla temsil edilir:

Konuşmanın başında, istemci ve sunucu initialize el sıkışmasını kurmalıdır. İstemci, diğer herhangi bir yöntemden önce tek bir initialize isteği göndermelidir ve sunucu bunu bir yanıtla onaylar. Bu, sunucuya yeteneklerini tanıtma fırsatı verir ve her iki tarafın da gerçek çalışma başlamadan önce protokol sürümleri, özellik bayrakları ve varsayılanlar üzerinde anlaşmasına olanak tanır. OpenAI'ın VS Code uzantısından bir örnek yük:

Sunucu şu yanıtı verir:

Bir istemci yeni bir istek yaptığında, önce bir iş parçacığı ve ardından bir tur oluşturur. Sunucu, ilerleme bildirimlerini geri gönderecektir (thread/started ve turn/started). Ayrıca, burada kullanıcı mesajı gibi öğe olarak kaydettiği girdileri de geri gönderir.

Araç çağrıları, öğeler olarak istemciye geri gönderilir. Ayrıca sunucu, bir sunucu isteği göndererek bir eylemi çalıştırabilmek için önce istemci onayı isteyebilir. Onay süreci, istemci "allow" veya "deny" ile yanıt verinceye kadar turu durdurur. VS Code uzantısında onay akışı şu şekilde görünmektedir:

Son olarak, sunucu bir otonom ajan mesajı gönderir ve ardından turn/completed ile turu tamamlar. Otonom ajan mesaj delta olayları, mesaj item/completed ile tamamlanana kadar mesajın parçalarını geri iletir.

Diyagramdaki mesajlar okunabilirlik amacıyla sadeleştirilmiştir. Tam bir tur için JSON'ı görmek istiyorsanız Codex CLI deposundaki test istemcisini çalıştırabilirsiniz.

Şimdi, farklı istemci yüzeylerinin App Server aracılığıyla Codex'i nasıl yerleştirdiğine bakalım. Üç deseni ele alacağız: yerel uygulamalar ve IDE'ler, Codex web çalışma zamanı ve TUI.

Üçünün tamamında taşıma, stdio (JSONL) üzerinden JSON-RPC ile yapılır. JSON-RPC, tercih ettiğiniz dilde istemci bağlamaları oluşturmayı basit hale getirir. Codex yüzeyleri ve iş ortağı entegrasyonları, Go, Python, TypeScript, Swift ve Kotlin gibi dillerde App Server istemcileri uygulamıştır. TypeScript için, şunu çalıştırarak tanımları doğrudan Rust protokolünden oluşturabilirsiniz:

Diğer diller için bir JSON Şeması paketi oluşturabilir ve bunu tercih ettiğiniz kod oluşturucuya beslemek için çalıştırabilirsiniz:

Yerel istemciler genellikle platforma özgü bir App Server ikili dosyasını paketler veya getirir, uzun süreli bir alt süreç olarak başlatır ve JSON-RPC için çift yönlü bir stdio kanalını açık tutar. Örneğin, VS Code uzantımızda ve Masaüstü Uygulamamızda, gönderilen yapay nesne platforma özgü Codex ikili dosyasını içerir ve test edilmiş bir sürüme sabitlenmiştir, böylece istemci her zaman doğruladığımız tam bitleri çalıştırır.

Her entegrasyon, müşteri güncellemelerini sık sık sunamaz. Xcode gibi bazı iş ortakları, istemciyi kararlı tutarak ve gerektiğinde daha yeni bir App Server ikili dosyasına yönlendirmesine izin vererek sürüm döngülerini ayırır. Bu sayede sunucu tarafındaki iyileştirmeleri (örneğin, Codex çekirdeğinde daha iyi otomatik sıkıştırma veya yeni desteklenen yapılandırma anahtarları) benimseyebilir ve bir istemci sürümünü beklemeden hata düzeltmelerini kullanıma sunabilirler. Uygulama Sunucusu'nun JSON-RPC yüzeyi geriye dönük uyumlu olacak şekilde tasarlanmıştır, bu sayede eski istemciler yeni sunucularla güvenle iletişim kurabilir.

Codex Web, Codex donanımını kullanır, ancak bunu bir konteyner ortamında çalıştırır. Bir çalışan, kontrol edilen çalışma alanı ile bir konteyner hazırlar, içinde Uygulama Sunucusu ikili dosyasını başlatır ve stdio² kanalı üzerinden uzun süreli bir JSON-RPC bağlantısını sürdürür. Web uygulaması (kullanıcının tarayıcı sekmesinde çalışan), HTTP ve SSE üzerinden Codex arka ucuyla iletişim kurar ve çalışan tarafından üretilen görev olaylarını SSE ile akış halinde iletir. Bu, tarayıcı tarafındaki kullanıcı arayüzünü hafif tutar ve masaüstü ile web genelinde tutarlı bir çalışma zamanı sağlar.

Web oturumları geçici olduğundan (sekmeler kapanır, ağlar kesilir), web uygulaması uzun süreli görevler için güvenilir bir kaynak olamaz. Durum ve ilerlemenin sunucuda tutulması, sekme kaybolsa bile çalışmanın devam etmesini sağlar. Akış protokolü ve kaydedilmiş iş parçacığı oturumları, yeni bir oturumun yeniden bağlanmasını, kaldığı yerden devam etmesini ve istemcide durumu yeniden oluşturmadan arayı kapatmasını kolaylaştırır.

Tarihsel olarak, TUI, ajan döngüsüyle aynı işlemde çalışan ve uygulama sunucusu protokolü yerine doğrudan Rust çekirdek türleriyle iletişim kuran "yerel" bir istemciydi. Bu, erken yinelemeyi hızlı hâle getirdi, ancak TUI'yi de özel bir durum yüzeyi hâline getirdi.

Artık App Server mevcut olduğuna göre, diğer tüm istemciler gibi davranması için onu kullanacak şekilde TUI'yi yeniden düzenlemeyi⁠(yeni bir pencerede açılır) planlıyoruz: bir App Server alt süreci başlatmak, stdio üzerinden JSON-RPC ile iletişim kurmak ve aynı akış olaylarını ve onayları işlemek. Bu, TUI'nin uzak bir makinede çalışan bir Codex sunucusuna bağlanabileceği iş akışlarını etkinleştirir, ajanı hesaplama işlemine yakın tutar ve dizüstü bilgisayar uyku moduna geçse veya bağlantısı kesilse bile çalışmaya devam ederken, aynı zamanda yerel olarak canlı güncellemeler ve kontroller sağlar.

Codex App Server, gelecekte sürdüreceğimiz birinci sınıf entegrasyon yöntemi olacak, ancak daha sınırlı işlevselliğe sahip başka yöntemler de mevcut. Varsayılan olarak, müşterilerimizin Codex ile entegrasyon için Codex App Server'ı kullanmasını öneririz, ancak farklı entegrasyon yöntemlerini inceleyip bunların artılarını ve eksilerini anlamakta fayda var. Aşağıda Codex'i çalıştırmanın en yaygın yolları ve her birinin ne zaman uygun olabileceği belirtilmiştir.

codex mcp-server⁠(yeni bir pencerede açılır) çalıştırın ve stdio sunucularını destekleyen herhangi bir MCP istemcisine bağlanın (örneğin, OpenAI Agents SDK⁠(yeni bir pencerede açılır)). Zaten MCP tabanlı bir iş akışınız varsa ve Codex'i çağrılabilir bir araç olarak kullanmak istiyorsanız, bu sizin için uygun bir seçenektir. Dezavantajı ise, yalnızca MCP'nin sunduğu bilgileri alabilmenizdir, bu nedenle daha zengin oturum semantiğine dayanan Codex'e özgü etkileşimler (ör. diff güncellemeleri) MCP uç noktaları üzerinden net bir şekilde eşlenemeyebilir.

Bazı ekosistemler, birden fazla model sağlayıcı ve çalışma zamanını hedefleyebilen taşınabilir bir arayüz sunar. Birden fazla ajanı koordine eden tek bir soyutlama istiyorsanız bu, iyi bir seçim olabilir. Bunun karşılığında, bu protokoller genellikle ortak yetenek alt kümesinde birleşir ve bu da, özellikle sağlayıcıya özgü araç ve oturum semantiği önemli olduğunda, daha zengin etkileşimlerin temsil edilmesini zorlaştırabilir. Bu alan hızla gelişiyor ve gerçek dünyadaki ajan iş akışlarını temsil etmek için en iyi temel öğeleri belirledikçe daha yaygın standartların ortaya çıkmasını bekliyoruz (beceriler⁠(yeni bir pencerede açılır) bunun iyi bir örneğidir).

Tam Codex donanımını kararlı ve kullanıcı arayüzü dostu bir olay akışı olarak sunmak istediğinizde App Server'ı seçin. Böylece otonom ajan döngüsünün tam işlevselliğine ve ChatGPT ile oturum açma, model keşfi, yapılandırma yönetimi gibi diğer destekleyici özelliklere sahip olursunuz. Ana maliyet, kendi dilinizde istemci tarafı JSON-RPC bağlamasını oluşturmanız gerektiği için entegrasyon çalışmasıdır. Ancak pratikte, JSON şemasını ve dokümantasyonu sağladığınızda Codex, ağır işlerin büyük kısmını üstlenebilir. Birlikte çalıştığımız birçok ekip, Codex'i kullanarak kısa sürede çalışan bir entegrasyon gerçekleştirebildi.

Tek seferlik görevler ve CI çalıştırmaları için hafif ve betiklenebilir bir CLI modu. Tek bir komutun etkileşimli olmayan bir şekilde tamamlanmasını, günlükler için yapılandırılmış çıktıyı aktarmasını ve açık bir başarı veya başarısızlık sinyaliyle sonlanmasını istediğiniz otomasyon ve ardışık düzenler için çok uygundur.

Kendi uygulamanız içinden yerel Codex ajanlarını programlı olarak kontrol etmek için bir TypeScript kütüphanesi. Sunucu tarafı araçlar ve iş akışları için ayrı bir JSON-RPC istemcisi oluşturmadan yerel bir kütüphane arayüzü istediğinizde en iyi seçenektir. App Server'dan daha önce piyasaya sürüldüğü için, şu anda daha az dil ve daha küçük bir yüzey alanı desteklemektedir. Geliştiricilerin ilgisi varsa, App Server protokolünü saran ek SDK'lar ekleyebiliriz, böylece ekipler JSON-RPC bağlamaları yazmadan daha fazla donanım yüzeyini kapsayabilirler.

Bu gönderide, ajanlarla etkileşim kurmak için yeni bir standart tasarlama yaklaşımımızı ve Codex donanımını kararlı ve kullanıcı dostu bir protokole dönüştürme yöntemimizi paylaştık. AppServer'ın Codex çekirdeğini nasıl sunduğunu, istemcilerin tam otonom ajan döngüsünü yönetmesine nasıl olanak tanıdığını ve TUI, yerel IDE entegrasyonları ve web çalışma zamanı gibi çeşitli yüzeylere nasıl güç verdiğini ele aldık.

Bu, Codex'i kendi iş akışlarınıza entegre etmek için fikirler uyandırdıysa, App Server'ı denemeye değer. Tüm kaynak kod, Codex CLI açık kaynak repo⁠(yeni bir pencerede açılır)'sunda bulunur. Geri bildirimlerinizi ve özellik taleplerinizi paylaşmaktan çekinmeyin. Sizden haber almayı ve ajanları herkes için daha erişilebilir hale getirmeyi sürdürmeyi dört gözle bekliyoruz.