アーキテクチャ

OpenAI がエージェントのハーネスを運用します。アプリケーションはハーネスにタスクを送り、結果を受け取ります。エージェントにコンピューティングリソースやファイルが必要な場合は、環境を追加します。

構成要素

• ハーネス： OpenAI がホストする Codex インスタンスです。モデルとツールを呼び出すループを実行し、エージェントのセッションを維持します。
• 環境： エージェントがコマンドやコードを実行し、ファイルを操作する場所です。リモートのサンドボックス、手元のノート PC、Docker コンテナ、AWS Lambda 関数などを環境として使えます。
• アプリケーションサーバー： エージェントを自社の製品に接続するためのコードです。タスクを送信し、イベントを受信し、関数ツールの呼び出しを処理します。環境を自前で用意する場合は、このコードで環境のライフサイクルも管理します。

まずはタスクに必要な構成要素を選びます。ハーネスは環境がなくても動作します。アプリケーションはストリーミングや Webhook で進捗を受け取れます。

環境を使わない構成

質問に答えたり、ツールを使って外部サービスにアクセスしたりするエージェントには、専用のコンピューティングリソースやファイルが不要な場合があります。その場合は environment.type を none に設定します。次の例は環境の設定部分です。セッションを作成するには、エージェントと初期入力も指定します。

12345{
  "environment": {
    "type": "none"
  }
}

アプリケーションがセッションに入力を送ると、ハーネスはモデルを呼び出し、設定済みのツールを使って結果を返します。後から作業を続けられるように、OpenAI がセッションを維持します。

ハーネスはリモートの MCP ツールを直接呼び出せます。関数ツールを使う場合は、アプリケーション側のコードで呼び出しを受け取るたびに、対応する関数を実行して結果を返します。

環境がない場合、組み込みの Bash ツールと apply-patch ツール、ワークスペースのファイル、エグゼキューターの MCP は利用できません。

図に示した仮想ランタイムは任意で利用できます。アプリケーションの関数ツールを通じて、ファイルとシェルコマンドを提供します。

OpenAI ホスト環境の追加

エージェントがスクリプトを実行したり、ファイルを編集したり、成果物を作成したりする必要がある場合は、environment.type を openai_hosted に設定します。OpenAI がセッション用のサンドボックスを作成して管理します。

エージェントに必要なパッケージ、ファイル、ネットワークアクセスを設定します。ハーネスはサンドボックス内でコマンドを直接実行します。アプリケーションは引き続き、タスクの送信、イベントの受信、関数ツールの呼び出しの処理を担当します。

破線の矢印は、次のセクションで説明するように、環境を自分で管理する場合にのみ該当します。

設定項目については、OpenAI ホスト環境を参照してください。

独自環境の接続

エージェントが独自のインフラストラクチャ、プライベートネットワーク、カスタムソフトウェアのいずれかを必要とする場合は、environment.type: "self_hosted" を使います。

アプリケーション側のコードで環境を起動し、エグゼキューターをセッションに接続します。エグゼキューターは、ハーネスが要求したコマンドやツールを実行します。アプリケーションは接続と環境のライフサイクルを管理しますが、コマンドを個別に転送する必要はありません。

環境のプロビジョニング、再接続、シャットダウン、必要なファイルの保存は利用者が担当します。これらの処理はアプリケーションサーバーや Webhook ハンドラーで管理できます。

コンピューティングリソースを停止する前に、新しく届くタスクの受け付けを調整し、実行待ちの処理がないことを確認してください。

セットアップとシャットダウンの要件については、サンドボックスの接続とサンドボックスのライフサイクルを参照してください。

進捗と結果の受信

どの環境構成でも、次の方法を単独で使うことも、併用することもできます。

• ストリーミング： エージェントの作業中に、製品内に表示する出力など、詳細なイベントを受信します。
• Webhook： ストリームを開いたままにせずに、セッションの状態変化を受信します。ハンドラーで結果を取得したり、関数ツールを実行したり、セルフホスト環境を管理したりできます。

関数ツールには、呼び出しを受け取って結果を返すハンドラーが必要です。ハンドラーが利用できない場合、エージェントが結果を待ち続けることがあります。また、イベントやライフサイクルを処理するハンドラーに障害が発生すると、進捗の通知や環境の管理が中断することがあります。

組み込み方法の詳細は、セッションイベントと Webhook を参照してください。