OpenAI Assistants API 迁移 Responses API：别再依赖即将下线的 Prompt 对象

直接结论：截至 2026 年 8 月 21 日，OpenAI Assistants API 已经是必须退出的旧接口，并将在 2026 年 8 月 26 日关闭。但不要把 Assistant 简单迁成 reusable Prompt object：该对象也已进入弃用流程，v1/prompts 计划于 2026 年 11 月 30 日关闭。长期方案应直接使用 Responses API，把 instructions、tools 和输出契约放入应用代码，用 Conversations 或自有数据库管理状态。

这篇文章原来讨论“Assistants API 还是自定义 Agent”。现在真正的问题变成了：如何只迁移一次，并把平台执行、会话状态、行为配置和业务编排分清楚。

别把 Assistant 迁成即将下线的 Prompt 对象

官方 Assistants 迁移指南曾把 Assistant 映射到 Prompt，但同一页面已经加入警告：reusable Prompt objects 也在弃用。OpenAI 的 Prompt 对象迁移指南进一步建议，把 Prompt 内容移入应用代码，以便自行审查、测试、部署和版本控制。

短期过渡项目仍可以使用 Prompt ID，但必须安排退出时间。现在才开始迁移的项目，更稳妥的长期路径是：Responses 负责执行，配置归应用仓库，状态归 Conversations 或自有数据库。否则会形成 Assistant ID → Prompt ID → 应用内配置 的连续三代依赖。

先做什么：把 Assistants 项目拆成六个责任层

不要从“把 thread_id 换成另一个 ID”开始。先把现有系统拆成六层：

1. 指令与模型配置：Assistant instructions、模型、温度和工具配置分别在哪里维护；
2. 会话状态：Thread/Message 当前承担了多少真正的业务状态；
3. 工具与文件：Function Calling、File Search、Code Interpreter 的输入输出和权限边界；
4. 运行状态：Run / required_action / tool output 的等待和恢复逻辑；
5. 业务审批：支付、发布、删除、外发等动作是否依赖应用自己的审批单；
6. 外部副作用：工具重试时是否有稳定幂等键、唯一约束和结果复用。

前四层可以大量迁移到 OpenAI 当前的 Responses / Conversations / Tools 体系，后两层不能因为换了 API 就交给模型平台。

Assistants API 为什么现在必须迁移

OpenAI 当前 Assistants 文档已经明确标记 Deprecated，并给出 2026 年 8 月 26 日的 shutdown 日期。官方同时明确建议新集成使用 Responses API。

这意味着原先“Assistants API 上线快，所以原型优先选它”的建议已经失效。即使只是内部 Demo，也没有理由在一个即将关闭的接口上继续积累新代码。

现有 Assistants 项目仍然可以在停用日前运行，但应该立即冻结新增架构依赖，把精力放到：

• 导出和核对 Assistant、Thread、Message、File / Vector Store 等对象；
• 建立 Responses API 的等价业务路径；
• 验证工具调用、文件检索、多轮上下文和权限；
• 双写或影子运行关键请求；
• 为生产流量准备回滚开关；
• 在 8 月 26 日前完成切流。

Responses API 解决了什么

Responses API 是 OpenAI 当前推荐的统一模型调用接口。它可以直接组合文本/多模态输入、function calling、Web Search、File Search、Code Interpreter、Remote MCP 等工具能力。

多轮会话不再必须围绕 Assistants 的 Thread/Run 对象设计。对于需要持久会话状态的应用，可以使用 Conversations 管理跨 Response 调用的 items；轻量场景也可以使用 previous_response_id 串联前一次响应。

但这里最容易产生新的误区：Conversation 不是你的业务数据库。 用户身份、租户权限、订单状态、审批记录、幂等键、任务过期时间、补偿事务仍应由应用自己的数据库负责。

迁移时不要机械做“对象一对一替换”

旧 Assistants 架构通常长这样：

Assistant
  └─ Thread
      ├─ Message
      └─ Run
          ├─ Run Step
          └─ required_action / submit_tool_outputs

迁移后的应用更适合按责任拆开：

Application DB
  ├─ user / tenant / permission
  ├─ business workflow state
  ├─ approval ticket
  └─ idempotency ledger

OpenAI
  ├─ Responses API
  ├─ Conversation / previous_response_id
  └─ Tools: function / file_search / code_interpreter / remote MCP

这样做的价值不是“对象更少”，而是让平台会话状态和业务真相彻底分离。未来即使换模型、换供应商或把某个工具迁回自建服务，也不需要重写订单和审批状态。

Responses API vs 自定义 Agent：现在应该怎么选

场景	Responses API 为主	自定义编排层为主
单模型问答 + 工具调用	适合	通常没必要
File Search / Code Interpreter	适合	只在特殊合规/成本边界下自建
简单多轮会话	Conversations / previous_response_id 足够	通常没必要
多供应商模型路由	需要额外封装	更适合
严格状态机 / 长时间工作流	需要应用状态配合	更适合
高风险 Human-in-the-loop	平台工具能力可参与	审批真相应在业务层
Exactly-once 外部副作用	不提供业务保证	必须自行实现
私有部署 / 本地模型	不适用	更适合

所以“自定义 Agent”不是为了和 Responses API 对抗。更合理的架构是：Responses API 负责 OpenAI 模型与托管工具，自定义编排层负责业务状态、权限、恢复与跨系统事务。

零费用离线验证：验证结构，不伪装成线上性能实测

这次配套验证没有创建 API Key，也没有调用 OpenAI API。Node.js 本地测试覆盖配置转换、消息时间顺序、Responses 请求结构、function call output 映射，以及未知 content 类型必须失败关闭五项契约，结果为 5 项通过、0 项失败。

这只能证明固定样本下的结构迁移契约通过，不能证明线上模型可用性、回答质量、延迟、Token 成本、Vector Store、File Search、限流或生产数据保留。真正上线前仍需要受控的真实 API 验收。

5 天迁移清单

如果你的生产系统仍依赖 Assistants API，我会按这个顺序处理：

1. 冻结新的 Assistants-only 功能；
2. 清点 Assistant、Thread、Run、File/Vector Store 的使用路径；
3. 为每条路径建立 Responses API 等价测试；
4. 将用户/租户/审批/幂等从 Thread metadata 中抽离到业务数据库；
5. 对 function calling 做输入 Schema、权限和副作用回归；
6. 对 File Search / Code Interpreter 做数据保留与权限复核；
7. 影子运行真实请求，比较结果和失败模式；
8. 增加切流开关和回滚路径；
9. 在 2026 年 8 月 26 日前停止生产依赖 Assistants API。

一个容易忽略的数据边界

OpenAI 当前数据控制文档对 /v1/responses、Conversations 和旧 Assistants 对象的应用状态保留规则并不完全相同。迁移不是只改 SDK 方法名，还要重新核对组织的数据保留、Zero Data Retention、后台执行和工具使用要求。

如果你的系统处理企业私有数据、健康数据、金融数据或其他敏感信息，这一步应该进入迁移验收清单，而不是等上线后再补。

FAQ

Responses API 必须依赖 Prompt 对象吗？

不必须。Responses 请求可以直接传入 model、instructions、tools 和 input。由于 reusable Prompt objects 同样进入弃用流程，新迁移项目更适合把配置放在应用代码或自有配置系统中。

Assistants API 关闭后 Thread 会自动变成 Conversation 吗？

不要假设会自动迁移。应用应按照官方迁移指南显式迁移和验证自己的数据与调用路径。尤其不要把旧 Thread ID 当成未来业务层永久主键。

现有项目只差几天，能不能先不迁？

如果是生产依赖，不建议。截止日期是 2026 年 8 月 26 日，留给故障回退的时间已经很少。至少要立即完成等价路径、回归测试和切流开关。

Responses API 能代替 LangGraph 之类的框架吗？

不是同一层。Responses API 提供模型、工具和会话能力；LangGraph 等框架解决显式工作流、状态、恢复、分支和长任务编排。简单应用可以只用 Responses API，复杂业务可以把 Responses API 作为模型/工具执行层。

继续阅读

• OpenAI Agents SDK RunState：Tool Approval 跨进程恢复
• AI Agent 全栈指南
• LangGraph Human-in-the-loop 审批流
• MCP OAuth 认证与生产授权

专题入口 / AI Agent Hub

从单个 Agent 问题继续进入完整生产体系

AI Agent 专题统一组织架构、记忆、工具调用、评测、安全、部署和多智能体协作，让每篇文章都回到明确的主题主页面。

进入 AI Agent 专题 → 查看架构指南 订阅