OpenAI Codex アプリサーバーのアーキテクチャと統合

OpenAI は Codex アプリサーバーをリリースしました。これは標準化された JSON-RPC プロトコルと長時間稼働プロセスで、Codex エージェントハーネスを多様なクライアントアプリケーションに公開します。このアーキテクチャにより、開発者は IDE、デスクトップアプリ、Web 環境などに、ワークスペース探索、リアルタイム進捗ストリーミング、diff 発行といった高忠実度エージェントループを、コアエージェントロジックを再実装せずに統合できます。

Codex アプリサーバーのアーキテクチャ

Codex アプリサーバーはクライアントと「Codex コア」の間の変換レイヤーとして機能します。Codex コアにはエージェントループ、ツール実行ロジック、スレッド管理が含まれます。

コアコンポーネント

アプリサーバープロセスは主に 4 つのコンポーネントから構成されます:

  • Stdio Reader: 受信通信チャネルを処理します。
  • Codex Message Processor: クライアントの JSON-RPC リクエストを Codex コア操作に変換し、内部イベントストリームを安定した UI 向け通知に変換します。
  • Thread Manager: スレッドごとに 1 つのコアセッションを生成し、コアセッションのライフサイクルを管理します。
  • Core Threads: エージェントループが実行される実際のランタイムインスタンスです。

Codex ハーネス

エージェントループに加えて、アプリサーバーは以下を含む完全な Codex ハーネスを公開します:

  • Thread Lifecycle and Persistence: 会話の作成、再開、分岐、アーカイブが可能で、クライアントが再接続した際に一貫したタイムラインを提供します。
  • Configuration and Authentication: デフォルト設定や認証フロー（例: "Sign in with ChatGPT"）の管理。
  • Tool Execution and Extensions: シェルやファイルツール用のサンドボックス環境、MCP サーバーやスキルとの統合。

会話プリミティブ

エージェント相互作用の非線形性に対処するため、アプリサーバープロトコルは 3 つのコアプリミティブを使用し、レジリエンスと UI への統合の容易さを確保します。

1. アイテム

アイテムは入力と出力の最小単位です。各アイテム（例: ユーザーメッセージ、ツール実行、diff）は以下のライフサイクルをたどります:

  • item/started: アイテムが開始されます。
  • item/*/delta: コンテンツが増分でストリーミングされます（ストリーミングタイプの場合）。
  • item/completed: アイテムが最終ペイロードで完了します。

2. ターン

ターンはユーザー入力によりトリガーされるエージェント作業の単位です。エージェントが生成する中間ステップと最終出力を表す一連のアイテムを含みます。

3. スレッド

スレッドはセッションの永続コンテナです。複数のターンを保持し、クライアントがセッションに再接続して履歴を再構築せずに表示できるようにします。

クライアント統合パターン

アプリサーバーは stdio（JSONL）上の JSON-RPC を使用するため、Go、Python、TypeScript、Swift、Kotlin など複数言語でクライアントバインディングが可能です。

ローカルアプリとIDE

ローカルクライアント（例: VS Code 拡張、Codex Desktop App）はプラットフォーム固有のアプリサーバーバイナリを子プロセスとしてバンドルします。Xcode のようなパートナーは、クライアントリリースとは独立して新しいアプリサーバーバイナリを指すことで、サーバー側の改善やバグ修正をフルクライアント更新なしで採用できます。

Codex Web

コンテナ化環境では、ワーカーがワークスペース付きコンテナをプロビジョニングし、アプリサーバーバイナリを起動します。Web アプリは HTTP と SSE を介して Codex バックエンドと通信し、ワーカーからのイベントをストリーミングします。これにより、ブラウザタブが閉じても長時間タスクが継続します。

TUI と Codex CLI

当初 TUI は Rust コア型と直接やり取りしていましたが、現在はアプリサーバープロトコルにリファクタリング中です。これにより TUI はリモート Codex サーバーに接続でき、エージェントを計算リソースに近い場所に置きつつローカル更新を受け取れます。

統合方法の比較

OpenAI はフルハーネスが必要なケースにアプリサーバーを推奨しますが、特定のユースケースに応じた他のオプションも提供しています:

方法 最適な使用ケース トレードオフ
Codex App Server フルハーネス、安定した UI フレンドリーなイベントストリーム、認証管理。 クライアント側の JSON-RPC バインディングの構築が必要です。
MCP Server Codex が呼び出し可能なツールとして使用される既存の MCP ベースのワークフロー。 MCP のセマンティクスに限定され、diff 更新などのリッチなセッション機能が欠如しています。
Cross-provider Protocols 異なるモデルプロバイダー間で複数エージェントを調整。 多くの場合、共通の機能サブセットに限定され、プロバイダー固有のセマンティクスが欠如しています。
CLI Mode 単発タスク、CI/CD パイプライン、非対話型自動化。 非対話型で、単一コマンドの完了を目的としています。
TypeScript Library TS アプリケーション内でローカルエージェントをプログラム的に制御。 現在、App Server に比べてサポート言語が少なく、対象範囲も狭いです。

アプリサーバーのソースコードはオープンソースの Codex CLI リポジトリで入手可能です。

Sources