OpenAI Codex CLI エージェントループ技術概要

OpenAI は Codex CLI エージェントループの内部アーキテクチャを詳細に説明しています。このコアオーケストレーションロジックは、ユーザー、LLM、ローカルソフトウェアツール間のやり取りを管理します。このシステムは、ツール呼び出しを反復的に実行し、会話コンテキストが増大することを管理することで、パフォーマンスと安定性を維持しながら信頼できるソフトウェア変更を実現するよう設計されています。

エージェントループアーキテクチャ

エージェントループは、ユーザーとモデル間の情報フローをオーケストレーションする中心的なメカニズムです。会話における単一の「ターン」は、最終状態に達するまで推論とツール実行を複数回繰り返すことで構成されます。

反復プロセス

  1. 入力とプロンプト作成: エージェントはユーザー入力を受け取り、モデル用のテキストプロンプトを作成します。
  2. 推論: プロンプトはトークン化され、モデルに送信されて応答が生成されます。
  3. 意思決定ポイント: モデルは最終的なアシスタントメッセージを生成してターンを終了するか、ツール呼び出し（例: ls のようなシェルコマンドの実行）を要求します。
  4. 実行とフィードバック: ツールが呼び出された場合、エージェントはコマンドを実行し、出力をプロンプトに追加してモデルに再問い合わせます。

このサイクルは、モデルがアシスタントメッセージを出すまで繰り返され、作業が完了し制御がユーザーに戻ることを示します。

モデル推論とプロンプト構築

Codex CLI はエージェントループを駆動するために Responses API を利用します。設定に応じて、ChatGPT ログイン、API キーを使用した OpenAI ホストモデル、あるいは gpt-oss と Ollama や LM Studio を組み合わせたローカルインスタンスなど、さまざまなエンドポイントに接続します。

初期プロンプトの構築

文字通りのプロンプトを送信するのではなく、Codex は特定の入力タイプを含む JSON ペイロードを送ります。Responses API サーバーはこれらをロールに基づいてプロンプトに構築し、優先順位（高い順）は system、developer、user、assistant です。

初期プロンプトの主要な構成要素は次のとおりです：

  • 指示: コンテキストに挿入されるシステムまたはデベロッパーメッセージ。
  • ツール: スキーマで定義されたツールのリストで、Codex が提供するシェルツール、Responses API ツール、そして MCP（Model Context Protocol）サーバー経由でユーザーが提供するツールが含まれます。
  • 入力: 集約されたテキスト、画像、またはファイル。これには config.toml からのデベロッパー指示や、プロジェクトルートまたは $CODEX_HOME にある AGENTS.md や AGENTS.override.md ファイルから取得されたユーザー指示が含まれます。

会話ターンの処理

各ターンは Server-Sent Events（SSE）ストリームとして処理されます。モデルが推論や関数呼び出しを生成した場合、これらは次のリクエスト用に input フィールドに追加されます。パフォーマンス最適化のため、Codex は古いプロンプトが新しいプロンプトの正確なプレフィックスであることを保証し、これがプロンプトキャッシュを有効にするために重要です。

パフォーマンスとコンテキスト管理

会話が増えるにつれてプロンプトの長さが伸び、モデルのコンテキストウィンドウが枯渇しレイテンシが増加する可能性があります。Codex はこれを緩和するために、プロンプトキャッシュと会話圧縮という 2 つの主要戦略を採用しています。

プロンプトキャッシュ

送信する JSON ペイロードが増大する二次的コストを回避するため、Codex はプロンプトキャッシュに依存しています。キャッシュヒットは正確なプレフィックス一致の場合にのみ発生します。これらのヒットを維持するため、Codex は会話の以前のメッセージを変更せず、新しいメッセージを追加して変更を反映します：

  • 設定変更: サンドボックス設定や承認モードの変更は新しい role=developer メッセージとして追加されます。
  • 環境変更: カレントワーキングディレクトリの変更は新しい role=user メッセージとして追加されます。

ツールの順序を一貫して維持できない（初期の MCP ツール実装など）場合、キャッシュミスが発生し、パフォーマンスが低下する可能性があります。

コンテキストウィンドウの圧縮

トークン数が auto_compact_limit を超えると、Codex は Responses API の /responses/compact エンドポイントを使用します。このプロセスは、膨大な会話履歴をより小さく代表的な項目リストに置き換えます。これには、encrypted_content を含む特別な type=compaction 項目が含まれ、完全なトークン履歴を必要とせずにモデルの潜在的な会話理解を保持します。

Sources