OpenAI Agents SDK #6：把 Agent 关进「安全箱」——Sandbox 执行环境全解析

Harness 管脑子，Sandbox 管手脚

• Harness（控制层）：管理 Agent 的意识——instructions、tools、approvals、tracing，这些留在 SDK 里
• Compute（执行层）：隔离沙箱，实际运行代码、读写文件、执行 shell 命令，放进独立的 SandboxAgent 里

SandboxAgent：普通 Agent 多了什么？

Manifest：工作区合约

SandboxRunConfig：单次运行的精细控制

from agents.sandbox import SandboxRunConfig, DockerSandboxClient

run_config = SandboxRunConfig(
    client=DockerSandboxClient(image="python:3.11-slim"),  # 指定运行时
    session=None,                                           # 注入已有 session（可选）
    session_state=my_snapshot,                             # 恢复快照（可选）
    snapshot=True,                                         # 运行完后生成快照
    materialize_concurrency=4,                             # 并发挂载 mount 的限制
)

• client：创建沙箱的客户端。不传则使用 Agent 级默认值
• session：注入一个已有的 sandbox session（适合多轮对话共享同一工作区）
• session_state：从快照恢复（RunState、SandboxSessionState 或已保存快照均可）
• snapshot：是否在运行结束后序列化当前工作区状态
• materialize_concurrency：并发初始化 mount 的上限（避免大量 Git clone 同时触发）

支持的执行环境：从本地到云端

完整代码示例解读

from agents.sandbox import (
    SandboxAgent,
    Manifest,
    LocalDir,
    SandboxRunConfig,
    UnixLocalSandboxClient,
)
from agents import Runner

# 1. 定义 SandboxAgent
agent = SandboxAgent(
    name="code-assistant",
    instructions="你是一个代码助手，可以读写文件并运行 shell 命令。",

# 工作区合约：从宿主机挂载当前项目目录
    default_manifest=Manifest(
        local_dirs=[
            LocalDir(
                host_path="./my-project",   # 宿主机路径
                sandbox_path="/workspace",  # 沙箱内路径
                read_only=False,            # 允许写入
            )
        ],
        environment={"PYTHONPATH": "/workspace"},
    ),

# 能力声明：允许 shell 执行和文件系统操作
    capabilities=["shell", "filesystem"],
)

# 2. 配置本次运行：使用本地 Unix 沙箱，运行后生成快照
run_config = SandboxRunConfig(
    client=UnixLocalSandboxClient(),
    snapshot=True,   # 运行结束后序列化 session 状态
)

# 3. 执行
result = await Runner.run(
    agent,
    "帮我检查 /workspace 下的所有 Python 文件并运行测试",
    run_config=run_config,
)

# 4. 保存快照，供下次运行恢复
session_state = result.session_state

• LocalDir(read_only=False) 表示 Agent 可以向宿主机写回文件。生产环境建议先用 read_only=True 验证逻辑，再开放写权限
• capabilities=["shell", "filesystem"] 是白名单机制——没有列出的能力默认不开放。内置 capabilities 还包括 skills、memory、compaction2
• snapshot=True 后，result.session_state 可以序列化存储，下次通过 SandboxRunConfig(session_state=...) 恢复，这是长周期任务断点续跑的核心机制

Capabilities 内置能力清单

为什么需要 Sandbox？三个真实场景

关于 Sandbox 供应商生态

实践建议

小结