本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 Lambda MicroVMs做為 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 小時，包括執行中和暫停時間。在最後輪換後終止它，或在輪換之間暫停它。您建立一個可重複使用的映像，然後從應用程式或 Webhook 啟動器啟動 MicroVM。這兩種方法都使用相同的映像和登入資料。如需詳細資訊，請參閱 Lambda MicroVMs 上 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. 啟動器`RunMicrovm`會使用映像、執行角色、網路連接器和`runHookPayload`帶有工作階段連線值的 來呼叫 。

1. MicroVM 的`/run`勾點使用其 IAM 執行角色從 AWS Secrets Manager 擷取執行器金鑰並啟動 Codex。

1. 執行器會在 向 OpenAI 註冊`https://api.openai.com`。然後，它會開啟 的安全 WebSocket 連線`wss://codex-cloud-environments.chatgpt.com`，以接收工具命令並傳回結果。

1. 您的應用程式可以透過 MicroVM 已驗證的 HTTPS 端點上傳輸入檔案和下載輸出檔案。它遵循工作階段事件串流，並可輪流暫停 MicroVM。

1. 在最後輪換之後，您的應用程式會終止 MicroVM。

![Lambda MicroVMs 上 AWS Agents API 沙盒的 Webhook 受管佈建](https://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/microvms-openai-agents-webhook-architecture.png)


圖 1。 AWS Lambda MicroVMs 上 Agents API 沙盒的 Webhook 受管佈建。

將應用程式金鑰和 Webhook 簽署秘密保留在 MicroVM 之外。啟動器只會傳遞執行器金鑰秘密 ARN；VM 會使用其執行角色擷取金鑰。

## 金鑰屬性
<a name="microvms-integrations-openai-agents-api-properties"></a>


| 屬性 | 優勢 | 
| --- | --- | 
| Firecracker 隔離 | 每個工作階段 MicroVM 的硬體虛擬化界限 | 
| 快照型啟動 | 每個 MicroVM 都會從預備映像的快照啟動 | 
| 透過執行角色的 IAM | /run 勾點會使用 MicroVM 的執行角色讀取執行器金鑰；金鑰不會存放在映像中 | 
| 狀態持續時間 | 每個 MicroVM 最多可以執行 8 小時，包括暫停時間 | 
| 在轉彎之間暫停和繼續 | 會保留記憶體和磁碟狀態，以便在相同的環境中繼續追蹤 | 
| 以用量為基礎的運算 | 執行 VMs 會產生運算費用。暫停會停止運算費用；快照儲存和讀取/寫入會分別計費。 | 

## 先決條件
<a name="microvms-integrations-openai-agents-api-prereqs"></a>
+ 具有 Lambda MicroVMs AWS 存取權 AWS 的帳戶、包含 的 CLI 版本`lambda-microvms`，以及建置映像和執行 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`)。將它存放在 Secrets Manager 中，例如 `codex/agents-api/executor`。`/run` 掛鉤會以 的形式將其傳遞至 Codex`CODEX_API_KEY`。
+ 可唯讀 executor-key 秘密的 MicroVM 執行角色。如果秘密使用客戶受管 AWS 金鑰管理服務 (AWS AWS KMS) 金鑰，請新增解密許可。請參閱 [安全與許可](microvms-security.md)。

## 準備 MicroVM 映像
<a name="microvms-integrations-openai-agents-api-image"></a>

建置包含 Codex CLI、您的工具相依性、工作目錄，例如 `/workspace`和生命週期掛鉤的 HTTP 伺服器的影像。


| 勾點 | Behavior (行為) | 
| --- | --- | 
| /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`映像。在映像組態中啟用選取的勾點，並設定勾點連接埠以符合您的伺服器。讓工作階段 IDs、登入資料和即時執行器連線遠離映像快照。如需建置和掛接組態，請參閱[MicroVM 映像](microvms-images.md)。

在啟動時，您的應用程式或啟動器會將下列值序列化為 中的 JSON`runHookPayload`：


| Value | 用途 | 
| --- | --- | 
| session.environment.id | 識別執行器連線到的環境 | 
| session.environment.remote\_url | 提供執行器的 OpenAI 連線 URL | 
| Executor-key 秘密 ARN | 讓勾點使用 MicroVM 的執行角色擷取金鑰 | 

執行器程序啟動後從`/run`勾點傳回，無需等待轉彎完成，以避免勾點逾時。

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

您可以從應用程式或 Webhook 啟動器啟動 MicroVMs。在這兩種情況下，請保持工作階段事件串流開啟，直到輪換完成。

### 應用程式受管佈建
<a name="microvms-integrations-openai-agents-api-launching-application"></a>

1. 建立工作目錄符合映像的自我託管工作階段，然後開啟其事件串流。

1. `RunMicrovm` 使用映像 ARN 和版本、執行角色、網路連接器和 呼叫 `runHookPayload`。將傳回的 與工作階段 ID `microvmId`一起儲存。

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. 在叫用啟動器的 Amazon API Gateway 中部署`POST /webhook`路由。授予啟動器許可，以讀取其登入資料、檢查、啟動、繼續和終止所選映像中的 MicroVMs、傳遞 MicroVM 執行角色，並使用設定的網路連接器。

1. 註冊 `agent.session.action_required`和 的端點`agent.session.failed`。使用啟動器的應用程式金鑰，將端點的簽署秘密存放在 Secrets Manager 中。

1. 在存取工作階段或啟動運算之前，先對原始請求內文驗證 Webhook 簽章。然後擷取目前的工作階段，並確認處理常式擁有該工作階段，例如比對專用的已儲存客服人員。

1. 如果 `environment_connection` 仍在擱置中，請使用 檢查記錄的 MicroVM`GetMicrovm`。`ResumeMicrovm` 如果暫停，則繼續使用 。`RunMicrovm` 只有在未記錄 VM 時呼叫 ，然後儲存其 ID。如果儲存失敗，請終止您啟動的 VM。如果執行器在連線逾時之前連線，等待輸入會繼續進行，而不會重新提交。

1. 對於`agent.session.failed`事件，擷取目前的工作階段，並只在其狀態仍然失敗時終止其記錄的 MicroVM。忽略已刪除的工作階段、已解決的動作，以及另一個處理常式擁有的工作階段。

[參考範例](https://github.com/openai/openai-cookbook/tree/main/examples/agents_api/sandboxes/aws)會將 MicroVM ID 儲存在工作階段中繼資料中。並行 Webhook 交付可以在儲存 ID 之前啟動額外的 VMs。生產使用之前，請防止同時啟動相同工作階段和刪除重複的 Webhook 事件。

## 結束轉彎
<a name="microvms-integrations-openai-agents-api-ending-turn"></a>

圖 2 顯示單一回合的 MicroVM 生命週期，以及後續回合的選用暫停和繼續路徑。

![一個 Agents API 輪換的 MicroVM 生命週期](https://docs.aws.amazon.com/zh_tw/lambda/latest/dg/images/microvms-openai-agents-turn-lifecycle.png)


圖 2. 一個 Agents API 轉彎的 MicroVM 生命週期。 `RunMicrovm`啟動 MicroVM、`/run`勾點啟動執行器、環境連接、轉彎執行和轉彎結束。在單轉路徑中，您可以擷取檔案並呼叫 `TerminateMicrovm`。在多轉路徑中，MicroVM 會在轉彎後暫停，並在下一個連線請求上繼續。

在工作階段串流上，等待主要代理`agent.session.turn.cancelled`程式的 `agent.session.turn.failed`、 `agent.session.turn.completed`或 ，其中 `event.turn.subagent_id`為 `null`。子代理程式共用 MicroVM，因此其終端事件不會觸發清除。擷取您需要的檔案。在最後輪換之後，呼叫 `TerminateMicrovm` 並確認 VM 達到 `TERMINATED`。後續輪換時，請保持執行或暫停。如果您的應用程式發生錯誤，請執行清除。

將結果轉換為串流事件，而不是 Webhook 訂閱。`agent.session.failed` Webhook 涵蓋工作階段失敗，但並非每個失敗輪換。因此，請勿`agent.session.idle`單獨終止 ，因為它可能會在等待輸入開始之前到達。

若要在未執行清除時限制 MicroVM 的生命週期，請在啟動時設定下列設定：


| 設定 | 指引 | 
| --- | --- | 
| maximumDurationInSeconds | 設定工作負載的上限，例如 900 的 15 分鐘測試。即使工作正在進行，此限制也適用。 | 
| maxIdleDurationSeconds | 涵蓋預期的工作負載。Lambda 會測量傳入流量，因此執行器的傳出連線不會重設此計時器。 | 
| suspendedDurationSeconds / autoResumeEnabled | 單轉模式使用 0/false，不會繼續暫停MicroVMs。 | 

如需生命週期和閒置控制，請參閱 [執行和使用 MicroVMs](microvms-launching.md)。

分別刪除工作階段。刪除工作階段不會停止 MicroVM 或傳送刪除 Webhook。保留映像和 executor-key 秘密以供重複使用。如需處理後續輪換，請參閱[沙盒生命週期](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。

**啟動器日誌。**在 CloudWatch Logs 中檢閱啟動器 Lambda 函數的日誌：

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

**執行 MicroVMs。**`MICROVM_IMAGE_ARN` 設定為映像 ARN、使用部署的區域 AWS ，並列出映像MicroVMs：

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

將工作階段和 MicroVM IDs 記錄在一起，以便您可以追蹤端對端的執行。將登入資料和原始 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)
+ [執行和使用 MicroVMs](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)
+ [AWS 指南上的 OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/environments/providers/aws)