エージェントのセッションは、環境の停止後も存続できます。self_hosted 環境で使用するコンピューティングリソースとファイルは、アプリケーションが管理します。
環境の起動
アプリケーションは、セッションを作成した後にコンピューティングリソースを起動できます。プロバイダーの SDK または API でリソースを起動し、セッションの環境 ID と環境キーを使ってエグゼキューターを接続します。
OpenAI Cookbook のアプリケーションでサンドボックスを管理する例を参照してください。
各セッションの環境は、1 つのコンポーネントで管理してください。セッションとプロバイダーのコンピューティングリソースの対応関係を保存します。同じリクエストが繰り返された場合や、複数のリクエストが同時に届いた場合にも、環境が重複して作成されないようにしてください。
Webhook を使ったコンピューティングリソースの起動
入力の処理に環境への接続が必要になるまで、起動を待つこともできます。API は agent.session.action_required を発行して required_action.type: "environment_connection" を通知し、エグゼキューターの接続を待ちます。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 も送信されません。