从OpenAI Agents SDK迁移到Agents API：架构上究竟有哪些变化？

从 OpenAI Agents SDK 迁移到 Agents API 并不是重命名导入。核心架构边界发生了变化：SDK 在你的应用程序内部运行智能体循环，而 Agents API 在 OpenAI 一侧运行托管的 Codex 执行框架和持久会话。因此，迁移问题不是“哪些类映射到哪些端点？”，而是“哪些运行时职责跨越边界转移，哪些留在我们的应用程序中，哪些需要重新设计？”

迁移是从应用程序拥有的循环转向托管执行框架

在 Agents SDK 中，一次运行是应用程序级别的一轮。SDK 运行器调用模型、检查输出、执行工具、遵循交接并持续进行，直到到达停止点。你的进程承载该循环，因此拥有其生命周期。

在 Agents API 中，OpenAI 运行执行框架。会话是智能体配置的持久实例，它接受任务、产生事件、可以暂停以等待所需操作，并可以随时间继续。OpenAI 管理会话、编排、上下文压缩和恢复；你的应用程序发送工作、处理函数工具、接收事件，并可选地管理自托管执行环境。

这种所有权转移就是迁移。其他一切——API 语法、工具模式、事件处理、会话 ID——都由此而来。

运行时边界迁移图

哪些内容可以在不改变所有权的情况下从概念上迁移

若干应用程序概念即使表示形式发生变化，也能顺利通过迁移保留下来。模型、指令、JSON-schema 函数定义、MCP 访问、工具描述和结构化输出要求仍然是智能体配置关注点。

OpenAI 的 Agents API 配置模型明确通过模型、指令、工具、推理和输出行为来定义智能体。函数工具仍然是应用程序代码：执行框架请求函数调用，你的处理程序返回结果。OpenAI 还指出，与 Responses API 一起使用的函数实现可以在 Agents API 会话流程中复用。

哪些内容不应一对一迁移

危险的迁移模式是在 Agents API 中重建每个 SDK 运行时抽象。这可能导致你为托管执行框架付费，同时仍在应用程序中运行一个影子执行框架。

步骤 1 — 将领域状态与代理会话状态分离

在接触 API 调用之前，先对你 SDK 应用当前承载的状态进行分类。有些状态仅用于维持代理对话的推进。其他状态则是业务事实：用户权限、项目状态、订单数据、工作流审批、客户记录、文档版本、策略状态或应用配置。

第二类状态不应依赖于 Agents API 会话。持久会话对代理而言是有用的连续性，但它不能替代你产品的真实来源。如果会话消失、过期、被重建或更改实现，你的应用仍必须知道什么是真实的。

状态放置测试

	状态类型	首选所有者	原因
对话连续性
业务事实
持久工件
工作暂存状态

步骤 2 — 将运行器思维转变为会话与事件思维

SDK 应用通常以调用 run 并接收结果的方式思考。Agents API 则以持久会话的方式思考，其轮次可以异步运行。向空闲会话发送消息会启动工作；在活动轮次期间发送消息可以引导它。进度通过流式传输或 webhook 到达。

这会影响应用架构。长时间运行的生产工作不应依赖于单个 HTTP 请求保持存活。你的产品需要稳定的会话标识符、生命周期持久化、webhook 验证、幂等处理器，以及进程重启后协调当前会话状态的方法。

步骤 3 — 围绕所需操作重新设计函数工具

函数工具仍然是重要的应用边界。你在代理配置中定义函数及其 JSON schema。当 harness 需要该函数时，会话可以进入需要操作的状态。你的应用检索所需操作，执行业务逻辑并返回结果。

这意味着函数实现应可安全恢复。webhook 可能在另一个工作进程处理时被投递。网络故障可能发生在外部副作用之后但在结果返回之前。因此，迁移是向重要工具添加调用 ID、幂等键、显式授权、超时策略和审计记录的好时机。

步骤 4 — 决定执行应发生在何处

Agents API 将托管 harness 与执行环境分离。代理可以在没有专用环境的情况下运行，在 OpenAI 托管的沙箱中运行，或通过与会话连接的自托管环境运行。

这产生了一个 SDK 应用可能从未明确做出的迁移决策：哪些代码应作为应用函数运行，哪些代码属于沙箱，哪些工作负载需要你控制的基础设施？

步骤 5 — 用显式生命周期处理替代隐式恢复

托管 harness 提供会话级恢复，但你的应用仍然拥有其周围的每个外部依赖。自托管环境需要配置、重新连接和关闭。函数处理器可能失败。webhook 可能被重试。产品侧状态可能在代理空闲时发生变化。

因此，迁移需要两种恢复模型：代理运行时恢复和业务操作恢复。第一种越来越多地由 Agents API 管理。第二种仍然是你的责任。

第6步 — 围绕新的追踪边界重建可观测性

Agents API 会话会暴露事件、保存的历史记录、轮次、工具调用、子代理和令牌使用情况。OpenAI 还在平台中提供会话日志和追踪导出。

不要因为平台追踪有所改进就丢弃你的应用可观测性。产品日志仍然需要将代理会话与用户身份、授权决策、领域对象、工具副作用、审批记录和最终接受的结果关联起来。有用的生产追踪是代理运行时证据与业务运行时证据之间的连接。

第7步 — 在更改运行时之前保留评估

迁移可能看起来成功，因为新系统仍然产生看似合理的答案，同时悄然改变了工具选择、会话连续性、交接行为、延迟或故障恢复。在切换运行时之前建立行为基线。

基线应包括代表性任务、预期工具调用、禁止操作、审批点、状态连续性、恢复场景和最终输出验收标准。尽可能对相同案例运行新旧架构。

迁移验证测试

在切换之前验证新运行时

1

1. 冻结行为基线

捕获代表性 SDK 追踪、预期输出、工具路径、审批点和失败案例。

2

2. 清点状态所有权

将每个状态字段标记为代理会话状态、权威领域状态、持久工件或临时工作状态。

3

3. 复用稳定的工具实现

将业务功能保留在应用接口之后；尽可能只替换面向代理的集成。

4

4. 构建一个 Agents API 垂直切片

迁移一个生产形态的工作流，包括会话创建、工具、事件、环境和持久化。

5

5. 注入中断

测试进程重启、webhook 重试、函数超时、自托管环境重连和过期领域状态。

6

6. 比较追踪，而不仅仅是答案

对照基线验证工具选择、授权、证据路径、状态转换和副作用。

7

7. 运行影子流量

在可行的情况下，在使新运行时成为权威之前重放或镜像代表性任务。

8

8. 在可逆边界之后切换

保持集成适配器和回滚能力，直到生产行为稳定。

迁移期间要衡量什么

何时还不要迁移

现有的 Agents SDK 应用不会仅仅因为平台方向改变就变成糟糕的架构。OpenAI 继续维护、安全修复、关键错误修复和兼容性工作。如果应用稳定、评估良好且没有受阻的路线图需求，立即迁移运行时可能并不合理。

• Agents API 中尚不提供所需的 SDK 能力。
• 迁移会扰乱关键生产期，且无法带来近期价值。
• 应用依赖于尚未在托管 harness 上验证的自定义编排语义。
• 提供商可移植性是硬性要求，且当前 SDK 抽象具有重大价值。
• 你的团队尚未将业务状态与代理运行时状态分离，导致切换不安全。
• 新的 Agents API 行为尚未针对代表性生产工作负载进行测试。

迁移何时变得具有战略重要性

当产品需求与托管 harness 一致时，迁移变得更具吸引力：持久的长时运行工作、平台管理的上下文压缩和恢复、更新的代理运行时能力、沙箱执行、更丰富的托管生命周期管理，或希望减少应用运营的编排代码量。

最强的信号不是“旧 SDK 功能完备”。而是“我们的路线图现在依赖于那些自然归属于托管 Agents API 运行时的能力。”

什么会改变这个答案？

如果 OpenAI 发布自动化迁移工具、引入显式兼容层、更改 Agents API 会话语义、扩大或缩小自托管环境支持范围，或更改 Agents SDK 的支持政策，迁移策略将会改变。

如果你的产品需求发生变化，迁移策略也会改变。简单的请求-响应助手可能根本不需要持久化的托管执行框架。长时间运行的编码、研究或运维智能体则可以从 Agents API 的所有权模型中获益更多。

局限性

不存在通用的 SDK 到 API 的一对一迁移映射，因为不同应用使用 Agents SDK 的方式各不相同。有些严重依赖会话和交接；有些则将其用作函数工具的轻量运行器。正确的迁移方式取决于你的应用目前实际承担哪些职责。

Agents API 也处于公开测试阶段，因此实现细节可能会演变。请将本文中的所有权原则视为比任何单个端点形态都更持久。

结论

从 Agents SDK 迁移到 Agents API 最好理解为移动智能体运行时边界。托管执行框架接管了更多的循环、会话连续性、压缩和恢复。你的应用应该更明确地界定仍属于自身的职责：领域真相、授权、函数副作用、产物、可审计性和产品生命周期。

如果一次迁移保留了所有旧的编排机制，仅仅将 SDK 调用替换为 Agents API 调用，那么它很可能错失了架构上的机会。目标不是在新运行时之上复制旧运行时。目标是决定哪些运行时职责不再属于你的应用。

常见问题

从 Agents SDK 迁移到 Agents API

从 Agents SDK 迁移到 Agents API 只是 API 重写吗？

不是。主要变化是运行时所有权：Agents SDK 在你的应用中运行智能体循环，而 Agents API 运行托管的 Codex 执行框架和持久会话。状态、生命周期、事件处理和恢复应作为架构关注点进行审查。

我的函数工具需要重写吗？

如果业务实现已经位于稳定的应用接口之后，通常可以复用。面向智能体的集成会发生变化，因为 Agents API 函数调用通过会话所需操作和结果来处理。

我应该将业务状态迁移到 Agents API 会话中吗？

通常不需要。将权威的业务和产品状态保留在你自己的数据库或服务中。将会话用于智能体连续性和工作上下文，而不是作为产品的唯一真相来源。

Agents API 需要 webhook 吗？

不一定，因为流式传输也可用。Webhook 对于长时间运行或异步会话特别有用，你的应用可以在不保持开放流的情况下对生命周期变化做出反应。

每个现有的 Agents SDK 应用现在都应该迁移吗？

不是。SDK 仍以维护模式提供支持。当新运行时提供有意义的路线图价值，并且所需行为已针对生产形态的评估进行验证后，再进行迁移。

术语表

关键迁移术语

运行时边界

平台管理的智能体运行时与应用拥有的运行时之间的职责划分。

执行框架

协调模型调用、工具、上下文、编排和持续执行的智能体运行时。

会话

一个持久的 Agents API 实例，跨轮次保存智能体的配置、对话和已保存的工作。

所需操作

Agents API 需要外部输入（如函数结果或环境连接）才能继续工作的会话状态。

自托管环境

由你的基础设施运行并连接到托管 Agents API 执行框架的执行环境。

迁移验证测试

一种分阶段验证方法，将新运行时与行为基线、故障注入、追踪和可逆切换标准进行比较。

主要来源与延伸阅读

OpenAI — Agents SDK

当前支持政策：Agents SDK 功能完备，仍受维护，新应用应从 Agents API 开始。

OpenAI — 使用 Agents SDK 运行智能体

SDK 应用拥有的智能体循环和延续模型的文档。

OpenAI — Agents API 概述

定义 Agents API 核心概念：智能体、环境、会话、事件和项目。

OpenAI — Agents API 架构

解释托管执行框架、应用服务器、OpenAI 托管和自托管执行环境的边界。

OpenAI — 配置智能体

定义可复用的智能体配置和会话级自定义。

OpenAI — 运行并继续会话

记录持久会话、异步轮次、流式传输和引导。

OpenAI — Agents API 函数

函数工具定义以及必需函数结果的应用程序处理程序边界。

OpenAI — 会话 Webhook

异步会话的生命周期事件、必需操作和自托管环境连接。

OpenAI — Agents API 可观测性和使用情况

会话日志、事件、轮次、工具调用、子代理、追踪和令牌使用情况检查。

从 OpenAI Agents SDK 迁移到 Agents API 并不是重命名导入。核心架构边界发生了变化：SDK 在您的应用程序内运行代理循环，而 Agents API 在 OpenAI 侧运行托管的 Codex 执行框架和持久会话。因此，迁移问题不是“哪些类映射到哪些端点？”，而是“哪些运行时职责跨越边界转移，哪些留在我们的应用程序中，哪些需要重新设计？”

迁移是从应用程序拥有的循环转向托管执行框架

在 Agents SDK 中，一次运行是应用程序级别的轮次。SDK 运行器调用模型、检查输出、执行工具、遵循交接并持续运行，直到到达停止点。您的进程承载该循环，因此拥有其生命周期。

在 Agents API 中，OpenAI 运行执行框架。会话是代理配置的持久实例，它接受任务、产生事件、可以暂停以执行必需操作，并可以随时间继续。OpenAI 管理会话、编排、上下文压缩和恢复；您的应用程序发送工作、处理函数工具、接收事件，并可选地管理自托管执行环境。

这种所有权转移就是迁移。其他一切——API 语法、工具模式、事件处理、会话 ID——都由此而来。

运行时边界迁移图

哪些内容可以在不改变所有权的情况下进行概念性迁移

若干应用程序概念在迁移后可以完好保留，尽管其表示形式发生了变化。模型、指令、JSON 模式函数定义、MCP 访问、工具描述和结构化输出要求仍然是代理配置关注点。

OpenAI 的 Agents API 配置模型通过模型、指令、工具、推理和输出行为明确定义代理。函数工具仍然是应用程序代码：执行框架请求函数调用，您的处理程序返回结果。OpenAI 还指出，与 Responses API 一起使用的函数实现可以在 Agents API 会话流程中复用。

哪些内容不应一对一迁移

危险的迁移模式是在 Agents API 中重建每一个 SDK 运行时抽象。这可能导致你为托管执行框架付费，同时仍在应用中运行一个影子执行框架。

第 1 步 — 将领域状态与代理会话状态分离

在接触 API 调用之前，先对你 SDK 应用当前承载的状态进行分类。有些状态仅用于保持代理对话继续进行。其他状态是业务事实：用户权限、项目状态、订单数据、工作流审批、客户记录、文档版本、策略状态或应用配置。

第二类不应变得依赖于 Agents API 会话。持久会话对代理来说是有用的连续性；它不是产品事实来源的替代品。如果会话消失、过期、重建或更改实现，你的应用仍必须知道什么是真实的。

状态放置测试

	状态类型	首选所有者	原因
对话连续性
业务事实
持久工件
工作暂存状态

第 2 步 — 将运行器思维转变为会话与事件思维

SDK 应用通常以调用 run 并接收结果的思维方式思考。Agents API 则以持久会话的思维方式思考，其轮次可以异步运行。向空闲会话发送消息会启动工作；在活动轮次期间发送消息可以引导它。进度通过流式传输或 webhook 到达。

这会影响应用架构。长时间运行的生产工作不应依赖于一个保持存活的 HTTP 请求。你的产品需要稳定的会话标识符、生命周期持久化、webhook 验证、幂等处理器，以及进程重启后协调当前会话状态的方法。

第 3 步 — 围绕所需操作重新设计函数工具

函数工具仍然是重要的应用边界。你在代理配置中定义函数及其 JSON schema。当执行框架需要该函数时，会话可以进入 action-required 状态。你的应用检索所需操作，执行业务逻辑并返回结果。

这意味着函数实现应可安全恢复。webhook 可能在另一个工作进程处理时被送达。网络故障可能发生在外部副作用之后但结果返回之前。因此，迁移是向重要工具添加调用 ID、幂等键、显式授权、超时策略和审计记录的好时机。

第 4 步 — 决定执行应发生在哪里

Agents API 将托管执行框架与执行环境分离。代理可以在没有专用环境的情况下运行，在 OpenAI 托管的沙箱中运行，或通过与会话连接的自托管环境运行。

这产生了一个 SDK 应用可能从未明确做出的迁移决策：哪些代码应作为应用函数运行，哪些代码属于沙箱，以及哪些工作负载需要你控制的基础设施？

第 5 步 — 用显式生命周期处理替换隐式恢复

托管执行框架提供会话级恢复，但你的应用程序仍然拥有其周围的每一个外部依赖。自托管环境需要配置、重新连接和关闭。函数处理器可能失败。Webhook 可能被重试。产品侧状态可能在代理空闲时发生变化。

因此，迁移需要两种恢复模型：代理运行时恢复和业务操作恢复。第一种正越来越多地由 Agents API 管理。第二种仍然是你的责任。

第 6 步 — 围绕新的追踪边界重建可观测性

Agents API 会话暴露事件、保存的历史记录、轮次、工具调用、子代理和令牌使用情况。OpenAI 还在平台中提供会话日志和追踪导出。

不要因为平台追踪有所改进就丢弃你的应用程序可观测性。产品日志仍然需要将代理会话连接到用户身份、授权决策、领域对象、工具副作用、审批记录和最终接受的结果。有用的生产追踪是代理运行时证据与业务运行时证据之间的连接。

第 7 步 — 在更改运行时之前保留评估

迁移可能看起来成功，因为新系统仍然产生看似合理的答案，同时悄悄改变了工具选择、会话连续性、交接行为、延迟或故障恢复。在切换运行时之前建立行为基线。

基线应包括代表性任务、预期工具调用、禁止操作、审批点、状态连续性、恢复场景和最终输出验收标准。尽可能针对相同用例运行旧架构和新架构。

迁移验证测试

在切换之前验证新运行时

1

1. 冻结行为基线

捕获代表性的 SDK 追踪、预期输出、工具路径、审批点和失败用例。

2

2. 盘点状态所有权

将每个状态字段标记为代理会话状态、权威领域状态、持久产物或临时工作状态。

3

3. 复用稳定的工具实现

将业务函数保留在应用程序接口之后；尽可能只替换面向代理的集成。

4

4. 构建一个 Agents API 垂直切片

迁移一个生产形态的工作流，包括会话创建、工具、事件、环境和持久化。

5

5. 注入中断

测试进程重启、Webhook 重试、函数超时、自托管环境重新连接和过期领域状态。

6

6. 比较追踪，而不仅仅是答案

对照基线验证工具选择、授权、证据路径、状态转换和副作用。

7

7. 运行影子流量

在可行的情况下，在使新运行时成为权威之前重放或镜像代表性任务。

8

8. 在可逆边界之后切换

在生产行为稳定之前保留集成适配器和回滚能力。

迁移期间应衡量什么

何时还不应迁移

现有的 Agents SDK 应用程序不会仅仅因为平台方向改变就变成糟糕的架构。OpenAI 继续维护、安全修复、关键错误修复和兼容性工作。如果应用程序稳定、经过良好评估并且没有受阻的路线图需求，那么立即进行运行时迁移可能并不合理。

• Agents API 中尚不提供所需的 SDK 能力。
• 迁移会扰乱关键生产期，且无法带来近期价值。
• 应用程序依赖于尚未在托管执行框架上验证的自定义编排语义。
• 提供商可移植性是硬性要求，而当前 SDK 抽象具有实质性价值。
• 你的团队尚未将业务状态与代理运行时状态分离，导致切换不安全。
• 新的 Agents API 行为尚未针对代表性生产工作负载进行测试。

迁移何时具有战略重要性

当产品需求与托管执行框架相匹配时，迁移会变得更具吸引力：持久的长时运行工作、平台管理的上下文压缩与恢复、更新的智能体运行时能力、沙箱化执行、更丰富的托管生命周期管理，或希望减少应用程序所运行的编排代码量。

最强的信号不是“旧 SDK 功能已完备”，而是“我们的路线图现在依赖于那些天然归属于托管 Agents API 运行时的能力”。

什么会改变这一答案？

如果 OpenAI 发布自动化迁移工具、引入明确的兼容层、更改 Agents API 会话语义、扩大或缩小自托管环境支持，或更改 Agents SDK 的支持政策，迁移策略将会改变。

如果你的产品需求发生变化，它也会改变。简单的请求-响应助手可能根本不需要持久的托管执行框架。长时运行的编码、研究或运维智能体则可以从 Agents API 的所有权模型中获益更多。

局限性

不存在通用的 SDK 到 API 的一对一迁移映射，因为应用程序对 Agents SDK 的使用方式各不相同。有些严重依赖会话和交接；另一些则将其用作围绕函数工具的轻量运行器。正确的迁移取决于你的应用程序当前实际承担哪些职责。

Agents API 也处于公开测试阶段，因此实现细节可能会演变。请将本文中的所有权原则视为比任何单个端点形态都更持久。

结论

从 Agents SDK 迁移到 Agents API 最好理解为移动智能体运行时边界。托管执行框架接管了更多的循环、会话连续性、压缩和恢复。你的应用程序应更明确地界定仍属于自身的职责：领域真相、授权、函数副作用、工件、可审计性和产品生命周期。

如果一次迁移保留了所有旧的编排机制，仅仅将 SDK 调用替换为 Agents API 调用，那么它很可能错失了架构上的机会。目标不是在新运行时之上复现旧运行时，而是决定哪些运行时职责不再属于你的应用程序。

常见问题

从 Agents SDK 迁移到 Agents API

从 Agents SDK 迁移到 Agents API 只是重写 API 吗？

不是。主要变化是运行时所有权：Agents SDK 在你的应用程序中运行智能体循环，而 Agents API 运行托管的 Codex 执行框架和持久会话。状态、生命周期、事件处理和恢复应作为架构问题来审查。

我的函数工具需要重写吗？

如果业务实现已经位于稳定的应用程序接口之后，通常可以复用。面向智能体的集成会发生变化，因为 Agents API 函数调用通过会话所需操作和结果来处理。

我应该将业务状态移入 Agents API 会话吗？

通常不需要。将权威的业务和产品状态保留在你自己的数据库或服务中。将会话用于智能体连续性和工作上下文，而不是作为产品的唯一真相来源。

Agents API 需要 webhook 吗？

不一定，因为流式传输也可用。Webhook 对于长时运行或异步会话特别有用，在这些场景中，你的应用程序应对生命周期变化做出反应，而无需保持打开的流。

每个现有的 Agents SDK 应用程序现在都应该迁移吗？

不。SDK 仍以维护模式提供支持。当新运行时提供有意义的路线图价值，并且在所需行为已针对生产形态的评估验证之后，再进行迁移。

术语表

关键迁移术语

运行时边界

平台管理的智能体运行时与应用程序拥有的运行时之间的职责划分。

执行框架

协调模型调用、工具、上下文、编排和持续执行的智能体运行时。

会话

一个持久的 Agents API 实例，保存智能体的配置、对话和跨轮次保存的工作。

所需操作

Agents API 需要外部输入（如函数结果或环境连接）才能继续工作的会话状态。

自托管环境

由你的基础设施运行并连接到托管 Agents API 执行框架的执行环境。

迁移验证测试

一种分阶段验证方法，将新运行时与行为基线、故障注入、追踪和可逆切换标准进行比较。

主要来源与延伸阅读

OpenAI — Agents SDK

当前支持政策：Agents SDK 功能已完备，仍受维护，新应用程序应从 Agents API 开始。

OpenAI — 使用 Agents SDK 运行智能体

SDK 应用拥有的智能体循环与延续模型的文档。

OpenAI — Agents API 概述

定义 Agents API 核心概念：智能体、环境、会话、事件和条目。

OpenAI — Agents API 架构

解释托管执行框架、应用服务器、OpenAI 托管和自托管执行环境的边界。

OpenAI — 配置智能体

定义可复用的智能体配置和会话级自定义。

OpenAI — 运行和延续会话

记录持久会话、异步轮次、流式传输和引导。

OpenAI — Agents API 函数

函数工具定义以及必需函数结果的应用处理程序边界。

OpenAI — 会话 Webhook

异步会话的生命周期事件、必需操作和自托管环境连接。

OpenAI — Agents API 可观测性和使用情况

会话日志、事件、轮次、工具调用、子智能体、追踪和令牌使用情况检查。