# Agent Eval

> 【Agent 评估】评估 AI Agent 输出质量。触发时机：用户说"评估 agent"、"测试 agent 质量"、"agent eval"、"检查 agent 输出"时。

- Skill: `afine907/agent-eval` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add afine907/agent-eval`
- Raw SKILL.md: https://api.skillmd.com/api/skills/afine907/agent-eval/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: afine907 (https://skillmd.com/u/afine907)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/afine907/agent-eval

---


# 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](references/eval-dimensions.md)

## Step 2: 构建评估测试用例

### 测试用例结构

```json
{
  "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](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: 生成评估报告

### 报告模板

```markdown
# 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` — 工具准确率评估依赖工具调用模式定义