本文是「Agent 开发实践与思考」系列第 14 篇。系列目录：
- 2024
- 2025
年初给转码 Agent 更换过一版模型。十几个自测示例的表现都优于旧版；上线后的第一个真实迁移单元中，验证契约三层均通过，评审时却发现弹窗提交成功后父列表没有刷新。旧代码没有覆盖这个行为的测试，新版本模型也没有排查到它。类型检查和构建通过，不能证明迁移已经完成。
完成巡检 Agent 的异步改造后，同样需要评估。它会消费告警、查询日志，有时还会执行可逆的处置动作。离线跑通一条告警链路，不能证明它会在长期运行中稳定地产生相同判断，也不能证明它始终遵守转人工的边界。
最初我将评估理解为准备一批任务并统计通过率。实际落地时，需要分别处理任务结果、执行轨迹、资源消耗，以及线上出现但离线集未覆盖的问题。将它们合并为一个总分，无法据此定位应修改的部分。
Agent 评估的指标维度
梳理内部评估体系时，我将常见文献中的维度列在同一张表中。业界大多数文献主要关注任务完成率（“Beyond Accuracy: A Multi-Dimensional Framework for Evaluating Agentic AI”, 2024）。企业内部落地时，成本、可靠性和安全性也需要单独评估；仅用通过率可能无法暴露这些问题。
| 维度 | 典型指标 | 我在意的原因 |
|---|---|---|
| 任务完成率 | Success Rate、Resolve Rate | 回答任务是否完成 |
| 推理步骤效率 | Steps-to-completion、Token 消耗 | 两个方案都完成任务时，成本可能相差一个数量级 |
| 工具调用准确率 | API Call Correctness | 参数和 schema 是否正确，可由机械规则判断 |
| 规划能力 | Plan Quality Score | 多步任务是否采用合理的分解路径 |
| 鲁棒性 | Error Recovery Rate | 工具失败或环境异常后能否恢复 |
| 泛化能力 | Cross-domain Transfer Score | 更换仓库或告警类型后是否仍然稳定 |
| 成本效率 | $/task、Token/task | 影响系统是否能够长期运行 |
| 安全性 | Constraint Violation Rate | 用于发现越权和误操作 |
| 可靠性 | Variance across runs | 同一任务多次运行时结果是否稳定 |
| 自主性 | Human Intervention Rate | 跟踪人工介入比例的变化 |
| 多轮交互 | Context Retention | 长会话或长任务中，早期约束是否仍然生效 |
| 可解释性 | Decision Justification Quality | 出问题时能否定位原因 |
不需要为每个任务评估全部十二项。一次性、单轮的问答类任务，前四项和安全性通常足够；巡检 Agent 与转码 Agent 会长期运行，并且能够修改外部状态，因此可靠性、自主性和安全性应提高权重。否则，单次通过可能掩盖系统在真实环境中的不稳定行为。
代码类任务还有通用列表未覆盖的维度。转码和重构需要在新实现中保留旧行为，不能仅以生成新代码作为完成标准。
| 专有维度 | 评估方法 | 核心挑战 |
|---|---|---|
| 语义保持性 | 单测 PASS_TO_PASS + 接口兼容检查 | 测试覆盖不足时，无法证明改动前后完全等价 |
| 代码质量提升 | CodeBLEU、圈复杂度变化、重复率变化 | 质量指标主观性强，自动化只能覆盖一部分 |
| 安全性（不引入新 Bug） | 编译通过 + 回归测试 + 类型检查 | “部分重构”容易遗漏引用方 |
| 跨文件上下文理解 | 多文件编辑正确性 + 依赖链追踪 | 大仓库中上下文窗口和检索都可能不足 |
拆解 Coding Agent 一文中的迁移说明、影响图和验证契约，为这四项专有维度收集证据：迁移说明里的 contract 和 behaviors 字段对应语义保持性，verification 对应安全性，影响图对应跨文件理解。评估应将这些证据结构化执行、记录并支持复现。
按优先级，我将任务完成率、语义保持性和安全性放在第一梯队，要求每次通过；代码质量、成本效率和可靠性放在第二梯队，常规迭代中持续检查；跨文件理解、规划能力和自主性放在第三梯队，跟踪其变化趋势。这个排序适用于当前的任务分布和风险偏好，不是通用结论。
任务契约定义初始状态、权限与完成条件
任务本身不足以构成可评估单元。评估还需要定义初始状态、Agent 的允许操作、完成条件和停止条件。这四项构成任务契约。
转码 Agent 的契约通常保存在仓库中，包括基线 commit、允许修改的目录、不可修改的接口、验收命令、预算和需要人工确认的问题。拆解 Coding Agent 一文中的迁移说明、阶段权限和验证契约，都是可供程序和人读取的任务条件记录。代码、测试和文档相互冲突时，needs_review 也应是契约允许的结果；系统应停止写入，等待人工确认。
巡检 Agent 的任务契约还需要定义动作影响范围和幂等条件。查询日志和 trace 可以自动执行；重启实例、摘流等可逆动作需要记录事件 ID、目标对象和执行结果；回滚、修改配置、写业务库等动作只能生成待办。评估应检查它是否在相应条件下遵守权限边界，排障报告是否通顺不能证明这一点。
无法写出任务契约的题目不应进入评估集。团队未表达业务验收条件时，模型无法替代团队补齐这些条件。
终态、轨迹和权限边界分别评估
一条 Agent trace 可拆分为三类评价对象，它们的判据和用途不同。
第一类是终态，包括文件是否生成、代码是否通过测试、告警是否被正确处置。终态校验接近工程真正关心的结果，也允许多条正确路径同时通过。WebArena 将网页任务放在可重置环境中，检查页面、数据库或文件的最终状态；转码任务也应重置到基线 commit，运行验证契约后检查最终状态。
第二类是轨迹。终态正确不能证明过程可靠：Agent 可能先进行越权调用，再偶然得到可用结果；也可能重复查询相同接口，最后才修改正确的文件。轨迹至少应检查四项：所选工具是否属于当前阶段允许的集合，参数是否符合 schema 和权限，动作顺序是否违反前置条件，是否超过轮数、时间或费用预算。
轨迹不宜按细节程度作为评分目标。许多任务存在多条合理路径，将唯一的”标准调用序列”作为答案，会误判正常方案。我只约束不可变的部分。例如，转码任务的写操作必须携带 expectedVersion，且不能在 Investigate 阶段调用写工具；巡检任务在重启前必须查询日志和 trace。其余搜索与检查的顺序由 Agent 决定。需要判断语义合理性时，再从 trace 中抽样交给 LLM 或人工检查。
第三类是边界。信息不足时是否停在 needs_review 或 needs_decision，是否拒绝越权请求，审批未通过时是否继续执行。这类任务通常没有成功的业务终态，却直接影响系统是否越权。我将它们单独设为拒绝题和升级题，不与普通成功题合并计算通过率。通过率上升时，还要检查系统是否只是更频繁地执行操作。
工具调用还需要机械检查，对应上表中的”工具调用准确率”。JSON 是否可解析、字段是否齐全、路径是否越过白名单，应由代码断言。这些检查能够判断调用是否合规，不能判断是否应选择该工具。两类问题需要分开处理，避免将 schema 通过视为工具选择正确。
使用确定性、规则与人工判据
我按成本从低到高将判据分为三层。并非每条任务都需要经过三层；能够在前一层结束的任务无需继续处理。这对应业界常用的”自动化功能测试 + LLM-as-Judge + 抽样人工”组合。
第一层是确定性校验。测试结果、退出码、文件 diff、工具 schema、权限和预算应由程序判断。转码任务运行 typecheck、单测、构建和受影响流程的检查，验证契约中声明的每一项都属于这一层。巡检任务的确定性校验包括是否记录事件 ID、目标对象是否匹配、执行结果是否成功返回。工具调用记录应由执行器输出结构化结果，不应让模型根据一段 stderr 判断参数错误、环境故障或权限拒绝。
第二层是规则化答案校验。重构领域常用 CodeBLEU 结合语法树和数据流自动评估代码质量。检索也应单独评估。在 embedding 召回评测中，我使用真实查询、相关性分级、Recall@K、MRR 和 bad case 检查检索结果。检索分数仅表示正确材料是否进入候选集，不能替代端到端任务通过率。
第三层是 LLM-as-Judge 和人工评估。它们用于程序难以定义的问题，例如重构后的代码可读性是否提升、诊断是否引用足够证据、多个等价方案中哪个更符合当前约束。LLM 用于扩大覆盖面；人工用于抽审、校准裁判，以及处理低置信或有争议的样本。人工全量打分的成本高且一致性有限；仅由 LLM 判断也会产生同类问题。
一条 trace 通常先全量运行第一层；命中硬错误则直接失败。需要文本判断的子集进入第二层和第三层；规则与 Judge 结论不一致、Judge 置信度低，或涉及高风险副作用的样本进入人工队列。人工结论应回写题目、规则或 Judge few-shot，而不应只保留在一次 review 中。
记录并校准 LLM 裁判偏差
LLM-as-Judge 不适合直接以 1 到 5 分作为结论。实际使用中，需要处理几类重复出现的偏差。
位置偏差较容易测量。将两个候选答案放在一起时，排在前面的答案通常更容易得分。每次比较时，我会交换 A、B 后再运行一次，只有两次结论一致才采用；不一致则判平或交给人工。MT-Bench 的裁判研究也提到过这种偏差。
另一个问题是自我偏好。由模型 X 评估模型 X 的答案时，分数可能偏高。裁判模型和被测模型应尽量分开；至少在一次版本比较中，不要同时更换生成模型和裁判模型。
绝对分数常集中在中间区间，也容易偏好更长的回答。将”改动好不好”拆为可观察的问题更稳定，例如是否遗漏调用方、是否引入新的圈复杂度、是否存在没有依据的行为假设。比较两版 Agent 时，配对比较通常比绝对打分更适用，只需判断”在当前任务契约下哪个更符合要求”。
裁判结果还会随模型版本和 prompt 变化而漂移。每次评估需要记录裁判模型、prompt、温度和 rubric 版本。每周抽取几十条交由人工复核；如果人工不同意裁判的比例超过一成，应先修正裁判，再讨论 Agent 是否退化。缺少这层校准时，模型升级前后的分数曲线不具可比性。
用重复运行评估稳定性
第一批数据集只有两百多题。一次改动后通过率增加了 5%，但重复运行后又回到原来的水平。温度设为 0 不能保证整条链路确定，因为检索排序、工具响应和外部状态仍可能变化。
现在每次大改都会在固定数据集上运行三遍，同时检查总体通过率和每题三次的结果。提升幅度小于这些运行的方差时，不将其记入发布记录。这个办法不严格，但可以避免单次运行造成误判，对应维度表中的”可靠性”。
τ-bench 的 pass^k 说明了相同问题：同一任务独立运行 k 次，要求每次都成功。pass^1 表示单次是否完成，pass^k 才用于衡量稳定完成的能力。论文中 pass^1 和 pass^8 的差距很大，说明单次成功不能代表可靠性。三次重复是成本较低的近似，可用于在发布前识别不稳定改动。
每次比较还需要 baseline。新版本只能与同一数据集、同一环境和同一裁判条件下的旧版本比较。数据集、工具 schema 或裁判模型更新时，绝对分数会变化，不应将不同条件下的分数直接用于判断提升。
将成本与过程错误写入评估报告
一次改版的通过率没有变化，平均工具调用次数却从 4 次增加到 11 次。结果质量相同，成本增加了一倍以上。只报告通过率时，这类变化会被忽略。不同 Agent 的 Token 消耗可能相差十倍以上，成本效率需要作为独立指标跟踪。
每次任务还应记录轮数、工具调用数、输入输出 token、折算成本、延迟、重复调用和预算耗尽次数。两个 Agent 都完成任务时，一个调用 3 次工具、另一个调用 15 次工具，线上体验和账单不同。上下文成本那篇计算的是单次调用成本，这里需要计算整个任务的成本。
轮数上限也应计入失败统计。Agent 到达上限，说明它已在错误路径上消耗资源；即使最后一段回复偶然可用，也不应计为正常完成。
用线上 trace 补充离线回归集
离线集用于回归比较。它可以表明改动是否影响已知任务，不能保证线上不会出现新的任务分布。
线上需要持续采样 trace。转码 Agent 可关注测试通过率、人工修改 diff、PR 被拒绝和回滚；巡检 Agent 可关注重复告警、错误处置、人工撤销和漏报。这些指标会受产品流量、权限和外部系统状态影响，不能直接作为模型能力分数，但可以帮助发现离线集未覆盖的新 case。
新 case 不应在出现一次后立即加入评估集。需要先确认它属于产品需求变化、外部系统故障、任务契约缺失还是 Agent 能力问题。只有 Agent 能力问题适合写成稳定的回归题，否则评估集会混入无法稳定复现的线上问题。
公开基准可用于设计内部评估
SWE-bench、WebArena、τ-bench、GAIA、AgentBench、ToolBench 的评测对象不同。SWE-bench 评估代码修复和测试通过；WebArena 评估网页环境中的多步操作；τ-bench 评估带政策约束的多轮工具任务；GAIA 偏向通用助手的浏览、工具和推理；ToolBench 更接近 API 编排。它们可用于筛选模型、理解 harness 暴露的问题，也可借鉴其环境和判据设计。
代码重构方向近两年也在补充专项基准。RefactorBench 用 100 个手工构造的多文件任务评估状态化推理，最佳系统通过率只有 30% 到 40%；SWE-Refactor 从真实 Java 项目中挖掘了上千个开发者重构实例，区分原子重构和复合重构两个粒度，复合重构的顶级成绩也只有 39.4%；SWE Atlas Refactoring 使用真实开源项目的多文件生产代码进行第三方独立评测，当前最好成绩为 48.57%。三个基准报告都提到上下文丢失、跨文件状态不一致和依赖遗漏等失败模式，与转码任务中遇到的问题一致。这表明多文件重构仍是行业中的困难任务。
这些基准不能证明内部转码 Agent 或巡检 Agent 可以上线。任务分布、工具描述、权限模型和执行环境都会改变结果。同一个模型更换工具封装或 prompt 后，分数可能不同。比较基准结果时，至少需要固定模型、工具集合、提示词、最大轮数和环境版本；不同 harness 下的分数不应作为同一尺度比较。
公开基准的作用是明确评估设计：存在终态时检查终态，存在安全边界时单列拒绝题，存在随机性时重复运行，开放文本才引入裁判。业务数据和验收条件仍需自行准备。
评估平台与判据代码的职责
评估平台用于记录、组织实验、执行判据和查看回归，不能替业务定义任务契约。
LangSmith 适合已使用 LangChain 或 LangGraph 开发的团队，可将 trace、数据集、实验和人工反馈集中管理，接入成本较低。Langfuse 更适合需要自托管，或需要自行控制工具调用、检索和自定义分数的场景。我使用 Langfuse 记录 trace 和版本，判据仍保留在业务代码中。
DeepEval 的形态接近 pytest，适合将离线评估接入 CI。它提供若干 LLM 指标，也支持自定义指标。Inspect AI 面向 Agent 多步评测设计，支持沙箱、工具调用和多步任务；评估重构类 Agent 时我会优先考虑它。RAGAS 只覆盖检索和生成的 RAG 维度，适合评估检索组件，不能代替 Agent 的终态和权限评估。Arize Phoenix 偏 OpenTelemetry 观测和自托管链路分析。Promptfoo 可补充提示注入、越权和数据泄露等红队 case，不能代替任务成功率评估。
工具选型需要考虑现有技术栈、数据是否可以出网、是否需要自托管，以及判据是否要接入 CI。对这类系统，一个 trace 平台、可重置的评估环境、业务代码中的确定性校验、少量经校准的 LLM Judge 和人工抽审已经构成最小组合。完成这些基础设施后，再决定是否引入额外的评估 SaaS。
评估体系的四个建设阶段
评估体系需要持续维护。我按四个阶段推进。
第一阶段是快速验证：选择一小批已有的真实迁移单元或历史告警，运行”确定性校验 + 简单裁判”的最小闭环，确认判据能否自动运行，不以覆盖率为目标。第二阶段是定制扩展：基于内部仓库和真实业务规则构建专有评测集，接入语义保持性、安全性等专有维度的检查，覆盖主要任务类型。第三阶段是接入 CI：每次升级模型、prompt 或工具版本时自动运行评测集、生成报告并与历史版本比较，未通过则拦截发布。第四阶段是生产监控：持续将线上 trace 接入观测平台，收集离线集未覆盖的新失败模式，用于更新评估集。
这四个阶段可以并行推进。团队尚未完成第一阶段时直接建设生产监控，通常意味着缺少可判断结果的任务契约，监控数据也缺乏解释依据。
当前仍需完善的数据集与漏报评估
现在修改提示词、更换模型、调整检索或新增工具前，都会先运行离线集。转码 Agent 主要检查语义保持性、安全性和测试通过率；巡检 Agent 主要检查终态和拒绝题；检索组件先检查召回，再运行端到端任务。除通过率外，还会检查成本、稳定性和失败分类。
数据集维护仍需要投入较多时间。业务规则和仓库结构会变化，三个月前收集的 case 即使得分高，也不能代表当前线上没有新问题。我目前每周从日志补充题目，并淘汰长期不出现的旧题。
巡检 Agent 的漏报更难评估。离线集可以评估已有告警进入后 Agent 的处理过程，无法评估本应发现却没有产生事件的情况。当前只能通过日志审计、抽审和主动巡检覆盖部分场景，这部分仍缺少低成本的评估方法。
