摘要OpenAI 在 2024 年推出的 Assistants API 曾是 Agent 开发的事实标准但 2026 年 8 月 26 日它将迎来硬关闭。官方推荐两条迁移路径Responses API对话与工具原语和Agent SDK多 Agent 编排。本文从功能映射、代码迁移、数据迁移、成本影响四个维度给出实战指南核心结论是简单对话场景 2 小时可切到 Responses API需要状态持久化、多 Agent 协作的系统建议直接上 Agent SDKVector Store 必须提前导出否则关闭后不可恢复。一、事件背景为什么 Assistants API 必须死1.1 时间线时间事件来源2023-11OpenAI DevDay 发布 Assistants APIBetaOpenAI2024-06增加 Vector Store、文件搜索、Code InterpreterOpenAI2025-03Responses API 发布官方定位下一代对话原语OpenAI2025-11OpenAI 宣布 2026-08-26 关闭 Assistants APIOpenAI2026-04Agent SDK 1.0 发布支持多 Agent handoffOpenAI2026-08-24距离关闭仅剩 48 小时本文1.2 官方弃用的三个技术原因原因说明状态模型过重Assistants 的 thread/run/step 三态机在长会话中极易出现run 卡住调试困难工具生态割裂Code Interpreter、文件搜索、function calling 各自为政难以与外部 MCP/A2A 工具对接多 Agent 支持弱单个 assistant 难以表达路由 → 执行 → 总结的多角色协作Agent SDK 因此诞生二、迁移路径选择Responses API vs Agent SDK2.1 两个方案定位维度Responses APIAgent SDK抽象层级低层对话原语替代 chat.completions高层 Agent 编排框架状态管理无状态需自己维护 thread内置状态机支持 handoff工具调用原生 function/web_search/file_searchfunction handoff 可插拔工具多 Agent需自行实现原生支持多 Agent 路由代码量少接近 completions中需理解 agent/ handoff 概念适合场景客服、单轮工具调用、轻量助手复杂工作流、多角色协作、企业 Agent2.2 决策树你的系统是否依赖 thread/run/vector store 持久化 ├─ 否 ── 直接用 Responses API迁移成本最低 └─ 是 ── 是否需要多 Agent 协作 ├─ 否 ── Responses API 自建状态存储 └─ 是 ── Agent SDK长期更优三、代码迁移实战Assistants API → Responses API3.1 旧代码创建 Thread 并运行# Assistants API 旧写法fromopenaiimportOpenAI clientOpenAI()threadclient.beta.threads.create()client.beta.threads.messages.create(thread_idthread.id,roleuser,content帮我查一下明天北京飞上海的机票)runclient.beta.threads.runs.create(thread_idthread.id,assistant_idasst_xxx,tools[{type:function,function:{name:search_flights}}])# 轮询 run 状态处理 function calling再提交结果whilerun.statusin[queued,in_progress,requires_action]:runclient.beta.threads.runs.retrieve(thread_idthread.id,run_idrun.id)ifrun.statusrequires_action:tool_outputs[]fortool_callinrun.required_action.submit_tool_outputs.tool_calls:outputhandle_function(tool_call.function.name,tool_call.function.arguments)tool_outputs.append({tool_call_id:tool_call.id,output:output})runclient.beta.threads.runs.submit_tool_outputs(thread_idthread.id,run_idrun.id,tool_outputstool_outputs)3.2 新代码Responses API# Responses API 新写法fromopenaiimportOpenAI clientOpenAI()responseclient.responses.create(modelgpt-5.6-mini,input[{role:system,content:你是一个旅行助手可调用 search_flights 工具。},{role:user,content:帮我查一下明天北京飞上海的机票}],tools[{type:function,name:search_flights,description:查询航班,parameters:{type:object,properties:{from:{type:string},to:{type:string},date:{type:string}},required:[from,to,date]}}])# 处理 function calling单次或循环whileresponse.statusrequires_action:tool_outputs[]fortool_callinresponse.output:iftool_call.typefunction_call:resulthandle_function(tool_call.name,tool_call.arguments)tool_outputs.append({tool_call_id:tool_call.call_id,output:result})responseclient.responses.create(modelgpt-5.6-mini,previous_response_idresponse.id,inputtool_outputs)print(response.output_text)3.3 核心差异对照旧概念新概念说明beta.threads.create无需创建直接发responses.createResponses API 无 thread 实体thread_idprevious_response_id用 response id 链式维持上下文assistant_idmodelinstructionsassistant 配置内联到请求run.statusresponse.status状态语义基本一致required_actionresponse.output中的function_call结构略有变化submit_tool_outputs再次调用responses.create并传inputtool_outputs更简洁四、Vector Store 与文件搜索迁移4.1 旧 Vector Store 的替代方案旧能力推荐替代备注Vector Store 上传文件Responses API 的file_search工具需在项目中配置 file_search自动分块自行用text-embedding-3-large分块写入向量库更灵活但增加代码量检索增强生成Responses APIfile_search或自建 RAG官方 file_search 支持 PDF/TXT/DOCX4.2 数据导出脚本必须在 8/26 前执行# 批量导出 Vector Store 中的文件fromopenaiimportOpenAI clientOpenAI()forvsinclient.beta.vector_stores.list():print(f导出 Vector Store:{vs.id}{vs.name})forfileinclient.beta.vector_stores.files.list(vector_store_idvs.id):contentclient.files.content(file.id)withopen(fbackup/{file.id}_{vs.name},wb)asf:f.write(content.read())⚠️关键提醒关闭后 Vector Store 文件可能无法下载务必提前备份。五、迁移到 Agent SDK复杂系统的更优解5.1 Agent SDK 核心概念fromagentsimportAgent,Runnerimportasyncio sales_agentAgent(name销售顾问,instructions你是销售顾问负责推荐产品。,modelgpt-5.6-mini)tech_agentAgent(name技术支持,instructions你是技术支持负责解决报错。,modelgpt-5.6-mini)triage_agentAgent(name路由,instructions根据用户问题路由到销售顾问或技术支持。,handoffs[sales_agent,tech_agent])asyncdefmain():resultawaitRunner.run(triage_agent,input我的订单还没发货但你们新出的 Pro 版有什么功能)print(result.final_output)asyncio.run(main())5.2 Agent SDK vs 旧 Assistants 多 assistant 方案维度旧 Assistants多 assistantAgent SDK切换方式客户端手动切换 assistant_id模型自主 handoff上下文共享需自行同步 thread自动携带历史错误恢复无内置重试内置重试与 tracing可观测性弱内置 span/trace六、成本与性能变化6.1 定价对比以 gpt-5.6-mini 为例接口输入$/MTok输出$/MTok缓存命中chat.completions0.502.00不支持Assistants API0.502.00不支持Responses API0.502.000.10Agent SDK底层 Responses0.502.000.106.2 隐性成本变化项目旧 Assistants新方案影响轮询等待run 状态轮询延迟不可控同步 Responses单次返回平均延迟下降 20-40%状态存储官方托管自建或 Agent SDK 内置增加少量存储成本向量检索按文件大小计费file_search 或自建向量库大体持平七、常见迁移坑点坑点表现解决方案thread_id丢失会话历史断裂用数据库保存previous_response_id链function 参数格式变化新 API 用arguments字符串统一封装json.loads多轮 tool 调用循环死锁忘记更新previous_response_id每次循环传入最新 response idVector Store 未导出8/26 后无法检索历史文件立即执行备份脚本Assistant 元数据迁移name/instructions/model 散落写成 YAML/JSON 配置中心八、FAQQ18 月 26 日之后 Assistants API 会立刻不可用吗官方声明是硬关闭即所有beta.threads.*、beta.assistants.*、beta.vector_stores.*端点将返回 410 Gone。不要抱侥幸心理。Q2Responses API 能完全替代 Assistants API 吗不能 100% 替代。Responses API 是无状态原语缺乏原生的 thread 持久化。如果你依赖 OpenAI 托管的 thread 历史需要自建存储或迁移到 Agent SDK。Q3Agent SDK 是否绑定 Python目前官方 SDK 以 Python 为主TypeScript 版本处于 beta。其他语言需直接调用 REST API。Q4Vector Store 中的文件关闭后还能取回吗历史经验表明Beta 服务关闭后数据保留窗口通常很短数周到数月。务必在 8/26 前导出不要依赖官方后续开放下载。Q5迁移到 Responses API 需要改模型版本吗Responses API 支持 gpt-4o 及以上模型但推荐使用 gpt-5.x 系列以获得 tool 调用稳定性。旧模型如 gpt-3.5-turbo 不保证完全兼容。Q6function calling 的结果格式有什么变化Assistants API 用tool_call_idoutputResponses API 同样用tool_call_id但字段位置在input数组的tool类型消息中。建议封装统一接口。Q7企业级系统如何最小化迁移风险推荐双写策略旧 Assistants API 继续运行一周同时把新流量切到 Responses API / Agent SDK对比输出一致性后再全量切换。Q8有没有官方迁移工具OpenAI 提供了迁移指南和示例代码但没有一键迁移工具。涉及 Vector Store 和自定义工具的系统仍需手动改造。九、参考资料OpenAI. “Migrating from Assistants API to Responses API.” OpenAI Platform Docs, 2026-03.OpenAI. “Agent SDK Documentation.” OpenAI Platform Docs, 2026-04.OpenAI. “Assistants API Deprecation Notice.” OpenAI Developer Forum, 2025-11.LangChain. “OpenAI Responses API Integration.” LangChain Blog, 2026-05.机器之心. “OpenAI Assistants API 关闭在即开发者该如何迁移” 2026-08-20.InfoQ. “Responses API 与 Agent SDKOpenAI 的 Agent 架构新阶段.” 2026-06. OpenAI Assistants API 关闭倒计时：从 Assistants 到 Responses API / Agent SDK 的迁移实战
摘要OpenAI 在 2024 年推出的 Assistants API 曾是 Agent 开发的事实标准但 2026 年 8 月 26 日它将迎来硬关闭。官方推荐两条迁移路径Responses API对话与工具原语和Agent SDK多 Agent 编排。本文从功能映射、代码迁移、数据迁移、成本影响四个维度给出实战指南核心结论是简单对话场景 2 小时可切到 Responses API需要状态持久化、多 Agent 协作的系统建议直接上 Agent SDKVector Store 必须提前导出否则关闭后不可恢复。一、事件背景为什么 Assistants API 必须死1.1 时间线时间事件来源2023-11OpenAI DevDay 发布 Assistants APIBetaOpenAI2024-06增加 Vector Store、文件搜索、Code InterpreterOpenAI2025-03Responses API 发布官方定位下一代对话原语OpenAI2025-11OpenAI 宣布 2026-08-26 关闭 Assistants APIOpenAI2026-04Agent SDK 1.0 发布支持多 Agent handoffOpenAI2026-08-24距离关闭仅剩 48 小时本文1.2 官方弃用的三个技术原因原因说明状态模型过重Assistants 的 thread/run/step 三态机在长会话中极易出现run 卡住调试困难工具生态割裂Code Interpreter、文件搜索、function calling 各自为政难以与外部 MCP/A2A 工具对接多 Agent 支持弱单个 assistant 难以表达路由 → 执行 → 总结的多角色协作Agent SDK 因此诞生二、迁移路径选择Responses API vs Agent SDK2.1 两个方案定位维度Responses APIAgent SDK抽象层级低层对话原语替代 chat.completions高层 Agent 编排框架状态管理无状态需自己维护 thread内置状态机支持 handoff工具调用原生 function/web_search/file_searchfunction handoff 可插拔工具多 Agent需自行实现原生支持多 Agent 路由代码量少接近 completions中需理解 agent/ handoff 概念适合场景客服、单轮工具调用、轻量助手复杂工作流、多角色协作、企业 Agent2.2 决策树你的系统是否依赖 thread/run/vector store 持久化 ├─ 否 ── 直接用 Responses API迁移成本最低 └─ 是 ── 是否需要多 Agent 协作 ├─ 否 ── Responses API 自建状态存储 └─ 是 ── Agent SDK长期更优三、代码迁移实战Assistants API → Responses API3.1 旧代码创建 Thread 并运行# Assistants API 旧写法fromopenaiimportOpenAI clientOpenAI()threadclient.beta.threads.create()client.beta.threads.messages.create(thread_idthread.id,roleuser,content帮我查一下明天北京飞上海的机票)runclient.beta.threads.runs.create(thread_idthread.id,assistant_idasst_xxx,tools[{type:function,function:{name:search_flights}}])# 轮询 run 状态处理 function calling再提交结果whilerun.statusin[queued,in_progress,requires_action]:runclient.beta.threads.runs.retrieve(thread_idthread.id,run_idrun.id)ifrun.statusrequires_action:tool_outputs[]fortool_callinrun.required_action.submit_tool_outputs.tool_calls:outputhandle_function(tool_call.function.name,tool_call.function.arguments)tool_outputs.append({tool_call_id:tool_call.id,output:output})runclient.beta.threads.runs.submit_tool_outputs(thread_idthread.id,run_idrun.id,tool_outputstool_outputs)3.2 新代码Responses API# Responses API 新写法fromopenaiimportOpenAI clientOpenAI()responseclient.responses.create(modelgpt-5.6-mini,input[{role:system,content:你是一个旅行助手可调用 search_flights 工具。},{role:user,content:帮我查一下明天北京飞上海的机票}],tools[{type:function,name:search_flights,description:查询航班,parameters:{type:object,properties:{from:{type:string},to:{type:string},date:{type:string}},required:[from,to,date]}}])# 处理 function calling单次或循环whileresponse.statusrequires_action:tool_outputs[]fortool_callinresponse.output:iftool_call.typefunction_call:resulthandle_function(tool_call.name,tool_call.arguments)tool_outputs.append({tool_call_id:tool_call.call_id,output:result})responseclient.responses.create(modelgpt-5.6-mini,previous_response_idresponse.id,inputtool_outputs)print(response.output_text)3.3 核心差异对照旧概念新概念说明beta.threads.create无需创建直接发responses.createResponses API 无 thread 实体thread_idprevious_response_id用 response id 链式维持上下文assistant_idmodelinstructionsassistant 配置内联到请求run.statusresponse.status状态语义基本一致required_actionresponse.output中的function_call结构略有变化submit_tool_outputs再次调用responses.create并传inputtool_outputs更简洁四、Vector Store 与文件搜索迁移4.1 旧 Vector Store 的替代方案旧能力推荐替代备注Vector Store 上传文件Responses API 的file_search工具需在项目中配置 file_search自动分块自行用text-embedding-3-large分块写入向量库更灵活但增加代码量检索增强生成Responses APIfile_search或自建 RAG官方 file_search 支持 PDF/TXT/DOCX4.2 数据导出脚本必须在 8/26 前执行# 批量导出 Vector Store 中的文件fromopenaiimportOpenAI clientOpenAI()forvsinclient.beta.vector_stores.list():print(f导出 Vector Store:{vs.id}{vs.name})forfileinclient.beta.vector_stores.files.list(vector_store_idvs.id):contentclient.files.content(file.id)withopen(fbackup/{file.id}_{vs.name},wb)asf:f.write(content.read())⚠️关键提醒关闭后 Vector Store 文件可能无法下载务必提前备份。五、迁移到 Agent SDK复杂系统的更优解5.1 Agent SDK 核心概念fromagentsimportAgent,Runnerimportasyncio sales_agentAgent(name销售顾问,instructions你是销售顾问负责推荐产品。,modelgpt-5.6-mini)tech_agentAgent(name技术支持,instructions你是技术支持负责解决报错。,modelgpt-5.6-mini)triage_agentAgent(name路由,instructions根据用户问题路由到销售顾问或技术支持。,handoffs[sales_agent,tech_agent])asyncdefmain():resultawaitRunner.run(triage_agent,input我的订单还没发货但你们新出的 Pro 版有什么功能)print(result.final_output)asyncio.run(main())5.2 Agent SDK vs 旧 Assistants 多 assistant 方案维度旧 Assistants多 assistantAgent SDK切换方式客户端手动切换 assistant_id模型自主 handoff上下文共享需自行同步 thread自动携带历史错误恢复无内置重试内置重试与 tracing可观测性弱内置 span/trace六、成本与性能变化6.1 定价对比以 gpt-5.6-mini 为例接口输入$/MTok输出$/MTok缓存命中chat.completions0.502.00不支持Assistants API0.502.00不支持Responses API0.502.000.10Agent SDK底层 Responses0.502.000.106.2 隐性成本变化项目旧 Assistants新方案影响轮询等待run 状态轮询延迟不可控同步 Responses单次返回平均延迟下降 20-40%状态存储官方托管自建或 Agent SDK 内置增加少量存储成本向量检索按文件大小计费file_search 或自建向量库大体持平七、常见迁移坑点坑点表现解决方案thread_id丢失会话历史断裂用数据库保存previous_response_id链function 参数格式变化新 API 用arguments字符串统一封装json.loads多轮 tool 调用循环死锁忘记更新previous_response_id每次循环传入最新 response idVector Store 未导出8/26 后无法检索历史文件立即执行备份脚本Assistant 元数据迁移name/instructions/model 散落写成 YAML/JSON 配置中心八、FAQQ18 月 26 日之后 Assistants API 会立刻不可用吗官方声明是硬关闭即所有beta.threads.*、beta.assistants.*、beta.vector_stores.*端点将返回 410 Gone。不要抱侥幸心理。Q2Responses API 能完全替代 Assistants API 吗不能 100% 替代。Responses API 是无状态原语缺乏原生的 thread 持久化。如果你依赖 OpenAI 托管的 thread 历史需要自建存储或迁移到 Agent SDK。Q3Agent SDK 是否绑定 Python目前官方 SDK 以 Python 为主TypeScript 版本处于 beta。其他语言需直接调用 REST API。Q4Vector Store 中的文件关闭后还能取回吗历史经验表明Beta 服务关闭后数据保留窗口通常很短数周到数月。务必在 8/26 前导出不要依赖官方后续开放下载。Q5迁移到 Responses API 需要改模型版本吗Responses API 支持 gpt-4o 及以上模型但推荐使用 gpt-5.x 系列以获得 tool 调用稳定性。旧模型如 gpt-3.5-turbo 不保证完全兼容。Q6function calling 的结果格式有什么变化Assistants API 用tool_call_idoutputResponses API 同样用tool_call_id但字段位置在input数组的tool类型消息中。建议封装统一接口。Q7企业级系统如何最小化迁移风险推荐双写策略旧 Assistants API 继续运行一周同时把新流量切到 Responses API / Agent SDK对比输出一致性后再全量切换。Q8有没有官方迁移工具OpenAI 提供了迁移指南和示例代码但没有一键迁移工具。涉及 Vector Store 和自定义工具的系统仍需手动改造。九、参考资料OpenAI. “Migrating from Assistants API to Responses API.” OpenAI Platform Docs, 2026-03.OpenAI. “Agent SDK Documentation.” OpenAI Platform Docs, 2026-04.OpenAI. “Assistants API Deprecation Notice.” OpenAI Developer Forum, 2025-11.LangChain. “OpenAI Responses API Integration.” LangChain Blog, 2026-05.机器之心. “OpenAI Assistants API 关闭在即开发者该如何迁移” 2026-08-20.InfoQ. “Responses API 与 Agent SDKOpenAI 的 Agent 架构新阶段.” 2026-06.