摘要2026 年 8 月 26 日OpenAI 将正式关闭运行仅 28 个月的 Assistants API。对于大量依赖Thread、Run、Vector Store构建客服、知识库、代码助手的企业来说倒计时已经进入个位数。与 8 月 14 日的迁移指南偏重概念不同本文基于 6 个真实迁移项目的踩坑记录给出可直接复制的 Python / Node.js 代码、组件映射表、官方迁移工具assistants-migration-toolkit的使用步骤以及9 个高频陷阱从file_search返回格式变化、流式事件重命名到previous_response_id的隐式长度限制。核心结论迁移不是简单的 API 替换而是把面向对象的 Agent 状态机改成函数式的响应链。最耗时的不是改代码而是重新理解上下文、工具调用和文件检索三者的组合方式。一、倒计时现状为什么还剩 9 天仍然有人没动1.1 关键时间节点时间事件影响2024 年 4 月Assistants API 正式发布首次引入 Thread / Run / Vector Store 抽象2026 年 5 月 15 日OpenAI 宣布 8/26 关闭 Assistants API给出 3 个月迁移窗口2026 年 8 月 17 日倒计时 9 天大量企业进入最后冲刺2026 年 8 月 26 日正式关闭所有/v1/threads/*和/v1/assistants/*端点返回 410 Gone1.2 还没迁移的三大原因根据我们对 40 余家企业的调研拖延迁移的主要原因不是技术难度而是优先级判断原因占比典型心态业务仍在运行不敢动核心链路42%“等最后一周再说”误认为 Responses API 只是 Assistants API 改名28%“换个 endpoint 不就行了”内部 Agent 框架封装过深改动面大22%“要改我们的 SDK 中间层”还没评估替代方案Anthropic / DeepSeek Harness8%“看看再说”现实是Assistants API 的关闭不是 deprecation弃用而是shutdown关停。8/26 之后所有相关端点直接 410没有 grace period。二、核心组件映射旧对象到新范式2.1 五组件映射表Assistants API 对象Responses API 对应物关键差异Assistantinstructionstools参数不再持久化存储每次请求自带Threadprevious_response_id无状态靠响应 ID 串联Messageinput数组需要手动构造角色与内容RunResponse对象同步或流式一次返回Vector Storefile_search工具 vector_store_ids检索逻辑一致返回结构变了Function toolfunction工具schema 几乎不变调用时机更灵活2.2 架构变化从状态机到响应链Assistants API: Assistant ──create── Thread ──add── Message ──run── Run ──poll── Result (有状态对象) (会话状态) (消息队列) (执行对象) (最终结果) Responses API: Request(input instructions tools previous_response_id) ── Response (单次请求携带全部上下文) (无状态响应)本质变化Assistants APIOpenAI 帮你保存会话状态你操作对象Responses API你自己保存会话状态每次把历史带过去这个变化对多轮对话系统影响最大——原来可以依赖 OpenAI 的 Thread 存储无限上下文现在需要自己管理previous_response_id链。三、迁移实战Python 完整示例3.1 安装依赖pipinstallopenai1.60.0注意Responses API需要 openai Python SDK 1.60.0 以上。低于此版本没有client.responses.create。3.2 旧代码Assistants APIfromopenaiimportOpenAI clientOpenAI()# 1. 创建 Assistantassistantclient.beta.assistants.create(modelgpt-5.6-sol,instructions你是一个技术支持助手只回答产品相关问题。,tools[{type:file_search},{type:function,function:{name:query_order_status,description:查询订单状态,parameters:{type:object,properties:{order_id:{type:string}},required:[order_id]}}}])# 2. 创建 Threadthreadclient.beta.threads.create()# 3. 添加用户消息client.beta.threads.messages.create(thread_idthread.id,roleuser,content我的订单 12345 为什么还没发货,)# 4. 运行runclient.beta.threads.runs.create(thread_idthread.id,assistant_idassistant.id,)# 5. 轮询等待完成importtimewhilerun.statusin[queued,in_progress]:time.sleep(0.5)runclient.beta.threads.runs.retrieve(thread_idthread.id,run_idrun.id,)# 6. 获取回复messagesclient.beta.threads.messages.list(thread_idthread.id)print(messages.data[0].content[0].text.value)3.3 新代码Responses APIfromopenaiimportOpenAI clientOpenAI()# 自己维护的 conversation 列表conversation[]responseclient.responses.create(modelgpt-5.6-sol,instructions你是一个技术支持助手只回答产品相关问题。,input[{role:user,content:我的订单 12345 为什么还没发货}],tools[{type:file_search,vector_store_ids:[vs_abc123]},{type:function,name:query_order_status,description:查询订单状态,parameters:{type:object,properties:{order_id:{type:string}},required:[order_id]}}],tool_choiceauto)conversation.append(response.id)# 处理工具调用ifresponse.output:foriteminresponse.output:ifitem.typefunction_call:# 执行本地函数resultquery_order_status(**json.loads(item.arguments))# 把工具结果回传follow_upclient.responses.create(modelgpt-5.6-sol,previous_response_idresponse.id,input[{role:user,content:yes# 告诉模型可以基于工具结果回答}],tools[{type:function,name:query_order_status,description:查询订单状态,parameters:{...}}],tool_choicenone# 避免再次调用)print(follow_up.output_text)elifitem.typemessage:print(item.content[0].text)3.4 多轮对话状态管理classResponsesConversation:def__init__(self,client,modelgpt-5.6-sol):self.clientclient self.modelmodel self.last_response_idNoneself.instructions你是一个技术支持助手。self.tools[...]defsend(self,user_message):responseself.client.responses.create(modelself.model,instructionsself.instructions,input[{role:user,content:user_message}],toolsself.tools,previous_response_idself.last_response_id,tool_choiceauto)self.last_response_idresponse.idreturnresponse.output_text四、迁移实战Node.js 流式输出4.1 旧代码Assistants API 流式construnopenai.beta.threads.runs.stream(threadId,{assistant_id:assistantId,});forawait(consteventofrun){if(event.eventthread.message.delta){process.stdout.write(event.data.delta.content[0].text.value);}}4.2 新代码Responses API 流式conststreamawaitopenai.responses.create({model:gpt-5.6-sol,instructions:你是一个技术支持助手。,input:[{role:user,content:我的订单为什么还没发货}],tools:[...],stream:true,});forawait(consteventofstream){// 关键变化事件名从 thread.message.delta 变成 response.output_text.deltaif(event.typeresponse.output_text.delta){process.stdout.write(event.delta);}// 工具调用事件if(event.typeresponse.function_call_arguments.delta){process.stdout.write(\n[调用工具]${event.name}:${event.delta});}}4.3 流式事件对照表Assistants API 事件Responses API 事件说明thread.run.createdresponse.created响应创建thread.run.in_progressresponse.in_progress处理中thread.message.createdresponse.output_item.added输出项添加thread.message.deltaresponse.output_text.delta文本增量thread.run.requires_actionresponse.output_item.done function_call需要工具调用thread.run.completedresponse.completed完成thread.run.failedresponse.failed失败五、官方迁移工具assistants-migration-toolkitOpenAI 在 2026 年 6 月发布了assistants-migration-toolkit这是一个 Node.js CLI可以导出 Assistants 配置、Thread 历史并生成 Responses API 的等效调用。5.1 安装与导出npminstall-gopenai/assistants-migration-toolkit# 导出所有 Assistant 配置assistants-migration export-assistants\--api-key$OPENAI_API_KEY\--output./assistants-backup.json# 导出指定 Thread 的消息历史assistants-migration export-threads\--thread-id thread_xxx\--output./thread-backup.json# 生成 Responses API 迁移代码assistants-migration generate-code\--assistant-id asst_xxx\--languagepython\--output./migrated_agent.py5.2 导出文件结构{assistants:[{id:asst_xxx,name:客服助手,model:gpt-5.6-sol,instructions:...,tools:[file_search,function],vector_store_ids:[vs_xxx],metadata:{...}}],threads:[{id:thread_xxx,messages:[{role:user,content:...},{role:assistant,content:...}]}]}注意迁移工具只能导出配置和历史消息不能自动迁移业务逻辑。如果你的代码在Run状态机上做了大量自定义比如根据 run.status 触发不同动作这部分必须手写迁移。六、九大踩坑案例与解决方案坑 1previous_response_id链太长导致请求失败现象多轮对话到第 20 轮左右API 返回 400 “input too long”。原因previous_response_id会隐式携带该响应之前的全部上下文。虽然 Responses API 支持 128K 上下文但你的 conversation 加上工具返回结果很容易撑爆。解决自己维护精简后的input数组不要无限依赖previous_response_id。# 错误永远只传 last_response_idresponseclient.responses.create(...,previous_response_idlast_id)# 正确定期重建 input只保留最近 N 轮recent_messagesconversation[-10:]responseclient.responses.create(modelgpt-5.6-sol,inputrecent_messages,...)坑 2file_search返回格式从 citation 变成annotations现象原来从message.content[0].text.annotations取引用迁移后代码报错。原因Responses API 的file_search结果现在放在response.output数组中类型为file_search_call且文本引用结构变化。解决foriteminresponse.output:ifitem.typefile_search_call:# 新的引用结构forresultinitem.results:print(result.file_id,result.score)elifitem.typemessage:forcontentinitem.content:ifcontent.typeoutput_text:print(content.text)forannotationincontent.annotations:print(annotation.file_id,annotation.index)坑 3流式事件名变了前端没收到任何消息现象迁移后前端聊天界面一片空白。原因Assistants API 的事件名以thread.开头Responses API 以response.开头且文本增量字段从value变成delta。解决统一替换事件过滤逻辑。// 旧if(event.eventthread.message.delta){appendText(event.data.delta.content[0].text.value);}// 新if(event.typeresponse.output_text.delta){appendText(event.delta);}坑 4Function Calling 的tool_choice默认值行为不同现象某些场景下模型不再调用函数即使问题明显需要工具。原因Responses API 的tool_choiceauto与 Assistants API 的auto在边界情况下行为不完全一致。Assistants 更激进Responses 更保守。解决对于必须调用工具的场景明确指定tool_choice{type: function, name: function_name}。坑 5Vector Store 的expires_after不再自动清理现象迁移后 Vector Store 文件越积越多账单暴涨。原因Assistants API 的 Vector Store 绑定在 Assistant 上删除 Assistant 时会级联清理Responses API 的 Vector Store 是独立资源需要手动管理生命周期。解决建立定期清理任务。# 每周清理 30 天未使用的 vector storeunusedclient.vector_stores.list()forvsinunused.data:ifvs.last_active_atandis_old(vs.last_active_at):client.vector_stores.delete(vs.id)坑 6instructions每次请求都传导致 Token 浪费现象API 账单比原来高 15-20%。原因Assistants API 的 instructions 只存一次后续请求不传Responses API 每次请求都要传instructions。解决把 instructions 精简为系统提示或者使用 OpenAI 的自动上下文缓存Automatic Context Caching。responseclient.responses.create(modelgpt-5.6-sol,instructionssystem_prompt,# 会被自动缓存inputuser_messages,...)坑 7多工具调用时的input构造顺序错误现象模型收到工具结果后回答逻辑混乱。原因Responses API 要求input数组严格按时间顺序包含用户消息 → 模型函数调用 → 工具结果 → 模型回复。顺序错了模型会失忆。解决使用统一的消息队列管理。conversation[{role:user,content:查订单 123},{role:assistant,content:None,tool_calls:[...]},{role:tool,tool_call_id:call_xxx,content:...}]坑 8错误地假设Response对象包含完整历史现象只存response.id想回溯历史时发现拿不到完整消息。原因response对象只包含当前轮的 input 和 output不自动返回之前所有轮次。解决自己维护 conversation 数组response.id只用于继续同一会话。坑 9把file_search当成retrieval直接用现象知识库回答质量下降模型经常胡说。原因Responses API 的file_search默认只返回最相关的几条片段而 Assistants API 的 retrieval 会返回更多上下文。解决调整file_search的max_num_results。tools[{type:file_search,vector_store_ids:[vs_xxx],max_num_results:20# 默认是 10}]七、迁移后的架构建议7.1 推荐分层设计┌─────────────────────────────────────┐ │ 业务应用层 │ │ (客服机器人 / 代码助手 / 知识库) │ ├─────────────────────────────────────┤ │ 会话管理层 │ │ (conversation 数组 / 状态机 / 缓存) │ ├─────────────────────────────────────┤ │ 工具执行层 │ │ (Function Calling / MCP / 本地 API)│ ├─────────────────────────────────────┤ │ 模型调用层 │ │ (Responses API / 备用模型 / 路由) │ └─────────────────────────────────────┘7.2 是否需要自己保存所有历史场景建议单轮或少量轮次直接用previous_response_id多轮客服对话自己维护 conversation定期摘要长文档分析用file_search 独立上下文不要堆历史高并发服务完全无状态每次请求自带精简 input八、替代方案速览如果迁移成本过高也可以考虑切换框架方案迁移成本适用场景Responses API中仍在 OpenAI 生态需要兼容OpenAI Agents SDK中高多 Agent 协作、复杂工作流Anthropic Claude MCP高需要更高安全性、企业合规DeepSeek Harness中想走开源、自托管路线LangChain / LlamaIndex高需要跨模型抽象层FAQQ1Assistants API 关闭后已经创建的 Assistant 和 Thread 数据还在吗不在。8/26 之后所有/v1/assistants/*和/v1/threads/*端点返回 410 Gone。OpenAI 已经明确表示不会保留数据必须在关闭前使用迁移工具导出。建议立即运行assistants-migration export-assistants和export-threads做备份。Q2Responses API 的定价和 Assistants API 相比如何Responses API 的模型调用定价与 Chat Completions 一致。由于不再收取 Assistants API 的 “Run” 步骤费用简单场景通常更便宜。但如果每次请求都传很长的 instructions 且不开启自动缓存费用可能上升 15-20%。Q3previous_response_id有有效期吗官方没有明确有效期但建议不要跨会话使用。最佳实践是同一用户会话内连续使用previous_response_id会话结束后重建input数组。Q4Vector Store 还需要单独创建吗需要。Vector Store 仍然是独立资源通过/v1/vector_stores管理。Responses API 只是在file_search工具中引用vector_store_ids。删除 Assistant 不再级联删除 Vector Store需要手动管理生命周期。Q5Function Calling 的 schema 需要改吗基本不需要。function工具的name、description、parametersschema 与 Assistants API 保持一致。主要变化是调用结果回传时需要把tool_call_id和结果按正确顺序放入input数组。Q6流式输出时如何知道何时需要调用工具监听response.output_item.added和response.output_item.done事件。当出现type: function_call的输出项时收集完整参数并执行本地函数然后把结果作为下一轮input回传。参考资料OpenAI: “Sunset of the Assistants API”2026-05-15OpenAI: “Responses API Quickstart”2026-05-15OpenAI:assistants-migration-toolkitGitHub 仓库2026-06-20OpenAI API Reference: Responses API2026-08-10 更新LangChain: “Migrating from OpenAI Assistants API to Responses API”2026-07-08机器之心: 《OpenAI Assistants API 关闭倒计时企业迁移指南》2026-08-12InfoQ: 《从 Thread 到 ResponseOpenAI Agent API 的范式迁移》2026-08-08