# Lambda MicroVM を OpenAI Agents API のサンドボックスとして使用する
<a name="microvms-integrations-openai-agents-api"></a>

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 セルフホスト型サンドボックスの [リファレンスの例](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) を参照してください。

## 仕組み
<a name="microvms-integrations-openai-agents-api-how-it-works"></a>

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

1. アプリケーションはセルフホストセッションを作成し、Agents API に入力を送信します。

1. セッションにエグゼキュータが必要な場合、OpenAI は `environment_connection` アクションを含む `agent.session.action_required` webhook をアカウントの Amazon API Gateway エンドポイントに送信します。

1. ランチャー Lambda 関数は、webhook 署名を検証し、現在のセッションを取得し、ハンドラーがそれを所有していることを確認します。

1. ランチャーは、イメージ、実行ロール、ネットワークコネクタ、およびセッションの接続値を保持する `runHookPayload` を指定して `RunMicrovm` を呼び出します。

1. MicroVM の `/run` フックは、IAM 実行ロールを使用して AWS Secrets Manager からエグゼキュータキーを取得し、Codex を起動します。

1. エグゼキュータは、 `https://api.openai.com` で OpenAI に登録します。次に、`wss://codex-cloud-environments.chatgpt.com` への安全な WebSocket 接続を開き、ツールコマンドを受信して結果を返します。

1. アプリケーションは、MicroVM の認証済み HTTPS エンドポイントを介して入力ファイルをアップロードし、出力ファイルをダウンロードできます。セッションイベントストリームに従い、ターン間で MicroVM を一時停止できます。

1. 最後のターンが終了した後、アプリケーションは MicroVM を終了させます。

![AWS Lambda MicroVM 上の Agents API サンドボックスの webhook 管理プロビジョニング](https://docs.aws.amazon.com/ja_jp/lambda/latest/dg/images/microvms-openai-agents-webhook-architecture.png)


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

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

## 主要プロパティ
<a name="microvms-integrations-openai-agents-api-properties"></a>


| プロパティ | Benefit | 
| --- | --- | 
| Firecracker の分離 | 各セッションの MicroVM に対するハードウェア仮想化境界 | 
| スナップショットベースの起動 | 各 MicroVM は、準備済みイメージのスナップショットから起動 | 
| 実行ロールによる IAM | /run フックは MicroVM の実行ロールを使用してエグゼキュータキーを読み取ります。キーはイメージに保存されません。 | 
| ステートフル期間 | 各 MicroVM は、停止時間を含めて最大 8 時間実行できます。 | 
| ターン間の一時停止と再開 | メモリとディスクの状態は保持されるため、フォローアップターンは同じ環境で続行されます。 | 
| 使用量ベースのコンピューティング | VMs を実行すると、コンピューティング料金が発生します。一時停止するとコンピューティング料金が停止します。スナップショットストレージと読み取り/書き込みは個別に請求されます。 | 

## 前提条件
<a name="microvms-integrations-openai-agents-api-prereqs"></a>
+ Lambda MicroVM へのアクセス権を持つ AWS アカウント、`lambda-microvms` を含む AWS CLI バージョン、およびイメージのビルドと MicroVMs の実行に必要なアクセス許可。Amazon Simple Storage Service (Amazon S3) アーティファクトバケットと AWS Identity and Access Management (IAM) イメージビルドロールを作成するには、[最初の Lambda MicroVM を作成する](microvms-getting-started.md) を参照してください。
+ セッションを作成して入力を送信するための OpenAI アプリケーションキー (`OPENAI_API_KEY`)。
+ セッションと同じ組織、プロジェクト、およびユーザーまたはサービスアカウントを持つ別の OpenAI エグゼキュータキー (`OPENAI_EXECUTOR_API_KEY`)。`codex/agents-api/executor` として Secrets Manager に保存します。`/run` フックはこれを `CODEX_API_KEY` として Codex に渡します。
+ エグゼキュータキーシークレットのみを読み取ることができる MicroVM 実行ロール。シークレットがカスタマーマネージド AWS Key Management Service (AWS AWS KMS) キーを使用している場合は、復号アクセス許可を追加します。「[セキュリティおよびアクセス許可](microvms-security.md)」を参照してください。

## MicroVM イメージの準備
<a name="microvms-integrations-openai-agents-api-image"></a>

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


| フック | 動作 | 
| --- | --- | 
| /aws/lambda-microvms/runtime/v1/ready | サーバーが Lambda によるスナップショット作成の準備ができたら、HTTP 200 を返します。エグゼキュータは切断されたままになります。 | 
| /aws/lambda-microvms/runtime/v1/run | セッション接続値とシークレット ARN を読み取り、エグゼキュータキーを取得し、エグゼキュータを起動します。 | 
| /aws/lambda-microvms/runtime/v1/validate | オプション。Codex が実行され、ワークスペースが書き込み可能であることを確認します。 | 
| /aws/lambda-microvms/runtime/v1/suspend | 一時停止/再開に必要です。エグゼキュータを停止し、 AWS が VM のスナップショットを作成する前に書き込みをフラッシュします。 | 
| /aws/lambda-microvms/runtime/v1/resume | 一時停止/再開に必要です。キーを再度取得し、同じ環境のエグゼキュータを再起動します。 | 
| /aws/lambda-microvms/runtime/v1/terminate | オプション。エグゼキュータを停止し、終了前に書き込みをフラッシュします。 | 

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

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


| 値 | 目的 | 
| --- | --- | 
| session.environment.id | エグゼキュータが接続する環境を識別 | 
| session.environment.remote\_url | エグゼキュータの OpenAI 接続 URL を提供 | 
| エグゼキュータのキーシークレット ARN | MicroVM の実行ロールを使用して、フックがキーを取得できるようにします | 

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

## MicroVMs の起動
<a name="microvms-integrations-openai-agents-api-launching"></a>

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

### アプリケーションマネージドプロビジョニング
<a name="microvms-integrations-openai-agents-api-launching-application"></a>

1. 作業ディレクトリがイメージと一致するセルフホストセッションを作成し、そのイベントストリームを開きます。

1. イメージ ARN とバージョン、実行ロール、ネットワークコネクタ、および `runHookPayload` を使用して `RunMicrovm` を呼び出します。返された `microvmId` をセッション ID と一緒に保存します。

1. `agent.session.environment.connected` を待ってから入力を送信し、ターン結果に従います。

1. [ターンの終了](#microvms-integrations-openai-agents-api-ending-turn) の説明に従って、出力ファイルを取得してターンを終了します。

### Webhook マネージドプロビジョニング
<a name="microvms-integrations-openai-agents-api-launching-webhook"></a>

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

1. ランチャーを呼び出す `POST /webhook` ルートを Amazon API Gateway にデプロイします。ランチャーに、認証情報の読み取り、選択したイメージからの MicroVM の検査、起動、再開、終了、MicroVM 実行ロールの引き渡し、および設定されたネットワークコネクタの使用に関するアクセス許可を付与します。

1. `agent.session.action_required` と `agent.session.failed` のエンドポイントを登録します。ランチャーのアプリケーションキーを使用して、エンドポイントの署名シークレットを Secrets Manager に保存します。

1. セッションにアクセスするか、コンピューティングを起動する前に、webhook の署名を raw リクエスト本文と照合して検証します。次に、現在のセッションを取得し、専用の保存済みエージェントを照合するなどして、ハンドラーがセッションを所有していることを確認します。

1. `environment_connection` がまだ保留中の場合は、`GetMicrovm` を使用して記録された MicroVM を検査します。中断している場合は、`ResumeMicrovm` で再開します。VM が記録されていない場合にのみ `RunMicrovm` を呼び出し、その ID を保存します。保存に失敗した場合は、起動した VM を終了します。エグゼキュータが接続タイムアウト前に接続した場合、待機中の入力は再送信されずに続行されます。

1. `agent.session.failed` イベントの場合、現在のセッションを取得し、ステータスがまだ失敗している場合にのみ、記録された MicroVM を終了します。削除されたセッション、解決済みのアクション、および別のハンドラーが所有するセッションは無視します。

[リファレンスの例](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws) では、MicroVM ID をセッションメタデータに保存します。同時 webhook 配信では、その ID が保存される前に追加の VM を起動できます。本番環境で使用する前に、同じセッションの同時起動を防ぎ、webhook イベントの重複を排除してください。

## ターンの終了
<a name="microvms-integrations-openai-agents-api-ending-turn"></a>

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

![1 つの Agents API ターンの MicroVM ライフサイクル](https://docs.aws.amazon.com/ja_jp/lambda/latest/dg/images/microvms-openai-agents-turn-lifecycle.png)


図 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 の有効期間を制限するには、起動時に次の設定を行います。


| 設定 | ガイダンス | 
| --- | --- | 
| maximumDurationInSeconds | 15 分間のテストでは 900 など、ワークロードの上限を設定します。この制限は、作業の進行中にも適用されます。 | 
| maxIdleDurationSeconds | 予想されるワークロードをカバーします。Lambda はインバウンドトラフィックを測定するため、エグゼキュータのアウトバウンド接続はこのタイマーをリセットしません。 | 
| suspendedDurationSeconds / autoResumeEnabled | 中断された MicroVM を再開しないシングルターンパターンには、0 / false を使用します。 | 

ライフタイムコントロールとアイドルコントロールについては、 [MicroVM の実行と使用](microvms-launching.md) を参照してください。

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

## ターン間の中断と再開
<a name="microvms-integrations-openai-agents-api-suspend-resume"></a>

ターン間でメモリとディスクの状態を保持するには、メインエージェントのターンが完了し、すべてのツールとサブエージェントが終了した後に MicroVM を一時停止します。次にセッションにエグゼキュータが必要な場合は、同じ MicroVM を再開します。
+ ゼロ以外の `suspendedDurationSeconds` を設定します。MicroVM の停止中は、スナップショットストレージ料金が適用されます。
+ 書き込みをフラッシュして接続を閉じる `/suspend` フックと、認証情報を更新してエグゼキュータを再接続する `/resume` フックを有効にします。
+ アプリケーション管理パスは、次の入力を送信する前に VM を再開します。Webhook 管理パスでは、入力を送信すると VM を再開する接続リクエストがトリガーされます。エグゼキュータが再接続すると、ターンが続行されます。

**注記**  
`maximumDurationInSeconds` は、実行時間と停止時間の合計を 8 時間に制限します。オンデマンドで再開するには、`ResumeMicrovm` を呼び出します。自動再開には MicroVM へのインバウンドトラフィックが必要です。Agents API への入力だけでは再開されません。

## ネットワーク
<a name="microvms-integrations-openai-agents-api-networking"></a>

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

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

## モニタリング
<a name="microvms-integrations-openai-agents-api-monitoring"></a>

いずれかの例を実行し、`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 ボディをログに含めないようにします。

## トラブルシューティング
<a name="microvms-integrations-openai-agents-api-troubleshooting"></a>


| 症状 | チェック対象 | 
| --- | --- | 
| Webhook 署名が拒否されました | エンドポイントの署名シークレットを使用して、変更されていないリクエスト本文を検証します。 | 
| MicroVM が起動しない | Webhook サブスクリプション、セッション所有権フィルター、保留中の environment\_connection アクション、およびランチャーの IAM アクセス許可を確認します。 | 
| イメージビルドが失敗する | Amazon S3 アーティファクト、イメージビルドロール、および /ready フックレスポンスを確認します。 | 
| /run が失敗またはタイムアウトする | シークレットアクセスとエグゼキュータの起動を確認します。ターンの後ではなく、プロセスの開始後に返します。 | 
| エグゼキュータが接続できない | 環境 ID、リモート URL、キーの所有権、アウトバウンドネットワークアクセスを確認します。 | 
| MicroVM がターン中に停止する | 最大有効期間とアイドルポリシーを確認します。アウトバウンドのエグゼキュータトラフィックは、インバウンドアクティビティとしてカウントされません。 | 

接続の失敗については、 `agent.session.environment.failed` イベントとエグゼキュータログを確認します。共有エグゼキュータ契約については、 [セルフホスト型サンドボックス](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws) を参照してください。

## 関連リソース
<a name="microvms-integrations-openai-agents-api-related"></a>
+ [AWS Lambda MicroVMs](lambda-microvms-guide.md)
+ [MicroVM の実行と使用](microvms-launching.md)
+ [セキュリティおよびアクセス許可](microvms-security.md)
+ [RunMicrovm API リファレンス](https://docs.aws.amazon.com/cli/latest/reference/lambda-microvms/run-microvm.html)
+ [OpenAI Agents API セルフホスト型サンドボックス](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)
+ [OpenAI Agents API AWS ガイド](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)