OpenAI Agents SDK 重构深度解析：Harness 与沙盒解耦如何重塑工业级 Agent 生态

一、引言：被补上的最后一块短板

2026年4月16日，OpenAI 对外发布了 Agents SDK 的重大更新。这次更新的背景，其实早在两个月前就被开发者社区反复吐槽过：GPT-5.4 带着原生 computer use（计算机使用）能力高调登场，模型能操作电脑了——但 Agent 跑在哪台机器上、跑的过程中如何保证安全、任务崩溃后怎么续命，这些问题依然是一片空白，全靠开发者自己东拼西凑。

说白了，模型能力是有了，但运行模型的"底座"还没搭好。

这一次，OpenAI 干脆把 Agents SDK 从「聊天机器人的玩具」彻底改造成了「生产级 Agent 的底座」。核心动作只有一个：把 Harness（控制层）和 Compute（计算层，也就是沙盒）彻底解耦。这看似简单的架构拆分，实际上重新定义了 Agent 基础设施的游戏规则。

本文将从架构原理、代码实战、安全模型、行业影响四个维度，对这次更新做一次完整深度的解析。

二、为什么旧版 SDK 撑不住了

在聊这次重构之前，有必要搞清楚旧版 SDK 的局限性到底在哪里。

2025年3月，OpenAI 首次推出 Agents SDK 时，定位是「轻量、少抽象、几行 Python 就能跑起来」。这个定位本身没有错，但它是为聊天机器人场景设计的——你来我往、即时响应、单轮或几轮对话就能完成。

问题在于，2026年的模型能力已经完全不同了。Agent 的任务从几分钟的问答变成了可能持续数小时甚至数天的长周期任务。Agent 需要读写文件、跑代码、调工具、跨系统协作——这些能力是旧版 SDK 完全没考虑到的。

用一个不严谨但形象的比喻：旧版 SDK 像是一个「前台接待员」，负责接待来访者并给出回应；而现在需要的 Agent 是一个「远程出差工程师」，要能独立在客户的服务器上工作数天，中途可能断网断电，归来时还得带着完整的交付物。

三、核心架构：Harness 与 Compute 的彻底解耦

3.1 什么是 Harness

Harness 是整个新架构的控制中枢，运行在可信基础设施上。它的职责包括：

• 模型调用：统一管理 GPT-5.4 的调用逻辑
• 工具路由：决定 Agent 在何时调用哪个工具（MCP、skills、shell、文件编辑等）
• 任务编排：管理复杂任务的分步执行、子任务分发、上下文维护
• 暂停与恢复：支持 Agent 执行过程中的状态保存与断点续传
• 审批与追踪：在关键节点插入人工审批或日志记录

换句话说，Harness 负责「想清楚要做什么」，但不负责实际执行。

3.2 什么是 Compute（沙盒）

Compute 层是一个完全隔离的沙盒执行环境，负责 Harness 下达的指令的实际执行：

• 读写文件
• 安装依赖包
• 执行代码
• 调用命令行工具
• 产出最终产物

关键点在于：API 密钥、凭证、敏感数据完全不会进入沙盒环境。沙盒甚至可以配置为与外部网络完全断开，没有任何对外流量。Harness 和沙盒之间只通过标准化的接口通信，沙盒看到的只有任务指令和必要的输入数据。

3.3 两层解耦的工程意义

这种解耦带来的实际好处是巨大的：

安全隔离：即使沙盒中的代码被恶意注入，攻击者也无法接触到 API 密钥或内部系统。传统的 Agent 架构中，Agent 生成的代码往往直接跑在宿主机上，一旦代码有问题，整个系统的安全性都会受到威胁。

环境可移植性：换一个沙盒供应商，不需要改一行业务代码，只需要改 Harness 的配置。这种能力在以前是不可想象的。

长任务可靠性：沙盒容器可以随时被销毁重建，Agent 的执行状态（Harness 视角）不会丢失。这解决了 Agent 长周期任务中「一崩全崩」的历史难题。

四、Manifest 抽象层：一次编写，到处运行

如果说 Harness 和沙盒的分离是底层架构，那么 Manifest 就是连接两者的「配置文件」。

4.1 Manifest 的作用

Manifest 是一份 JSON/YAML 格式的清单，用于定义 Agent 工作空间的完整配置：

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

manifest = Manifest(
    entries={
        "data": LocalDir(src="./financial_data"),      # 挂载本地目录
        "cache": S3Bucket(                              # 挂载 S3 存储桶
            bucket="company-dataroom",
            prefix="cache/",
            region="us-east-1"
        )
    },
    output_dir="./agent_output",                        # 产物输出目录
    storage_provider="aws_s3"                           # 存储后端
)

通过这份 Manifest，开发者可以自由组合：

• 本地文件系统：LocalDir
• 云存储：AWS S3、Google Cloud Storage、Azure Blob Storage、Cloudflare R2

完全不需要改业务代码，换一家存储服务商，改 Manifest 配置就行。

4.2 实际应用场景

一个典型的场景是：财务团队需要在沙盒里跑一个 Agent，对比两份年度财报的关键指标。

用 Manifest 配置好数据源（可以是本地文件、S3 桶，甚至多个不同来源），Agent 在沙盒中读取数据、运行分析代码、输出结论。整个过程对 Agent 来说是透明的，它只看到统一的文件路径接口。

五、七大沙盒厂商一键接入

这次更新最受关注的合作伙伴生态亮点是：Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 七家沙盒厂商同时进入了官方支持列表。

这不是简单的「合作伙伴」关系。OpenAI 给出的是 SDK 层面的原生集成——换句话说，你不需要自己写任何适配代码，SDK 已经帮你把接口接好了。

5.1 各厂商的差异化定位

5.2 切换成本趋近于零

这是这次更新最令开发者振奋的地方。用 OpenAI 官方的说法：

今天用 E2B 写的 Agent，明天想换成 Modal，不需要重写一行代码，只需要改 Harness 配置里的 SandboxRunConfig。

这种供应商无关性（vendor-agnostic）意味着企业不再需要被单一沙盒供应商绑定。谁的性价比高、谁离数据源近、谁的合规性更强，切换就是了。

六、代码实战：20行代码跑通财报分析 Agent

官方给出了一个最小可用示例，展示了如何在本地沙盒中运行一个财报对比 Agent。让我完整解析这段代码：

# 安装依赖
# pip install "openai-agents>=0.14.0"

import asyncio
import tempfile
from pathlib import Path
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 import UnixLocalSandboxClient

async def main() -> None:
    # 创建临时数据目录
    with tempfile.TemporaryDirectory() as tmp:
        dataroom = Path(tmp) / "data"
        dataroom.mkdir()
        
        # 写入财报数据（Markdown 格式的表格）
        (dataroom / "metrics.md").write_text(
            """# Annual metrics
| Year | Revenue | Operating income | Operating cash flow |
| --- | ---: | ---: | ---: |
| FY2025 | $124.3M | $18.6M | $24.1M |
| FY2024 | $98.7M | $12.4M | $17.9M |""",
            encoding="utf-8",
        )

        # 定义沙盒 Agent
        agent = SandboxAgent(
            name="Dataroom Analyst",
            model="gpt-5.4",
            instructions="使用 data/ 目录下的文件回答问题，引用源文件名。",
            default_manifest=Manifest(
                entries={"data": LocalDir(src=dataroom)}
            ),
        )

        # 在本地沙盒中运行 Agent
        result = await Runner.run(
            agent,
            "对比 FY2025 和 FY2024 的收入、营业利润和经营现金流。",
            run_config=RunConfig(
                sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
            ),
        )
        print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

逐行解析这个流程：

第1-6行：导入必要的模块。SandboxAgent 是运行在沙盒中的 Agent 实例，Manifest 定义了数据来源，SandboxRunConfig 指定了沙盒客户端（这里用的是本地 Unix 沙盒，也可以换成任意第三方）。

第8-13行：创建临时目录并写入两份财报数据。这模拟的是企业将敏感文件放入隔离数据室的场景。

第15-22行：核心配置。SandboxAgent 接受三个关键参数：name 给 Agent 起个标识，model 指定用哪个模型（这里显式指定了 gpt-5.4），instructions 是 Agent 的系统指令，default_manifest 则是 Agent 能访问的数据源。data/ 目录之外的文件，沙盒中的 Agent 根本看不到。

第24-33行：运行 Agent。Runner.run() 是统一的执行入口，sandbox 参数决定了 Agent 跑在哪个执行环境中。这里的 UnixLocalSandboxClient() 代表本地沙盒，如果要切换到 Modal，只需要改成 ModalSandboxClient()。

七、安全架构：凭证不过境

这是整个新架构最核心的设计哲学，也是 Agent 安全性的一座里程碑。

7.1 传统架构的安全隐患

在传统 Agent 架构中，Agent（比如一个 GPT-5.4 驱动的代码执行 Agent）通常有以下路径：

模型生成代码 → 代码直接跑在宿主机上 → 需要宿主机的凭证/权限

这个路径存在两个致命问题：

1. 凭证泄露风险：如果 Agent 被提示词注入（Prompt Injection）攻击，恶意指令可能让 Agent 读取环境变量中的 API 密钥并外传。
2. 横向移动风险：代码在宿主机上执行，理论上可以访问宿主机上的所有资源。

7.2 新架构如何堵住漏洞

在 Harness/沙盒分离架构中，Harness 运行在可信环境中，掌握着所有凭证和 API 密钥。沙盒是一个零信任环境——它不持有任何凭证，只能通过 Harness 暴露的接口与外部通信。

通信路径变成了：

Harness（持有凭证）→ 下达任务指令（不含凭证）→ 沙盒执行 → 返回结果 → Harness 处理

沙盒中的代码看到的只有「任务指令」和「数据文件」。即使沙盒被完全攻陷，攻击者也只能拿到这一次任务的数据，无法横向扩散到其他系统。

7.3 网络隔离配置

更进一步，沙盒可以配置为与外部网络完全断开：

sandbox_config = SandboxRunConfig(
    client=UnixLocalSandboxClient(),
    network_mode="isolated",  # 完全断网
    max_execution_time=3600    # 最多运行1小时
)

在隔离模式下，沙盒中的代码无法发起任何外部网络请求，也无法访问非 Manifest 中指定的文件。这种配置对于处理敏感财务数据、医疗记录等场景至关重要。

八、性能数据：工业级能力的实证

这次更新并不是纯粹的理论升级，背后已经有了一批硬数字支撑。

8.1 FurtherAI：900页保险理赔文档100%提取

FurtherAI 的 CTO Sashank Gondala 披露了一个令人印象深刻的案例：他们的 Agent 使用新架构啃下了一份 900多页的保险理赔记录，提取成功率达到了 100%。

对于保险从业者来说，这三个词凑在一起意味着什么？业内人都清楚，保险理赔文档是结构最混乱、数据最不规范的文档类型之一——格式不统一、手写内容混杂、表格跨越多页、历史数据引用交叉。传统方案跑到某一页崩溃是常态。100%提取的背后，是新架构下沙盒的稳定执行和状态恢复能力在支撑。

8.2 代码量缩减6倍

Tomoro AI 的研发工程师 Douglas Adams 给出的数据同样震撼：相同能力的 Agent，新架构下的代码量比以前少了6倍。

背后的原因在于：Harness 提供的标准化能力（记忆管理、文件工具、MCP 集成、AGENTS.md 自定义指令）把大量原来需要开发者自己手写的脚手架代码变成了 SDK 内置能力。开发者只需要关注业务逻辑，其余交给 Harness。

8.3 企业级应用数据

Modal 技术团队透露，Ramp 已经用 Modal 跑了一支后台编码 Agent 大军，公司 超过一半的 PR（Pull Request） 都是这些 Agent 自己创建的。

Stripe 也不甘落后，今年早些时候披露其内部 AI Agent 每周产出超过1000个 PR。

这两个案例的共同点是：这些公司都在 OpenAI 新 SDK 发布之前就已经搭建了自己的 Agent 基础设施，付出了大量工程成本。而现在，OpenAI 把这些能力直接放进了 SDK，意味着中小企业也能用几行代码获得同等的能力。

九、行业冲击：LangChain 们何去何从

这是这次更新对整个行业最深远的影响。

9.1 第三方框架的核心价值是什么

过去一年，LangChain、LangGraph、CrewAI、AutoGen 这些框架靠什么活着？说白了就是：补 OpenAI 原生 SDK 不够「生产可用」的空白。

Agent 编排、记忆管理、执行护栏、运行追踪、多 Agent 协作——这些都是第三方框架的主战场，也是它们的商业价值所在。

9.2 OpenAI 的「地板战略」

这次 SDK 更新，OpenAI 实际上在做一件事：把中间那层地板踩实了。

新版 SDK 原生支持的能力包括：

• 配置化记忆管理
• 感知沙盒的任务编排
• Codex 级的文件系统工具
• MCP 工具调用
• Skills 渐进式能力披露
• AGENTS.md 自定义指令
• Shell 工具执行
• apply/patch 文件编辑
• 快照与状态恢复
• 多沙盒并行与子 Agent 隔离

这些都是 LangChain、LangGraph 等框架的核心卖点。现在 OpenAI 自己做了，第三方框架的空间肉眼可见地在收窄。

9.3 第三方框架的出路

OpenAI 这次更新的官方口径是「兼容所有沙盒服务商」，但换一个角度看，这也是在把沙盒供应商纳入 OpenAI 的生态位。今天可能是 OpenAI 的合作伙伴，明天就可能只是 OpenAI 生态下的「组件供应商」。

对于 LangChain 等框架来说，留给它们的路只有两条：

往上走：做更高级的垂直场景编排，做特定行业的解决方案，做 OpenAI 不擅长或者不愿意做的深度定制。

往下走：退化为纯粹的沙盒供应商或工具链提供商，专注于某个细分领域的执行层优化。

夹在中间的那层——通用 Agent 编排框架——已经被 OpenAI 这次更新基本覆盖了。

十、不足与展望

10.1 当前的局限性

尽管这次更新方向清晰，但仍然存在一些不足：

Python 先行，TypeScript 排队：新能力目前只上了 Python，TypeScript 版本在后续更新计划里。对于大量使用 TypeScript 的前端和 Node.js 生态来说，这意味着目前还无法直接使用。

SDK 版本仍在 0.Y.Z：这意味着 API 还在快速迭代中，生产使用存在一定的兼容性风险。

复杂场景的长期稳定性：作为刚发布的新版本，SDK 在超大规模并发、极端复杂任务链等场景下的稳定性，仍需要大量实际应用的验证。

跨沙盒供应商的迁移成熟度：虽然 Manifest 抽象层在理论上支持供应商无关切换，但实际迁移过程中可能遇到的各种边界情况还没有被充分验证。

10.2 未来趋势

从更宏观的视角来看，Anthropic 也在相近的时间段推出了 Claude Managed Agents，同样提供原生沙盒、状态持久化、故障自愈等能力。这说明「安全隔离 + 状态可恢复」已经成为了头部 AI 厂商对 Agent 基础设施的共识判断。

接下来几个可以预见的趋势：

1. Agent 基础设施的标准化：随着 OpenAI 和 Anthropic 各自推出自己的标准，行业的 Agent 运行时标准会逐渐收敛。
2. 沙盒供应商的生态分化：沙盒厂商会逐渐分化，一部分走向「安全合规」路线（医疗、金融等强监管行业），一部分走向「极致性能」路线（高频交易、实时数据处理）。
3. 「Agent 级」开发模式普及：未来的软件开发团队，可能会像今天有专门的 DevOps 工程师一样，出现专门的 Agent 工程师岗位——负责 Agent 的编排、监控、合规和优化。

十一、总结

这次 OpenAI Agents SDK 的更新，本质上是在做一件事：把 Agent 从「模型能力」变成「系统工程」。

Harness 和沙盒的解耦，不仅是一个技术架构的选择，更是一个关于「谁来负责 Agent 执行安全」的回答。OpenAI 选择把这个责任从开发者手里接过来，放进 SDK 的默认配置里。

对于开发者来说，这意味着：

• 开发成本大幅下降：以前需要自己搭的沙盒、状态管理、凭证隔离，现在几行配置就能搞定。
• 安全基线提升：即使是不懂安全的业务开发者，只要用 SDK 的默认配置，安全性也比手写方案强得多。
• 供应商锁定风险降低：Manifest 抽象层让切换沙盒供应商的成本趋近于零。

对于整个行业来说，OpenAI 的这次「下场做基建」，把 Agent 框架领域的竞争门槛一下子拉高了一个数量级。那些还在靠「给 OpenAI SDK 打补丁」活着的公司，需要认真思考下一步的出路了。

GPT-5.4 出厂那天被一些人说成是「没有惊喜的例行升级」。40天后回头看，真正的惊喜今天才发。

选题来源：OpenAI Agents SDK 2026年4月16日更新
标签：AI Agent | OpenAI | Agents SDK | 沙盒 | 架构设计 | Python | 企业级AI
关键词：AI Agent | OpenAI Agents SDK | Harness | Sandbox | 沙盒隔离 | Manifest | GPT-5.4 | LangChain | Computer Use | 状态恢复 | MCP协议 | Python | 生产级Agent