Agent 的灰度发布：提示词、模型、工具三条变更通道的隔离

传统灰度在 Agent 上失效的原因

微服务的灰度是按流量切：新版本接 5% 请求，看错误率和延迟，没问题再往上加。

这套做法搬到 Agent 上会失灵，原因是 Agent 的一次调用里同时存在三种可以独立变化的东西：

• 提示词（系统提示、few-shot、工具描述）
• 模型（厂商、版本、温度、参数）
• 工具（Schema 定义与背后实现）

这三样里任何一样变了，对外行为都可能变。而它们都不在代码里，走的是配置和外部依赖，所以版本号管不住它们。

结果是一个典型的场景：线上服务版本号没变，但某个上午行为突然变了——因为模型厂商做了静默升级，或者有人改了提示词。

灰度的单位不是请求，是配置快照

我的做法是把三条通道各自的版本组合成一个不可变的快照，形如：

prompt:v42 | model:vendor-a/2.1 | tools:v18

这个三元组就是灰度单位。发布时不是发布"新代码"，而是发布"新快照"，流量按快照分桶。

好处有三点：

• 出问题时能确定到底是哪条通道的哪一版，而不是笼统地说"新版本有问题"
• 三条通道可以独立滚动，改提示词不需要动模型
• 回滚是改一个指针，不是回滚代码

通道一：提示词

提示词的问题不是版本管理，是变更太容易。改一句话不用评审、不用测试，直接生效。

我的约束是两条：

提示词必须有版本号和变更记录。 谁改的、改了什么、为什么改。这条不是为了流程好看，是因为出事时你需要把某一次改动和某一天的指标下滑对起来。没有记录就一定对不上。

提示词不进代码仓库的发布流程。 它应该走配置中心，带灰度能力。但这也意味着它绕过了 CI 的检查，所以需要单独的回归——上线前用固定的用例集跑一遍。

通道二：模型

模型通道最需要克制，因为它的行为不可预测。

换模型不是换实现，是换了一个决策函数。同一个提示词，在 A 模型上能正确调用工具，在 B 模型上可能就不调了，或者调错参数。这类差异没法靠代码评审发现。

我的做法是：

模型变更必须整版切换，不做按比例灰度。

这条和常规做法相反。理由是模型行为差异是系统性的——如果新模型在 5% 流量上有问题，另外 95% 大概率也有，只是没暴露。按比例灰度给你的是虚假的安全感，而且会拉长不一致的时间窗。

正确做法是：用离线评测集全量跑一遍，通过就整版切，切完盯紧指标，出问题立刻切回。切换要能在分钟级完成，这是比灰度更重要的能力。

记录模型的确切版本串，不要只记别名。

厂商的 latest 类别名会静默指到新版本。我踩过这个坑：某天效果变差，查了半天发现是别名背后的实际版本换了。现在所有调用都记录返回里的确切版本号，并且别名不允许出现在生产配置里。

通道三：工具

工具通道的问题是它有两层：Schema 和实现。

Schema 变了（加参数、改类型、改描述），模型看到的东西就变了，行为会跟着变。实现变了但 Schema 没变，模型看不出来，但副作用可能变。

所以要分开管：

• Schema 变更按破坏性变更对待，加版本号，新旧并存一段时间，等提示词和调用方都迁完再下线旧的
• 实现变更走正常的服务发布流程，但要有幂等和副作用校验，因为 Agent 会重试

还有一点容易被忽略：工具描述也是提示词的一部分。很多人改工具描述时以为是改文档，实际上是在改模型的行为依据。

最隐蔽的一类问题：任务中途换了版本

前面说的都是发布层面。真正难处理的是运行时。

一个 Agent 任务可能跑十几步、几十分钟。如果在这期间发布把快照切了，同一个任务的前几步和后几步就跑在不同的配置上。后果是状态不兼容——按 v18 的工具 Schema 写入的数据，用 v19 的逻辑去读，就可能解析失败或语义错位。

所以必须做任务内版本锁定：任务开始时把快照固定下来，整个任务生命周期都用这一份，新快照只对新任务生效。

这需要一个前提：快照必须能被旧代码读到。也就是说快照不做原地修改，只追加。这是配置中心的基本要求，但经常被"删除旧版本"的清理策略破坏。

没有评测就没有灰度

灰度看什么指标？如果是看线上业务指标，那太慢了——等你看出来，已经影响了一批用户。

Agent 的灰度判断必须靠离线评测集，而且要按通道分组：

• 提示词、工具类变更：跑行为用例（该调的工具调了没有、参数对不对、格式合规吗）
• 模型类变更：跑质量用例（答案正确率、拒绝率、幻觉率）

评测集不需要大，五十到一百条覆盖主要路径就行。关键是它要稳定——同一份输入，同一份判定逻辑，这样才能比较两个版本。

没有这套东西的时候，我见过的最常见情况是：大家都不敢改提示词，或者改了也不知道变好还是变坏，最后靠"感觉还行"上线。

一个反对意见

不建议做小比例（1%～5%）的提示词灰度。

提示词的改动通常是全有或全无的：改了一句话，要么这个场景就不犯了，要么还是犯。它不像性能优化那样有渐进分布，5% 流量上的结论不能线性外推到 100%。

而且小比例灰度会让你误以为风险可控，从而跳过评测。

我更倾向于：小改动可以直接全量，配快速回滚；大改动必须先跑评测，再全量。灰度在这个场景里提供的价值，小于它带来的复杂度。

落地顺序

1. 先把三条通道的版本号定义出来，组合成不可变快照。
2. 让每次调用都记录快照，日志和 Trace 里带上。
3. 做任务内快照锁定，禁止中途切换。
4. 建最小评测集，按通道分组。
5. 最后才做流量分桶。到这一步你会发现，多数变更其实不需要分桶。

收尾

Agent 的发布治理，核心不是"怎么切流量"，而是"怎么知道变的是哪一样"。

提示词、模型、工具三条通道各自独立、各自有版本、组合成快照、任务内锁定。这四件事做到，灰度才有意义；做不到，灰度只是把一个说不清的变化分散到更多用户身上。

同系列：

• Agent 的状态与持久化：断点续跑、幂等与副作用补偿 https://cloud.tencent.com.cn/developer/article/2752149
• 工具层治理：Schema 版本、权限边界与破坏性操作的闸门 https://cloud.tencent.com.cn/developer/article/2759896
• 上下文装配架构：上下文预算、分层压缩与缓存复用 https://cloud.tencent.com.cn/developer/article/2753689
• Agent 评测体系架构 https://cloud.tencent.com.cn/developer/article/2750538