evaluation

Agent 系统的评估方法

评估 Agent 系统的方式应不同于传统软件，因为 Agent 会动态决策，每次运行的结果具有非确定性，而且通常没有唯一的正确答案。构建评估框架时，应考虑这些特点，提供可执行的反馈、捕获回归问题，并验证上下文工程的选择是否达到了预期效果。

适用场景

• 系统性测试 Agent 的性能
• 验证上下文工程的选择
• 衡量长期改进
• 在部署前捕获回归问题
• 为 Agent 流水线构建质量门禁
• 比较不同的 Agent 配置
• 持续评估生产系统
• 构建 LLM 评审器：直接评分、成对比较、量规生成、对照人工评分进行校准、缓解偏差

以下工作属于其他技能的职责范围，因此不应启用此技能：

• 在衡量之前调试特定的上下文故障模式：context-optimization（诊断模式，references/degradation.md）。
• 评估工具的工具 API 契约：tool-design。

模式

模式	适用场景	阅读内容
默认	结果衡量、评分量规、测试集、确定性门禁、持续监控	本文件，然后阅读 references/metrics.md
LLM 作为评审器	设计或调试基于模型的评审器：直接评分与成对比较、量规生成、置信度校准、与人工评分的一致性、偏差缓解、评审小组或分层评审	先阅读 references/llm-as-judge.md，然后阅读下方与任务匹配的评审器参考资料

先运行默认模式。只有在确定性检查和评分量规稳定后，且待解决的问题是如何让模型进行评审时，才切换到 LLM 作为评审器模式。

LLM 作为评审器参考资料：

• 实现模式 - 阅读时机：从头构建评估流水线，或将 LLM 评审器集成到 CI/CD 中
• 偏差缓解技术 - 阅读时机：评估结果呈现出不一致或可疑的评分模式
• 评审器指标选择 - 阅读时机：选择用于验证评审器可靠性的统计指标（量规指标和结果指标见 references/metrics.md）
• 流水线图示 - 阅读时机：设计多阶段评估系统的架构
• 提示词模板和完整示例 - 阅读时机：编写直接评分或成对比较提示词，或查看完整的详细示例

核心概念

将评估重点放在结果而非执行路径上，因为 Agent 可能会找到通往目标的其他有效路径。判断 Agent 是否通过合理的过程达成了正确结果，而不是是否遵循了特定步骤顺序。

使用多维评分标准，而非单一分数，因为一个数字会掩盖特定维度上的关键失败。将事实准确性、完整性、引文准确性、来源质量和工具效率作为独立维度进行评估，然后根据具体用例为它们分配权重。

只有在确定性检查和评分标准稳定后，才使用模型评判式评估。如果工作重点涉及评判提示词、成对比较、校准或偏差缓解，请切换到 LLM-as-judge 模式。

只要产物具有可由机器检查的结构，就应在 LLM 评判之前进行确定性验证。模式有效性、重复键、评分标准计算、清单同步、检索状态和必需的证据路径都应快速失败，避免评估器浪费 token 或返回主观分数。

性能驱动因素

设计评估预算时，应参考浏览 Agent 研究结果：token 用量、工具调用次数和模型选择可能主导测得的性能差异（claim-evaluation-browsecomp-variance）。

因素	解释的差异	影响
Token 用量	主要驱动因素	增加探索可以提升性能，直到成本或上下文质量开始恶化
工具调用次数	次要驱动因素	只有在调用能够检索到有用证据时，增加工具使用才有帮助
模型选择	次要但有乘数效应	更好的模型通常能更高效地使用 token 和工具

设计评估时应依据这些影响采取行动：

• 设定合理的 token 预算：使用符合生产实际的 token 限制评估 Agent，而非提供无限资源。
• 比较模型升级与 token 增加的效果：与预算更高但较弱的模型相比，更好的模型可能会更高效地使用 token。
• 验证多 Agent 架构：额外的 Agent 会增加 token 消耗和工具调用次数；应将其与单 Agent 基准进行评估。

详细主题

评估挑战

处理非确定性和多种有效路径

设计能够容忍路径差异的评估，因为 Agent 可能会采取完全不同但有效的路径来达成目标。一个 Agent 可能搜索 3 个来源，另一个可能搜索 10 个；两者都可能给出正确答案。避免检查特定步骤，而应定义结果标准（正确性、完整性、质量）并据此评分，将执行路径视为参考信息，而非评估依据。

测试依赖上下文的失败

应在不同复杂度和交互长度下进行评估，因为 Agent 的失败往往会以微妙的方式受到上下文影响。Agent 可能能够处理简单查询，却无法处理复杂查询；使用一组工具时表现良好，换一组工具时却会失败；或者随着上下文累积，在长时间交互后表现下降。应纳入简单、中等、复杂和非常复杂的测试用例，以揭示这些模式。

分别评估综合质量维度

将 Agent 的质量拆分为独立维度（事实准确性、完整性、连贯性、工具效率、流程质量），并分别评分，因为 Agent 可能准确性得分较高但效率较低，反之亦然。然后根据用例优先级计算加权总分。这种方法能够揭示需要改进的维度，而不会因取平均值而掩盖关键信息。

评估评分标准设计

构建多维评分标准

为涵盖关键维度的评分标准定义从优秀到不合格的描述性等级。纳入以下核心维度，并根据具体用例调整权重：

• 事实准确性：陈述与真实情况相符（知识类任务应赋予较高权重）
• 完整性：输出涵盖请求的各个方面（研究类任务应赋予较高权重）
• 引用准确性：引用与所声称的来源相符（对可信度敏感的场景应赋予相应权重）
• 来源质量：使用适当的一手来源（对要求权威性的输出应赋予相应权重）
• 工具效率：以合理的调用次数使用合适的工具（对成本敏感的系统应赋予相应权重）

将评分标准转换为数值分数

将各维度的评估映射为数值分数（0.0 到 1.0），应用各维度的权重，并计算加权总分。根据用例要求设置通过阈值，通常通用场景设为 0.7，高风险应用设为 0.9。将各维度的分数与总分一并存储，因为分项结果有助于针对性改进。

评估方法

使用 LLM 评审实现规模化评估

构建基于 LLM 的评估提示词，其中包括：清晰的任务描述、待测试的 Agent 输出、可用时提供真实答案、带明确等级说明的评估量表，以及要求给出包含推理过程的结构化判断。LLM 评审能够在大型测试集上提供一致且可扩展的评估。使用与被评估 Agent 不同的模型系列，以避免自我增强偏差。存在客观标准或真实答案时，选择直接评分；主观偏好评估则使用成对比较。在成对比较中，务必评估两种排列顺序，并将意见不一致视为平局。要求评审先提供证据再给出分数，并在信任评审结果前，使用由人工评分的样本对其进行验证（详情请参阅 LLM-as-judge 模式）。

补充人工评估

将边缘情况、异常查询以及随机抽取的生产流量样本交由人工审核，因为人工能够发现自动化评估会遗漏的幻觉答案、系统故障和细微偏见。跟踪人工审核中发现的问题模式，以识别系统性问题，并将结果反馈到自动化评估标准中。

对有状态 Agent 采用最终状态评估

对于会修改持久化状态（文件、数据库、配置）的 Agent，应评估最终状态是否符合预期，而不是关注 Agent 如何达到该状态。定义预期最终状态的断言，并在每次测试运行后以编程方式进行验证。

测试集设计

选择有代表性的样本

在开发早期，由于改动影响显著且容易改进的问题较多，应从小规模样本（20-30 个案例）开始。随着系统成熟，扩大到 50 个以上案例，以获得可靠的评估信号。从真实使用模式中抽样，补充已知边缘情况，并确保覆盖不同复杂度等级。

按复杂度分层

按复杂度划分测试集，避免简单示例拉高分数：

• 简单：单次工具调用、事实查询
• 中等：多次工具调用、比较逻辑
• 复杂：多次工具调用、显著歧义
• 非常复杂：长时间交互、深入推理、综合分析

除总分外，还应报告各层级的分数，以揭示 Agent 实际上在哪些方面遇到困难。

上下文工程评估

系统地验证上下文策略

使用不同的上下文策略运行 Agent，测试集保持一致，并比较质量分数、令牌用量和效率指标。这样可以从其他变量中分离出上下文工程的影响，避免基于个别经验做出决策。

开展性能退化测试

通过在不同上下文大小下运行 Agent，测试上下文退化对性能的影响。识别上下文开始造成问题的性能断崖，并确定安全运行限值。将这些限值反馈到上下文管理策略中。

持续评估

构建自动化评估流水线

将评估集成到开发工作流中，使其在 Agent 变更时自动运行。持续跟踪结果、比较不同版本，并阻止关键指标退化的部署。

监控生产环境质量

对生产环境中的交互进行抽样并持续评估。当质量低于警告阈值（通过率 0.85）和严重阈值（通过率 0.70）时设置警报。维护仪表板，展示不同时间窗口内的趋势分析，以便发现逐渐退化的情况。

实用指南

构建评估框架

按照以下顺序构建评估框架，因为跳过前面的步骤会导致测量结果无法反映真实质量：

1. 在编写任何评估代码之前，先定义与使用场景相关的质量维度，因为之后选择的维度往往反映的是哪些内容容易衡量，而非哪些内容真正重要。
2. 制定清晰、具体的等级定义，让评估者（人工或大模型）给出一致的评分。
3. 根据真实使用模式和边缘情况构建测试集，按复杂度分层，至少包含 50 个案例，以确保信号可靠。
4. 实现自动化评估流水线，使其在每次重大变更时运行。
5. 在进行变更之前建立基准指标，以便与已知基准对比衡量改进情况。
6. 对所有重大变更运行评估，并与基准进行比较。
7. 跟踪指标随时间的变化以分析趋势，因为逐渐退化比突然下降更难察觉。
8. 定期通过人工审核补充自动化评估。
9. 将确定性验证失败与质量判断分开，避免无效产物借助有利的大模型评分蒙混过关。

避免评估陷阱

防范以下常见问题，避免影响评估的可靠性：

• 过拟合于特定路径：评估结果，而非具体步骤，因为 Agent 会找到新颖且有效的路径。
• 忽略边缘情况：纳入多样化的测试场景，覆盖完整的复杂度范围。
• 执着于单一指标：使用多维度评估标准，因为单一分数会掩盖特定维度上的失败。
• 忽视上下文效应：使用符合实际情况的上下文大小和历史记录进行测试，而非在理想化环境中测试。
• 跳过人工评估：自动化评估会遗漏人类能够可靠发现的细微问题。

示例

示例 1：简单评估

def evaluate_agent_response(response, expected):
    rubric = load_rubric()
    scores = {}
    for dimension, config in rubric.items():
        scores[dimension] = assess_dimension(response, expected, dimension)
    overall = weighted_average(scores, config["weights"])
    return {"passed": overall >= 0.7, "scores": scores}

示例 2：测试集结构

测试集应涵盖多个复杂度级别，以确保评估全面：

test_set = [
    {
        "name": "simple_lookup",
        "input": "What is the capital of France?",
        "expected": {"type": "fact", "answer": "Paris"},
        "complexity": "simple",
        "description": "Single tool call, factual lookup"
    },
    {
        "name": "medium_query",
        "input": "Compare the revenue of Apple and Microsoft last quarter",
        "complexity": "medium",
        "description": "Multiple tool calls, comparison logic"
    },
    {
        "name": "multi_step_reasoning",
        "input": "Analyze sales data from Q1-Q4 and create a summary report with trends",
        "complexity": "complex",
        "description": "Many tool calls, aggregation, analysis"
    },
    {
        "name": "research_synthesis",
        "input": "Research emerging AI technologies, evaluate their potential impact, and recommend adoption strategy",
        "complexity": "very_complex",
        "description": "Extended interaction, deep reasoning, synthesis"
    }
]

示例 3：模型判断前的确定性门禁

def evaluate_pr_candidate(candidate):
    structure = run_validate_repo(candidate)
    if not structure.ok:
        return {"passed": False, "reason": "deterministic validation failed", "details": structure.errors}

    quality = run_rubric_eval(candidate)
    return {"passed": quality.overall >= 0.8, "scores": quality.dimensions}

示例 4：质量门禁维度

gate:
  deterministic:
    - schema_valid
    - required_files_present
    - no_duplicate_ids
  quality:
    factual_accuracy: min 0.85
    completeness: min 0.80
    source_traceability: min 0.90

指南

1. 使用多维度评估标准，而非单一指标
2. 评估结果，而非具体执行路径
3. 覆盖从简单到复杂的各个复杂度级别
4. 使用符合实际情况的上下文大小和历史记录进行测试
5. 持续运行评估，而非仅在发布前运行
6. 通过人工审核补充大模型评估
7. 跟踪指标随时间的变化，以检测趋势
8. 根据使用场景设置明确的通过/失败阈值

注意事项

1. 针对特定代码路径过拟合评测：测试通过，但 Agent 遇到细微的输入变化时就会失败。应根据结果和语义制定评测标准，而不是依据表面模式，并定期轮换测试输入。
2. LLM 评审的自我提升偏差：模型给自己生成的输出打分，往往高于独立评审的评分。评估时应使用与被评估模型不同模型系列的模型作为评审者。
3. 测试集污染：评测示例泄漏到训练数据或提示词模板中，导致分数虚高。应对评测集进行版本管理，并与提示词或微调所用的任何数据分开存放。
4. 指标投机：只优化指标而不注重实际质量，会造出得分很高、却令用户失望的 Agent。应定期使用人工判断交叉验证自动化指标。
5. 单维度评分：单一汇总分数会掩盖特定维度上的关键故障。始终在报告总分的同时报告各维度分数；若任何单一维度低于最低阈值，就应判定评测失败。
6. 评测集过小：少于 50 个示例时，信号不可靠，且不同运行之间的方差较高。应将评测集扩充到至少 50 个案例，并报告置信区间。
7. 未按难度分层：简单示例会抬高总分，掩盖困难案例中的失败。应按复杂度层级报告分数，并对总分加权，避免简单案例占据主导。
8. 将评测视为一次性工作：评测必须持续进行，而不能只作为上线门槛。随着模型更新、工具变化和使用模式演变，Agent 的质量会发生偏移。每次变更后以及按固定的生产周期运行评测。

集成

此技能负责结果衡量、质量门槛和评审者设计。相邻技能负责控制循环治理以及被衡量的系统：

• context-optimization：衡量优化对令牌数、成本、延迟和质量的影响；诊断并衡量性能退化模式（references/degradation.md）。
• tool-design：评估工具的架构和错误处理。
• multi-agent-patterns：评估协作质量和并行化的权衡。
• tool-design：评估工具选择和恢复的有效性。
• memory-systems：评估记忆检索和保留质量。
• pstack：其基准测试清单参考资料会在报告提速或回退数据前，对其进行审核（限制因素、调优、错误、可重复性）。

参考资料

内部参考资料：

• 指标参考 - 阅读时机：设计具体的评测指标、选择评分尺度或实现加权评分规则计算时
• LLM-as-Judge - 阅读时机：设计基于模型的评审者时；其中列出了 judge-* 参考资料（提示词模板、实现模式、偏差缓解、评审者指标、流水线图）和 scripts/llm_judge_example.py

内部技能：

• 所有其他技能都通过质量衡量与评测相连

外部资源：

• LLM 评测基准 - 阅读时机：选择或构建用于 Agent 对比的基准测试套件时
• Agent 评测研究论文 - 阅读时机：采用新的评测方法或验证当前方法时
• 生产监控实践 - 阅读时机：为实时系统设置告警、仪表板或抽样策略时