OpenAI Agents API 与 Agents SDK 与 Responses API：2026 年你应该基于什么来构建？

OpenAI 的智能体技术栈在 2026 年 9 月发生了重大变化。新的 Agents API 引入了托管的 Codex 执行框架，用于持久化的云端智能体，而较旧的 Agents SDK 则进入了功能完备的维护阶段。Responses API 仍然是希望直接调用模型或自行掌控智能体循环的应用程序所使用的较低层级接口。这三者并非同一事物的三种可互换封装：它们将运行时边界置于不同的位置。

架构已经改变：选择的是运行时边界，而不是库

重要的决策不再只是“我应该安装哪个 SDK？”而是由谁拥有执行框架、智能体循环、持久化会话状态、上下文压缩、恢复、执行环境和应用程序生命周期。

OpenAI 当前的 Agents 概览明确说明了这一边界。Agents API 运行托管的 Codex 执行框架，并管理编排以及持久化会话状态。Responses API 提供模型响应和托管能力，而由你的应用程序拥有周围的智能体循环。Agents SDK 在你的应用程序中运行循环，如今已功能完备，而不再是重大新智能体功能的前进路径。

简要对比

1. Agents API：托管执行框架，持久化云端智能体

Agents API 通过 OpenAI 托管的服务公开 Codex 执行框架。OpenAI 管理会话、编排、上下文压缩和恢复。你的应用程序仍然提供工具并选择执行环境。

最后这一点区别很重要。“托管智能体”并不一定意味着“所有计算都在 OpenAI 内部运行”。Agents API 架构支持无环境、OpenAI 托管环境，或连接到托管执行框架的自托管环境。使用自托管环境时，你的应用程序负责配置、重新连接、关闭和持久化文件，而执行框架仍由托管方管理。

因此，Agents API 是一种运行时服务，而不仅仅是一种请求格式。会话可以持久化、流式传输进度、接收额外任务、使用工具、处理文件，并在长时间运行的工作中恢复。

使用 Agents API 你能获得什么

• 托管的 Codex 执行框架，无需自行构建和运营主要的智能体循环。
• 持久化会话，适用于跨多轮和长时间运行的任务。
• 托管的编排、上下文压缩和恢复。
• 根据工作负载需求，可选择 OpenAI 托管或自托管的执行环境。
• 用于进度和生命周期事件的流式传输和 Webhook。
• OpenAI 明确推荐用于新智能体应用的平台方向。

你仍然需要负责的部分

• 你的产品和应用服务器。
• 函数工具实现和业务逻辑。
• 围绕你自己系统的授权和策略决策。
• 当你选择自托管计算时的执行环境生命周期。
• 评估、验收标准、领域特定的防护措施，以及决定智能体被允许做什么。

2. Responses API：掌控循环，使用平台原语

当你希望使用 OpenAI 模型和工具能力，而不想将整个智能体运行时委托出去时，Responses API 是更低层级的选择。OpenAI 将 Responses 描述为新项目推荐的 API 原语，以及 Chat Completions 的演进，具备内置工具、多轮状态选项、多模态输入和智能体工具使用能力。

一个 Responses 请求本身可以调用工具，但当你围绕它构建智能体时，你的应用程序仍需负责更大的工作流。这意味着你的代码决定如何持久化应用状态、何时继续、如何恢复、如何协调专家、如何压缩长历史记录，以及如何表示可恢复的工作。

这本身并不逊色。当智能体行为必须深度嵌入现有应用逻辑、当你需要自定义状态模型，或当托管式运行框架会隐藏你真正需要的控制权时，这就是正确的边界。

3. Agents SDK：仍受支持，但不再是默认的前进路径

Agents SDK 仍然是一个开源框架，用于在你的应用程序中运行智能体工作流。它在 TypeScript 和 Python 中提供智能体定义、工具、交接、护栏、追踪、会话和运行器循环。

但其战略地位已经改变。OpenAI 现在将 Agents SDK 标记为功能完备：维护、安全修复、关键错误修复和兼容性工作仍在继续，但不计划推出重大新功能。OpenAI 推荐新应用程序使用 Agents API。

这并不意味着现有的 SDK 应用程序应立即重写。它意味着架构不应再假设 SDK 是下一个重大智能体运行时能力的落点。

Codex SDK 的定位

当前的选择并不是简单的三岔路口。OpenAI 的运行时概览将 Codex SDK 列为在你运营的基础设施中运行 Codex 运行框架的选项。这在架构上既不同于托管的 Agents API，也不同于 Agents SDK。

如果你的真实需求是“我想要 Codex 运行框架，但我需要自己运营它”，那么 Codex SDK 就是值得评估的界面。如果你的需求是“我想掌控围绕模型调用的循环”，请评估 Responses。如果你的需求是“我已经有一个可用的 Agents SDK 应用程序”，现有 SDK 可以继续有效，同时你可以根据其维护状态进行规划。

运行时所有权测试

有用的架构决策始于确定你的团队必须拥有什么。将每项需求评分为必须控制、倾向于控制或倾向于托管。

新系统的决策树

什么不应驱动决策

迁移是架构变更，而不是重命名导入

从 Agents SDK 迁移到 Agents API 会改变所有权归属。在 SDK 中，循环运行在你的应用内。在 Agents API 中，OpenAI 运行执行框架和会话，而你的应用通过任务、事件、工具和环境边界进行集成。

因此，真正的迁移计划需要梳理会话状态、自定义编排、交接、工具执行、审批、存储、追踪、重试、故障恢复、环境生命周期，以及任何特定于提供商的抽象。代码量可能下降，但运维假设会发生变化。

迁移清单

• 智能体定义和指令所有权。
• 工具定义以及每个工具的执行位置。
• 交接、管理者/专家模式以及子智能体行为。
• 会话标识符、对话状态、可恢复性和历史保留。
• 人工审批和中断语义。
• 自定义上下文裁剪或压缩逻辑。
• 追踪、评估、可观测性和生产调试。
• 自托管文件、容器、私有网络访问或其他执行依赖。
• 提供商抽象或非 OpenAI 模型依赖。
• 重试、超时、幂等性、恢复和生命周期假设。

公开测试版改变了风险模型

Agents API 是新智能体应用的推荐方向，但它也处于公开测试阶段。这些事实并不矛盾。战略方向回答的是“平台将走向何方？”测试版状态回答的是“我应该为多少接口和运维变化预留预算？”

对于生产系统，应将集成隔离在应用边界之后。尽可能将领域状态、权限、审计数据和业务规则保留在供应商特定的会话对象之外。这样更容易吸收 API 演进，而不会让智能体运行时成为整个产品的真相来源。

一种实用的默认架构

对于许多新的 OpenAI 原生应用，2026 年一个合理的默认方案是：使用 Agents API 提供托管执行框架和持久会话，应用拥有领域服务和授权，业务操作使用显式函数工具，并根据数据和计算需求选择 OpenAI 托管或自托管执行。

这样可以让智能体运行时保持强大，同时不让它成为业务真相的所有者。应用仍然决定用户可以做什么、哪些数据具有权威性、哪些操作需要审批，以及如何验证结果。

什么会改变这个答案？

如果 Agents API 增加或移除能力、以不同的契约退出测试版、改变环境或定价边界，或引入减少所有权差异的迁移工具，那么建议就会改变。如果你的应用依赖提供商可移植性、自定义编排语义、仅本地执行，或托管执行框架无法支持的能力，建议也会改变。

对于现有的 Agents SDK 应用，答案还会随迁移成本而变化。如果系统稳定、经过充分评估，并且没有被 SDK 的功能完备状态所阻碍，那么立即迁移可能带来的风险大于价值。如果产品路线图依赖于仅在 Agents API 中提供的能力，那么延迟迁移可能会造成另一种债务。

局限性

本比较聚焦于运行时所有权和 OpenAI 所声明的平台方向。它不会针对特定工作负载对延迟、质量或总成本进行基准测试。这些属性取决于模型选择、工具使用、环境、任务长度、缓存、沙箱使用和应用架构。

Agents API 也足够新，生产经验仍在积累中。因此，设计应通过具有代表性的工作负载进行验证，而不是仅根据产品定位来选择。

结论

2026 年 OpenAI 智能体决策的核心在于运行时所有权。Agents API 意味着 OpenAI 拥有更多 harness 和持久会话机制。Responses 意味着你的应用程序拥有围绕平台原语的循环。Agents SDK 对现有系统仍然有效，但已不再是重大新智能体运行时功能的默认目标。

对于新应用程序，除非有实际需求推动你向技术栈更低层移动，否则应遵循平台方向。从 Agents API 开始，当你需要拥有循环时转向 Responses，当你需要将 harness 部署在自己的基础设施中时评估 Codex SDK，并在现有投资或临时能力缺口使其合理时保留 Agents SDK。

常见问题

术语表

主要来源与延伸阅读