Agent Builder 停服迁移:把可视化工作流重建成可测试的代码
Agent Builder 停服迁移:把可视化工作流重建成可测试的代码

2026 年 11 月 30 日,OpenAI 将关闭 Agent Builder。很多团队是在收到邮件或看到控制台提示后才开始盘点:画布里跑着客服分流、销售线索、文档问答,网站上的 ChatKit 还在用,代码里还留着一串可复用提示词 ID。问题不是“要不要迁”,而是先迁哪个、导出能不能用、上线前怎么证明新系统没有变差。

先给结论。第一,停的是 Agent Builder、Evals 和可复用提示词,不是模型与 Responses API。第二,ChatKit 前端保留,但指向 Agent Builder 的托管后端要迁走。第三,官方导出是代码脚手架,不转换工作流图,也不保证行为一致。第四,真正的工作量在资产盘点、语义重建和双轨验证。第五,迁移的目标不是换一个画布,而是让工作流逻辑回到企业自己的代码、版本库和运维体系里。

一、先划范围:停的是画布和评测台

据 OpenAI 2026 年 6 月 3 日的弃用公告,三项产品进入停服流程。官方时间表可以压成一张表:

产品时间状态要做什么
Agent Builder2026-11-30计划关闭导出并重建
Evals2026-10-31 起只读;11-30 关闭控制台与 API 计划关闭导出数据集与结果,迁到 Promptfoo
v1/prompts2026-11-30计划关闭提示词内容迁入应用代码
ChatKit未列入关闭继续可用托管后端要迁到自建服务
Responses API 与模型未列入关闭不受影响无需迁移

这张表里有两个容易误读的地方。第一个是 ChatKit。OpenAI 在 Agent Builder 指南中写明 ChatKit 继续可用,但 ChatKit 有两种接法:托管模式连接 Agent Builder 工作流,由 OpenAI 运行;高级集成模式连接你自己服务器上的 Agent,例如用 Agents SDK 构建的服务。前者的前端可以留着,后端必须在停服前搬走;后者本来就不依赖 Agent Builder。如果网站上的 ChatKit 组件指向托管工作流,停服后组件还在,背后的工作流不会继续运行。迁到自建服务后,服务器、鉴权、权限和监控也随之一并转到自己身上。

第二个是 Evals。2026 年 10 月 31 日起,现有评测转为只读;11 月 30 日,控制台和 API 计划关闭。只读意味着还能看,但不适合再作为日常评测流程。数据集、评分器、历史结果要在关闭前导出。OpenAI 在迁移文档中把 Promptfoo 作为继续评测的路径;Promptfoo 是开源 CLI 与库,配置可以进版本库,也能接进 CI。

还有一个边界要说清楚:官方没有说明停服后对旧 workflow ID 或 prompt ID 的请求会返回什么,也没有说明停服后是否还能导出。工程上按“不能”处理,所有需要保留的内容在 11 月 30 日前完成导出和备份。

二、谁受影响:四类资产,不是一类

很多团队以为“迁 Agent Builder”就是迁画布,实际要盘的是四类资产。

第一类,Agent Builder 工作流。包括已发布和草稿。已发布工作流可能被 ChatKit、内部系统、定时任务或 API 调用;草稿里也可能藏着还没上线但业务已经答应的流程。两类都要列。

第二类,ChatKit 托管后端。网站或应用里的聊天组件本身不用重写,但它指向的工作流要换成自建服务。高级集成模式需要一个新的服务端入口,负责会话、鉴权、工具调用和日志。

第三类,代码里的可复用提示词。v1/prompts 关闭后,代码里通过 prompt ID 取提示词的调用会失效。OpenAI 的建议是把提示词内容迁进应用代码。迁移不是把字符串复制过去就完了,还要把版本、变量、模型参数和评测用例一起带过去。

第四类,Evals 资产。数据集、评分器、历史运行结果和对比记录。它们既是质量基线,也是迁移后证明“没有变差”的证据。只读不等于可以慢慢处理,关闭后控制台和 API 都不可用。

Connector Registry 不在这次停服清单里,但工作流迁到新环境后,连接器的授权、scope 和密钥要重新配置。画布里的“已连接”状态不能当作新系统的凭证。

三、先盘点:把画布资产变成一张可决策的表

不要先写代码。先做一张资产表,每个工作流一行。字段至少覆盖五组:

分组字段用来判断
标识workflow_id、名称、版本、创建时间标识与变更历史
业务业务负责人、技术负责人、使用部门谁对停服后果负责
入口ChatKit、内部系统、API、定时任务、人工触发停服后从哪里断
技术模型、节点数、工具、MCP Server、数据源、提示词版本重建范围与依赖
运行日调用量、失败率、P95 延迟、单次成本优先级与验收基线
风险人工审批点、重试规则、超时、是否写生产系统切换风险与回滚方案
状态是否生产、最近一次使用、停服影响迁、停还是冻结

字段不必一次求全,但“业务负责人、入口、日调用量、是否生产、失败后果”不能缺。没有负责人的流程,先不进入迁移范围;没人能说清失败后果的流程,也无法定优先级。

盘完以后按四档分级:

级别判断标准处理方式
P0客户可见、生产核心、停服即业务中断优先重建,完整双轨验证
P1内部高频使用,停服会明显影响效率排期重建,简化验收
P2试点、低频、可临时人工替代导出备份,暂不重建
P3实验、废弃、无人使用冻结,不再投入

分级的目的不是写报告,而是做减法。P3 直接冻结,不再投入;P2 只做导出备份,不重建;P0 和 P1 进入迁移队列。很多迁移项目的时间不是花在 P0 上,而是被一堆“曾经演示过”的流程拖住。

盘点的另一个产出是依赖图:哪个工作流调用了哪个工具、哪个连接器、哪个提示词、哪个数据源。依赖图能提前暴露“迁了一个流程,结果另一个流程的提示词 ID 也失效”的连锁问题。

四、导出的边界:拿到的是脚手架,不是成品

OpenAI 的迁移指南给了四步:在 Agent Builder 打开工作流,选择顶部导航的 Code,选择 Agents SDK,再选 TypeScript 或 Python,复制完整导出到代码仓库。

指南同时写明:这个过程不会转换工作流图,也不保证所有行为原样迁移。这句话是整篇文档里最需要划重点的一句。导出物适合当起点:agent 定义、工具签名、提示词文本和部分编排代码。它不是一个可以直接上线的等价系统。

重建前,建议做一张“画布语义到代码组件”的对照表:

画布元素代码里的对应物验证点
Agent 节点Agent 定义与 instructions模型、参数、工具集是否一致
条件分支路由函数或图边边界条件、默认分支、空值
循环与批处理迭代器或任务队列最大轮次、超时、幂等
Guardrail输入校验与输出校验触发顺序、失败策略、误拦截
Set stateSession 或数据库并发写、恢复、过期清理
User approval中断与审批单超时、越权、审批期间状态变化
Tool 与 MCP函数工具或 MCP 客户端鉴权、scope、超时、错误分类
Retry错误分类与退避策略哪些能重试,哪些必须停

这张表要在写代码前填完。每填一行,就问三个问题:旧系统在这里的默认值是什么?失败时走哪条分支?新系统怎么证明行为一致?三问答不上来,这一行就还不能算迁完。

最常见的三类丢失,都不在模型调用本身。第一类是隐式默认值:画布节点里没填的模型参数、超时、重试次数,导出后可能变成框架默认值。第二类是类型转换:节点之间的字符串、对象、数组在画布里有隐式转换,代码里需要显式处理。第三类是 guardrail 顺序:输入校验、工具调用、输出校验的先后关系,画布用连线表达,代码里要用控制流表达。三类问题都不会在“能跑通一个 demo”时暴露,只会在真实输入的边界条件上出现。

五、三条路线怎么选

官方给出两条主路径:Agents SDK 和 ChatGPT Workspace Agents;工程上通常还有第三条:工作流工具或自建 MCP 服务。三条路线对应不同的确定性要求。

场景建议路线前提与代价
客户可见、业务关键、带 ChatKit 前端Agents SDK 自托管可测试、可版本化;托管与运维自己承担
内部自然语言助手、团队已用 ChatGPTWorkspace Agents需 Business、Enterprise 或 Edu 工作区及创建权限
跨系统、步骤确定的自动化n8n 等工作流工具模型只做少量判断,流程更可控
Agent 主要读写企业自有系统自建 MCP Server工具可跨助手复用,需自己做鉴权与审计

路线一,Agents SDK 自托管。适合业务关键、客户可见、带 ChatKit 前端的工作流。SDK 的核心原语不多:Agent 定义、handoff(把任务交给另一个 Agent)、guardrail(输入输出校验)、session(会话记忆)和 tracing(链路追踪)。代码进版本库,能做代码评审、单元测试和回放;模型也可以按步骤选择,通过适配层接不同供应商。代价是托管、鉴权、权限、扩缩容和监控都要自己负责。

路线二,ChatGPT Workspace Agents。适合内部自然语言助手:团队已经在 ChatGPT 里工作,流程不依赖强确定性,出错也能人工兜底。官方要求 ChatGPT Business、Enterprise 或 Edu 工作区,并且账号有创建工作区智能体的权限。做法是把导出的代码粘贴到对话里,让构建器转换,再检查它标记出的行为差异。官方也提示,依赖强确定性的工作流未必能原样迁移。

路线三,工作流工具或自建 MCP。如果原来的“智能体”本质是“一个系统里发生 X,就去另一个系统做 Y”,用 n8n 这类工作流工具可能比 Agent 更合适:步骤确定、模型只负责少量判断。如果 Agent 主要是读写企业自己的系统,可以把工具做成自建 MCP Server,让同一组工具在 ChatGPT、Claude 和其他助手之间复用,下一次平台变化时迁移成本更低。

三条路线可以组合。常见做法是:P0 走 SDK,内部低频助手走 Workspace Agents,跨系统通知走工作流工具,企业系统工具统一收口到 MCP。不要为了“统一”把确定性的流程硬塞进 Agent,也不要为了“快”把客户可见的流程放进一个不可测试的画布替代品。

六、重建:把工作流拆成可测试的组件

迁移不是把整个画布写成一个超长函数。建议按职责拆目录:

agents/          每个 Agent 的指令、模型参数、工具集
tools/           函数工具与 MCP 客户端,含超时、重试、鉴权
workflows/       编排:顺序、分支、循环、并行
guardrails/      输入校验、输出校验、敏感动作审批
state/           会话状态、任务状态、幂等键
evals/           数据集、评分器、回归用例
observability/   日志、指标、追踪、告警

拆完以后,有五个工程点必须补上,画布通常不会替你做:

一是幂等。工具调用可能超时后重试,写工单、发邮件、创建订单这类动作要有幂等键,避免“重试一次,重复一条”。幂等键由业务对象生成,不由模型生成。

二是人工审批。画布里的人工节点迁到代码后,要变成可恢复的中断:任务暂停、生成审批单、记录审批人、恢复执行。审批超时怎么办、审批人离职怎么办、审批期间状态变了怎么办,都要有规则。

三是错误分类。不是所有错误都值得重试。网络超时、限流可以退避重试;参数错误、权限拒绝、业务校验失败重试多少次都没用,应该直接失败并告警。把错误分成可重试、不可重试、需人工三类,比统一重试三次更有效。

四是状态持久化。会话状态放数据库或专用 session 存储,进程重启后能恢复;长任务要能从中断点继续,而不是从头再跑。状态里不要存明文密钥和完整敏感数据。

五是密钥与权限。画布里的连接器授权不能原样复制。新环境按工具、按环境、按任务发凭证,能短时有效就不长期保存;上线前轮换一次,避免旧密钥留在导出文件和日志里。

还有一件事容易被忽略:给工作流补上画布没有的可观测性。每次运行记录 trace_id、会话、Agent、工具、参数摘要、结果摘要、耗时、token 用量、重试次数和人工介入点。没有这些,迁移后只能看到“成功或失败”,无法定位是哪一步变差。

七、双轨验证:用真实输入证明没有变差

迁移完成不等于可以切换。上线前至少做四步双轨验证。

第一步,冻结回放集。从旧系统近 30 天的真实输入里抽样,覆盖高频、长尾、边界和失败案例。不要只用产品经理准备的“标准问题”;真实输入里的错别字、指代、缺参数和多意图,才是迁移后最容易出问题的地方。

第二步,新旧并行回放。同一批输入分别跑旧工作流和新服务,按会话 ID 对齐。对比三层:最终输出、工具调用序列、中间状态。只看最终回答,会漏掉“答案对了但调用了不该调用的工具”这种问题。

第三步,影子流量。在真实入口上把一小部分流量复制到新系统,不对外返回结果,只做记录和比对。影子流量能发现回放集覆盖不到的真实分布,也能测出新服务的延迟和成本。

第四步,人工复核。对高风险场景和差异样本做人工抽检,记录判定理由。抽检不是走过场,要能回答“这条差异是模型随机性、提示词变化,还是工具行为变化”。

验收指标建议固定为八项:

指标看什么与旧系统怎么比
任务成功率端到端完成且结果被接受不低于旧系统基线
人工接管率需要人工兜底或审批的比例不高于基线加两个百分点
工具错误率超时、鉴权失败、参数错误不超过基线的一点二倍
P95 延迟端到端耗时不超过基线的一点二倍
单次任务成本模型、托管与重试分摊与预算和基线对账
回归通过率固定回放集通过比例达到项目约定阈值
审计覆盖率关键调用是否有完整字段不低于约定比例
回滚耗时从发现异常到恢复旧路径在约定时间窗内

阈值不要拍脑袋。以旧系统近 30 天的基线为参照,P0 工作流的任务成功率不低于基线,人工接管率不高于基线加两个百分点,工具错误率和 P95 延迟不超过基线的一点二倍;回归通过率、审计覆盖率和回滚耗时按项目验收标准设定。这些是示例口径,实际以客户环境和业务容忍度为准。

我们还建议加一条“差异解释率”:所有与旧系统不一致的样本,必须有归因记录。差异解释率达不到约定比例,说明团队还没有真正理解新旧系统的行为差异,不建议全量切换。

八、边界与成本

迁到自托管,责任也跟着迁。服务器、操作系统、运行时、依赖升级、鉴权、密钥、备份、扩缩容、监控和值班,原来由平台承担的部分,现在由企业自己承担。没有运维能力的团队,选 Workspace Agents 或托管工作流工具更现实;但要把数据边界、管理员权限和连接器授权一起评估。

成本建议分四本账算:模型调用、托管资源、运维人力、评测运行。迁移后成本上升,常见原因不是模型单价,而是重试变多、上下文变长、工具调用链变长,以及为了双轨验证同时跑两套系统。把四本账分开记,才能判断是迁移本身贵,还是旧流程本来就有浪费。

合规边界也要提前确认。工作流里如果涉及客户数据、订单、工单、合同或个人信息,迁到新环境后数据存放在哪里、保留多久、谁能访问、是否跨境,都要按企业制度和适用法规重新评估。本文讨论的是工程迁移方法,不构成法律意见。

三个不建议:不建议把 P3 实验流程一起迁;不建议把导出代码直接当生产代码;不建议用提示词里的“不要做危险操作”代替权限、审批和出口控制。

九、常见问题

问:ChatKit 是不是也要停?
不是。OpenAI 明确 ChatKit 继续可用。要迁的是它背后的托管工作流。前端组件可以保留,后端换成自建服务;自建后服务器和运维由企业负责。

问:导出的 TypeScript 或 Python 能直接上线吗?
不建议。官方说明导出不转换工作流图,也不保证行为一致。把导出当脚手架,补齐分支、校验、状态、审批、重试和可观测性,再用真实输入回放验证。

问:Evals 的数据还能拿回来吗?
2026 年 10 月 31 日起现有评测只读,11 月 30 日控制台和 API 计划关闭。要在关闭前导出数据集、评分器和历史结果,并按 Promptfoo 的配置格式重建回归用例。关闭后能否读取,官方没有给出保证。

问:没有工程团队,能不能全部放 Workspace Agents?
内部自然语言助手可以,但需要 Business、Enterprise 或 Edu 工作区,且依赖强确定性的流程未必能原样迁移。客户可见、涉及写入或付款的流程,仍建议走可测试的代码路线。

问:迁移一个工作流要多久?
取决于节点数、自定义工具、审批点和验证范围,不能用一个固定天数回答。先盘点再估算;P0 流程通常要经历重建、回放、影子流量和人工复核,时间主要花在验证,不在导出。

附:口径与来源

  • 停服范围与时间:OpenAI API Deprecations,2026-06-03 公告;Agent Builder 计划于 2026-11-30 关闭,Evals 于 2026-10-31 转为只读、11-30 关闭控制台与 API,v1/prompts 与可复用提示词对象于 11-30 关闭;ChatKit 继续可用,Responses API 与模型不受影响。核对日期:2026-11-17。
  • 产品发布:OpenAI《Introducing AgentKit》,2025-10-06;Agent Builder 为可视化多智能体工作流画布,支持版本、预览、ChatKit 嵌入与 SDK 代码导出。
  • 导出步骤与边界:OpenAI《Migrate from Agent Builder》;四步为打开工作流、选择 Code、选择 Agents SDK、选择 TypeScript 或 Python 并复制完整导出;原文写明“不转换工作流图,也不保证所有行为原样迁移”。
  • Workspace Agents:OpenAI 迁移指南要求 ChatGPT Business、Enterprise 或 Edu 工作区及创建工作区智能体的权限;ChatGPT Business 发布说明记录了 2026-04-22 起逐步开放、2026-05-22 起在 Business、Enterprise、Edu 正式可用。
  • 评测迁移:OpenAI Cookbook《Moving from OpenAI Evals to Promptfoo》;Promptfoo 为开源 CLI 与库,配置可本地运行或接入 CI。
  • Agents SDK 能力:OpenAI Agents SDK 文档;核心原语包括 Agents、handoffs、guardrails、sessions、tracing、human-in-the-loop 与 MCP 工具调用;默认使用 Responses API,也可通过模型适配层接其他供应商。
  • 独立分析:Reflektlab《OpenAI Agent Builder Is Shutting Down on 30 November 2026》、Hidekazu Konishi 的停服范围逐页核对、AgenticWire《What the Export Loses》,用于交叉验证官方时间线与导出边界;其服务报价与迁移天数不作为本文依据。
  • 文中的资产表、P0–P3 分级、语义对照表、双轨回放与八项验收指标,为美辰信息技术在企业智能体迁移项目中的实践模板;阈值需按业务场景、数据分级和客户环境调整。

迁移的最终判断标准不是“新系统能跑”,而是“旧系统停掉后,业务还能按原来的质量运行,并且你知道哪里可能变差、怎么发现、怎么回滚”。把这句话写进验收单,比任何一张架构图都更有用。