如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

AWS Lambda MicroVMs

在你的 AWS 帳戶中執行 Agents API 沙盒。

使用 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。

應用程式將輸入傳送至 Agents API。需要連線時,webhook 經由 API Gateway 傳送至 Lambda 啟動函式,再由函式啟動 AWS Lambda MicroVM。啟動函式使用可重複使用的映像檔。虛擬機器從 Secrets Manager 讀取環境金鑰,並主動連線至 OpenAI。應用程式會擷取輸出檔案。

開始之前

請準備下列資源:

  • 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 管理佈建。無論使用哪一種方式,從建立連線、處理輸入到回合結束,都要保持工作階段的事件串流開啟。

由應用程式管理佈建

  1. 建立自託管工作階段,將工作目錄設為與映像檔一致,然後開啟該工作階段的事件串流。
  2. 呼叫 AWS RunMicrovm,傳入映像檔的 ARN 和版本、執行角色、網路連接器及 runHookPayload。將傳回的 microvmId 與工作階段 ID 一起儲存。
  3. 等候 agent.session.environment.connected 事件,接著傳送輸入,並透過串流追蹤該回合的結果。
  4. 擷取輸出檔案並停止 MicroVM。

由 webhook 管理佈建

使用 API Gateway HTTP API 和 Lambda 啟動函式。應用程式負責建立工作階段、開啟事件串流並提交輸入。當工作階段需要連線時,webhook 會觸發啟動函式,啟動或恢復運算資源。

  1. 部署 POST /webhook 路由來叫用啟動函式。針對選定的映像檔,授予啟動函式 lambda:RunMicrovm、lambda:GetMicrovm、lambda:ResumeMicrovm 和 lambda:TerminateMicrovm 權限。啟動函式也需要權限才能讀取自己的憑證、傳遞 MicroVM 執行角色,以及使用已設定的網路連接器。
  2. 註冊端點以接收 agent.session.action_required 和 agent.session.failed 事件。將端點的簽章密鑰與啟動函式的應用程式金鑰一起儲存。
  3. 在存取工作階段或啟動運算資源之前,先使用原始請求主體驗證 webhook 簽章。取得目前的工作階段,並確認它由此處理常式負責,例如檢查工作階段使用的是否為預先儲存的專用智慧體。
  4. 如果 environment_connection 仍待處理,請使用 GetMicrovm 檢查已記錄的虛擬機器。若狀態為 SUSPENDED,請使用 ResumeMicrovm 恢復虛擬機器。若狀態為 PENDING 或 RUNNING,請等候虛擬機器建立連線。只有在沒有虛擬機器記錄時,才呼叫 RunMicrovm。將虛擬機器 ID 儲存至工作階段中繼資料。如果儲存失敗,請終止剛啟動的虛擬機器。
  5. 如果工作階段的狀態仍為 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 事件和執行器日誌。如需瞭解各種自託管環境共用的執行器規格,請參閱自託管沙盒。

參考資料