エージェントのセッションは、環境が終了した後も存続できます。self_hosted 環境で使用するコンピューティングリソースとファイルは、アプリケーションが管理します。
環境の起動
アプリケーションは、セッションの作成後にコンピューティングリソースを起動できます。プロバイダーの SDK または API を使用して起動し、セッションの環境 ID と環境キーを使ってエグゼキューターを接続します。
OpenAI Cookbook のアプリケーションで管理するサンドボックスの例を参照してください。
各セッションの環境は、単一のコンポーネントで管理してください。セッションとプロバイダーのコンピューティングリソースの対応関係を保存します。リクエストが繰り返されたり、同時に届いたりしても、環境が重複して作成されないようにする必要があります。
Webhook によるコンピューティングリソースの起動
入力の処理に環境への接続が必要になるまで待つこともできます。API は、エグゼキューターの接続を待つ前に、required_action.type: "environment_connection" を含む agent.session.action_required を送出します。Webhook ハンドラーが環境を起動または再接続します。
OpenAI Cookbook のWebhook で管理するサンドボックスの例を参照してください。
Webhook のセットアップに従って、agent.session.action_required と agent.session.failed のハンドラーを登録します。ハンドラーの署名シークレットとセッション読み取り用の認証情報は、エグゼキューターの環境キーとは別に管理してください。複数のプロバイダーハンドラーでプロジェクトを共有する場合は、セッションを管理するハンドラーにイベントを振り分けます。
ハンドラーとワーカーには、それぞれ次の役割があります。
- 検証してキューに追加します。 Webhook の署名を検証します。接続リクエストは、
data.required_action.typeがenvironment_connectionの場合にのみキューに追加します。セッションの失敗もキューに追加します。キューへの追加が成功した後にのみ、成功を示す HTTP レスポンスを返します。 - 現在の状態を確認します。 ワーカーがセッションを取得します。削除済みのセッションと解決済みのアクションは無視します。接続がまだ必要なセルフホスト型セッションでは、
session.environment.idとsession.environment.remote_urlを使ってエグゼキューターを起動または再接続します。セッションがまだ失敗状態の場合は、そのコンピューティングリソースを解放します。
セッションストリームでは、同じリクエストが agent.session.requires_action として通知されます。function_call の必須アクションで必要なのは関数の結果であり、環境の起動ではありません。ターン作成イベントや agent.session.in_progress イベントが届いてからでは、オフラインのエグゼキューターを起動するには遅すぎます。
ハンドラーをデプロイしたら、セルフホスト型セッションを作成し、入力を送信します。作業ディレクトリと、エージェントフィルターが設定されている場合はその条件を、ハンドラーの設定に合わせてください。期限内にエグゼキューターが接続すれば、元の送信内容の処理が続行されます。
環境の稼働維持または停止
再利用できるようターン間もコンピューティングリソースを稼働させておくか、ターン終了後に猶予期間を設けてから停止します。新たに届く処理と停止処理が競合しないように調整してください。接続が要求されたり、実行が開始されたりした場合は、予定していた停止をキャンセルします。コンピューティングリソースを停止する前に、状態を再確認してください。
アイドルイベントだけでは、安全に停止できるとは判断できません。接続リクエストが解消された時点で、待機中の入力のターンが始まる前に届くことがあるためです。アプリケーション側で新たに届く処理と停止処理の調整ができない場合は、環境を稼働させたままにしてください。
切断後の再接続
接続イベントは状態を通知します。agent.session.environment.connected と agent.session.environment.disconnected を使って接続を監視します。セットアップ時には、agent.session.environment.pending または agent.session.environment.failed が送出されることもあります。これらのイベントは、コンピューティングリソースを要求するものではありません。起動のトリガーには environment_connection の必須アクションを使用し、プロバイダーの正常性は別途確認してください。
ターンの途中で接続が切れると、ターン自体は完了してもツールが失敗することがあります。ツールの結果とエージェントの最終応答を確認してください。切断されても、Webhook による再接続の要求や、強制終了されたコマンドの再起動が自動で行われることはありません。後続の入力によって再接続が要求されることはあります。
API は、入力時に必要な接続を最大 5 分間待機します。この待機時間に合わせて、クライアントとプロキシのタイムアウトを設定してください。待機時間を超えると、送信は失敗します。最初の入力は非同期で失敗し、セッションが failed 状態になることがあります。
API は、プロセスのクラッシュ後に保留中の入力が復旧することを保証しません。再試行する前に、リクエストまたはセッションの結果を確認してください。元のリクエストが待機中の間は再送信しないでください。遅れて接続が確立されても、タイムアウトした入力が再実行されることはありません。
環境 ID を再利用しても、置き換え先のコンピューティングリソースでファイルが復元されるわけではありません。ファイルを保持するには、プロバイダーのストレージやスナップショットを使用してください。
クリーンアップ
新しい入力の受け付けを停止します。コンピューティングリソースを稼働させたまま残さないよう、すでに進行中の起動処理とクリーンアップを調整してください。
セッションの削除と、プロバイダーのコンピューティングリソースの停止は、別々に行ってください。セッションを削除しても、その環境は停止せず、削除の Webhook も送出されません。