evaluation

Agent 系统的评估方法

评估 Agent 系统的方式应有别于传统软件，因为 Agent 会做出动态决策，在不同运行之间具有非确定性，而且通常不存在唯一正确答案。构建评估框架时，应考虑这些特征，提供可操作的反馈、发现回归问题，并验证上下文工程方案是否实现了预期效果。

何时启用

在以下情况下启用此技能：

• 系统地测试 Agent 的表现
• 验证上下文工程方案
• 衡量随时间推移的改进
• 在部署前发现回归问题
• 为 Agent 流水线构建质量门槛
• 比较不同的 Agent 配置
• 持续评估生产系统

以下相关工作由其他技能负责，请勿为其启用此技能：

• 设计 LLM 评判器本身、成对比较、评判器校准或偏差缓解：advanced-evaluation。
• 设计自主控制界面、新颖性门槛、回滚或 PR 审批边界：harness-engineering。
• 在衡量之前调试特定的上下文失效模式：context-degradation。

核心概念

评估应关注结果而非执行路径，因为 Agent 可能会找到其他有效的目标达成方式。应判断 Agent 是否通过合理的过程取得正确结果，而不是是否遵循特定的步骤顺序。

应使用多维评分标准，而非单一分数，因为一个数字会掩盖特定维度上的关键问题。应将事实准确性、完整性、引用准确性、来源质量和工具效率分别记录为不同维度，再根据具体用例分配权重。

只有在确定性检查和评分标准稳定后，才使用模型评判的评估。如果工作重点是评判提示词、成对比较、校准或偏差缓解，请转而使用 Advanced Evaluation。

只要产物包含可由机器检查的结构，就应先进行确定性验证，再进行 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-as-Judge 扩展评估规模

构建基于 LLM 的评估提示词，其中包括：清晰的任务描述、待评估的 Agent 输出、可用时提供的真实答案、带有明确等级描述的评估量表，以及要求给出结构化判断和推理的说明。LLM 评审器可以在大型测试集上提供一致且可扩展的评估。应使用与被评估 Agent 不同的模型系列，以避免自我增强偏差。

辅以人工评估

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

对有状态 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 的质量会发生漂移。应在每次变更时以及按固定的生产节奏运行评估。

集成

此技能负责结果衡量和质量门槛。相邻技能负责专门的评估器设计和控制环路治理：

• advanced-evaluation：LLM-as-judge 提示词设计、成对比较、校准和偏差缓解。
• harness-engineering：锁定的评估器、可编辑界面、回滚和人工审批边界。
• context-degradation：检测和衡量退化模式。
• context-optimization：衡量优化对令牌、成本、延迟和质量的影响。
• multi-agent-patterns：评估协作质量和并行化权衡。
• tool-design：评估工具选择和恢复效果。
• memory-systems：评估记忆检索和保留质量。

参考资料

内部参考：

• 指标参考 - 适用于：设计具体评估指标、选择评分等级或实现加权评分标准计算

内部技能：

• 所有其他技能都与评估相结合，用于质量衡量

外部资源：

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

---

技能元数据

创建日期：2025-12-20 最后更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：1.2.0