OpenAI Agent SDK 与 Agents API 怎么选：控制权、成本与迁移

OpenAI 于2026 年 9 月 10 日推出了托管式 Agents API。如果会话状态、上下文压缩和故障恢复才是主要运维负担，应选它；如果应用必须自主掌控运行时、部署和数据链路，则应选 Agents SDK。比较 OpenAI Agents API 与 OpenAI Agent SDK，真正要权衡的是控制权和运维成本，因为托管服务不另收运行框架费用。

OpenAI Agent SDK 与 Agents API 该选哪个？

对于要交付长时运行智能体的小型平台团队，OpenAI Agents API 通常是更好的默认选择。OpenAI 负责运行 Codex harness，保存会话及其工作成果，压缩上下文，协调子智能体，并支持跨异步轮次恢复。这省掉了一整类很少能形成产品差异化的基础设施工作。OpenAI 已于2026 年 9 月 10 日将其作为公开测试版发布，并表示所有开发者均可使用。

假设一家已融资的初创公司后端团队不大，正在开发文档审查智能体，而且审批可能要等上几个小时，那么托管会话的价值会高于自主管理循环。有限的产品团队时间更应该投入策略、工具、评测和用户体验。

如果运行时控制不是偏好，而是硬性要求，那么 OpenAI Agents SDK 更合适。它在你的应用内部运行，部署、存储、审批逻辑、工具实现和状态策略都由你掌控。对于强制执行 Zero Data Retention（ZDR）政策的中型企业 CTO，目前应走这条路线，因为 Agents API 公开测试版不支持 ZDR。

如果资深开发者已经拥有成熟的 worker 集群、自定义遥测和经过验证的恢复链路，只为少维护一个并不复杂的循环而迁移，并不划算。SDK 能保留这些控制权，同时仍提供智能体、工具、handoff、护栏、会话、人工审核和追踪能力。

OpenAI Agent SDK 与 Agents API 一览

官方定义下，两者的核心差异在于编排在哪里运行，以及跨任务状态归谁所有。两种方案都能调用 OpenAI 模型和工具；无论选哪一种，模型 token 都不会免费。

实际判断很直接。如果智能体只是在现有服务中完成一次短请求，使用 SDK 所增加的所有权负担可能很小。如果它要编辑文件、等待审批、熬过断连、委派工作，并在第二天继续运行，那么生命周期状态每多一种，托管 API 就能少掉更多自建组件。

Harness 与沙箱是两个不同的架构决策

Agents API 管理智能体的核心循环，但并不强制所有工具都在 OpenAI 的计算资源上运行。OpenAI 将这套托管循环称为 Codex harness：它协调模型调用、工具使用、上下文、会话和子智能体。执行环境则是另一项独立资源，命令在那里运行，文件也在那里保存。

执行环境可以不存在，也可以由 OpenAI 托管或由用户自托管。没有执行环境时，harness 仍可调用远程 MCP 服务器，并把函数调用发给你的应用，但它没有内置 Bash、apply-patch 工具或工作区文件。使用 OpenAI 托管沙箱时，Linux 工作区由 OpenAI 配置。使用自托管环境时，你的执行器负责运行命令和文件操作，托管 harness 则发出请求。架构指南明确区分了这两层。

理解这一区别，可以避开两种代价高昂的误判。第一，仅仅因为代码必须在自己的 VPC 内运行，就直接选择 Agents SDK，还为时过早：Agents API 可以连接自托管环境。第二，因为希望 OpenAI 运行一切而选择 Agents API，同样草率：应用函数处理器仍在你的代码中执行；如果使用自托管执行器，资源配置、重新连接、关闭和文件持久化也仍由你负责。

对于私有数据分析工作流，托管 harness 可以向应用服务发送 SQL 函数调用，而不必获得通用 shell。对于编程智能体，它可以使用 OpenAI 托管沙箱。对于专有构建系统，它又可以连接你自己的隔离 worker。这是在同一个托管编排层下实现的三种执行模式。

长时任务的会话所有权：Agents API 胜出

当任务生命周期长于一次应用请求时，Agents API 更具优势。一个会话会保留智能体配置、对话和已保存的工作。会话空闲时，新输入会启动异步轮次；会话正在工作时，新输入则可引导当前轮次。应用既可以订阅事件流，也可以通过 webhook 接收状态变化。

当会话接近上下文上限时，OpenAI 还会负责上下文压缩。所谓压缩，就是用更精简的保留表示取代较早的细节，让智能体可以跨多个上下文窗口持续工作。解释起来简单，真正稳定运营却很难：保留的摘要既要留下决策、工具结果和未完成工作，又不能永久携带此前的每一个 token。

恢复能力是一个不太显眼、却很重要的优势。事件流不会重放错过的事件。连接中断后，应用可以重新获取会话及已保存条目，再从持久记录继续，而不是依赖进程内存重建一轮智能体执行。会话指南说明了已完成轮次、失败轮次、取消操作和仅仅处于空闲状态的会话之间的区别。

以一家已融资初创公司的合同审查智能体为例。它先读取文档，再请专业子智能体比对条款，暂停等待法务审批，之后接收修正，最后产出交付物。产品价值来自审查本身；会话重放、上下文压缩、中断的事件流和轮次恢复都属于运营成本。托管 API 正是为吸收这类工作负载而设计的。

需要坦白的一项限制是计费精度。智能体可能进行多次模型调用，而根智能体、子智能体、重试、工具和沙箱都会产生成本。OpenAI 表示，Agents API 的 usage 字段仅为尽力统计，可能为 null，也可能在之后变化，不能视作最终账单。reasoning token 按输出 token 计算，缓存输入仍会计费。调试时可参考 usage 指南，财务管控则应与账单数据核对。

控制台同样属于可观测性边界的一部分。公开测试版的客户 API 不支持详细 trace 获取和外部 trace exporter。如果遥测管道要求以编程方式导出每一条 trace，这项缺口比一个精致的托管控制台更值得关注。

运行时与部署控制：Agents SDK 胜出

如果应用必须精确决定一次执行如何启动、暂停、恢复、存储状态、分发工具以及处理失败，就应选择 Agents SDK。它的 runner 负责智能体循环和 handoff，但循环本身位于你的服务内部。因此，产品代码可以在每一次状态转换外层加入自己的事务、队列、限流、审批记录和遥测。

SDK 提供 TypeScript 和 Python 版本，Python 仓库采用 MIT License，因此软件包不收取按席位计算的许可费。OpenAI 模型调用、托管工具、沙箱服务商以及运行应用所需的计算资源仍是独立成本。SDK 指南将其定位为代码优先的应用方案，由应用自行掌控部署、存储、审批和运行时集成。

状态管理灵活，但不会自动完成。SDK 应用可以重放 result.history，把 SDK 会话持久化到自己的存储，关联一个 OpenAI Conversations ID，或接续此前的 Responses API response ID。每种做法都有价值，但智能体运行指南提醒：如果没有主动协调不同层级，同时使用本地重放与服务端托管状态，可能会导致上下文重复。

在受监管的内部服务中，这种灵活性很有价值。可以把一次审批及其后的智能体续跑纳入同一数据库事务，将状态放在获批区域内，让工具在私有网络控制之后运行，并把智能体执行接入现有任务系统。也可以通过 SDK 的模型层集成其他模型或提供商，而不必将托管 Codex harness 设为永久的编排边界。

代价在于运维所有权。进程崩溃后如何恢复，由你解决；队列重复投递后的幂等性，由你解决；历史增长、压缩策略、工具重试、状态迁移和部署回滚，也都由你解决。SDK 把这些事项的控制权交给你，但只有应用真正需要这份控制时，它才有价值。

成本对比：Agents API 不另收 Harness 费用

如果两种运行时使用相同的 OpenAI 模型、token 组合和工具调用，那么 token 与托管工具账单也相同。价格已于 2026 年 9 月 11 日对照 OpenAI 实时页面核验。GPT-6 Astra 标准短上下文价格为每 1 million 输入 token $10.00、每 1 million 输出 token $50.00。Web search 每 1,000 次调用收费 $10.00，搜索内容 token 再按所选模型费率计费。托管式 Agents API 本身不另收费用。

下面用一组统一口径的工作负载来计算。它们是场景假设，并非实际生产数据：

• 每月 1,000 个智能体任务。
• 每个任务在 GPT-6 Astra 上合计使用 10,000 个未缓存输入 token 和 2,000 个输出 token；返回的搜索内容计入输入额度。
• 每个任务调用一次 web search。
• Agents API 托管方案为每个任务新开一个 1 GB 容器计费会话，按已公布的 $0.03 费率计算。复用沙箱会降低这项支出。
• SDK 方案使用一个共享 worker，假定每月成本为 $40 且容量足够。不计存储、网络和人力。

模型部分每个任务的输入成本为 $0.10，输出成本为 $0.10，合计 $0.20。按假设的 12,000-token 组合折算，每 1,000 个混合模型 token 成本为 $0.0167。一次 web search 再增加 $0.01，因此每个任务共同产生的 OpenAI 支出为 $0.21。

在 1,000 个任务的规模下，如果每个任务都新开一个 1 GB 托管容器，Agents API 总成本为 $240：模型和搜索这部分共同支出为 $210，容器为 $30。SDK 方案总成本为 $250：同样是 $210 的 OpenAI 用量，再加假设中的 $40 worker。仅看直接支出，低用量下托管容器胜出。

在 10,000 个任务的规模下，托管方案升至 $2,400：共同支出 $2,100，容器支出 $300。按共享 worker 假设，SDK 方案为 $2,140。直接计算资源成本的交叉点是每月 1,334 个全新容器会话——这是按每次会话 $0.03 计费后首次超过 $40 的整数会话数。

最值得关注的是自托管 Agents API。如果 Agents API 使用同一个假定成本为 $40 的 worker，那么它在 10,000 个任务下的总成本同样是 $2,140。Codex harness 依旧由 OpenAI 托管，但执行成本与 SDK 场景一致，因为 OpenAI 不额外收取 harness 费用。

现金账单仍遗漏了最大的变量：工程时间。超过交叉点后，如果 SDK 每月要消耗数小时的平台开发工作，那么省下 $260 的计算成本并无意义。低于交叉点时，一套成熟的 SDK 系统也可能几乎不需要额外维护成本。

无论采用哪种架构，如需设置严格预算控制，都应将工作负载估算与 AI 智能体 API 预算控制 2026中的项目级保护措施结合起来。估算只是规划工具，不是强制执行机制。

从 SDK 迁移到 Agents API：要付出什么成本？

从 Agents SDK 转向 Agents API 是运行时迁移，不是换一个软件包名称。智能体定义和工具 schema 可能看起来相似，但 session ID、SDK 会话、Responses conversation、Agents API 会话和沙箱都是不同资源。应把状态视为需要跨越边界的数据，而不是假定某个标识符可以原样移植。

1. 1

   冻结行为契约

   记录当前的智能体指令、工具 schema、审批节点、输出形式、token 预算和失败策略。对比期间保持模型和工具不变，避免把质量变化误判为运行时改进。

2. 2

   映射智能体与工具配置

   把模型、指令、MCP 连接和函数定义迁入 Agents API 配置。应用函数处理器仍需要一个能够接收调用并返回结果的服务；编排迁移后，它们不会自动变成托管服务。

3. 3

   划清状态边界

   将新对话创建为 Agents API 会话，并把相应 ID 保存在应用的对话记录旁。迁移期间应继续支持读取旧 SDK 历史。如果旧上下文必须延续，只把必要的业务状态转换为明确输入，不要把 SDK 会话假装成 Agents API 会话。

4. 4

   替换生命周期管道

   用会话创建、事件、已保存条目、required action、webhook、取消和删除，替代进程内 runner 入口。每个 webhook 和函数结果都要加入幂等保障，因为托管状态并不能消除应用边界上的重复投递风险。

5. 5

   影子运行并做回归测试

   让同一套评测集分别跑过两条路径。比较任务成功率、输入与输出 token 总量、工具调用、耗时、恢复表现和人工干预。只有新路径达到旧契约要求后，才迁移流量。

一份示例迁移预算能让取舍更具体。假设现有工作流包含三个函数工具、持久会话和人工审批。按每小时 $150 计算，共安排 24 个工程小时：配置与工具映射 6 小时，会话和生命周期工作 8 小时，webhook、恢复与幂等处理 6 小时，回归与成本检查 4 小时。一次性迁移成本为 $3,600。

如果托管式上下文压缩、恢复、会话和编排每月能节省假定的 6 个工程小时，人力成本每月可减少 $900，四个月即可回本。如果现有 SDK 路径只是偶尔需要维护，回本就可能遥遥无期。这里真正重要的是这些假设：迁移的理由应是运维工作减少，而不是 token 更便宜。

哪些团队不该迁移到 Agents API？

如果公开测试版的数据管控无法通过采购要求，就不要迁移。目前的 Agents API 概览明确说明，数据驻留仅限美国，且不支持 Zero Data Retention。自托管沙箱无法改变这项政策，因为 harness 和会话仍位于托管服务中。

出现以下任一情况，都应继续使用 Agents SDK：

• 运行时必须在应用直接控制的自定义调度器、事务边界或延迟范围内执行。
• 存储、trace 导出或数据驻留政策无法适配托管式公开测试版。
• 智能体依赖灵活的提供商选择或模型抽象，不应绑定 Codex harness。
• 现有 SDK 系统已经可靠地处理上下文压缩、恢复、可观测性和部署，而且日常维护很少。
• 大多数任务短暂且无状态，持久化托管会话省不掉多少基础设施。

公开测试版也意味着要考虑发布阶段。OpenAI 表示，在正式可用前会快速迭代。变更控制周期严格的团队，可以现在先做评估，等契约稳定后再迁移。

SDK 同样有不该选的时候。精简型初创团队不应仅仅为了规避理论上的锁定风险，就悄悄重建会话、恢复、沙箱生命周期和编排。产品根本用不到的控制权，只会变成维护债务。

如果智能体需要执行代码，还应单独比较环境层，可参考 2026 年最佳 AI 智能体代码沙箱。选择沙箱无法回答编排状态应由谁掌控。

客户数据只能提供方向，不能直接套用

早期数据倾向于托管方案，但它们来自 OpenAI 在 9 月 10 日发布的上线文章中的客户报告，并不是独立的对照基准。SafetyKit 报告每个案例的成本降低 60%。Hypha 报告在拆分托管 harness 与自有沙箱后，智能体失败响应减少 86%。Ciridae 报告评测得分从 0.71 提高到 0.85，延迟降低 4x。

这些结果说明运行时边界确实可能带来影响，却不能证明你的迁移能节省多少，因为原文没有对客户此前的架构、模型组合、token 用量、任务难度或工程人力做统一口径处理。应把这些报告作为开展影子评测的理由，而不是拿来做预测。

OpenAI Agents API 与 Agents SDK 常见问题

为什么要使用 OpenAI Agents SDK？

当应用需要直接掌控部署、存储、审批决策、工具实现和运行时循环时，应使用 OpenAI Agents SDK。它提供 OpenAI 的智能体基础组件，但不要求把编排迁移到托管式 Agents API。

OpenAI Agents SDK 和 PydanticAI，哪个更适合我？

这是另一项框架对比。首先要确定，是通过 Agents API 让 OpenAI 管理 Codex harness，还是采用由应用掌控的 SDK 运行时；如果选择后者，再在这条路径内比较不同 SDK 框架。

哪个 AI Agent SDK 最好？

没有任何 SDK 能适合所有架构。如果 TypeScript 或 Python 循环、工具、handoff、护栏、会话以及 OpenAI 集成符合应用需求，同时又希望自行掌控部署，那么 OpenAI Agents SDK 是很合适的选择。

OpenAI Agent SDK 免费吗？

Python Agents SDK 采用 MIT 许可，因此软件包本身不收许可费。模型调用、付费工具、沙箱服务以及运行应用的基础设施仍需付费。

OpenAI Agent SDK 怎么用？

安装官方 TypeScript 或 Python 软件包，使用指令和工具定义智能体，选择一种状态策略，再在自己的应用内运行。只在工作流确有需要时，添加审批、持久化、追踪和沙箱。

一个 OpenAI 智能体要多少钱？

把模型输入、缓存输入、输出、工具调用、沙箱或应用计算资源、第三方服务和运维人力全部相加。Agents API 不另收 harness 费用；按本文假设，与每月 $40 的共享 worker 相比，直接环境成本会在每月 1,334 个全新 1 GB 容器会话时反转。

OpenAI API 免费还是收费？

OpenAI API 的模型与付费工具用量会按照 API 定价计量收费。ChatGPT 套餐属于另一份产品合约，不能覆盖 Agents API 或 Agents SDK 应用的 API 用量。

为什么要花 $20 购买 ChatGPT？

这是 ChatGPT 订阅决策，与 Agents API 和 SDK 的选择无关。ChatGPT 订阅按照相应套餐条款提供 ChatGPT 产品访问权限；OpenAI API 用量单独计费。

OpenAI Agent Builder 免费还是收费？

Agent Builder 曾包含在标准 API 模型定价内，但它不是本文比较的任何一种运行时。OpenAI 表示正在逐步停用 Agent Builder，并计划于 2026 年 11 月 30 日关闭。

下周一就做这件事

下周挑一个长时运行的工作流，做一次影子对比。保持模型、指令、token 预算、工具和评测集不变。把新的测试对话放到 Agents API，现有用户历史继续走 SDK 路径；如果要单独衡量托管 harness 的价值，两边还应使用相同的执行环境。

记录任务成功率、token 总量、付费工具调用、沙箱计费会话、恢复事件、人工干预和工程时间。如果省下的会话与恢复工作超过失去控制权的代价，就选 Agents API。如果托管服务不满足数据要求，或节省的运维时间不足以收回迁移成本，就保留 Agents SDK。

更换智能体运行时之前，先领取 AI 业务工作流审计清单。