OpenAI Agents SDK 怎么把沙箱任务拆成可恢复步骤

OpenAI Agents SDK 的沙箱任务要想失败后继续，关键不是把整段提示词再发一遍，而是同时保存“运行状态”和“工作区状态”。可以把任务拆成 prepare、transform、review 等阶段，每个阶段成功后在沙箱里写入一个幂等检查点；恢复时再根据故障位置选择 RunState、session_state 或 snapshot。这套 Sandbox Agents 能力目前仍是 beta，接口细节可能变化。

记住一个简单判断：同一次 Agent 运行被暂停，用 RunState；还想连回已经序列化的沙箱会话，用 session_state；要启动一个新沙箱但带上旧文件，用 snapshot。snapshot 保存的是工作区内容，不是完整的对话历史。

先把三种恢复边界分开

这三个名字容易被当成同一种“保存状态”，但负责的对象不同。RunState 是 Runner 管理的运行级暂停/恢复边界，适合人工审批、进程中断或需要继续同一条运行链的场景；session_state 是已经序列化的沙箱会话状态，交给同一个沙箱客户端去重连；snapshot 则是新会话的工作区种子，里面应该是可以重新装载的文件和产物。

尤其不要把 snapshot 当作聊天记录备份。它的职责是恢复文件、目录和生成的工件；如果还需要继续模型对话，应另外保存 SDK 的会话或运行上下文。挂载目录和临时目录也不应被当成快照中的永久文件。

为每个阶段写入幂等检查点

“可恢复”首先是业务设计，其次才是 SDK 配置。每个阶段应该有稳定名称、输入摘要、产物路径和状态。阶段成功后再写检查点，失败时不要先把阶段标成完成；这样即使下一次从快照启动，也能判断哪些文件可信。

from pathlib import Path
import json

STAGES = ("prepare", "transform", "review")
CHECKPOINT = Path("state/checkpoint.json")

def save_checkpoint(stage, artifacts):
    # 只有产物已经落盘并可复查时，才推进检查点
    CHECKPOINT.parent.mkdir(parents=True, exist_ok=True)
    payload = {"stage": stage, "artifacts": artifacts}
    CHECKPOINT.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")

def next_stage():
    # 缺少检查点就从第一阶段开始，避免凭猜测跳过工作
    if not CHECKPOINT.exists():
        return STAGES[0]
    saved = json.loads(CHECKPOINT.read_text(encoding="utf-8"))
    index = STAGES.index(saved["stage"])
    return STAGES[index + 1] if index + 1 

这段代码刻意只记录文件工件，不记录模型“认为已经完成”的自然语言。生产任务还应给每个阶段增加输入摘要、写入时间和版本号；重试时先验证这些工件存在，再决定是否跳过已经完成的阶段。阶段函数要做到幂等，例如重复执行 transform 不会把同一个结果追加两次。

用 SandboxRunConfig 组织恢复或新建

真正调用 Runner 时，先问一个问题：手上是活的 session、可反序列化的 session_state，还是只有工作区快照？活会话由应用自己负责生命周期；序列化会话需要客户端恢复；只有快照时则创建新的沙箱。下面的配置表达的是选择关系，快照目录应由应用配置，不要从用户输入拼接受信任的宿主路径。

from pathlib import Path
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import LocalSnapshotSpec, SandboxRunConfig
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

async def run_from_snapshot(agent, prompt):
    # 新会话从持久化工作区启动；对话历史仍由上层单独管理
    client = UnixLocalSandboxClient()
    sandbox = SandboxRunConfig(
        client=client,
        snapshot=LocalSnapshotSpec(base_path=Path("/var/lib/agent-snapshots")),
    )
    return await Runner.run(agent, prompt, run_config=RunConfig(sandbox=sandbox))

如果原沙箱仍然可信且只是在进程间迁移，传入序列化后的 session_state；如果是 Runner 自己管理的暂停流程，优先让 RunState 携带它的沙箱状态。不要把三者同时填上再期待 SDK 替你猜意图，恢复来源应该由外层任务状态明确选择。

故障后按检查清单恢复

1. 先读取 checkpoint.json，确认最后一个成功阶段和产物清单；文件不完整就回退到上一个检查点。
2. 判断故障属于运行暂停、会话断开还是工作区重建，分别选择 RunState、session_state 或 snapshot。
3. 为当前阶段生成新的幂等任务键，避免重试把外部写入、上传或通知执行两遍。
4. 恢复后先做轻量复查：工作目录存在、检查点版本匹配、必需工件可读，再让 Agent 继续。
5. 如果容器身份或快照来源无法确认，宁可从可信快照新建沙箱，也不要附着到不明会话。

这套拆分的价值在于把“模型继续思考”和“文件继续存在”分开管理。前者由运行或会话状态负责，后者由检查点和快照负责；任何一层丢失时，故障范围都能被限制在当前阶段。

OpenAI Agents SDK 沙箱恢复常见问题

RunState 和 snapshot 能互相替代吗？

不能。RunState 面向一次 Runner 运行的暂停与恢复，snapshot 面向新沙箱的工作区内容。一个保存了运行上下文，也不意味着另一个会自动保存所有文件。

什么时候应该使用 session_state？

当应用已经把沙箱会话序列化，并且仍准备通过同一个客户端恢复该会话时使用。若只想带着文件启动干净的新会话，应改用 snapshot。

检查点文件要不要写进 snapshot？

要。检查点是判断阶段和产物是否可信的最小依据，应与对应产物一起持久化；但恢复后仍要检查版本和文件完整性。