OpenAI’ın Codex CLI Ajan Döngüsünün İç Yapısı

27 Ocak 2026'da OpenAI, şirketin komut satırı kodlama ajanı olan Codex CLI'ın konuşmaları gerçekte nasıl yürüttüğünü, araçları nasıl çağırdığını ve bağlamı nasıl yönettiğini açıklayan alışılmadık derecede ayrıntılı mühendislik notları yayımladı.

Ajan döngüsü nasıl görünür?

Codex CLI'ın kalbinde, mühendislerin "ajan döngüsü" (agent loop) olarak adlandırdığı basit ve tekrarlayan bir model yer alıyor: kullanıcı girdisini kabul et, bir prompt hazırla, modelden bir yanıt iste, modelin talep ettiği araç çağrılarını gerçekleştir, araç çıktılarını konuşmaya ekle ve model son bir asistan mesajı döndürene kadar bu süreci tekrarla.

Bu model basit gibi görünse de dokümantasyon, performans ve güvenilirliği birlikte şekillendiren birçok küçük tasarım kararını ortaya koyuyor. Modele gönderilen prompt tek bir metin bloğu değil; önceliklendirilmiş bileşenlerin yapılandırılmış bir bütünüdür. Sistem, geliştirici, asistan ve kullanıcı rolleri, hangi talimatların öncelikli olduğunu belirler. Bir araçlar (tools) alanı; yerel kabuk (shell) komutları, planlama yardımcı programları, web araması ve Model Context Protocol (MCP) sunucuları aracılığıyla sunulan özel servisler gibi mevcut fonksiyonları tanıtır. Ortam bağlamı (environment context) ise sandbox izinlerini, çalışma dizinlerini ve hangi dosya veya işlemlerin ajan tarafından görülebileceğini tanımlar.

Araç çağrıları, MCP ve sandboxing

Model bir araç çağrısı yaptığında, Codex bu aracı kontrollü bir ortamda (kendi sandbox'ında) çalıştırır, çıktıyı yakalar ve sonucu konuşmaya ekler. Özel araçlar, birkaç şirketin benimsediği açık bir standart olan ve bir modelin basit bir kabuğun ötesindeki yetenekleri keşfedip çağırmasına olanak tanıyan MCP sunucuları aracılığıyla uygulanabilir. Dokümantasyon ayrıca ekibin bu entegrasyonları kurarken keşfettiği —örneğin, MCP araçlarının tutarsız bir şekilde listelenmesi gibi— ve yamalanması gereken belirli hataları da ele alıyor.

OpenAI, sandbox kullanımı ve araç erişiminin ilerideki yazılar için aktif çalışma alanları olduğunu belirtiyor. İlk dokümantasyon, dosya sistemine veya ağ servislerine yazma erişimi olan ajanların tam tehdit modelinden ziyade döngü mekaniğine ve performans iyileştirmelerine odaklanıyor.

Durum bilgisi içermeyen istekler, gizlilik seçimleri ve bağlam kopyalamanın maliyeti

Bu şişme doğrusal değildir. Her tur token ekler ve her tur önceki turları bütünüyle içerdiğinden, prompt boyutu tur sayısına göre karesel bir büyüme eğilimi gösterir. Ekip bunu açıkça belgeliyor ve bağlam sıkıştırma (context compaction) ve prompt önbelleğe alma (prompt caching) ile bu durumu nasıl hafiflettiklerini açıklıyor.

Prompt önbelleğe alma ve tam ön ekler

Prompt önbelleğe alma pragmatik bir optimizasyondur: Eğer yeni bir istek, daha önce önbelleğe alınmış bir prompt'un tam ön eki (exact prefix) ise, sağlayıcı hesaplamayı yeniden kullanabilir ve sonuçları daha hızlı döndürebilir. Ancak önbellekler katılık gerektirir. Mevcut araçlarda yapılan herhangi bir değişiklik, model değişimi ve hatta bir sandbox yapılandırma ayarı bile ön eki geçersiz kılabilir ve bir önbellek isabetini (cache hit) maliyetli bir hataya (cache miss) dönüştürebilir. OpenAI mühendisleri, geliştiricilerin tutarlı bir gecikme süresine ihtiyaç duyduklarında konuşma ortasında yeniden yapılandırmadan kaçınmaları gerektiği konusunda uyarıyor.

Önbellek isabetleri tam ön ek eşleşmesine bağlıdır; bu nedenle araç manifestolarını sabitlemek ve devam eden bir etkileşim sırasında model seçimini sabit tutmak mantıklı uygulamalardır. Önbellek hataları sık sık meydana geldiğinde sistem, tam da geliştiricilerin ajanın hızlı hissettirmesini beklediği anlarda, her çağrıda tam bir yeniden işlemeye geriler.

Bağlam sıkıştırma: Anlamı kaybetmeden geçmişi sıkıştırmak

Token büyümesini yönetmek için Codex, otomatik bağlam sıkıştırma (context compaction) uygular. CLI, bunu bir kullanıcı komutuna bırakmak yerine, eski konuşma turlarını şifrelenmiş bir içerik öğesine sıkıştıran ve aynı zamanda modelin devam etmek için ihtiyaç duyduğu özetlenmiş bilgileri koruyan özel bir API uç noktasını çağırır. Önceki sürümler manuel kullanıcı sıkıştırması gerektiriyordu; yeni yaklaşım süreci, modelin çalışma belleğini koruyan bir API çağrısına dönüştürüyor.

Sıkıştırma token maliyetini düşürür ancak beraberinde bazı incelikler getirir: Özetler, sonraki aşamalarda halüsinasyonu önleyecek kadar aslına sadık olmalı, şifreleme özellikleri gizlilik kısıtlamalarına uymalı ve sıkıştırma sezgiselleri durumun hangi parçalarının temel, hangilerinin feda edilebilir olduğuna karar vermelidir. Dokümantasyon bunları yerleşik tasarımlardan ziyade açık mühendislik seçimleri olarak işaretliyor.

Pratik sınırlar ve geliştirici deneyimi

OpenAI’ın notları güçlü ve zayıf yönler konusunda oldukça samimi. Kodlama ajanlarının başarılı olduğu iskele kurma, boilerplate hazırlama veya hızlı prototipleme gibi basit görevler için Codex hızlı ve kullanışlıdır. Modelin eğitim verilerinde görmediği daha derin, bağlam açısından yoğun mühendislik çalışmaları için ise ajan kırılgandır. Umut verici taslaklar oluşturacak, ardından duraksayacak veya insan müdahalesi gerektiren hatalı adımlar üretecektir.

Codex'i dahili olarak test eden mühendisler, ajanın ilk proje oluşturma sürecini büyük ölçüde hızlandırabildiğini ancak henüz sağlam mühendislik için gereken yinelemeli, uzman hata ayıklama sürecinin yerini alamayacağını gördüler. Ekip ayrıca, Codex'i Codex'in parçalarını oluşturmak için kullandıklarını da doğruladı; bu durum, kendi çıktıları üzerinde eğitilmiş araçlar hakkında ilginç geri bildirim sorularını gündeme getiren bir uygulama.

OpenAI bunu neden açtı—şeffaflık, rekabet ve standartlar

Operasyonel ayrıntılarını genellikle gizli tutan bir şirketten, bir tüketici ürününün dahili mühendisliğine dair böylesine derinlemesine bir inceleme yayımlanması dikkat çekici. OpenAI'ın bu paylaşımı, ajan standartlarına yönelik daha geniş bir ekosistem hamlesiyle örtüşüyor: Anthropic ve OpenAI'ın her ikisi de araç keşfi ve çağırma için MCP'yi destekliyor ve her ikisi de geliştiricilerin davranışları uçtan uca inceleyebilmesi için CLI istemcilerini açık kaynak olarak yayımlıyor.

Şeffaflık birkaç farklı kitleye hizmet ediyor. Geliştiriciler, güvenilir ajanlar oluşturmak için uygulama modelleri ve pratik tavsiyeler alıyor. Güvenlik odaklı mühendisler, sandbox ve araç erişimi ödünleşimlerini titizlikle inceleyebiliyor. Rakipler ve standartlar topluluğu, birlikte çalışabilirlik için istemci davranışını tersine mühendislik ile çözmek zorunda kalmadıklarından daha hızlı yineleme yapabiliyor.

Kodlama ajanlarını kullanan ekipler için operasyonel tavsiyeler

• Prompt önbellek isabetlerini ve istikrarlı performansı en üst düzeye çıkarmak için modelleri ve araç manifestolarını bir oturum içinde sabitleyin.
• Token maliyetlerini kontrol etmek ve kontrolsüz prompt büyümesini önlemek için uzun görevlerde bağlam sıkıştırmayı proaktif olarak kullanın.
• Yanlışlıkla oluşabilecek veya kötü niyetli yan etkileri azaltmak için ajan izinlerini sınırlayın ve sandbox'larda yazılabilir klasörleri izole edin.
• Manuel hata ayıklama için hazırlıklı olun ve bütçe ayırın: Ajanlar taslak oluşturma ve yinelemeyi hızlandırır, ancak karmaşık kod tabanlarında uzman muhakemesinin yerini henüz tutamazlar.

Sırada ne var?

Yazıyı kaleme alan mühendis; CLI'ın mimarisini daha derinlemesine, araç uygulamalarını ve sandboxing modelini kapsayacak devam yazılarının sinyalini verdi. Bu gelecek yazılar önemli olacak: Ajanlar geliştiricilerin ortamlarına daha derin erişim kazandıkça; güvenli yürütme, kaynak takibi ve doğrulanabilir araç çağırma mekanizmaları, ekiplerin onları birer asistan olarak mı benimseyeceğini yoksa riskli birer merak unsuru olarak mı göreceğini belirleyecek.

Şimdilik OpenAI'ın notları, kodlama ajanlarının etrafındaki gizemi somut ayar düğmelerine ve kaldıraçlara dönüştürüyor. Bu değişim, mühendislik ekiplerinin performans, gizlilik ve kırılganlık gibi bilinen ödünleşimleri üretim kesintileri sırasında acı yoldan keşfetmek yerine, bunlara göre plan yapmasını kolaylaştırıyor.

Codex CLI'ın dokümantasyonu bir davet niteliğinde: Uygulamayı okuyun, uç vakaları test edin ve net avantajlardan yararlanırken sınırları kabul eden iş akışları tasarlayın. Ajanları günlük geliştirici araçlarına dahil etmek için yarışan bir sektörde, hata modları hakkındaki netlik, en nadir ve en yararlı değerdir.

Kaynaklar

• OpenAI (dokümantasyon: "Unrolling the Codex agent loop")
• Anthropic (Model Context Protocol spesifikasyonu ve Claude Code materyalleri)
• OpenAI mühendislik depoları ve Codex CLI uygulama notları