文章摘要

前十一篇已经完成Agent目标解析、Tool Calling、状态管理、Memory、Planner-Executor-Reviewer闭环、Checkpoint、Human-in-the-Loop、多Agent协作、共享状态，以及代码与浏览器安全执行。系统已经具备完整的生产运行能力，但“能够运行”并不等于“值得发布”。

Agent质量不能只看最终文本。一个答案可能内容正确，却通过错误Tool、重复副作用、过度成本或未经审批的路径获得；离线黄金数据集可能高分，真实用户却因为长尾意图、权限、工具故障、延迟和多轮状态而无法完成任务；LLM-as-a-Judge可能受位置、长度、模型家族和Rubric影响；新版本可能在固定Benchmark上更好，却在真实流量中导致转人工率和成本上升。

本篇为整套生产级Agent系统补上最后一层质量控制：将Response、Trajectory、Task Success、Business Outcome和Safety统一到Evaluation Control Plane；使用冻结数据集保证历史可比，使用当前数据集覆盖最新Hard Case；通过生产Trace重放验证真实任务分布；通过影子流量比较稳定版和候选版，但严格阻断真实写操作；通过金丝雀验证真实用户、工具和业务结果；通过版本粘性、Slice阈值、零容忍安全指标和自动回滚控制发布；通过线上反馈、人工纠正和Judge分歧持续扩展数据集。

完成本篇后，《手搓生产级 AI Agent 系统》形成从任务理解、工具执行、持久化、协作、安全到质量发布的完整工程闭环。

一、本篇解决的问题

1. Agent质量应该评什么 2. 最终答案与执行轨迹如何同时评测 3. 黄金数据集如何版本化 4. 数据集更新后如何保持历史可比 5. LLM Judge如何校准 6. 生产Trace如何安全重放 7. 影子流量如何禁止真实副作用 8. 稳定版与候选版如何Pairwise比较 9. 金丝雀如何保持Run版本粘性 10. 哪些指标允许回归，哪些零容忍 11. 线上失败如何进入Hard Case 12. 如何自动扩量、暂停与回滚 13. 运行中的Checkpoint如何处理版本回退 14. 如何观测评测成本和Judge漂移

二、质量控制总体架构

┌─────────────────────────────────────────────┐ │ Candidate Manifest │ │ Model / Prompt / Graph / Tool / Policy │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ Offline Evaluation │ │ Rules / Frozen / Current / Replay │ └──────────────────┬──────────────────────────┘ │ pass ┌──────────────────▼──────────────────────────┐ │ Shadow Traffic │ │ Real Distribution / No Side Effects │ └──────────────────┬──────────────────────────┘ │ pass ┌──────────────────▼──────────────────────────┐ │ Canary │ │ Real Users / Sticky Run / Rollback │ └──────────────────┬──────────────────────────┘ │ ┌──────────────────▼──────────────────────────┐ │ Online Monitoring & Feedback │ │ Outcome / Human / Hard Case / Dataset │ └─────────────────────────────────────────────┘

三、Agent质量的五个层级

Response Quality Trajectory Quality Task Success Business Outcome Safety & Compliance

四、Response Quality

评估：

• 相关性；
• 完整性；
• 清晰度；
• 事实支持；
• 引用；
• 格式；
• 风格。

它是必要条件，但不是最终目标。

五、Trajectory Quality

评估：

• Planner是否合理；
• Tool是否正确；
• 参数是否正确；
• 顺序是否正确；
• 是否循环；
• 是否重复；
• 是否跳过审批；
• 是否正确恢复；
• 是否违反预算。

六、Task Success

由业务里程碑定义。

publicrecordTaskSuccessContract(StringtaskType,Set<String>requiredMilestones,Set<String>forbiddenOutcomes,DurationmaximumDuration,intmaximumUserCorrections,booleanhumanHandoffAllowed){}

七、Business Outcome

例如客服：

• 解决率；
• 转人工；
• 处理时长；
• 重开工单；
• 用户完成；
• 运营成本。

例如销售：

• 线索完整；
• 跟进创建；
• 错误触达；
• 转化；
• 合规。

八、Safety与Compliance

硬门禁：

跨租户访问 未经审批副作用 重复扣款 敏感数据泄露 危险Tool越权 旧审批执行 沙箱逃逸信号

这些不是平均分问题，而是零容忍事件。

九、Candidate Manifest

publicrecordAgentCandidateManifest(StringcandidateId,StringmodelProfile,StringpromptVersion,StringgraphVersion,StringplannerVersion,StringreviewerVersion,StringtoolCatalogVersion,StringknowledgeSnapshot,StringpolicyVersion,StringsandboxProfileVersion,StringevaluatorBundleVersion,StringimageDigest,StringmanifestHash){}

任何字段变化都生成新Candidate。

十、为什么Manifest不可变

否则评测期间修改Prompt或知识库，最终分数无法复现。

发布证据必须回答：

到底测的是哪个版本组合？

十一、Dataset分层

Smoke Dataset Frozen Regression Dataset Current Dataset Safety Dataset Trajectory Dataset Hard Case Dataset Production Replay Dataset

十二、Smoke Dataset

少量高价值样本，用于每次提交快速检查：

• Schema；
• Tool；
• 基本RAG；
• 高风险拒绝；
• 状态迁移。

十三、Frozen Regression Dataset

长期冻结，用于比较历史版本。

不能因为当前系统难题变化就不断修改。

十四、Current Dataset

持续加入：

• 新意图；
• 新知识；
• 新失败；
• 新语言；
• 新工具；
• 新风险。

用于判断当前真实能力。

十五、Safety Dataset

包括：

• Prompt Injection；
• 越权；
• 跨租户；
• 未审批副作用；
• 重复操作；
• 数据外传；
• 沙箱攻击；
• 浏览器恶意页面。

十六、Trajectory Dataset

不仅给输入和答案，还给：

• 允许Tool；
• 禁止Tool；
• 必需步骤；
• 最大调用数；
• 审批；
• Checkpoint；
• 失败注入。

十七、Dataset Manifest

publicrecordDatasetManifest(StringdatasetId,Stringversion,StringparentVersion,InstantcutoffTime,Map<String,Integer>sliceCounts,StringannotationPolicyVersion,StringdeduplicationVersion,StringcontentHash){}

十八、数据集更新后的双报告

Frozen Score 保证历史可比 Current Score 反映最新难题

新数据更难导致总分下降时，不应误判为模型回归。

十九、Slice

按：

• Task；
• 风险；
• 语言；
• 租户类型；
• 长上下文；
• Tool；
• 多轮；
• 浏览器；
• 代码；
• 新用户；
• 长尾；

切片。

二十、不要只看平均分

总体Task Success=94% 支付Slice=62% 越南语Slice=58% 浏览器提交=71%

总体平均值会掩盖关键失败。

二十一、评测器分层

确定性Rule 业务事实Evaluator LLM Judge 人工Reviewer 线上Outcome

二十二、确定性Rule

检查：

• Schema；
• 数字；
• JSON；
• Tool；
• 权限；
• 状态；
• 成本；
• 审批；
• 幂等；
• 禁止行为。

二十三、Spring AI Evaluator

Spring AI提供Evaluator接口，并提供相关性和基于给定上下文的事实支持评测能力。

可以用于：

• RAG相关性；
• Claim支持；
• 回归测试。

但它不替代Dataset、Slice、Gate和业务结果。

二十四、LLM Judge

适合：

• 开放式正确性；
• 完整性；
• 语义等价；
• Pairwise；
• 风格；
• 轨迹解释。

二十五、Judge偏差

需要治理：

• 位置；
• 长度；
• 自我偏好；
• 顺序；
• Prompt Injection；
• Reference错误；
• 模型漂移；
• 随机性。

二十六、Judge Manifest

publicrecordJudgeManifest(StringjudgeId,StringmodelProfile,StringpromptVersion,StringrubricVersion,doubletemperature,intsampleCount,StringmanifestHash){}

二十七、Pairwise双顺序

运行：

Stable=A Candidate=B Stable=B Candidate=A

不一致标记位置敏感，不强行判胜。

二十八、人工黄金集

人工标注：

• 明确通过；
• 明确失败；
• 边界；
• 高风险；
• 分歧。

Judge阈值在黄金集上校准。

二十九、False Pass

高风险最关注：

Judge把危险输出判为通过

发布门禁要限制Critical False Pass，而不只是总体一致率。

三十、Evaluation Case

publicrecordAgentEvaluationCase(StringcaseId,StringtaskType,Stringslice,JsonNodeinitialState,StringuserInput,List<RecordedToolInteraction>toolFixtures,TaskSuccessContractsuccessContract,List<ReferenceAnswer>references,RiskLevelrisk){}

三十一、Case Result

publicrecordAgentEvaluationResult(StringcaseId,StringcandidateId,ResponseEvaluationresponse,TrajectoryEvaluationtrajectory,TaskOutcomeoutcome,SafetyEvaluationsafety,CostUsageusage,Durationlatency,List<String>failureCodes,StringtraceRef){}

三十二、生产Trace重放

从生产采集：

• 输入；
• Context Manifest；
• Plan；
• Tool请求；
• Tool结果；
• 知识快照；
• 版本；
• 输出；
• 用户反馈。

候选使用录制依赖，不触发真实写操作。

三十三、重放固定时间

相对时间问题：

今天 上周 当前库存

必须使用原始request_time，否则候选与Stable面对不同世界。

三十四、隐私与权限

生产Trace进入评测：

• 去标识；
• 最小字段；
• 数据区域；
• 访问审批；
• 保留期；
• 删除；
• 审计。

评测环境权限不能比生产更宽。

三十五、影子流量

Stable正常响应用户；Candidate接收副本，结果只用于评测。

三十六、Shadow Tool Policy

publicenumShadowToolMode{RECORDED,READ_ONLY_LIVE,SANDBOX_WRITE,NO_OP,BLOCKED}

写Tool默认BLOCKED或SANDBOX_WRITE。

三十七、影子环境隔离

Candidate不共享：

• Memory；
• Checkpoint；
• 写缓存；
• 业务数据库；
• 通知；
• Artifact发布；
• 用户会话副作用。

三十八、影子比较

比较：

• 最终回答；
• Claim；
• Tool；
• 参数；
• 轨迹；
• 延迟；
• Token；
• 成本；
• Policy；
• 安全。

三十九、影子采样

按风险和价值：

新意图 长尾 工具任务 长上下文 新语言 低置信 高价值

加权。

四十、金丝雀

候选真正服务小比例真实用户。

前提：

离线通过 重放通过 影子通过 回滚演练通过

四十一、版本粘性

同一：

thread_id run_id

绑定同一Candidate。

不能多轮过程中切换Graph或Prompt。

四十二、Canary Assignment

publicrecordCanaryAssignment(StringassignmentId,StringroutingKey,StringcandidateId,intbucket,InstantcreatedAt,InstantexpiresAt){}

四十三、Canary扩量

内部用户 →低风险租户 →只读任务 →普通任务 →高价值任务

高风险任务最后进入，且保留人工门禁。

四十四、金丝雀指标

质量

• Task Success；
• Judge Preference；
• Tool Success；
• 引用；
• Reviewer通过。

体验

• 重新提问；
• 放弃；
• 转人工；
• 首Token；
• 总延迟。

成本

• Token；
• Tool；
• 多Agent；
• Judge；
• Sandbox。

安全

• 越权；
• 未审批；
• 重复副作用；
• 注入；
• 数据泄露。

四十五、Gate Policy

publicrecordGatePolicy(Map<String,MetricThreshold>global,Map<String,Map<String,MetricThreshold>>slices,Set<String>zeroToleranceMetrics,intminimumSampleSize,Stringversion){}

四十六、零容忍

cross_tenant_access unapproved_side_effect duplicate_side_effect stale_approval sensitive_data_leak sandbox_escape

任何一次都阻断或回滚。

四十七、质量阈值

quality:minimum-task-success:0.92maximum-critical-failure:0maximum-latency-regression:0.15maximum-cost-regression:0.20maximum-human-handoff-regression:0.05

阈值按Slice覆盖。

四十八、样本不足

小样本金丝雀语义指标噪声大。

策略：

不自动扩量 延长观察 扩大低风险流量 人工检查

四十九、自动回滚

适合硬信号：

• 安全；
• 错误；
• 延迟；
• Provider；
• 重复副作用。

语义分数噪声较大时：

暂停扩量

而不是立即回滚。

五十、运行中的Run

回滚只切换新分配。

正在运行的Candidate Run可能：

• 有Checkpoint；
• 有Tool结果；
• 等待审批；
• 使用新State Schema。

处理：

• 继续原版本；
• 安全迁移；
• 取消；
• 人工。

不能直接交给Stable读取。

五十一、Release Decision

publicrecordReleaseDecision(StringdecisionId,StringcandidateId,ReleaseStagecurrentStage,ReleaseStagenextStage,GateDecisiondecision,List<String>evidenceRefs,List<GateViolation>violations,StringdecidedBy,InstantdecidedAt){}

五十二、线上反馈

显式：

• 点赞；
• 点踩；
• 评论；
• 人工评级。

隐式：

• 重复改写；
• 转人工；
• 撤销；
• 放弃；
• 重新执行；
• 业务完成。

五十三、反馈不能直接当真值

用户可能误解、情绪化或点击错误。

流程：

反馈 →归因 →抽样人工 →去标识 →Hard Case →Dataset版本

五十四、Hard Case Mining

挖掘：

• 高风险失败；
• Judge分歧；
• 用户纠正；
• Tool UNKNOWN；
• 长循环；
• 高成本；
• 高延迟；
• 新意图；
• 长尾语言。

五十五、数据闭环

线上Run →Feedback →Failure Taxonomy →Human Audit →Hard Case →Current Dataset →下一Candidate

五十六、失败分类

publicenumAgentFailureCode{INTENT_MISUNDERSTOOD,PLAN_INVALID,WRONG_TOOL,INVALID_ARGUMENT,TOOL_FAILURE,STALE_CONTEXT,UNSUPPORTED_CLAIM,LOOP,BUDGET_EXCEEDED,APPROVAL_VIOLATION,DUPLICATE_SIDE_EFFECT,USER_ABANDONED}

五十七、评测成本

成本包括：

• Candidate推理；
• Tool Fixture；
• Judge；
• 多次采样；
• 影子；
• 人工；
• 存储；
• Replay。

按Candidate、Stage、Slice归因。

五十八、评测缓存

Key包括：

case_hash candidate_manifest_hash evaluator_manifest_hash dataset_version

任何一项变化都Cache Miss。

五十九、OpenTelemetry与观测

Trace记录：

gen_ai operation model usage agent task evaluator evaluation score candidate stage

同时避免将完整敏感Prompt默认写入普通Telemetry。

六十、Trace结构

release.candidate ├─offline.eval │ ├─agent.run │ ├─rule.eval │ └─judge.eval ├─shadow.run │ ├─stable │ └─candidate ├─canary.run └─gate.decision

六十一、指标

agent_eval_case_total{ stage, result } agent_eval_task_success_rate{ slice } agent_eval_trajectory_violation_total{ code } agent_eval_judge_disagreement_rate agent_shadow_preference_rate agent_canary_task_success_rate{ candidate } agent_canary_cost_total{ candidate } agent_release_gate_total{ stage, decision } agent_release_rollback_total{ reason } agent_hard_case_total{ failure_code }

六十二、评测SLO

高风险Dataset覆盖率=100% 关键Tool轨迹覆盖率=100% Judge人工一致率≥85% Critical False Pass=0 影子真实副作用=0 金丝雀重复副作用=0 发布证据可追溯率=100%

六十三、自动化测试矩阵

规则失败阻断 Frozen回归 Current新Slice Judge顺序反转 Trace时间固定 影子写Tool阻断 影子Memory隔离 Canary粘性 零容忍回滚 运行中Checkpoint继续原版本 Hard Case去标识 重复Release Event幂等

六十四、发布流水线

stages:-deterministic-frozen-benchmark-current-benchmark-trace-replay-shadow-internal-canary-low-risk-canary-broad-canary-promote

六十五、管理后台

展示：

• Candidate Manifest；
• Dataset；
• Slice；
• Case；
• Failure；
• Judge；
• Cost；
• Shadow Diff；
• Canary；
• Gate；
• Rollback；
• Hard Case；
• 线上反馈。

六十六、人工决策

以下情况进入评审：

• Judge分歧；
• 样本不足；
• 新高风险Slice；
• 质量和成本权衡；
• 线上投诉；
• 旧Run迁移；
• 语义指标边界。

六十七、治理职责

产品

定义Task Success和业务结果。

研发

实现规则、Trace和Gate。

算法

维护Dataset、Judge和模型。

安全

维护零容忍指标和攻击集。

运营

处理反馈和人工接管。

六十八、不能只追求高分

过度优化Benchmark可能：

• 迎合Judge；
• 增加冗长；
• 增加成本；
• 降低真实体验；
• 忽略新意图。

必须持续用线上结果验证离线指标是否仍有预测力。

六十九、指标相关性

定期分析：

离线分数 与 线上Task Success 用户满意 转人工 业务结果

相关性下降时，更新Rubric、Dataset或指标。

七十、上线检查清单

□ Candidate Manifest完整且不可变 □ 质量覆盖Response、Trajectory、Task、Outcome和Safety □ Frozen与Current Dataset同时维护 □ Dataset按Slice报告 □ Rule、Judge和业务事实职责分离 □ Judge经过位置、长度和人工校准 □ Trace重放固定时间、知识和Tool □ 影子写操作、Memory和通知被阻断 □ Stable与Candidate缓存隔离 □ 金丝雀按Run版本粘性 □ 安全事件零容忍 □ 样本不足不自动扩量 □ 回滚只切换新流量 □ 运行中Checkpoint有兼容策略 □ Release Decision保存证据 □ 线上反馈经过审查进入Hard Case □ 评测成本和Judge漂移可观测

总结

全链路评测的核心不是给Agent增加更多分数，而是建立一条可信的发布证据链：

固定数据证明没有已知回归 生产重放证明能处理真实任务 影子流量证明候选不会污染生产 金丝雀证明真实用户和业务可接受 线上反馈证明质量可以持续演进

经过十二篇建设，生产级Agent系统已经形成完整闭环：

目标 →计划 →执行 →审校 →持久化 →人工 →多Agent →安全沙箱 →质量发布 →反馈改进

一个真正可上线的Agent，不仅要能完成任务，还必须证明它在不同数据、不同流量、不同故障和不同版本下，始终保持正确、安全、可控和可回滚。