Lambda MicroVM を OpenAI Agents API のサンドボックスとして使用する

AWS Lambda MicroVMs を OpenAI Agents API で構築されたエージェントのセルフホスト環境として使用し、ワークスペースファイル、ツールの実行、およびネットワークアクセスをユーザーが管理するインフラストラクチャに保持できます。OpenAI はエージェントハーネスを実行し、Lambda MicroVM はタスクを実行します。この例では codex exec-server を実行します。これにより、エージェントのツール呼び出しが実行され、セッションのワークスペースファイルが保持されます。イメージの内容、エグゼキュータが利用可能なネットワークパス、およびその実行ロールのスコープが指定されている AWS リソースを決定します。

各 MicroVM は、イメージのスナップショットから起動する Firecracker 分離環境として実行されます。MicroVM の合計有効期間は、実行時間と一時停止時間を含めて最大 8 時間です。最終ターンの終了後に終了させるか、ターンの合間に一時停止させます。再利用可能なイメージを 1 つ構築し、アプリケーションまたは webhook ランチャーから MicroVM を起動します。どちらのアプローチも、同じ画像と認証情報を使用します。詳細については、Lambda MicroVM 上の OpenAI Agents API セルフホスト型サンドボックスの リファレンスの例 を参照してください。

仕組み

Webhook 管理パスでは、ランチャー Lambda 関数は、セッションが最初にエグゼキュータを必要とするときに MicroVM を起動します。既存の MicroVM を再利用し、中断されている場合は最初に再開します。アプリケーションは、最終ターンの後にそれを終了させます。図 1 にフローを示します。

図 1: AWS Lambda MicroVM 上の Agents API サンドボックスの webhook 管理プロビジョニング

アプリケーションキーと webhook 署名シークレットは MicroVM の外部に保管します。ランチャーはエグゼキュータキーシークレット ARN のみを渡します。VM は実行ロールを使用してキーを取得します。

主要プロパティ

前提条件

MicroVM イメージの準備

Codex CLI、ツールの依存関係、/workspace などの作業ディレクトリ、およびライフサイクルフック用の HTTP サーバーを含むイメージを構築します。

Dockerfile とフックサーバーを Amazon S3 アーティファクトにパッケージ化し、8 GB のベースラインメモリ (4 vCPU ベースライン) で codex-executor イメージを構築します。イメージ設定で選択したフックを有効にし、サーバーに合わせてフックポートを設定します。セッション ID、認証情報、およびライブエグゼキュータ接続をイメージスナップショットに含めないようにします。ビルドとフックの設定については、 MicroVM イメージ を参照してください。

起動時に、アプリケーションまたはランチャーは runHookPayload で次の値を JSON としてシリアル化します。

フックのタイムアウトを避けるため、エグゼキュータプロセスが開始されたら、ターンが終了するのを待たずに /run フックから戻します。

MicroVMs の起動

MicroVMs は、アプリケーションまたは webhook ランチャーから起動できます。いずれの場合も、ターンが終了するまでセッションイベントストリームを開いたままにしてください。

アプリケーションマネージドプロビジョニング

Webhook マネージドプロビジョニング

アプリケーションはセッションを作成し、ストリームを開き、入力を送信します。ランチャーは、webhook が到着したときに残りの処理を行います。

リファレンスの例 では、MicroVM ID をセッションメタデータに保存します。同時 webhook 配信では、その ID が保存される前に追加の VM を起動できます。本番環境で使用する前に、同じセッションの同時起動を防ぎ、webhook イベントの重複を排除してください。

ターンの終了

図 2 は、1 ターンの MicroVM ライフサイクルと、フォローアップターンのオプションの一時停止および再開パスを示しています。

図 2: 1 つの Agents API ターンの MicroVM ライフサイクル。RunMicrovm は MicroVM を起動し、/run フックはエグゼキュータを起動し、環境は接続し、ターンは実行され、ターンは終了します。シングルターンパスでは、ファイルを取得して TerminateMicrovm を呼び出します。マルチターンパスでは、MicroVM はターン後に一時停止し、次の接続リクエストで再開します。

セッションストリームで、メインエージェントの agent.session.turn.completed、agent.session.turn.failed、または agent.session.turn.cancelled を待ちます。ここで、event.turn.subagent_id は null です。サブエージェントは MicroVM を共有するため、ターミナルイベントはクリーンアップをトリガーしません。必要なファイルを取得します。最終ターン後、TerminateMicrovm を呼び出し、VM が TERMINATED に達したことを確認します。フォローアップターンの場合は、実行したままにするか、一時停止します。アプリケーションでエラーが発生した場合は、クリーンアップを実行します。

ターン結果は、webhook サブスクリプションではなくストリームイベントとして届きます。agent.session.failed webhook はセッションの失敗を対象としますが、すべての失敗したターンを対象とするわけではありません。このため、入力待機の開始前に到着する可能性があるため、agent.session.idle 単独で終了しないでください。

クリーンアップが実行されない場合に MicroVM の有効期間を制限するには、起動時に次の設定を行います。

ライフタイムコントロールとアイドルコントロールについては、 MicroVM の実行と使用 を参照してください。

セッションを個別に削除します。セッションを削除しても、MicroVM が停止したり、削除 webhook が送信されたりすることはありません。イメージとエグゼキュータキーのシークレットは、再利用できるように保管します。フォローアップターンの処理については、 サンドボックスのライフサイクル を参照してください。

ターン間の中断と再開

ターン間でメモリとディスクの状態を保持するには、メインエージェントのターンが完了し、すべてのツールとサブエージェントが終了した後に MicroVM を一時停止します。次にセッションにエグゼキュータが必要な場合は、同じ MicroVM を再開します。

ネットワーク

エグゼキュータが必要とする OpenAI へのアウトバウンド接続と、Secrets Manager へのアクセスを許可します。プライベートリソースへのアクセスや独自のネットワーク制限を適用するには、起動時に VPC エグレスコネクタをアタッチします。「出力ネットワークコネクタを操作する」を参照してください。

この例では、サーバーのポートにスコープされた認証トークンを使用して、MicroVM の HTTPS エンドポイントを介したファイルのアップロードとダウンロードをサポートしています。

モニタリング

いずれかの例を実行し、hello.txt のダウンロード、MicroVM が TERMINATED に到達すること、および削除されたセッションが HTTP 404 を返すことを確認します。

Launcher ログ CloudWatch Logs でランチャー Lambda 関数のログを確認します。

aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m

MicroVM の実行 MICROVM_IMAGE_ARN をイメージ ARN に設定し、デプロイの AWS リージョンを使用して、イメージの MicroVM を一覧表示します。

aws lambda-microvms list-microvms \
  --image-identifier "$MICROVM_IMAGE_ARN" \
  --query 'items[].{id:microvmId,state:state}' --output table

セッション ID と MicroVM ID を一緒にログに記録して、エンドツーエンドの実行をトレースできるようにします。認証情報や生の webhook ボディをログに含めないようにします。

トラブルシューティング

接続の失敗については、 agent.session.environment.failed イベントとエグゼキュータログを確認します。共有エグゼキュータ契約については、 セルフホスト型サンドボックス を参照してください。

関連リソース