agent-evaluation

Agent 评估

构建能为发布负责人提供依据的证据，而不是展示有利示例或安全认证。

适用场景

• 在构建或更改 Agent 之前定义质量标准。
• 比较提示词、模型、工具、记忆策略或编排模式。
• 将生产环境中的故障转化为回归用例。
• 建立可重复的发布门槛或人工审核计划。

输入

收集 Agent 的目标、用户、支持的任务、不可接受的结果、当前基线、执行环境、可用追踪记录和评估预算。如果无法获得某项输入，请说明假设。

输出规范

生成：

1. 一份评估简报，包含范围、风险、假设和已冻结的系统版本。
2. 一份数据集清单，包含来源、类别、划分和污染控制措施。
3. 一份评分规范，包含评分标准、评审者、阈值和决胜规则。
4. 可复现的运行设置、汇总结果、不确定性和相对基线的变化。
5. 一份故障分类、代表性案例、证据局限说明，以及提交给负责人的决策备忘录。

工作流

1. 定义被测对象以及评估需要支持的决策。区分模型质量与工具、检索、策略和基础设施故障。
2. 将用户目标和风险转化为可观测标准。仅在相关时纳入任务成功率、安全性、延迟、成本和升级处理质量。
3. 在许可范围内，根据真实分布构建代表性用例。加入边界、长尾、格式错误输入、工具故障和对抗性用例。将保留集与提示词迭代隔离。
4. 选择主观性最低且可靠的评审方式。结构化事实优先使用确定性检查，语义质量使用受评分标准约束的模型评审，高影响或有争议的案例使用盲审人工评估。选择评审方式或门槛时，请阅读 evaluation-patterns.md。
5. 冻结提示词、模型版本、工具、数据快照、支持时可用的随机种子、重试次数和超时时间。在等效条件下运行候选版本和基线；对随机性用例重复运行。
6. 在采信汇总数据之前检查单个用例的故障。在样本量允许时，按任务、风险、语言、工具和用户群体细分结果。
7. 设置发布门槛，综合考虑关键用例的最低表现、相对基线不退化以及运行限制。将统计效力不足的结果标记为无法得出结论。
8. 将类似生产环境中的失败用例保存为回归测试样例，同时避免暴露私人数据。

使用 python3 scripts/aggregate_results.py results.jsonl --score-min 0 --score-max 1 --require-passed 验证记录标识和声明的分数范围，然后生成描述性摘要。当记录使用这些 variant 标签时，添加 --baseline old --candidate new。添加 --output summary.json 可将结果原子写入文件；目标必须是新路径或普通文件，并且不能通过路径写法、解析结果、符号链接或硬链接与输入文件指向同一文件。该脚本会明确报告已观测、缺失和通过率的总计分母以及近似不确定性；它不会认证安全性、代表性、显著性或发布就绪情况。

安全与权限

• 未经授权且未批准保留政策，不得将私人提示词、客户数据、凭证或专有输出发送给外部评审者。
• 未经明确许可，不得针对生产系统运行评估、消耗付费 API 预算或触发会改变状态的工具。
• 对医疗、法律、金融、就业、安全或访问控制决策，必须由具备资质的人员进行人工审核。
• 将评审者评分视为证据，而非事实依据；披露模型评审者的身份及利益冲突。

验证

• 确认每项发布标准至少对应一个用例，且每项关键风险都有负向测试。
• 验证训练集、开发集和留出集中的用例在语义上和来源标识符上均不重叠。
• 手动重新运行一个样本，并将评分者的判定与评分标准进行比较。
• 检查基线和候选版本是否使用了相同条件，并确认报告中的分母标明了所有缺失的通过标签、失败项和超时项。当每条记录都必须计入通过率分母时，请使用 --require-passed。
• 确认报告保留了复现重要结论所需的用例级证据。

故障处理

• 如果缺少有代表性的数据，请运行明确标注的探索性评估，并在设定生产门槛前请求提供数据。
• 如果评分者意见不一致，请完善评分标准，对比较过程进行盲测，并对分层抽样进行裁定。
• 如果结果不稳定，请增加重复次数，隔离非确定性依赖项，并报告置信区间或范围。
• 如果关键用例失败，无论总体平均结果如何，都应阻止发布，直到授权负责人接受该风险。

示例

对于“比较两个版本的客户支持 Agent”，请定义问题解决正确性、引用保真度、政策合规性、升级处理判断、延迟和成本；创建常规、模糊、多语言、提示词注入和工具不可用等用例；对版本标签进行盲测；将两个版本各运行三次；按用例类别汇总；检查回归；并基于证据给出发布、暂缓或有限范围推出的决定。