核心概念

为什么需要评估 AI Agent？

AI Agent 的输出具有非确定性——相同的输入可能产生不同的结果。手动测试无法系统性地衡量 Agent 的能力和可靠性。AgentEval 提供了一套标准化的评估框架，帮助你：

• 量化 Agent 的性能表现
• 追踪不同版本间的可靠性变化
• 对比不同配置和模型的效果
• 在 CI/CD 流水线中自动化质量把关

核心术语

Suite（评估套件）

评估套件是一个完整的配置，定义了要测试的 Agent、要运行的任务以及如何评分。对应 eval.yaml 文件。

Task（任务）

任务代表一个评估用例，包含输入提示词和预期输出。任务定义在 YAML 文件中，通过 task_files 从套件中引用。

Trial（试验）

每个任务会运行多次（通过 trials_per_task 配置），每次运行称为一次试验。多次试验支持统计可靠性度量。

Grader（评分器）

评分器评估 Agent 的输出是否符合预期。每个任务可以有一个或多个评分器，每个评分器产生一个分数（0.0-1.0）和通过/失败状态。

评估流程

加载配置 → 创建 Agent → 构建工作项 → 并发运行试验 → 评分 → 聚合结果 → 生成报告

1. 加载配置：解析 YAML，展开环境变量，加载外部任务文件，应用默认值
2. 创建 Agent：根据配置创建对应类型的 Agent 实例
3. 构建工作项：为每个任务生成指定数量的试验
4. 并发运行：通过调度器并发执行试验，支持速率限制
5. 评分：每个试验完成后，使用配置的评分器进行评分
6. 聚合结果：计算通过率、pass@k、pass^k 等指标
7. 生成报告：输出表格、JSON、HTML 等格式的报告

评分逻辑

• 每个评分器产生一个分数（0.0 到 1.0）和一个通过/失败状态
• 试验的最终分数是所有评分器的加权平均值
• 试验通过的条件是所有评分器都通过（AND 逻辑）
• 这意味着任何一个评分器失败都会导致整个试验失败，无论分数多高

pass@k 与 pass^k

pass@k（能力上限）

在 k 次尝试中至少获得一次正确答案的概率。公式：1 - C(n-c, k) / C(n, k)，其中 n = 总试验数，c = 通过的试验数。衡量 Agent 在最佳状态下的能力。

pass^k（可靠性）

在 k 次尝试中全部正确的概率。公式：C(c, k) / C(n, k)。衡量 Agent 的稳定性——对生产环境部署至关重要。

示例

假设 10 次试验中有 7 次通过：

• pass@1 = 0.70（单次尝试有 70% 的成功概率）
• pass@3 = 0.99（三次尝试中至少一次成功的概率为 99%）
• pass^3 = 0.29（三次尝试全部成功的概率为 29%）

pass@k 与 pass^k 之间的差距揭示了可靠性问题。