沙箱 Agent 与 Manifest/Capability 系统

DEV-03: 沙箱 Agent 与 Manifest/Capability 系统

学习目标

• 理解 SandboxAgent 相对于 Agent 的扩展字段
• 掌握 Manifest 文件系统描述与路径安全机制
• 理解 Capability 插件系统的五个钩子
• 掌握多后端架构（Docker / Modal）与 ComputerTool 生命周期

前置知识

本章涉及沙箱系统的通用原理，建议先阅读：

• 安全沙箱设计

下文直接聚焦 OpenAI Agents SDK 的具体实现。

项目实践

SandboxAgent vs Agent

SandboxAgent 继承 Agent，新增四个字段：

字段	用途
default_manifest	新 session 的工作区文件系统描述
base_instructions	覆盖 SDK 沙箱基础提示
capabilities	可插拔能力（可变 manifest、添加指令、暴露工具）
run_as	模型面对沙箱工具的用户身份（shell、文件读取、patch）

运输层不在 Agent 上：sandbox client 和 session 通过 RunConfig(sandbox=SandboxRunConfig(session=...)) 在运行时提供。

Manifest：声明式工作区描述

Manifest 是 Pydantic 模型，描述沙箱工作区：

路径安全：不允许绝对路径、不允许通过 .. 逃逸 root。所有路径在序列化前验证。

Capability 插件系统

Capability 是 Pydantic 基类，提供五个钩子：

钩子	作用
tools()	暴露工具给 Agent
process_manifest()	在 session 创建前变异 Manifest
instructions()	添加指令片段到提示
process_context()	在采样前转换模型输入
sampling_params()	添加模型请求参数

内置能力：Filesystem、Shell、Compaction。可选的 Memory 能力支持沙箱后端记忆提取与合并（两阶段：per-rollout 提取 + cross-rollout 合并）。

多后端架构

后端	特点
DockerSandboxClient	本地 Docker 容器、工作区通过 tar 物化、PTY 支持、快照持久化
ModalSandboxClient	Modal 云端、远程快照持久化（扩展模块）
UnixLocalSandboxClient	本地文件系统（开发/测试用）

ComputerTool 生命周期

ComputerTool 支持 per-run 实例：

• ComputerProvider(create, dispose)：每个 RunContextWrapper 创建一次 computer
• RunContextWrapper 级缓存：同一 run 中复用
• dispose_resolved_computers()：run 结束时释放
• 支持 sync Computer 和 async AsyncComputer 两种接口

ShellTool 双环境

模式	说明
本地（用户 ShellExecutor）	用户提供的 shell 执行器，本地执行
托管（container_auto / container_reference）	在托管容器中执行，不接受本地执行器

问题与规避

问题	规避方案
Manifest 路径逃逸	SDK 自动校验路径，拒绝绝对路径和 ..
Modal 后端不可用	安装可选扩展 openai-agents[sandbox-modal]
ComputerTool dispose 泄漏	始终调用 dispose_resolved_computers() 或在 run 结束时使用 context manager

设计取舍

为什么运输层不在 Agent 上

Sandbox client、session、options 在运行时提供（通过 RunConfig），而非存储在 Agent 上。这样做的好处：(1) Agent 定义是声明式的（manifest + capabilities），可序列化和复用；(2) 运行时配置（哪个 Docker host、哪个 session）与 Agent 定义解耦；(3) 同一 Agent 可在不同环境（开发/生产）中使用不同的 sandbox backend。

为什么 Capability 是 Pydantic 模型而非 ABC

Pydantic 提供自动序列化/反序列化、字段校验和默认值。这对于 Manifest 处理（将 capability 配置序列化到容器）和配置验证很有用。

参考来源

• OpenAI Agents SDK: Sandbox Agents
• OpenAI Agents SDK: Sandbox Guide