OpenAI AWS Lambda MicroVMs

使用 AWS Lambda MicroVMs，在自己的 AWS 账户运行智能体工具。OpenAI 运行框架，每个 MicroVM 运行 codex exec-server 并保存会话工作区文件。

示例默认每轮使用一个 MicroVM。先准备可复用镜像，再由应用或 OpenAI webhook 启动；两条路径使用相同镜像和凭证。每个会话只指定一个资源创建负责人。

应用管理与 webhook 管理的完整示例见 AWS Cookbook。

工作方式

Webhook 路径中，应用先创建自托管会话并提交输入。需要执行器时，OpenAI 发送含 environment_connection 动作的 agent.session.action_required。API Gateway 将事件交给启动器 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。
• 执行角色：只允许读取环境密钥秘密。自管 KMS 密钥还需解密权限，见 AWS 安全与权限。

应用密钥和 webhook 签名秘密留在 MicroVM 外。Webhook 启动器在自己的 Secrets Manager 秘密中保存这些凭证；VM 只接收环境密钥秘密的 ARN。

准备可复用镜像

镜像包含 Codex CLI、工具依赖、如 /workspace 的工作目录，以及处理 AWS 生命周期钩子的 HTTP 服务。

示例在 /aws/lambda-microvms/runtime/v1 下实现：

将 Dockerfile 与钩子服务器打包到 S3，构建如 codex-executor 的版本化镜像，启用六个钩子，端口与服务器一致。镜像快照不包含会话 ID、凭证和活动执行器连接。构建与钩子配置见 MicroVM镜像。

启动时，应用或启动器将以下值序列化成 JSON，放入 runHookPayload：

/run 从 AWS 请求体解析该字符串，取密钥，在子进程环境设置 CODEX_API_KEY，再启动执行器。进程启动后就返回；等待整轮结束可能导致钩子超时。

允许执行器必需的出站连接及 Secrets Manager 访问。私有资源或网络限制使用 AWS 出站连接器。下载文件时，可在服务器增加路由，通过 MicroVM HTTP 端点调用，并使用限定服务器端口的 AWS 认证令牌。

启动 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 权限，以及读取凭证、传递执行角色和使用网络连接器的权限。
2. 为 agent.session.action_required 和 agent.session.failed 注册端点，签名秘密与启动器应用密钥一起保存。
3. 使用原始请求体验证签名，再读取会话或启动资源。确认处理器拥有该会话，例如匹配专用已保存智能体。
4. environment_connection 仍待处理时，用 GetMicrovm 检查记录的VM。SUSPENDED 时调用 ResumeMicrovm，PENDING 或 RUNNING 时等待连接。仅在没有VM记录时调用 RunMicrovm；将ID写入会话元数据，保存失败就终止刚创建的VM。
5. 会话仍为 failed 时终止其VM；忽略已删除会话、已解决动作及其他处理器负责的事件。

执行器在连接超时前连上，等待输入会继续，无需重新提交。

原型可以同步启动，并将VM ID存于会话元数据。生产使用前要加入持久化启动归属、幂等控制及任务队列。仅靠元数据不能防止重复启动，慢启动也可能超过 webhook 响应截止。

停止 MicroVM

等待主智能体的 agent.session.turn.completed、agent.session.turn.failed 或 agent.session.turn.cancelled，其 event.turn.subagent_id 为 null。子智能体共享VM，其终结事件不能触发清理。最后轮次后先取文件，再调用 TerminateMicrovm，验证达到 TERMINATED；应用出错也要清理。

轮次结果是流事件，不是 webhook 订阅。agent.session.failed webhook 不覆盖所有失败轮次。不要仅因 agent.session.idle 就终止，它可能在等待输入开始前到达。

可设置以下 AWS 限制作清理失败时的兜底：

生命周期与空闲控制见 AWS 运行和使用MicroVM。另行删除会话，删除不会终止AWS资源或发删除webhook。镜像和环境密钥秘密可保留复用。后续轮次的资源复用、替换和文件持久化，见沙箱生命周期。

轮次之间挂起与恢复

AWS 挂起与恢复可保留内存与磁盘。suspendedDurationSeconds 要大于零，挂起期间收取快照存储费；maximumDurationInSeconds 将运行加挂起总时长限制为八小时。

两个示例使用 --suspend-resume 时，先写 /workspace/hello.txt，挂起VM，再在第二轮读取。应用管理示例直接恢复；webhook管理示例发送新输入，由启动器恢复已记录VM。两者都验证文件并在最后轮次清理。

/suspend 停执行器，/resume 重载密钥并重连。必须等工具与子智能体完成后再挂起。AWS自动恢复要求VM收到入站流量，仅发送Agents API输入不会唤醒它。

验证与监控

用在 /workspace 创建小文件的任务测试。确认执行器连接、轮次完成、下载文件内容正确、清理后VM为 TERMINATED。启动成功不等于集成已验证。

从 AWS 示例目录，用 jq 读取已保存构建状态中的镜像ARN和区域。自定义 --state 时调整路径；改过启动器名称时替换日志组：

来源示例 1（bash）：

## [中文] 示例 1：验证与监控。
## [中文] 用 jq 从镜像构建状态读取区域和 ARN，再查看启动器日志与 MicroVM 状态，验证清理结果。
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

日志同时记录会话与MicroVM ID，不记录凭证及原始webhook请求体。

排障

连接失败时检查 agent.session.environment.failed 及执行器日志；共用执行器协议见自托管沙箱。

参考

• 生命周期：运行和使用MicroVM，涵盖启动、挂起、恢复、终止。
• 安全：安全与权限，涵盖IAM角色、认证令牌与访问控制。