OpenAI Codex CLI iç işleyişinin analizi: ajan döngüsü ve prompt caching stratejisi

 (openai.com)
18 puan yazan darjeeling 2026-01-24 | 2 yorum | WhatsApp'ta paylaş

Özet:

  • Ajan Döngüsü'nün (Agent Loop) yapısı: Codex CLI'nin kullanıcı girdisini, model çıkarımını ve araç (Tool) çalıştırmayı nasıl koordine ederek gerçek işleri yerine getirdiğini ayrıntılı biçimde açıklar.
  • Prompt yapısı ve Responses API: Sistem komutlarının, araç tanımlarının ve yerel ortam bağlamının Responses API için JSON payload'una nasıl dönüştüğünü ve veri akışını analiz eder.
  • Performans optimizasyonu ve durum yönetimi: Prompt Caching'i en üst düzeye çıkarmaya yönelik stratejileri, bağlam penceresi sınırlarını aşmak için kullanılan konuşma sıkıştırma (Compaction) tekniğini ve ZDR (Zero Data Retention) için stateless tasarım ilkelerini ele alır.

Ayrıntılı özet:
OpenAI mühendislik ekibi, yerel bir yazılım ajanı olan Codex CLI'nin temel mantığı olan 'Ajan Döngüsü'nün (Agent Loop) çalışma prensibini derinlemesine inceleyen teknik bir makale yayımladı. Yazı, kullanıcının komutunu alıp modelle etkileşime giren, araçları çalıştıran ve sonucu geri döndüren tüm yaşam döngüsünü teknik bir bakış açısından açıklar.

1. Ajan Döngüsü (The Agent Loop)

Ajan döngüsü, kullanıcının girdisini alıp görev tamamlanana kadar modelle etkileşim kuran döngüsel bir yapıdır.

  • Süreç: kullanıcı girdisi -> prompt oluşturma -> model çıkarımı (Inference) -> (araç çağrısı isteği -> araç çalıştırma -> sonucun eklenmesi -> yeniden çıkarım) tekrarı -> nihai yanıt.
  • Tur (Turn): kullanıcının girdisinden modelin kullanıcıya nihai olarak bir mesaj (Assistant Message) göndermesine kadar geçen sürece tek bir 'tur' denir. Bu süreçte ajan yüzlerce araç çağrısı yapabilir (ör. ls çalıştırma, dosya düzenleme vb.).

2. Model çıkarımı ve Responses API

Codex CLI, modelle Responses API üzerinden iletişim kurar. Bu API, https://chatgpt.com/backend-api/codex/responses, https://api.openai.com/v1/responses veya localhost (Ollama vb.) olarak yapılandırılabilir.

İlk prompt'un oluşturulması (Building the Initial Prompt)

Prompt, basit bir metin değil; instructions, tools, input gibi alanlardan oluşan yapılandırılmış bir veridir.

  • Instructions: modelin davranış yönergelerini tanımlayan sistem veya geliştirici mesajlarıdır. (ör. ~/.codex/config.toml yapılandırma dosyasına başvuru)
  • Tools: modelin kullanabileceği araç tanımlarının listesidir. Shell çalıştırma, plan güncelleme (update_plan), web arama ve kullanıcı tanımlı MCP (Model Context Protocol) sunucu araçları buna dahildir.
  • Input: modele iletilen gerçek veri listesidir. Buna sandbox izin ayarları, projeye özel yönergeler ve mevcut çalışma dizini (cwd) ile shell türü gibi ortam bağlamı (Environment Context) dahildir.

JSON payload örneği:

{  
  "type": "message",  
  "role": "user",  
  "content": [  
    {  
      "type": "input_text",  
      "text": "README.md'e mimari diyagram ekle"  
    }  
  ]  
  // ... daha önce tanımlanan ortam bağlamı ve izin ayarlarıyla birlikte gönderilir  
}

3. Araç çalıştırma ve veri akışı

Model bir araç çağrısı (Function Call) istediğinde, ajan bunu çalıştırır ve sonucu konuşma geçmişine ekleyerek modeli yeniden çağırır.

Araç çalıştırma sonrası yeniden istek için JSON örneği:

[  
  /* ... önceki girdi öğeleri ... */  
  {  
    "type": "reasoning", // modelin akıl yürütme süreci (CoT)  
    "summary": [...],  
    "encrypted_content": "gAAAAABpaDW..." // şifrelenmiş akıl yürütme içeriği  
  },  
  {  
    "type": "function_call",  
    "name": "shell",  
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",  
    "call_id": "call_8675309..."  
  },  
  {  
    "type": "function_call_output", // araç çalıştırma sonucu  
    "call_id": "call_8675309...",  
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."  
  }  
]

Önceki prompt'un yeni prompt'un tam ön eki (Prefix) olacak şekilde kurulması önemlidir. Bu, aşağıda ele alınan prompt caching verimliliğini belirler.

4. Performans değerlendirmeleri: caching ve ZDR

Konuşma uzadıkça prompt boyutu doğrusal olarak artar; bu da maliyeti ve gecikmeyi yükseltir.

  • Prompt Caching: OpenAI modelleri, prompt'un baş kısmı eşleştiğinde (Prefix Match) önceki hesaplama sonuçlarını yeniden kullanarak hızı artırır.

  • Cache miss önleme: araç listesinin değişmesi, sandbox ayarlarının değişmesi gibi durumlar konuşmanın ortasında yaşanırsa cache bozulabilir. Bunu önlemek için Codex, yapılandırma değişikliklerini mevcut mesajları düzenlemek yerine yeni mesaj ekleme (Append) yöntemiyle işler.

  • Stateless ve ZDR: previous_response_id gibi parametreler kullanılmadan her seferinde tüm bağlam gönderilir. Bunun amacı, sunucuda veri tutmayan Zero Data Retention (ZDR) politikasına uymaktır. Şifrelenmiş akıl yürütme içeriğinin (encrypted_content) istemci tarafından alınıp yeniden sunucuya gönderilmesi sayesinde sunucu, durum saklamadan önceki akıl yürütme bağlamını geri yükleyebilir.

5. Bağlam penceresi yönetimi (Compaction)

Token sınırını aşmamak için Codex, konuşma geçmişini sıkıştırmak üzere /responses/compact endpoint'ini kullanır. Bu, basit bir özetleme değil; modelin örtük anlayışını (Latent understanding) koruyan encrypted_content içeren sıkıştırılmış öğe listesinin döndürülmesi ve bunun mevcut girdilerin yerine geçmesi yaklaşımıdır.

İlgili okumalar

2 yorum

 
iolothebard 2026-01-24

Claude Code en başından beri resmi belgelerde vardı ama…