1. 旧 Agent 应用为什么在 Assistants API 下线后直接 404如果你的项目里还留着client.beta.assistants.create、client.beta.threads.create这类调用现在最该关心的不是模型答得准不准而是请求发出去根本没有服务接。OpenAI 的 Assistants API 已经走完 sunset 流程旧接口返回 404 不是限流、不是鉴权过期而是对象本身不存在了。这个区别很重要限流你会重试鉴权过期你会换 Key而 404 意味着你整套基于 Assistant/Thread/Run 的编排逻辑需要换一套对象模型。受影响最典型的是四类应用客服机器人、知识库问答、长会话助手、带工具调用的 Agent。它们过去依赖 Assistants API 把「配置 会话 执行过程」打包成持久对象代码写得比较省心——建一个 Assistant 存好 instructions 和工具建一个 Thread 存消息然后 create run 再 poll 状态。现在这套持久对象没了官方迁移目标是 Responses API但这不是改个 endpoint 就能恢复的事。我见过最常见的误判是以为把https://api.openai.com/v1/threads换成/v1/responses就完事。结果请求格式对不上、会话状态接不回来、工具调用循环直接断掉。原因在于两边的抽象层级不同。旧模型里Assistant 是服务端持久配置对象Thread 是服务端持久消息容器Run 是在 Thread 上执行的一次任务状态由服务端维护。新模型里配置进入可版本化的 Prompt会话变成 Item 流Response 接收输入返回输出而工具调用循环、历史裁剪、重试这些编排职责更明确地落到了应用侧。换句话说迁移的本质是「把服务端帮你管的状态搬回你自己的代码里管」。这也是为什么本文不叫「改 URL 教程」而叫重建。下面我会先讲清楚对象映射再给出把 endpoint 和鉴权切到 TaoToken 的可复制配置最后用一次真实对话请求验证迁移是否成功。整套流程你可以跟着做不需要推倒重来但需要按对象逐个替换。2. 迁移前先把 TaoToken 接入配置准备好在动业务代码之前先把请求出口和鉴权准备好这样后面调试 Responses API 时不会把「迁移问题」和「网络/鉴权问题」混在一起。TaoToken 的接入方式兼容 OpenAI SDK 的调用习惯你只需要改 Base URL 和 API Key 两个地方模型 ID 按你实际要用的填。先拿 Key。打开 API Keys 页面创建一个密钥建议按项目或环境分开建方便后面出问题能单独吊销https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建后把 Key 存到环境变量不要硬编码进仓库。我习惯用.env加python-dotenv或系统的环境变量管理export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意 Base URL 这里写的是https://taotoken.net/api不带任何查询参数。SDK 会自动在它后面拼/v1/responses这类路径所以你不要自己再加/v1否则会变成/api/v1/v1/responses这种重复路径直接 404。如果你用的是 OpenAI 官方 SDK初始化客户端时这样写import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], )Node/TypeScript 项目同理import OpenAI from openai; const client new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, });这里有个容易踩的点旧代码里如果用的是openai.beta命名空间迁移后要改成普通客户端调用。beta.assistants、beta.threads、beta.runs这些入口在新对象模型下不再对应继续用只会报属性不存在。先把客户端初始化干净再往下写 Responses 调用。模型 ID 方面Responses API 用的是对话模型不是 Assistant 那种「配置对象里带模型」的写法。你在请求里直接指定model字段即可。具体可用模型以文档为准接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite配置阶段建议先跑一个最小连通性测试确认 Key 和 Base URL 没问题再进入对象迁移。这样后面如果报错你能快速判断是配置层还是代码层的问题。3. 可复制的 Responses API 配置与对象映射改造这一节是迁移的核心。我先把四组对象映射摆出来再给出可复制的配置片段。你要做的是把旧代码里对 Assistant/Thread/Run 的依赖逐个替换成 Prompt/Conversation/Response/Item 的用法。先看映射关系Assistants 旧对象Responses 侧对象职责变化AssistantsPrompts模型、工具、instructions 等配置变成可版本化 PromptThreadsConversations保存消息、工具调用、输出等 ItemRunsResponses接收输入返回输出工具循环由应用显式管理Run stepsItems执行过程以 Item 流形式呈现这里变的不只是名词。旧 Assistant 是服务端持久配置你建一次、存个 ID、以后每次 run 都引用它。新模型里官方建议在控制台把 instruction 和 tool bundle 建成具名 Prompt代码里引用稳定的 Prompt ID。这样配置和代码解耦改 prompt 不用发版。如果你暂时不想用控制台 Prompt也可以把 instructions 直接写在请求里但长期维护建议走 Prompt ID。会话部分旧 Thread 主要存消息新 Conversation 存的是 Item 流包括消息、工具调用和输出。历史裁剪、上下文窗口管理这些过去服务端帮你做一部分现在更明确地由应用侧负责。这意味着你要自己决定「带多少历史进下一次请求」。下面是一个可复制的 Responses 请求配置用 JSON 形式表达方便你对照自己的请求体{ model: 你的模型ID, instructions: 你是一个客服助手只根据知识库回答。, input: [ { role: user, content: 帮我查一下订单状态 } ], tools: [ { type: function, name: query_order, description: 根据订单号查询订单状态, parameters: { type: object, properties: { order_id: { type: string } }, required: [order_id] } } ] }对应到 Python SDK 调用response client.responses.create( model你的模型ID, instructions你是一个客服助手只根据知识库回答。, input[ {role: user, content: 帮我查一下订单状态} ], tools[ { type: function, name: query_order, description: 根据订单号查询订单状态, parameters: { type: object, properties: {order_id: {type: string}}, required: [order_id], }, } ], )如果你之前用settings.json或 TOML 管理配置可以这样组织把 Base URL、Key、Model ID 三件套集中管理[taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model 你的模型ID [agent] prompt_id 你的PromptID max_history_items 20工具调用循环是迁移里最容易出问题的地方。旧 Run 会自动处理「模型要求调用工具 → 你返回结果 → 模型继续」这个循环新模型下你要自己写。基本结构是拿到 response 后检查有没有 tool call有就执行工具、把结果作为新 Item 追加进 input再发一次请求直到没有 tool call 为止。这个循环必须显式写不能指望服务端帮你转。4. 用一次对话请求验证迁移是否成功配置改完别急着上生产。先用一次最小对话请求验证链路通不通再逐步加多轮和工具调用。验证的目标有三个请求能到达、返回结构符合预期、会话状态能接续。第一步跑一个无工具的纯对话请求response client.responses.create( model你的模型ID, input[{role: user, content: 用一句话说明你是什么模型}], ) print(response.output_text)如果这一步能打印出正常回答说明 Base URL、Key、模型 ID 三件套没问题。如果报 401是 Key 问题如果报 404多半是 Base URL 拼错或模型 ID 不存在如果报连接错误检查网络出口。第二步验证多轮会话。旧 Thread 的用法是建一次 Thread后续消息都往同一个 Thread 里塞。新模型下你要自己维护 Item 列表把历史带上history [] def chat(user_input): history.append({role: user, content: user_input}) response client.responses.create( model你的模型ID, inputhistory, ) answer response.output_text history.append({role: assistant, content: answer}) return answer print(chat(我叫小明)) print(chat(我叫什么名字))第二次请求应该能答出「小明」。如果答不出来说明历史没带上或者你只传了最新一条消息。这是迁移后最常见的「会话状态丢失」——不是服务端丢了是你没把 Item 流维护好。第三步验证工具调用。给模型一个会触发工具的输入观察返回里有没有 tool call 结构response client.responses.create( model你的模型ID, input[{role: user, content: 帮我查订单 A123}], tools[...], ) for item in response.output: if item.type function_call: print(触发工具:, item.name, item.arguments)看到function_call就说明工具声明生效了。接下来你要自己执行工具、把结果追加回 input、再请求一次直到模型给出最终文本。这一步跑通才算迁移完成。验证通过后建议把这次请求的完整响应结构打印出来存一份作为回归测试的基线。后面改 prompt 或换模型时拿它对比能快速发现行为漂移。5. 迁移常见报错排查401、local proxy failed、reading choices、OAuth迁移过程中报错集中在几类我按真实遇到的顺序列出来对照排查。401 Unauthorized。最常见的原因是 Key 没读到或读错。检查环境变量名是否和代码里一致检查 Key 有没有多余空格或换行。如果你把 Key 写在.env里确认加载顺序在客户端初始化之前。还有一种情况是 Key 被吊销或额度用尽去控制台确认状态。local proxy failed / connection error。这类报错通常出现在 Base URL 配置错误时。确认你写的是https://taotoken.net/api没有多余路径、没有尾部斜杠、没有自己加/v1。SDK 会自己拼路径你加多了就变成无效地址。另外检查本地是否有残留的代理环境变量HTTP_PROXY、HTTPS_PROXY指向了不可用的地址清掉再试。reading choices of undefined。这个报错说明代码在按旧的 Chat Completions 结构解析响应但 Responses API 返回的结构不一样。旧代码里习惯写response.choices[0].message.content新结构里文本在response.output_text输出项在response.output数组里。把解析逻辑改过来别继续用choices。OAuth / authentication 相关报错。如果你用的是某些 CLI 工具或 IDE 插件它们可能走的是 OAuth 登录流程而不是 API Key。迁移到 TaoToken 时要在工具的配置里显式填 Base URL、API Key、Model ID 三件套不要依赖它默认的登录态。以 Claude Code 这类工具为例配置里要写全{ base_url: https://taotoken.net/api, api_key: 你的密钥, model: 你的模型ID }三件套缺一个都可能报鉴权或模型找不到。如果你用 Cline、CC Switch 这类支持 MCP 的工具同样在配置里把这三项填全别只改其中一项。工具调用死循环。表现是模型反复要求调用同一个工具请求停不下来。原因通常是工具返回结果格式不对模型读不懂于是再调一次。检查你追加回 input 的工具结果 Item 结构是否符合规范字段名和类型别写错。另外给循环加一个最大轮次上限比如 5 次防止意外。历史越长越慢或报超长。旧 Thread 由服务端管理上下文新模型下你要自己裁剪。按 Item 数量或 token 估算截断保留最近 N 条或者做摘要压缩。别把全部历史无脑塞进去。排查时建议开 SDK 的日志把请求体和响应体打出来看。很多问题看一眼原始结构就清楚了比猜快得多。6. 迁移完成后继续用 Responses API 做长期 Agent迁移跑通只是起点。Responses API 的对象模型更适合做长期演进的 Agent因为配置、会话、执行三层职责清晰你可以分别优化。配置层用 Prompt ID 做版本管理改 prompt 不动代码会话层自己控制 Item 流做裁剪和摘要执行层显式管理工具循环方便加超时、重试和并发。如果你打算长期做编码类或 Agent 类应用建议把调用额度规划一下Coding Plan 适合持续高频的编码场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite调试模型行为、对比不同模型输出时可以直接在模型对话页面里试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入细节和参数说明以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite最后给一个实用建议把这次迁移当成一次架构梳理的机会。旧代码里那些「反正服务端会管」的假设现在都要显式写出来。写清楚之后你的 Agent 反而更可控——历史怎么裁、工具怎么重试、失败怎么降级全在你手里。迁移完成后先跑一周回归测试覆盖冷启动恢复、多轮状态、工具调用中断与重试、文件检索链路确认稳定再下线旧代码路径。