OpenAI Agents SDK 原生沙盒与 Manifest 指南

OpenAI 于 2026 年 4 月 15 日发布了重要的 Agents SDK 更新，启动博文中的安装命令就是信号：pip install "openai-agents>=0.14.0"（OpenAI）。这个版本号很关键。这不是一个新的提示词模板，也不是又一个函数调用封装器。它意味着 OpenAI 将文件操作、shell 操作、补丁应用、沙盒生命周期和工作区描述提升为了 SDK 级别的原语。

对于构建编码 Agent、文档 Agent、数据清理 Agent 或仓库维护机器人的开发者来说，这个设计转变很简单：不要再让每个团队围绕 Docker、临时目录、工具 schema、文件暂存和重试逻辑重复搭建同一套脆弱的脚手架。现在 SDK 提供了模型原生的执行框架、沙盒原生执行、文件系统工具、MCP、AGENTS.md、shell 访问、apply_patch，以及用于描述可移植工作区的 Manifest 抽象。

变化：从工具调用到真正的工作区

原版 Agents SDK 在编排方面已经很有用：Agent、工具、交接、护栏、追踪。4 月的更新补上了那些需要长期处理文件的 Agent 所缺失的运行时形态。

OpenAI 将更新后的 SDK 描述为：帮助开发者构建能够在受控沙盒环境中检查文件、运行命令、编辑代码，并处理长周期任务的 Agent（OpenAI）。“受控工作区”这个说法是关键。一个严肃的文件处理型 Agent 需要的不只是工具列表。它需要根目录、挂载的输入、输出位置、shell、权限、快照，以及在容器崩溃后恢复的方式。

在这次更新之前，一个典型的生产设置大致是这样的：

• 创建临时工作区
• 将文件复制进去
• 暴露读取、写入、shell 和补丁工具
• 手动校验路径
• 启动沙盒或容器
• 收集产物
• 如果任务运行时间较长，则快照状态
• 将所有这些转换成面向模型的指令

这些胶水代码正是许多 Agent 项目悄悄变得混乱的地方。新的 SDK 将其中相当一部分变成了一等配置。

OpenAI 的发布博文列出了对 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 和 Vercel 作为沙盒提供商的内置支持，同时也提供“自带沙盒”的路径（OpenAI）。也就是说，发布时就有 7 个托管提供商，再加上本地开发路径。

Manifest 是可移植性层

Manifest 抽象是这次发布中最实用的部分。它描述了模型开始工作之前，沙盒工作区应该包含什么。

在 Python 文档中，Sandbox Agents 被标记为 beta，需要 Python 3.10 或更高版本，并被介绍为一种给模型提供持久工作区的方式，让模型可以搜索文档集合、编辑文件、运行命令、生成产物，并从已保存的沙盒状态中恢复（OpenAI Agents SDK Python 文档）。

一个紧凑的 Python 形态如下：

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

重要的不是语法，而是契约。Manifest 可以描述本地文件、目录、Git 仓库、合成文件、环境变量、用户、用户组、输出目录和远程存储挂载。JavaScript 文档指出，Manifest 条目的路径是相对于工作区的，不能是绝对路径，也不能用 .. 逃逸出工作区；这正是你希望由运行时强制执行、而不是靠每条提示词记住的那类“无聊但重要”的约束（OpenAI Agents SDK JS 文档）。

能力：shell、文件系统、skills、memory、compaction

SandboxAgent 不只是一个带临时文件夹的普通 Agent。它携带了沙盒专用能力。

JS 概念文档列出的内置能力包括 shell()、filesystem()、skills()、memory() 和 compaction()（OpenAI Agents SDK JS 文档）。这里默认值很重要：文档说明 Capabilities.default() 包含文件系统、shell 和 compaction。这意味着常见的编码 Agent 循环不再是一堆定制工具定义。

文件系统能力暴露补丁风格的文件编辑。shell 能力暴露沙盒会话内的命令执行。Skills 允许你渐进式披露专门的指令或流程。Memory 和 compaction 帮助较长的运行保留有用状态，而无需把之前所有 token 都塞回下一轮。

这符合强编码 Agent 实际工作的方式。它们会检查，运行一条命令，编辑一个文件，再运行一条更小的命令，检查 diff，然后总结变更。如果你的框架把每一步都当成互不相关的 API 调用，模型就会花太多注意力来重建它所处的世界。沙盒会话给了模型一个立足点。

AGENTS.md 也自然适配这种模型。开放的 AGENTS.md 网站将其描述为一种用于指导编码 Agent 的 Markdown 格式，并称它已被超过 60,000 个开源项目使用（AGENTS.md）。这个文件应包含构建命令、测试说明、风格规则和仓库特定警告。在沙盒世界里，AGENTS.md 变成了工作区本地的操作上下文，而不是每个任务都要粘贴进去的一大段提示词。

Python 优先，TypeScript 正在追上

发布时，这是 Python 优先的。TechCrunch 在 4 月 15 日报道称，新的执行框架和沙盒能力会先在 Python 中发布，TypeScript 支持计划稍后推出（TechCrunch）。PyPI 也印证了这个日期：openai-agents 的 0.14.0 和 0.14.1 版本于 2026 年 4 月 15 日上传（PyPI）。

截至 2026 年 6 月 16 日，实际情况更加均衡。官方 JS 文档现在已经包含 beta 版 Sandbox Agents，要求 Node.js 22 或更高版本，并展示了 Manifest、SandboxAgent、UnixLocalSandboxClient、Docker 支持，以及通过 @openai/agents-extensions 使用托管提供商客户端（OpenAI Agents SDK JS 快速开始）。JS 文档还指出，在包解析和运行时 API 兼容的情况下，Deno 和 Bun 也可以使用。

领域	Python	TypeScript / JavaScript
4 月 15 日发布状态	首个受支持路径	计划稍后支持
当前沙盒文档	Beta，Python 3.10+	Beta，Node.js 22+
本地沙盒	UnixLocalSandboxClient	UnixLocalSandboxClient
Docker 沙盒	openai-agents[docker]	DockerSandboxClient
托管提供商	通过 SDK 集成支持	@openai/agents-extensions 提供商路径

这并不意味着两个生态完全一致。Python 是最初的发布界面，许多示例仍然会先落在那里。TypeScript 现在已经有足够的官方表面积来原型化真实的沙盒 Agent，但托管提供商细节、PTY 行为、挂载和生命周期支持，仍然需要按后端仔细阅读文档。

我现在会如何组织一个文件处理型 Agent

错误的做法是把沙盒当作一个神奇的安全盒子。它是运行时边界，不是产品规格。你仍然需要设计工作区。

一个清晰的结构如下：

• repo/：工作树或挂载的仓库
• task.md：模型必须首先阅读的任务规格
• inputs/：只读文档、数据集、截图或日志
• output/：最终生成产物唯一应该放置的位置
• AGENTS.md：构建、测试、风格和安全说明
• 沙盒用户：在后端支持时使用非 root 身份
• Manifest env：默认持久化的非机密配置，机密标记为临时

Manifest 应描述输入。Agent 指令应描述工作流。用户提示词应描述一次性任务。把这些分开。JS 文档明确警告，不要把属于 Manifest 的长篇参考材料塞进 instructions（OpenAI Agents SDK JS 文档）。

在生产环境中，应根据爆炸半径选择后端，而不是根据 demo 路径选择。Unix-local 适合开发。当你需要可重复性时，Docker 是更好的默认选择。当你需要每次运行的干净隔离、远程执行、扩缩容或提供商特定的快照行为时，托管提供商就很有意义。JS 客户端文档指出，托管提供商支持各不相同，开发者应查看提供商文档，了解环境变量、端口、PTY、快照和清理行为（OpenAI Agents SDK JS 客户端）。

生态解读

这次更新之所以重要，是因为它标准化了文件处理型 Agent 的形态。行业已经在几个原语上趋于一致：用于外部工具的 MCP、用于仓库说明的 AGENTS.md、用于真实检查的 shell、用于可审查编辑的 patching，以及用于隔离的 sandboxes。OpenAI 的 Agents SDK 现在把这些组件打包成了开发者真正可以组合的运行时。

尖锐边界仍然是权限。一个拥有广泛网络访问、可写挂载、长期凭证和模糊指令的沙盒 Agent，仍然可能造成损害。Manifest 有帮助，因为它让工作区输入和授权变得可见。但它不能取代审批策略、密钥卫生、依赖固定和产物审查。

今天最好的用例不是“Agent 做所有事情”。而是更窄、也更有价值的模式：给模型一个有边界的工作区、一份清晰的任务文件、仓库本地说明、shell 和 patch 工具，以及一条明确的验证路径。让它像一个初级工程师一样，在一次性环境中工作。然后检查 diff。

这比围绕聊天循环再手搓一个半吊子沙盒健康得多。

想亲手试用这些模型的读者，可以通过 onehop 使用兼容 OpenAI 的 API 调用它们，只需修改一个 base_url。它比官方一手渠道更便宜，新账号还可获得 $10 免费额度且无需银行卡：在 onehop 上调用 Claude 和其他模型，或注册获取 $10 免费额度。