切换模型后 Agent 失效，常见原因落在任务契约：字段格式变了，工具参数没有通过校验，长资料被截断，错误返回也和原模型不同。迁移前需要固定输入、输出、工具协议与验收样本，再逐层检查差异。ZGI Runtime 把模型路由、Agent、Skill、Workflow 和知识放进同一工作区，模型配置可以单独调整，业务流程继续按原有任务契约验收。
多模型接入解决了"可以调用谁"，生产任务还要回答"切换后能否按原路径完成"。模型返回了一段通顺文字，只能说明推理请求成功。下游工具是否收到合格参数、任务状态是否推进、业务系统是否给出回执，需要继续核对。
概念示意图：模型可以更换，输入输出、工具协议和验收样本保持稳定。
先定位失效发生在哪一层
模型迁移出现问题时，直接重写 Prompt 容易把几类故障混在一起。先保留同一输入，观察输出从哪一步开始偏离，再决定调整模型参数、路由规则还是业务流程。
| 检查层 | 常见变化 | 验证方式 |
|---|---|---|
| 输入 | 上下文长度、文件处理方式变化 | 用长短资料分别运行 |
| 输出 | 字段缺失、类型变化、夹带解释文字 | 用 Schema 校验结果 |
| 工具 | 参数名、枚举值或调用顺序变化 | 检查工具请求与回执 |
| 流程 | 分支条件没有命中，状态未推进 | 查看节点输入输出 |
| 异常 | 超时、限流和拒绝返回不同 | 主动运行失败样本 |
模型名称不应散落在每个 Agent 和 Workflow 节点里。更容易维护的做法，是先给业务任务配置稳定的模型入口，再由路由层管理提供商、默认模型、凭证和使用策略。ZGI 的模型路由承担这部分配置，迁移时可以集中调整入口，减少同一改动在多条流程里重复发生。
把任务契约留在模型之外
任务契约至少要写清四件事：允许进入模型的字段、模型必须返回的结构、可以调用的工具，以及任务何时完成或停止。结构化输出用 Schema 检查，工具调用由接口再次校验，任务完成以业务回执为准。模型负责生成下一步内容，不能替代这些确定性判断。
客服工单分流可以把输出固定为工单类型、优先级、依据片段和下一步动作。更换模型后，四个字段仍然沿用同一规则；缺少依据时进入人工队列，工具参数校验失败时停止提交。这样能看出新模型改进了哪部分，也能找到它破坏了哪条约定。
任务状态也要独立保存。模型调用超时后，系统应知道已经读取了哪些资料、哪些工具已经执行、当前等待什么结果。重试或切换模型时继续使用同一任务编号，已经成功的写入动作不能再次提交。
用固定样本完成迁移
正式切换前，可以从真实任务中选一组正常样本和失败样本。正常样本覆盖短问题、长资料、结构化输出与工具调用；失败样本覆盖缺少参数、权限不足、接口超时和空结果。旧模型与新模型使用相同输入，比较字段通过率、工具调用结果、任务完成状态和人工介入位置。
这组样本需要随 Skill、Workflow 和业务规则一起维护。模型升级后重新运行，结果变化才能落到具体字段和节点。企业也可以先在 ZGI 的测试工作区配置新模型，只让测试 Agent 使用；确认结构、工具和状态都能按原约定工作后，再调整正式入口。
开始迁移时，先挑一条会调用工具的真实流程。记录当前模型、路由、输入版本、任务编号和最终回执，再换模型运行同一批样本。只看回答是否通顺很难发现执行问题，沿着任务契约逐项核对会更快。
ZGI 官网：https://zgi.cn
GitHub：https://github.com/zgiai/zgi