afine907 Agent Eval — AI Agent 输出质量评估框架
评估 AI Agent 输出质量，适配 LLM 非确定性输出的统计评估方法。
核心洞察： AI Agent 是非确定性的——同一输入可以产生不同但都正确的输出。传统 QA 的"精确匹配"范式不适用，需要转向"行为属性验证 + 统计采样"。
Goal
评估 AI Agent 输出质量。覆盖幻觉检测、工具调用准确率、连贯性评分、任务完成验证。支持非确定性输出的统计评估
Trigger
- 用户说"评估 agent"、"测试 agent 质量"、"agent eval"、"检查 agent 输出"
- 构建完 Agent 后需要验证其是否正常工作
- 调试为什么 Agent 产生错误结果
- 对比两个 Agent 配置或提示的效果
工作流程
定义评估维度 → 构建测试用例 → 执行评估 → 评分输出 → 生成报告
Step 1: 定义评估维度
根据 Agent 类型选择适用的评估维度：
| 维度 | 定义 | 评分方式 | 适用场景 |
|---|---|---|---|
| 幻觉率 | 输出中包含的事实错误或虚构信息 | 事实核查 + 引用验证 | 知识问答、信息检索 |
| 工具准确率 | 选择了正确的工具、传递了正确参数、正确处理了结果 | 工具调用日志比对 | 工具使用 Agent |
| 连贯性 | 多步推理中上下文一致、无矛盾、角色稳定 | 一致性检查 + 矛盾检测 | 对话 Agent、长任务 |
| 任务完成率 | 目标达成、输出格式正确、边界情况处理 | 结果验证 + 格式检查 | 任务型 Agent |
| 安全合规 | 拒绝有害请求、不泄露敏感信息、遵循约束 | 安全测试 + 红队攻击 | 面向用户的 Agent |
| 延迟/成本 | 响应时间、Token 消耗、API 调用次数 | 性能指标采集 | 所有 Agent |
详细评分标准见 references/eval-dimensions.md
Step 2: 构建评估测试用例
测试用例结构
{
"id": "eval-001",
"name": "正常查询-事实型",
"input": "用户的问题或任务描述",
"context": "可选：对话历史、系统提示、可用工具列表",
"expected_behavior": "预期行为描述（非精确输出）",
"scoring_criteria": {
"hallucination": "输出中的事实必须可溯源",
"tool_accuracy": "应调用 search_api 工具",
"coherence": "回答应与上下文一致"
},
"pass_threshold": 0.8,
"tags": ["happy-path", "factual"]
}
测试用例矩阵
| 类别 | 覆盖点 | 数量建议 |
|---|---|---|
| 正常路径 | 典型输入、预期流程 | 每个功能 3-5 个 |
| 边界情况 | 空输入、超长输入、特殊字符 | 每类 2-3 个 |
| 对抗输入 | Prompt 注入、误导性输入、矛盾信息 | 每类 3-5 个 |
| 工具失败 | 工具超时、返回错误、不可用 | 每个工具 2-3 个 |
| 长对话 | 多轮对话、上下文累积 | 3-5 个场景 |
测试用例模板见 references/test-case-template.md
Step 3: 执行评估
统计采样策略
由于 LLM 的非确定性，每个测试用例需要多次运行才能得到可靠结论：
| 评估目的 | 每用例运行次数 | 统计方法 |
|---|---|---|
| 能力测试（能否做到） | 3 次 | pass@k：至少成功 1 次即通过 |
| 回归测试（是否退化） | 5 次 | 通过率 vs 基线：低于基线 5% 为回归 |
| 质量基线（当前水平） | 10+ 次 | 均值 ± 标准差，建立置信区间 |
执行流程
对每个测试用例:
运行 N 次 → 收集所有输出 → 记录延迟和 Token 消耗
关键规则：
- 不要用 snapshot testing（精确匹配）—— LLM 推理在硬件层面就有随机性，即使 temperature=0 也会有差异
- 不要 mock LLM —— 那样测试的恰好是你需要验证的行为
- 记录每次运行的完整追踪（输入、输出、中间步骤、工具调用）
Step 4: 评分输出
行为属性验证
不问"输出是否等于 X"，问"输出是否满足属性 A、B、C"：
幻觉检测评分：
- 输出中的事实陈述是否可溯源到提供的上下文？
- 是否存在编造的引用、数据、URL？
- 不确定的信息是否标注了不确定性？
工具调用准确率评分：
- 是否选择了正确的工具？（工具名匹配）
- 参数格式是否正确？（Schema 验证）
- 是否处理了工具返回的错误？（不静默忽略）
- 是否有不必要的工具调用？（效率）
连贯性评分：
- 是否与之前的对话历史一致？
- 是否存在自相矛盾的陈述？
- 角色/语气是否保持稳定？
任务完成率评分：
- 目标是否达成？
- 输出格式是否符合要求？
- 边界情况是否处理？
LLM-as-Judge
对于难以用规则判断的维度（如回答质量、语气一致性），使用 LLM 作为评分员：
评分提示模板：
你是一个评估专家。请根据以下标准对 Agent 输出评分（0-10）：
- 评估标准：{criteria}
- 用户输入：{input}
- Agent 输出：{output}
- 参考上下文：{context}
请给出分数和理由。
注意事项：
- LLM-as-Judge 本身也是非确定的 —— 对关键评估运行 3 次取平均
- 定期用人工标注校准 Judge 的准确性
- Judge 模型应比被评估的 Agent 模型更强
Step 5: 生成评估报告
报告模板
# Agent 评估报告
## 概览
- 评估时间：{timestamp}
- 测试用例数：{total_cases}
- 每用例运行次数：{runs_per_case}
- 总运行次数：{total_runs}
## 评分摘要
| 维度 | 平均分 | 标准差 | 通过率 | 基线对比 |
|------|--------|--------|--------|---------|
| 幻觉率 | 8.2 | 0.8 | 92% | +3% |
| 工具准确率 | 7.5 | 1.2 | 85% | -2% ⚠️ |
| 连贯性 | 9.0 | 0.5 | 98% | +1% |
| 任务完成率 | 8.0 | 0.9 | 90% | 持平 |
## 失败分析
### 工具准确率回归 (85%, -2%)
- 用例 eval-007：在参数格式复杂时选择错误工具（3/5 次失败）
- 用例 eval-012：未处理工具返回的 429 错误（2/5 次失败）
- 建议：改进工具描述中的格式示例，增加错误处理逻辑
## 成本分析
- 平均每用例 Token 消耗：{avg_tokens}
- 最高 Token 消耗用例：{max_case} ({max_tokens} tokens)
- 总评估成本：${total_cost}
快速使用
用户：我刚完成了一个客服 Agent，想验证它的回答质量
助手：使用 /agent-eval 定义评估维度、构建测试用例、执行统计评估、生成质量报告
边界情况
- Agent 无可用工具 — 仅评估对话质量维度，跳过工具准确率
- 多模态 Agent — 图片/音频输出需要人工评估或专门的多模态 Judge
- 有外部状态的 Agent — 测试环境需要 Mock 外部状态，确保评估可重复
- 实时 Agent — 需要在评估时控制时间因素（Mock 时间戳）
与其他技能的协作
test-generator— 为 Agent 的代码组件生成单元测试wo-yao-yan-pai— 评估发现的问题进入代码审查修复流程prompt-engineering— 评估揭示的提示质量问题用此技能优化tool-use-patterns— 工具准确率评估依赖工具调用模式定义