智能体评估报告
智能体评估报告 (Agent Evaluation Reporting)
概述
将原始的智能体评估运行结果转化为可用于决策的报告，且不掩盖失败或夸大能力。保持结果样本量、分母、延迟样本量和实验条件的透明度，以便读者能够复现每一个核心数据。
适用场景
- 报告 AI 智能体的基准测试、回归测试、试点或生产环境评估运行结果时。
- 结果集中同时出现自主完成和人工辅助完成的情况时。
- 失败、超时、基础设施导致的无效运行、重试或部分结果影响分母时。
- 比较两个智能体、提示词、测试框架或版本，并判断该比较是否有效时。
工作流程
第一步：冻结比较契约 (Comparison Contract)
记录任务集与采样方式、模型与供应商、提示词或策略版本、工具与框架版本、评估量表、超时与重试策略、Token 或成本预算、环境以及人工干预策略。为该配置分配一个稳定的标签或摘要 (Digest)。
如果两次运行之间存在实质性的条件差异，请将该比较标记为“非等效”。仅报告方向性观察结果，不要声称差异是由智能体的变更引起的。
第二步：构建互斥的结果账本
将每一次计划的尝试进行唯一分类：
| 结果 | 含义 |
|---|---|
| autonomous_success | 智能体在无需人工干预的情况下满足了评估要求。 |
| assisted_success | 任务仅在人工干预后才成功。 |
| failure | 运行达到了可评估的终结失败状态。 |
| timeout | 运行耗尽了声明的时间或步骤预算。 |
| invalid | 由于框架、环境或输入失败，智能体从未获得有效的评估。 |
尽可能保留尝试 ID、任务 ID 或种子值、重试索引、父尝试 ID、配置标签、结果、干预次数、时长、成本、评估证据和无效原因。绝不要静默丢弃无效或重试的运行记录。
同时构建唯一任务汇总 (Unique-task Rollup)。对于每个任务，保留其首次尝试的结果，并在预定义的重试策略结束后得出最终结果。一次执行尝试可能在“尝试级指标”中计入一次，但一个任务在“任务级完成指标”中只能计入一次。如果缺失重试血缘或重试策略，则不要报告最终任务完成率。
第三步：将每个指标锁定到分母
设 N_all 为所有执行尝试（含重试），N_eval = N_all - N_invalid 为可评估尝试。设 T_all 为唯一计划任务，T_eval 为在固定重试策略下具有有效任务级结果的任务。在报告每个比率时，必须在旁边标注具体数量。
自主尝试成功率 = N_autonomous / N_eval
辅助尝试成功率 = N_assisted / N_eval
尝试未完成率 = (N_failure + N_timeout) / N_eval
无效尝试率 = N_invalid / N_all
首次尝试完成率 = T_first_attempt_completed / T_all
最终任务完成率 = T_eventual_completed / T_eval明确标注“尝试级（attempt-level）”和“唯一任务级（unique-task）”指标；绝不要将尝试级比率称为“工作流完成率”。报告重试率和单任务尝试次数，以确保策略相关的收益可见。检查可评估的尝试结果之和是否等于 N_eval，所有尝试结果之和是否等于 N_all，以及任务汇总之和是否等于 T_all。
如果 N_eval == 0，请将所有尝试能力率报告为 unavailable（不可用）而非除以零，并将依赖这些比率的任何门禁（gate）标记为 inconclusive（不确定）。对于任何分母为零的指标，适用相同规则，包括当 T_all == 0 或 T_eval == 0 时的任务级比率。
第 4 步：确保延迟和成本样本的真实性
分别报告自主完成延迟、辅助端到端延迟以及失败至终止的时间。仅针对成功样本的 P50 并非整体 P50，且子组中位数不能通过平均或加权来还原为合并中位数。
仅根据单次运行的观测值计算全样本百分位数，并说明超时处理方式。如果时长存在右截断（right-censored），请报告截断策略或使用适当的生存估计。对 Token 和成本指标采用相同的样本标注。
第 5 步：量化不确定性和可比性
对于随机评估，在核心比率旁显示样本量以及置信区间或重复运行分布。对于对比分析，报告绝对差值（delta），并验证双方均遵循第 1 步中冻结的合约。如果数据缺失、条件不同或区间过宽，请使用 inconclusive 而非强行选出胜者。
第 6 步：将证据映射到预定义的决策门禁
在阅读结果之前定义就绪门禁，例如：最低自主成功率、最高超时率、零关键安全违规以及延迟或成本上限。为每个门禁返回 pass（通过）、fail（失败）或 inconclusive（不确定）。
不要仅凭成功率推断生产就绪状态。如果没有提供阈值或风险要求，请声明就绪状态尚未确定并列出缺失的门禁。
示例
针对 120 个唯一任务（每个任务尝试一次），其中包含 12 次基础设施无效运行、48 次自主成功、24 次辅助成功、20 次失败和 16 次超时：
可评估尝试次数: 108 / 120
自主成功率: 48 / 108 = 44.4%
辅助成功率: 24 / 108 = 22.2%
尝试未完成率: 36 / 108 = 33.3%
首次尝试完成率: 72 / 120 = 60.0%
最终任务完成率: 72 / 108 = 66.7% (无重试)
运营任务交付率: 72 / 120 = 60.0%
基础设施无效率: 12 / 120 = 10.0%
整体延迟 P50: 无法从子组聚合数据中得出
就绪状态: 在声明门禁前为不确定
``
最佳实践
- 将计数、公式、分母标签和排除项统一报告。
- 将自主能力与人工辅助的工作流完成度区分开。
- 即使在发布有效运行得分时，也要保留超时率和无效运行率。
- 将聚合指标与失败类别及代表性证据配对。
- 在做出因果改进结论前，确保两个候选方案在同一冻结合约下重新运行。
局限性
- 本技能用于结构化和解读提供的评估证据；它不验证评估器本身，也不重建缺失的运行记录。
- 规模较小或有偏差的任务集可能会产生看似精确但缺乏代表性的指标。
- 统计显著性并不等同于生产安全性、用户价值或认可度。
可承受成本。
- 当缺乏验收阈值、严重程度策略或所需证据时，就绪状态应判定为“不确定”。
安全性与可靠性注意事项
- 在报告中脱敏凭据、私有提示词、个人数据和敏感工具输出，同时保留稳定的证据引用。
- 将关键的安全违规视为独立的发布门禁，而非将其平均计入综合质量得分。
常见误区
- 问题： 将辅助完成（Assisted completions）呈现为自主成功。
解决方案： 分别公布自主完成率、辅助完成率和工作流完成率。
- 问题： 超时或无效运行从分母中消失。
解决方案： 在计算指标前，将完整结果账单与 N_all 进行核对。
- 问题： 将仅针对成功案例的 P50 耗时缩短呈现为系统速度提升。
解决方案： 标注样本群体，且仅根据单次运行数据报告所有运行的终端耗时。
- 问题： 在看到结果后临时决定发布结论。
解决方案： 执行预定义的门禁标准，否则返回 inconclusive（不确定）。
相关技能
@agent-evaluation - 设计行为测试、基准测试和可靠性评估。
@run-deep-swe` - 在报告结果前执行可复现的 DeepSWE 基准测试运行。