使用 AWS Lambda MicroVMs 在你的 AWS 帳戶中執行智慧體的工具。OpenAI 負責執行智慧體的任務執行框架,每個 MicroVM 則執行 codex exec-server,並存放該工作階段的工作區檔案。
範例預設每個回合使用一個 MicroVM。先準備可重複使用的映像檔,再透過應用程式或 OpenAI webhook 啟動 MicroVM。兩種方式使用相同的映像檔和憑證。每個工作階段只應由其中一方負責佈建。
試用 AWS Cookbook 範例,瞭解如何透過應用程式或 webhook 管理沙盒。
運作方式
採用 webhook 時,應用程式會建立自託管工作階段並傳送輸入。當工作階段需要執行器時,OpenAI 會傳送 agent.session.action_required 事件,其中包含 environment_connection 動作。API Gateway 會將 webhook 轉送至負責啟動 MicroVM 的 Lambda 函式。這個啟動函式會驗證簽章、檢查目前的工作階段,然後啟動或恢復 MicroVM。
MicroVM 的 /run 掛鉤會從 Secrets Manager 取得環境金鑰並啟動執行器。執行器會主動連線至 OpenAI,工作階段隨即開始處理等候中的輸入。應用程式會持續接收工作階段的事件串流、下載輸出檔案,並在最後一個回合結束後終止 MicroVM。

開始之前
請準備下列資源:
- AWS 存取權: 你需要可存取 Lambda MicroVMs 的帳戶、包含
lambda-microvms的 AWS CLI,以及建置映像檔和執行 MicroVM 的權限。請依照 AWS 入門指南建立用於存放成品的 S3 儲存貯體,以及用於建置映像檔的 IAM 角色。 - 應用程式金鑰: 使用
OPENAI_API_KEY建立工作階段並提交輸入。 - 環境金鑰(
OPENAI_EXECUTOR_API_KEY): 另外建立一把環境金鑰,確保它與應用程式金鑰屬於同一個組織和專案,且擁有者是同一位使用者或同一個服務帳戶。將金鑰值存放在 Secrets Manager,例如存入名為codex/agents-api/executor的秘密。/run掛鉤會透過CODEX_API_KEY將這把金鑰傳給 Codex。 - MicroVM 執行角色: 僅授予此角色讀取環境金鑰所屬秘密的權限。如果使用客戶管理的 KMS 金鑰,請加上解密權限。如需角色設定方式,請參閱 AWS 的安全性與權限文件。
請將應用程式金鑰和 webhook 簽章密鑰存放在 MicroVM 外部。如果使用 webhook 啟動函式,請將這些憑證存放在該函式專用的 Secrets Manager 秘密中。虛擬機器只會收到存放環境金鑰的秘密的 ARN。
準備可重複使用的映像檔
建置映像檔時,請納入 Codex CLI、工具所需的相依套件、工作目錄(例如 /workspace),以及用於處理 AWS 生命週期掛鉤的 HTTP 伺服器。
範例在 /aws/lambda-microvms/runtime/v1 路徑下實作了下列掛鉤:
| 掛鉤 | 行為 |
|---|---|
/ready |
當伺服器準備就緒,可供 AWS 建立快照時,傳回 HTTP 200。讓執行器維持未連線狀態。 |
/validate |
檢查 Codex 能否執行,以及工作區是否可寫入。 |
/run |
讀取工作階段的連線參數和秘密的 ARN,取得環境金鑰,然後啟動執行器。 |
/suspend |
在 AWS 為虛擬機器建立快照前停止執行器。 |
/resume |
重新載入環境金鑰,並使用先前儲存的連線參數重新啟動執行器。 |
/terminate |
在虛擬機器終止前停止執行器。 |
將 Dockerfile 和掛鉤伺服器打包成 S3 成品,然後建置帶有版本號的映像檔,例如 codex-executor。在映像檔設定中啟用全部六個掛鉤,並將掛鉤連接埠設為伺服器使用的連接埠。請勿將工作階段 ID、憑證或執行器的作用中連線納入映像檔快照。如需建置和掛鉤設定方式,請參閱 AWS 的 MicroVM 映像檔文件。
啟動時,應用程式或啟動函式會將下列值序列化為 JSON 字串,放入 runHookPayload:
| 值 | 用途 |
|---|---|
session.environment.id |
識別執行器要連線的環境。 |
session.environment.remote_url |
提供執行器連線至 OpenAI 所用的 URL。 |
| 存放環境金鑰的秘密的 ARN | 讓掛鉤使用 MicroVM 的執行角色取得金鑰。 |
/run 掛鉤會解析 AWS 請求主體中的這個字串、取得金鑰、在子程序的環境中設定 CODEX_API_KEY,並啟動執行器。程序一啟動,掛鉤就應傳回回應。如果等到智慧體的回合結束才回應,掛鉤可能會逾時。
請允許執行器建立所需的對外連線並存取 Secrets Manager。如果需要存取私有資源或網路設有限制,請設定 AWS 對外連線用的連接器。若要下載檔案,請在伺服器上新增路由,並使用範圍限定於該伺服器連接埠的 AWS 驗證權杖,透過 MicroVM 的 HTTP 端點呼叫此路由。
啟動 MicroVM
選擇由應用程式或 webhook 管理佈建。無論使用哪一種方式,從建立連線、處理輸入到回合結束,都要保持工作階段的事件串流開啟。
由應用程式管理佈建
- 建立自託管工作階段,將工作目錄設為與映像檔一致,然後開啟該工作階段的事件串流。
- 呼叫 AWS RunMicrovm,傳入映像檔的 ARN 和版本、執行角色、網路連接器及
runHookPayload。將傳回的microvmId與工作階段 ID 一起儲存。 - 等候
agent.session.environment.connected事件,接著傳送輸入,並透過串流追蹤該回合的結果。 - 擷取輸出檔案並停止 MicroVM。
由 webhook 管理佈建
使用 API Gateway HTTP API 和 Lambda 啟動函式。應用程式負責建立工作階段、開啟事件串流並提交輸入。當工作階段需要連線時,webhook 會觸發啟動函式,啟動或恢復運算資源。
- 部署
POST /webhook路由來叫用啟動函式。針對選定的映像檔,授予啟動函式lambda:RunMicrovm、lambda:GetMicrovm、lambda:ResumeMicrovm和lambda:TerminateMicrovm權限。啟動函式也需要權限才能讀取自己的憑證、傳遞 MicroVM 執行角色,以及使用已設定的網路連接器。 - 註冊端點以接收
agent.session.action_required和agent.session.failed事件。將端點的簽章密鑰與啟動函式的應用程式金鑰一起儲存。 - 在存取工作階段或啟動運算資源之前,先使用原始請求主體驗證 webhook 簽章。取得目前的工作階段,並確認它由此處理常式負責,例如檢查工作階段使用的是否為預先儲存的專用智慧體。
- 如果
environment_connection仍待處理,請使用GetMicrovm檢查已記錄的虛擬機器。若狀態為SUSPENDED,請使用ResumeMicrovm恢復虛擬機器。若狀態為PENDING或RUNNING,請等候虛擬機器建立連線。只有在沒有虛擬機器記錄時,才呼叫RunMicrovm。將虛擬機器 ID 儲存至工作階段中繼資料。如果儲存失敗,請終止剛啟動的虛擬機器。 - 如果工作階段的狀態仍為
failed,請終止該工作階段記錄的 MicroVM。略過已刪除的工作階段、已處理完畢的動作,以及由其他處理常式負責的事件。
如果執行器在連線逾時前成功連線,工作階段就會繼續處理等候中的輸入,無須重新提交。
在原型中,可以同步啟動 MicroVM,並將其 ID 存放在工作階段中繼資料中。投入正式環境前,請建立可持久記錄啟動責任歸屬的機制,確保啟動操作具備冪等性,並將佈建工作加入佇列。單靠中繼資料無法避免重複啟動,啟動時間過長也可能超過 webhook 的回應期限。
停止 MicroVM
在工作階段串流中,等候主要智慧體的 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled 事件(event.turn.subagent_id 為 null)。子代理程式共用同一個 MicroVM,因此子代理程式的回合結束事件不得觸發清理。最後一個回合結束後,請擷取所需檔案、呼叫 TerminateMicrovm,並確認虛擬機器已進入 TERMINATED 狀態。應用程式發生錯誤時也要執行清理。
回合結果會透過事件串流傳送,無法透過 webhook 訂閱。agent.session.failed webhook 會處理工作階段失敗的情況,但無法涵蓋所有失敗的回合。請勿僅因收到 agent.session.idle 就終止 MicroVM,因為這個事件可能在工作階段開始處理等候中的輸入之前送達。
請設定下列 AWS 限制,以便在漏執行清理時限制資源使用時間:
| 設定 | 建議 |
|---|---|
maximumDurationInSeconds |
設定工作負載的時間上限,例如可將上限設為 900,供 15 分鐘的測試使用。達到上限時,進行中的工作可能會中斷。 |
maxIdleDurationSeconds |
設定足以涵蓋預期工作負載的閒置時間。AWS 以傳入流量判斷活動狀態,執行器的對外連線不會重設此計時器。 |
suspendedDurationSeconds / autoResumeEnabled |
範例預設使用 0 / false。另一組設定值 300 / false 適用於加上 --suspend-resume 的情況。 |
如需存留時間和閒置時間的控制方式,請參閱 AWS 的執行與使用 MicroVM 文件。
請另行刪除工作階段。刪除工作階段不會終止 AWS 運算資源,也不會觸發刪除事件的 webhook。請保留映像檔和存放環境金鑰的秘密,以供重複使用。如有後續回合,請參閱沙盒生命週期,協調運算資源的重複使用或替換,並確保檔案能持續保留。
在回合之間暫停與恢復 MicroVM
使用 AWS 的暫停與恢復功能,在回合之間保留記憶體和磁碟內容。請將 suspendedDurationSeconds 設為非零值。暫停期間會產生快照儲存費用。maximumDurationInSeconds 所限制的時間包含執行和暫停時間,兩者合計最長為八小時。
執行任一範例時加上 --suspend-resume,即可寫入 /workspace/hello.txt、暫停虛擬機器,再於第二個回合讀取該檔案。由應用程式管理的範例會直接恢復虛擬機器。由 webhook 管理的範例則會再傳送一次輸入,觸發啟動函式恢復先前記錄的虛擬機器。兩個範例都會驗證檔案內容,並在最後一個回合結束後執行清理。
/suspend 掛鉤會停止執行器,/resume 掛鉤則會重新載入執行器的金鑰並重新建立連線。請等到工具和子代理程式都完成工作後,再暫停虛擬機器。AWS 的自動恢復功能需要虛擬機器收到傳入流量才會生效,單靠 Agents API 輸入無法喚醒虛擬機器。
驗證與監控
使用提示詞要求智慧體在 /workspace 中建立一個小檔案,以測試整合。確認執行器成功連線、回合順利完成、下載的檔案包含預期結果,且 MicroVM 在清理後進入 TERMINATED 狀態。僅確認 MicroVM 成功啟動,不足以驗證整合是否正常運作。
在 AWS 範例目錄中,使用 jq 從已儲存的建置狀態讀取映像檔 ARN 和區域。如果透過 --state 指定了自訂路徑,請相應調整下方路徑。如果已將啟動函式重新命名,請替換日誌群組名稱:
image_state=application_managed/.local/image.json
region=$(jq -r '.region' "$image_state")
image_arn=$(jq -r '.image_arn' "$image_state")
aws logs tail /aws/lambda/codex-agents-api-webhook --since 10m --region "$region"
aws lambda-microvms list-microvms \
--image-identifier "$image_arn" --region "$region" \
--query 'items[].{id:microvmId,state:state}' --output table
將工作階段 ID 和 MicroVM ID 一起寫入日誌,以便追蹤單次執行。請勿在日誌中記錄憑證或 webhook 的原始請求主體。
疑難排解
| 問題 | 檢查項目 |
|---|---|
| Webhook 簽章遭拒 | 使用端點的簽章密鑰,並以未經修改的請求主體驗證簽章。 |
| 未啟動任何 MicroVM | 檢查 webhook 訂閱、用來判斷工作階段歸屬的篩選條件、待處理的 environment_connection 動作,以及啟動函式的 IAM 權限。 |
| 映像檔建置失敗 | 檢查 S3 成品、映像檔建置角色,以及 /ready 掛鉤的回應。 |
/run 失敗或逾時 |
檢查秘密的存取權,以及執行器是否成功啟動。程序一啟動,掛鉤就應傳回回應,不要等到回合結束。 |
| 執行器無法連線 | 檢查環境 ID、遠端 URL、金鑰歸屬,以及對外網路存取權。 |
| 虛擬機器在回合中停止 | 檢查存留時間上限和閒置原則。執行器的對外流量不會計入傳入活動。 |
如果連線失敗,請檢查 agent.session.environment.failed 事件和執行器日誌。如需瞭解各種自託管環境共用的執行器規格,請參閱自託管沙盒。
參考資料
- 生命週期:執行與使用 MicroVM 說明如何啟動、暫停、恢復及終止 MicroVM。
- 安全性:安全性與權限說明 IAM 角色、驗證權杖及存取控制。