OpenAIAgents SDKSandbox

OpenAI 这次把 Agents SDK 抄了 Claude Code 的作业，但抄得很认真

一、发生了什么：一句话版本

新版 OpenAI Agents SDK 引入了两个核心能力。

第一，Model-native harness。模型原生的运行脚手架，处理工具编排、记忆管理、审批流、tracing、断点恢复。

第二，Native sandbox execution。原生沙盒执行，让 Agent 可以在隔离环境里读文件、跑命令、改代码、做长任务。

听起来熟悉吗？对，这就是 Claude Code 从第一天起的架构。Anthropic 把它从 IDE 工具里抽出来，命名成 Claude Agent SDK；OpenAI 这次也走到了同一个路口。

但路口走法不一样。下面才是有意思的部分。

Agents SDK 自身处理 loop、tools 与 durable execution（图源 OpenAI 官方公告）

二、最关键的一步：harness 和 compute 彻底解耦

旧世界里，Agent 框架是这么干的：

LangChain / LangGraph：你自己拼 chain，自己处理一切。

OpenAI 旧 Agents SDK（前身 Swarm）：偏工具调用编排，跑在哪儿你自己想办法。

Managed Agent API：一切打包好，但你被锁在它的 runtime 里。

新版 OpenAI Agents SDK 的设计原则是：模型脚手架（harness）和运行环境（compute）是两件事，必须解耦。

harness 留在受控环境持有 secrets，sandbox 可以跑在任何一家 compute provider（图源 OpenAI 官方公告）

代码长这样：

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

agent = SandboxAgent(
    name="Workspace Assistant",
    instructions="Inspect the sandbox workspace before answering.",
    default_manifest=Manifest(
        entries={
            "repo": GitRepo(repo="openai/openai-agents-python", ref="main"),
        }
    ),
)

result = Runner.run_sync(
    agent,
    "Inspect the repo README and summarize what this project does.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

注意最后那一行 client=UnixLocalSandboxClient()。

改一行，就能把整个 Agent 从本地 Unix 切换到 Docker、E2B、Modal、Daytona、Cloudflare、Runloop、Vercel 中的任意一个。

SDK 首发支持的 7 家 sandbox provider（图源 OpenAI 官方公告）

这不是 SDK 设计，这是基础设施抽象。

三、Manifest 是新核心，比想象中重要

很多人会盯着 SandboxAgent 看，但我认为 Manifest 才是这套设计真正的灵魂。

Manifest 描述了一个干净沙盒工作区的初始内容和布局：

· 要 clone 哪些 Git repo

· 要挂载哪些 mount

· 要预置哪些文件、helper、artifact

· 输出目录在哪

· 环境变量、依赖如何准备

它的本质是：把”Agent 的工作环境”变成可声明、可序列化、可重现的对象。

为什么这件事重要？因为它解决了一个几乎所有 Agent 平台都在私下吃苦头的问题——

Manifest 一旦标准化，配合 sandbox 的 snapshot / rehydration 能力，每个任务都可以从一个确定性的初始世界开始，跑完销毁。

这是把”工程化的 Agent”从描述语言转成可部署单位的关键一步。

四、安全模型：凭证留在 harness 侧

这条值得单独拎出来讲。

新版 SDK 的默认假设是：模型生成的代码所运行的环境，是潜在敌对环境。

所以——

harness 侧：持有 auth context、API key、数据库凭证、密钥管理器访问权限。

sandbox 侧：跑模型生成的代码，不直接接触任何凭证。

中间用工具调用桥接——Agent 想读数据库？通过 harness 暴露的工具，harness 内部去查，把结果递回 sandbox。

Gateway Service 拦截 sandbox 的出站调用，secrets 永远不流入模型生成代码的执行环境（图源 OpenAI 官方公告）

这是企业级 Agent 真正能上 prod 的安全前提。过去一年里，多少团队因为”Agent 自己写 SQL 直连库”踩了坑、躺了 P0，懂的都懂。

OpenAI 这次把它写进了默认架构。这是一次让 Agent 安全可上线的范式更新，不是一个 feature。

五、彩蛋：这套 SDK 跑 Claude，也很顺

OpenAI 自己在公告里没强调，但事实是——

新版 Agents SDK 兼容任何 Chat Completions 格式的模型，包括 Claude。

也就是说，OpenAI 替整个行业造了一套 Agent 编排层，然后告诉你：”你想用谁的模型都行。”

这是非常老练的一手。它不指望靠 SDK 锁死你，反而靠 SDK 把自己定位成 Agent 时代的 orchestration 标准制定者。锁不住模型，那就当地基。

六、和 Claude 的正面对比：到底谁领先？

我说点直白的。

Claude 这边：Claude Code 从 day 1 就是 harness + sandbox + 文件系统工具 + 持久化状态的架构，Claude Agent SDK 是把这套引擎抽出来给开发者用。Anthropic 走得更早、更彻底。

OpenAI 这边：晚来一年，但补课补得诚恳。Manifest 这种声明式工作区抽象、多 sandbox provider 的解耦设计，反而比 Anthropic 当前的实现更”基础设施化”。

谁赢？目前看是双赢，但范式趋同。

如果你是 indie maker、做产品 demo 速度优先，Claude Code / Agent SDK 一站式更顺。如果你是企业级 Agent 团队，要严格的 sandbox 隔离、要切换 compute provider、要审批流和 tracing，OpenAI 新 SDK 的解耦设计可能更对路。

但更重要的趋势是：Agent 基础设施层正在成为 table stakes（入场费）。谁还在自己用 LangChain 拼 chain、用 subprocess 跑代码、用 Redis 存上下文，今年要认真考虑迁移路径了。

七、给开发者的三个落地建议

1. 别再自己造 sandbox 轮子。

不管你选 OpenAI 还是 Claude 那条路，把代码执行隔离这件事外包给 SDK，比自己 wrap docker 健壮十倍。

2. 从今天起把”工作区”当作一等公民来设计。

Manifest / 工作区清单这种思路，会比”prompt + tools”的旧抽象更接近 Agent 工程的真相。

3. 认真审视你的凭证流向。

如果你现在的 Agent 把 OpenAI key 直接塞进了模型可以访问的环境里，请这周内改掉它。新 SDK 的安全模型给了一个很好的参考实现。

* * *

2025 年我说过一句话：Agent 不是模型的下游，是模型的载具。

这次 OpenAI 的更新，本质是承认：载具的形状，正在被收敛。

harness + sandbox + manifest，会是接下来两年所有 Agent 框架的最小公约数。

如果你正在搭自己的 Agent 系统，这是一个很好的暂停时刻——回头看看，你的架构和这套抽象之间，差了几层？