AI agent 灰度发布与功能开关：如何小流量验证新 prompt、新模型和新工具

AI agent 的一次小改动也可能影响很大。改一段提示词、换一个模型、调整工具 schema、增加一个检索源，都可能让旧任务退步。直接全量发布，等于把真实用户当成测试集。

灰度发布和功能开关能让 agent 变更更可控。对 AI agent 来说，发布对象不只是代码，还包括 prompt、模型、工具、检索源、权限规则和输出 schema。

先给结论：agent 变更要能开、能关、能回滚

变更	建议策略
prompt 调整	按版本灰度
模型切换	按任务类型或用户组灰度
新工具上线	默认关闭，白名单开启
RAG 源变化	对照评测后逐步放量
高风险动作	人工确认后再扩大范围

没有开关，就没有真正的回滚能力。

Feature flag 不能只控制页面入口

传统功能开关常控制 UI 是否展示。AI agent 的开关要更细：

flag	控制对象	示例
promptVersion	prompt 版本	`brief-agent-v8`
modelRoute	模型路由	简单任务用轻量模型，复杂任务用强模型
toolEnabled	工具开关	新发布工具只对白名单开放
ragSourceSet	检索源集合	新知识库只给内部账号
outputSchema	输出结构	v2 schema 小流量验证
humanReviewMode	审批策略	高风险任务强制确认

如果只控制“agent 是否开启”，一旦出问题只能全部关掉，无法定位和降级。

一、prompt 要版本化

不要只在代码里改一段文字。每个 prompt 版本要有 id、变更说明、适用任务、上线时间和回滚版本。

日志中也要记录本次任务使用哪个 prompt 版本。否则出现问题时无法定位是哪次改动导致。

发布记录可以这样写：

{
  "releaseId": "agent_release_20260506_01",
  "promptVersion": "brief-agent-v8",
  "basePromptVersion": "brief-agent-v7",
  "changedReason": "增强缺失字段追问",
  "expectedImpact": "降低信息不足时的错误继续率",
  "rollbackTo": "brief-agent-v7"
}

每一次 prompt 改动都应该能回答：改了什么、为什么改、预期改善哪个指标、怎么回滚。

二、灰度要按风险分组

可以先让内部账号、低风险任务、只读流程使用新版本，再逐步扩大到真实用户和写入流程。

阶段	范围
内部验证	团队账号
小流量	5%-10% 低风险任务
扩大流量	25%-50%
全量	指标稳定后发布

高风险工具不要和普通问答一起放量。

更稳的灰度维度包括：

维度	灰度方式
用户	内部账号、白名单、低风险客户
任务	只读任务先开，写入任务后开
工具	新工具默认关闭，按工具单独放量
成本	单任务预算较低的任务先开
置信度	高置信度结果自动继续，低置信度转人工

灰度不是简单 10% 流量，而是让风险小的请求先使用新版本。

三、对照指标要提前定义

灰度不是只看有没有报错。至少要看：成功率、人工接管率、格式错误率、工具失败率、平均耗时、成本、用户反馈。

如果新版本回答更好但成本翻倍，也未必值得全量。

建议给每个指标设置阻断阈值：

指标	观察方式	阻断条件示例
taskSuccessRate	任务完成率	比旧版本低 3%
schemaErrorRate	输出格式错误率	高于 1%
humanTakeoverRate	人工接管率	异常上升 20%
unsafeActionBlocked	高风险动作拦截	出现未拦截样本
avgCostPerRun	单次成本	上升超过 30%
p95Latency	95 分位耗时	超过基线 50%

没有阈值，灰度看板只会变成一堆数字。

四、回滚要保留旧版本和数据兼容

回滚不是把开关关掉这么简单。如果新版本写入了不同结构的数据，旧版本可能无法读取。发布前要确认数据结构是否兼容，或准备迁移和降级逻辑。

回滚预案至少包含：

1. 关闭新 promptVersion flag
2. 关闭新 toolEnabled flag
3. 新任务回到旧版本
4. 已在新版本运行中的任务继续使用原版本，避免中途切换
5. 对新 schema 写入的数据做兼容读取
6. 标记 release 为 rolled_back，并关联事故样本

最容易忽略的是第 4 点：长任务中途换 prompt 或工具，可能导致状态解释不一致。