OpenAI Agents API 详解：构建或下载 AI Agent 前要检查什么

先看结论：Agents API 改变了什么

OpenAI 在 2026 年 9 月 10 日公布 Agents API 公测版，把 Codex 背后的长任务运行框架做成开发者可以调用的服务。开发团队不必从零搭建 Agent 循环、上下文管理、工具协调和会话进度，而是可以让 OpenAI 负责运行框架，再决定 Agent 能够做什么。OpenAI 表示，公测期间不会额外收取 Agents API 费用，但模型 token 和工具使用仍然会产生正常成本。

这并不意味着所有项目都适合托管 API。真正需要比较的是控制权。如果产品要求自定义存储、应用自己掌握审批、私有执行环境或高度确定的流程，Agents SDK 或 Responses API 可能更合适。如果难点是让 Agent 长时间处理文件、代码、工具和子 Agent，那么托管框架可以减少大量基础设施工作。

为什么开发者应该关注这次发布

OpenAI 官方 Agents API 公告介绍了基于开源 Codex harness 的云端 Agent。OpenAI 负责维护运行框架，开发者可以查看公开基础并接入自己的能力。这里的变化是，Agent 不再只是加了一段提示词的模型请求，而是包含进度、工具、上下文、执行环境和失败恢复机制的运行时。

OpenAI 文档给出了三条路线。Agents API 总览适合希望由 OpenAI 管理框架并保存进度的长任务。Agents SDK是代码优先的方案：应用自己负责部署、存储、工具和审批，SDK 运行 Agent 循环。Responses API 则提供更底层的模型调用和自定义编排能力。

这套比较方法不只适用于 OpenAI。选择软件时，更有价值的问题是：谁拥有运行时？哪些部分能够检查、替换和审计？

托管框架可以替你处理哪些工作

生产级 Agent 不只需要一条好提示词。它还要在工具调用后继续执行，在长任务中保留有效状态，在上下文过大时压缩信息，协调专业子 Agent，处理文件，并报告进度。演示程序往往把这些细节隐藏在一个请求中，因此团队容易低估它们。

Agents API 面向的就是这一层运行能力。OpenAI 公告强调了长会话、工具、上下文管理、中间结果，以及 Agent 处理文件和运行代码的环境。当前文档还介绍了自动上下文压缩、多 Agent 编排、程序化工具调用、MCP 和可选沙箱。

这对想快速测试研究助手、代码维护、数据分析、事故响应或客服后台的团队很有吸引力。但它也带来新的责任：token 和工具成本、权限、数据边界、失败恢复，以及持续评估行为的工作。

Agents API、Agents SDK 和 Responses API 怎么选

如果难点是运行一个持久、会使用工具的 Agent，可以考虑 Agents API。它适合需要较长运行时间、文件或代码，并且希望使用 Codex 风格托管框架的任务。交换条件是运行时控制较少，但从原型走向服务的路径更短。

如果应用必须拥有循环和周边产品逻辑，选择 Agents SDK。它适合自定义数据库、应用控制的人工审批、专用工具路由、私有部署，以及需要紧密嵌入 TypeScript 或 Python 服务的流程。官方快速入门展示了代码优先路径：安装 SDK、定义 Agent、运行它，再逐步加入工具、交接、护栏和追踪。

如果你需要直接控制请求、会话状态、工具调用或自定义编排图，可以选择 Responses API。多 Agent 指南说明根 Agent 如何把独立工作分给子 Agent，同时应用仍要执行开发者定义的函数并处理返回结果。

可以先设想第一次失败的情况。如果问题是长任务后丢失上下文，托管会话可能有帮助。如果问题是 Agent 调用了敏感工具，而企业需要精确审批策略，那么应用掌握编排通常更重要。

沙箱其实是安全边界

能够读文件、运行代码或访问外部服务的 Agent 很强大，也因此构成安全边界。在采用公测版前，要写清楚 Agent 能访问哪些数据、代码在哪里执行、允许访问哪些网络地址、密钥如何暴露，以及工具收到异常输入时会发生什么。

OpenAI 描述了托管沙箱、自有基础设施、合作伙伴沙箱或不使用沙箱等选项。不要把它当成简单开关。原型可以接受较宽权限，生产 Agent 则应该使用最小能力、明确审批、审计日志和不会重复危险动作的恢复路径。

MCP 和程序化工具调用会让集成更容易，也会扩大权限面。建议从只读工具开始，用严格 schema 拒绝含糊参数，把写操作放在审批之后，并记录调查所需的精确输入和输出。

实际评估清单

在选择运行时或下载新的 Agent 工具前，使用同一套小测试：

1. 长任务连续性： 超时、工具失败或上下文压缩后能否恢复？
2. 工具纪律： 是否只调用必要工具，参数有效，并且知道什么时候停止？
3. 人工控制： 人能否批准、拒绝、修改或中断重要操作？
4. 数据处理： 是否说明保留、训练使用、加密、删除和地域处理？
5. 可观测性： 能否查看追踪、子 Agent 消息、工具调用、成本和结果？
6. 成本边界： 能否设预算、限制并发并发现失控循环？
7. 可迁移性： 公测变化后能否带走提示词、工具、状态和评估案例？
8. 质量证据： 是否有真实任务和回归集，而不是一个漂亮演示？

想寻找更多开发和效率软件，可以先在 BTTC 软件目录建立候选列表，再用接近真实权限和数据的流程测试。目录适合发现工具，不能替代安全审查。

Agents API 目前适合什么场景

它最适合快速验证研究、多来源分析、需要工作区的代码任务、运维分析和内部长流程。对于短小、确定性强、受严格监管，或已经可以用普通 API 加少量代码解决的任务，托管 Agent 的优势可能不明显。

更稳妥的早期架构通常很窄：一个边界明确的 Agent、少量工具、可见预算和人工复核点。只有当工作能拆成独立部分时才加入子 Agent。OpenAI 的多 Agent 文档也提醒，并行委派可以提高专注度和速度，但会增加 token 使用；如果步骤相互依赖，收益可能很小。

常见问题

Agents API 和 Agents SDK 是一回事吗？

不是。Agents API 在 OpenAI 服务中运行托管框架；Agents SDK 在你的应用中运行，并让团队更多控制部署、存储、工具和审批。

使用托管框架后还需要评估吗？

需要。托管运行时可以减少基础设施工作，但仍要准备真实任务、安全测试、成本监控和回归检查。

第一个 Agent 应该一开始就使用多个子 Agent 吗？

通常不应该。先从一个边界清晰的 Agent 开始，只有在研究、复核或实现可以并行，并且额外 token 成本值得时再扩展。

Agents API 公测版免费吗？

OpenAI 9 月 10 日的公告称公测期间没有额外 Agents API 费用，但 token 和工具仍按正常方式计费，因此必须测量实际支出。

总结

Agents API 的意义在于把 Agent 基础设施变成了一个软件选择。你可以用托管的 Codex 风格框架处理长任务，用 Agents SDK 把运行时留在应用中，也可以通过 Responses API 控制更底层流程。选择标准不是宣传热度，而是谁掌握状态、工具、审批、执行、观测和错误恢复。先用窄任务、严格权限、真实评估和迁移计划验证，再让 Agent 接触重要系统。