使用 AWS Lambda MicroVMs 在您的 AWS 账户中运行智能体的工具。OpenAI 负责运行智能体执行框架,每个 MicroVM 则运行 codex exec-server 并保存会话的工作空间文件。
默认情况下,示例为每轮交互使用一个 MicroVM。先准备可复用的镜像,再通过您的应用或 OpenAI webhook 启动 MicroVM。两种方式使用相同的镜像和凭证。每个会话只应由一方负责预置 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 执行角色: 将此角色在 Secrets Manager 中的读取权限限制为存放环境密钥的条目。如果您使用客户管理的 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,然后启动执行器。进程启动后,钩子就应返回。如果等到智能体完成本轮交互才返回,钩子可能会超时。
允许执行器建立所需的出站连接,并允许 MicroVM 访问 Secrets Manager。如果需要访问私有资源或网络受到限制,请配置 AWS 出站连接器。要支持文件下载,请在服务器上添加下载路由,并通过 MicroVM 的 HTTP 端点调用该路由。调用时请使用仅对该服务器端口有效的 AWS 身份验证令牌。
启动 MicroVM
请选择由应用或 webhook 负责预置 MicroVM。无论选择哪种方式,从建立连接、处理输入直到本轮交互结束,都应保持会话事件流打开。
由应用预置 MicroVM
- 创建自托管会话,确保其工作目录与镜像中的工作目录一致,然后打开会话事件流。
- 调用 AWS RunMicrovm,传入镜像 ARN 和版本、执行角色、网络连接器以及
runHookPayload。将返回的microvmId与会话 ID 一起保存。 - 等待
agent.session.environment.connected事件,然后发送输入,并从事件流中跟踪本轮交互的结果。 - 获取输出文件,然后停止 MicroVM。
由 webhook 预置 MicroVM
使用 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 就终止虚拟机,因为该事件可能在会话开始处理等待中的输入之前到达。
请配置以下 AWS 限制,以便在遗漏清理时限制虚拟机的存续时间:
| 设置 | 配置建议 |
|---|---|
maximumDurationInSeconds |
为工作负载设置时长上限,例如为 15 分钟的测试设置 900。达到上限时,正在运行的任务可能会中断。 |
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 角色、身份验证令牌和访问控制。