Analisis Cara Kerja Internal OpenAI Codex CLI: Agent Loop dan Strategi Prompt Caching

Ringkasan:

• Struktur agent loop: Menjelaskan secara rinci proses siklik di mana Codex CLI mengoordinasikan input pengguna, inferensi model, dan eksekusi tool untuk menyelesaikan pekerjaan nyata.
• Penyusunan prompt dan Responses API: Menganalisis proses serta aliran data saat perintah sistem, definisi tool, dan konteks lingkungan lokal diubah menjadi payload JSON untuk Responses API.
• Optimasi performa dan manajemen status: Membahas strategi untuk memaksimalkan prompt caching, teknik compaction percakapan untuk mengatasi batas context window, serta prinsip desain stateless untuk ZDR (Zero Data Retention).

Ringkasan detail:
Tim engineering OpenAI merilis artikel teknis yang menganalisis secara mendalam prinsip kerja 'agent loop', logika inti dari Codex CLI, agen perangkat lunak lokal. Tulisan ini menjelaskan dari sudut pandang teknis seluruh lifecycle, mulai dari menerima perintah pengguna, berinteraksi dengan model, menjalankan tool, hingga mengembalikan hasil.

1. Agent Loop (The Agent Loop)

Agent loop adalah struktur siklik yang menerima input pengguna dan berinteraksi dengan model hingga tugas selesai.

• Proses: input pengguna -> pembuatan prompt -> inferensi model -> (permintaan pemanggilan tool -> eksekusi tool -> lampirkan hasil -> inferensi ulang) berulang -> respons akhir.
• Turn: Proses dari input pengguna hingga model akhirnya mengirim pesan ke pengguna (Assistant Message) disebut satu 'turn'. Dalam proses ini, agen dapat melakukan ratusan pemanggilan tool (misalnya menjalankan ls, mengedit file, dan lain-lain).

2. Inferensi model dan Responses API

Codex CLI berkomunikasi dengan model melalui Responses API. API ini dapat dikonfigurasi ke https://chatgpt.com/backend-api/codex/responses, https://api.openai.com/v1/responses, atau localhost (seperti Ollama).

Penyusunan prompt awal (Building the Initial Prompt)

Prompt bukan sekadar teks sederhana, melainkan data terstruktur yang terdiri dari instructions, tools, input, dan sebagainya.

• Instructions: Pesan sistem atau developer yang mendefinisikan pedoman perilaku model. (misalnya merujuk ke file konfigurasi ~/.codex/config.toml)
• Tools: Daftar definisi tool yang dapat digunakan model. Termasuk eksekusi shell, pembaruan rencana (update_plan), pencarian web, serta tool server MCP (Model Context Protocol) kustom.
• Input: Daftar data aktual yang dikirim ke model. Ini mencakup pengaturan izin sandbox, instruksi per proyek, serta environment context seperti current working directory (cwd) dan jenis shell yang sedang digunakan.

Contoh payload JSON:

{  
  "type": "message",  
  "role": "user",  
  "content": [  
    {  
      "type": "input_text",  
      "text": "Tambahkan diagram arsitektur ke README.md"  
    }  
  ]  
  // ... environment context dan pengaturan izin yang telah didefinisikan sebelumnya juga dikirim bersama  
}  
  

3. Eksekusi tool dan aliran data

Saat model meminta pemanggilan tool (Function Call), agen mengeksekusinya, menambahkan hasilnya ke riwayat percakapan, lalu memanggil model kembali.

Contoh JSON permintaan ulang setelah eksekusi tool:

[  
  /* ... item input sebelumnya ... */  
  {  
    "type": "reasoning", // proses penalaran model (CoT)  
    "summary": [...],  
    "encrypted_content": "gAAAAABpaDW..." // isi penalaran terenkripsi  
  },  
  {  
    "type": "function_call",  
    "name": "shell",  
    "arguments": "{\"command\":\"cat README.md\",\"workdir\":\"/Users/mbolin/code/codex5\"}",  
    "call_id": "call_8675309..."  
  },  
  {  
    "type": "function_call_output", // hasil eksekusi tool  
    "call_id": "call_8675309...",  
    "output": "<p align=\"center\"><code>npm i -g @openai/codex</code>..."  
  }  
]  
  

Penting untuk menyusun prompt agar prompt sebelumnya menjadi prefix yang persis sama untuk prompt baru. Ini menentukan efisiensi prompt caching yang akan dibahas berikutnya.

4. Pertimbangan performa: caching dan ZDR

Semakin panjang percakapan, ukuran prompt akan bertambah secara linear, yang meningkatkan biaya dan latensi.

• Prompt caching: Model OpenAI dapat menggunakan ulang hasil komputasi sebelumnya untuk mempercepat proses jika bagian awal prompt cocok (prefix match).

• Mencegah cache miss: Jika perubahan daftar tool atau pengaturan sandbox terjadi di tengah percakapan, cache bisa rusak. Untuk mencegahnya, Codex menangani perubahan konfigurasi dengan cara menambahkan pesan baru (append), bukan mengubah pesan yang sudah ada.

• Stateless dan ZDR: Tidak menggunakan parameter seperti previous_response_id dan selalu mengirim seluruh konteks setiap kali. Ini dilakukan untuk mematuhi kebijakan Zero Data Retention (ZDR) yang tidak menyimpan data di server. Dengan cara klien menerima lalu mengirim kembali isi penalaran terenkripsi (encrypted_content) ke server, server dapat memulihkan konteks penalaran sebelumnya tanpa harus menyimpan state.

5. Manajemen context window (Compaction)

Agar tidak melampaui batas token, Codex menggunakan endpoint /responses/compact untuk mengompresi riwayat percakapan. Ini bukan sekadar ringkasan sederhana, melainkan mengembalikan daftar item terkompresi yang mencakup encrypted_content untuk menjaga latent understanding model, lalu menggantikan input yang ada.

[iolothebard]

Claude Code sudah ada di dokumentasi resmi sejak awal, tapi…

[iolothebard]

https://code.claude.com/docs/en/how-claude-code-works