OpenAI 在 9 月 10 日放出了 Agents API 的公开测试版。简单说，他们把支撑 Codex 和企业版 ChatGPT 的那套 agent 框架（叫 “Codex harness”）做成了托管 API——你不用再自己写上下文压缩、会话持久化、子代理编排这些容易出 bug 的基础设施代码了。我把官方文档和几份第三方技术分析对照读了一遍，这篇文章讲清楚它的能力边界、成本结构和几个不那么显眼的坑。
这东西到底解决什么问题
如果你之前做过 LLM agent 开发，大概率写过这三段「不写不行、写了也不增值」的代码：上下文窗口快满时自动压缩历史的逻辑、agent 任务跨重启续跑的持久化层、以及把大任务拆给子代理再合并结果的控制流。这三段代码每段都不难，但加起来几百行，而且每次换模型都可能要改。
OpenAI 把这些做成了 API 的内置能力。具体说，Agents API 的管理 harness 负责：
- 会话持久化：session 是 durable 的，能跨多个上下文窗口持续工作，自动压缩早期上下文
- 工具搜索：不把所有工具定义都塞进 prompt，按需加载相关定义，省 token 也保缓存
- 程序化工具调用：agent 可以并行调多个工具、链式操作、在代码里过滤合并结果
- 子代理：任务自动拆分给并行子代理，每个有独立上下文，主代理协调合并
OpenAI 在公告里给了一组数字：harness 设置（保留推理 + 上下文压缩）把 GPT-5.6 Sol 的 ARC-AGI-3 分数从 13.3% 拉到 38.3%，同时输出 token 减少 6 倍。Thrive Holdings 用它处理了 7000 份税务申报，准备时间缩短约三分之一。这些是官方说法，方向是对的——但具体数字你要自己测才知道，第三方技术分析也提醒了 “vendor-published customer quote” 要当作方向性参考而非基准测试。
5 分钟跑通第一个 Agent
先说环境要求：需要一个 OpenAI API Key（有余额的账户就行），Node.js 18+ 或 Python 3.8+。我用的是 Node.js，因为 openai npm 包 在 9/10 当天就发了 7.15.0 版本支持 Agents API。
安装 SDK：
npm install openai@latest最小可运行示例——创建一个会话，让 agent 在 OpenAI 托管沙箱里写 Python 脚本并执行：
import OpenAI from "openai";
const client = new OpenAI();
// 加 beta header（SDK 7.15.0+ 自动添加）
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output.",
},
environment: {
type: "openai_hosted",
},
input: "Write a Python script that prints a directory tree, run it, and show me the output.",
stream: true,
});
// 流式接收事件
for await (const event of session) {
if (event.type === "agent.session.turn.completed") {
console.log("Done!");
break;
}
console.log(event.type);
}官方文档描述的事件流大概长这样，你可以拿它对照自己的运行结果：
agent.session.created
agent.session.environment.ready
agent.session.turn.in_progress
agent.session.message.output_item // agent 输出了 Python 脚本
agent.session.tool.call // 调用了 shell 执行脚本
agent.session.tool.response // 拿到了脚本输出
agent.session.turn.completed这条链路是 Agents API 和普通 Chat Completions API 最大的体感差异：你不再拿一次性回复，而是看 agent 一步步真的去执行——它自己写脚本、自己跑、再把真实输出带回来。所以提示词里那句 “report the actual output” 不是修辞，是让 agent 把执行结果如实交回来。
四个核心概念
看懂了 quickstart，再回头看文档里的四个核心概念就清楚了：
Agent（代理）：模型 + 指令 + 工具 + MCP 服务器。这是你的”大脑”配置。
Environment（环境）：agent 执行命令和操作文件的地方。三种模式：
– openai_hosted：OpenAI 管的 Linux 沙箱，预装 Python/Node.js/CLI 工具
– self_hosted：你自己的基础设施，通过 executor 连接
– none：纯工具调用，没有沙箱执行能力（适合只调 API 的场景）
Session（会话）：durable 的代理实例。创建后可以发任务、看进度（流式或 webhook）、中途追加指令、甚至中断后恢复。
Events & Items：你发给 agent 的输入和 agent 的输出，包括消息、工具调用、产出物（artifact）等。
我在 之前写 Codex Harness 开源框架的文章里讲过 harness 的概念。现在 OpenAI 把那个 harness 做成了 API——相当于从「自己装框架」变成了「直接调 API」。
子代理并行：一行配置搞定
这是我觉得最有用的功能。如果你的任务可以拆成独立子任务，配一行 JSON 就能让 API 自动分配：
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
multi_agent: {
enabled: true,
max_concurrent_subagents: 3,
},
},
environment: { type: "openai_hosted" },
input: "分析 /workspace 下三个目录的代码质量，每个目录一个子代理，最后汇总报告。",
});主代理会把三个目录分给三个子代理，各自有独立上下文，并行分析，最后主代理合并结果。Cirridae（一家科技公司）报告说用这个功能后评估分数从 0.71 提到 0.85，延迟降了 4 倍。max_concurrent_subagents 这个参数值得留意——它直接决定你的并发成本上限，设成 3 就是最多同时跑 3 个沙箱。
成本：没有平台费，但沙箱有容器费
OpenAI 说 Agents API 没有额外平台费。准确说是没有一行叫 “Agents API” 的账单条目，但你实际会付三种费：
- 模型 token 费：按你选的模型的 API 价格
- OpenAI 工具费：web search 等内置工具按标准价格
- 沙箱容器费：如果用
openai_hosted沙箱，按标准容器价格计费
第三条容易被忽略。一个 durable session 本质上是一个保持运行的容器。如果你的 agent 会话跑几个小时，容器费是会累积的。Flowtivity 的分析提醒说 “a durable agent is a container that stays warm”，这是大实话。
跟 DeepSeek V4.1-Flash 那种「输入 8B/输出 16B 激活」的成本压缩思路不同，Agents API 省钱的方式不是降模型参数，而是通过上下文压缩减少重复 token 消耗、通过子代理并行减少串行等待。两种思路各有适用场景。
踩坑提醒
坑 1：数据驻留仅限美国。 OpenAI 文档明确写了 “The Agents API currently supports data residency only in the United States and does not support Zero Data Retention (ZDR)”。而且选 self-hosted 沙箱也不能改变这一点——session state 存在美国。如果你的应用有数据合规要求（比如欧盟 GDPR 或中国数据安全法），这一条是硬限制。
坑 2：function tool handler 必须在线。 如果你在代码里注册了 function tool（自定义工具函数），处理这些调用的 handler 必须持续在线。handler 不可用时 agent 会等待。这意味着你的应用服务器 uptime 直接影响 agent 可用性。别以为把任务丢给 OpenAI 就可以不管了。
坑 3：公测阶段 API 可能变。 现在的 API shape（四个对象、三种环境模式）在公测期间可能调整。写生产代码前先看 官方文档的最新版本。
坑 4：webhook 和 streaming 二选一。 streaming 适合实时看 agent 进度（比如给用户展示「正在分析…」），webhook 适合后台任务（不保持流连接）。但两种模式的事件类型和粒度有差异，混用容易漏事件。我建议先想清楚你的交互模式再选。
什么场景不建议用
如果你只需要简单的「调一个模型 API + 加几个工具」，Agents API 是过度工程。直接用 GPT 系列模型的标准 Chat Completions API 加 function calling 就够了，还更便宜。
Agents API 适合的场景是：任务需要多轮执行（agent 自己跑代码、看结果、再改）、需要跨上下文窗口持续工作、需要并行处理多个子任务。比如自动化代码审查、批量数据分析、持续监控+响应这类需要 agent 「长时间干活」的场景。
跟 Anthropic 的 CMA 企业平台比，Agents API 面向所有开发者（不需要联系销售），但有数据驻留限制。Anthropic 的方案更封闭但合规更灵活，OpenAI 的更开放但「美国 only」。
9 家合作方沙箱
除了 OpenAI 自己的沙箱，还有 9 家合作方提供执行环境：Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop、Vercel。如果你已经在用其中某一家的服务（比如 Vercel 做部署），可以直接用他们的沙箱，省得再配一套。
我对这条路径的判断是：优先选你已经付费的那家。因为 Agents API 本身不收平台费，真正会产生差异的是沙箱容器费——而容器费在你已有的云账单里往往有折扣或额度可抵。另外 Vercel 和 Cloudflare 这类边缘平台延迟更低，如果你的 agent 要和前端实时交互，这个差异比价格更值钱。
上手建议：拿 gpt-6-astra 建一个最小会话，先用 openai_hosted 跑通事件流，确认流式事件的类型和顺序符不符合你的预期，再决定是留在托管沙箱还是挪到合作方。一步到位改架构，容易在还没有体感的时候就把自己绕进去。
发表回复