OpenAI Agents SDK 沙箱执行如何做故障恢复：快照、重hydration 与凭据隔离

一个能读文件、跑命令、改代码的 AI 智能体，最容易在“任务已经跑了一半”时暴露工程短板：沙箱容器失效了，模型知道自己做到哪一步，却找不到原来的工作目录；如果把云端凭据直接塞进执行环境，恢复能力又可能变成新的泄露面。OpenAI Agents SDK 的新沙箱能力把这两个问题拆开处理：用 Manifest 描述工作区，用外置状态和快照让任务在新容器里接着跑。

从一次沙箱中断看出智能体平台的缺口

假设一个资料分析智能体已经读完 data/metrics.md，正在生成比较结果。此时执行容器过期，重新拉起的容器当然可以继续接受模型请求，但它未必拥有原来的临时文件、工具上下文和中间结果。只做“失败后重试”会让任务从头读取、重新计算，甚至重复写入外部系统。

这也是 Agents SDK 把 harness（编排外壳）和 compute（实际执行环境）分开的价值：编排层记录任务进度，沙箱只负责在受控范围内读写文件和运行工具。容器消失不必然等于任务消失。

Manifest 先固定工作区，再谈可恢复

恢复的第一步不是复制整个容器，而是让新容器得到同样清晰的文件边界。官方示例用 Manifest 把本地目录挂载到 data，智能体的指令也明确要求“只使用 data/ 下的文件”。这类声明比在提示词里写一长串绝对路径更稳定。

from agents.sandbox import Manifest, SandboxAgent
from agents.sandbox.entries import LocalDir

agent = SandboxAgent(
    name="Dataroom Analyst",
    instructions="Answer using only files in data/. Cite source filenames.",
    default_manifest=Manifest(entries={
        "data": LocalDir(src=dataroom),
    }),
)

实际项目还应把输入目录、输出目录和临时目录分开记录。这样重建环境时，输入可以只读挂载，输出可以按任务 ID 重新绑定，临时文件则明确允许丢失。

快照恢复保存什么，不能保存什么

快照和 rehydration 的正确理解是“把任务状态带到新的执行环境”，不是把旧容器做成永不消失的虚拟机。可恢复内容通常包括已完成的步骤、工具调用结果、输出文件索引和下一步所需的上下文；操作系统进程、临时端口和未提交的内存状态不应被当作可靠资产。

把每个阶段变成可验收的检查点

一个长任务可以在“读取证据”“计算结果”“写出报告”之间设置检查点。每个检查点写入任务 ID、输入摘要、输出路径和状态，例如 analysis-042 / evidence-read / completed。恢复时先核对最后一个 completed 检查点，再决定是继续还是重做该阶段。

这里别急着把所有中间文件都持久化。更稳妥的做法是保存可重算的引用和不可重算的外部结果；如果某一步会产生扣费、发信或写库动作，还需要业务侧幂等键，避免恢复后重复执行。

凭据隔离决定了恢复边界是否安全

沙箱里的代码可能是模型临时生成的，输入文件也可能含有诱导模型泄露信息的内容。OpenAI 的说明把 prompt injection 和 exfiltration 直接列为设计前提，因此凭据不应该作为普通文件挂载进模型可读的 data/ 目录，更不应写进日志和快照。

可操作的边界是：模型只拿到完成任务所需的最小工具接口，真正的密钥由编排层或受控代理在调用时注入；快照只保存引用、权限范围和调用结果摘要，不保存原始令牌。恢复后重新授予短时权限，并重新检查任务所属用户和沙箱租约。

哪些团队适合先采用，哪些场景要谨慎

需要跨多步处理文件、命令和工具的研发助手、资料分析器、代码迁移助手，最能从“统一工作区 + 可恢复执行”中受益。它们的共同点是任务较长，且中间结果可以被明确记录。

如果任务包含不可逆操作、强实时性交易或高度敏感的原始数据，沙箱能力不能替代业务授权、审计和人工确认。先从只读资料分析或生成补丁开始，确认恢复链路稳定后，再逐步开放写入和外部工具。

落地时用三条指标判断恢复是否真的可用

• 断点成功率：主动终止或模拟容器过期后，任务能否从最近检查点继续并得到相同的关键结果。
• 恢复耗时：从失效事件到新沙箱重新可用的时间，是否低于业务可接受的任务窗口。
• 暴露面检查：快照、日志、输出目录和错误信息中是否出现令牌、个人数据或超出授权范围的文件。

验收时不要只测“容器重启后能否返回 200”。应该故意让任务停在工具调用前、工具调用后和输出写入后三个位置，分别检查是否重复执行、是否丢文件、是否越权恢复。

相关问题

Agents SDK 的沙箱恢复是不是等同于虚拟机快照？

不是。它更接近把智能体的任务状态和工作区描述带到新执行环境，进程、临时端口等易失状态仍应按失败处理。

Manifest 为什么比提示词里的路径说明更重要？

Manifest 是执行环境的结构化边界，能在本地目录和不同沙箱提供商之间保持一致；提示词只能告诉模型规则，不能自动创建目录或控制挂载权限。

恢复时能不能把 API Key 一起写进快照？

不建议。快照只保留权限引用和必要的调用摘要，恢复后由外层权限服务重新发放短时凭据。

把“能运行”推进到“能恢复、可控权”

Agents SDK 沙箱能力真正改变的不是某个 API 名称，而是智能体的运行单位：工作区有明确边界，任务状态可以外置，执行环境可以替换，凭据也能留在模型之外。先用只读任务验证检查点和恢复指标，再逐步开放写入权限，通常比一开始追求全自动更容易把风险关在可见范围内。