agent-eval

Agent Eval 框架

评估一个 AI Coding Agent 在给定真实任务下，能否自主完成目标。

---

1. 核心问题

Agent Eval 回答的是：

给定一个明确的开发任务和初始代码库，Agent 能不能自己把它做完、做对、做稳？

它关注的是端到端能力，不是单步 prompt 的好坏，也不是单次检索的准确率。

---

2. 任务分类

不是所有任务都能用同一套标准评测。先分类，再设计指标。

类型	定义	例子	核心成功标准
功能实现	根据需求新增功能	"加一个用户登录接口"	功能可用、测试通过
Bug 修复	定位并修复已有问题	"修复 #123 的崩溃"	复现失败、回归通过
代码审查	检查代码问题并给出反馈	"审查这个 PR"	找到真问题、不误报
重构	在不改变行为的前提下改进结构	"把回调改成 async/await"	行为不变、测试通过
理解查询	回答关于代码库的问题	"这个项目怎么启动？"	回答准确、引用正确
测试生成	为已有代码生成测试	"给这个函数写单元测试"	覆盖关键路径、测试可运行

---

3. 评估维度

一个 Agent 任务的结果可以从多个维度评估：

3.1 正确性（Correctness）

• 任务目标是否达成？
• 相关测试是否通过？
• 是否引入了新的 bug？

常用指标：

• pass@k：在 k 次尝试中至少一次成功的比例
• success_rate：一次成功的比例
• regression_pass_rate：原有测试是否仍通过

3.2 效率（Efficiency）

• 用了多少轮对话？
• 调用了多少次工具？
• 消耗了多少 token？
• 耗时多久？

常用指标：

• avg_turns
• avg_tool_calls
• avg_tokens
• avg_duration

3.3 安全性（Safety）

• 是否误删/误改了不相关的文件？
• 是否执行了危险命令？
• 是否泄露了敏感信息？

常用指标：

• unrelated_file_change_rate
• dangerous_command_count
• permission_override_rate

3.4 鲁棒性（Robustness）

• 面对模糊需求、意外报错、工具失败时能否恢复？
• 同一任务多次运行，结果是否稳定？

常用指标：

• self_recovery_rate
• result_stability（多次运行的标准差）

3.5 可解释性（Interpretability）

• Agent 是否说明了它在做什么？
• 失败时是否给出了清晰的原因？

常用指标：

• action_explanation_rate
• failure_reason_clarity

---

4. 评测流程

步骤 1：准备任务

每个任务包含：

id: bugfix-001
name: 修复登录接口 500 错误
type: bugfix
difficulty: medium
domain: python / django

input:
  instruction: |
    用户反馈登录接口返回 500 错误，请修复。
    复现步骤：POST /api/login 不携带 password 字段。
  codebase: ./fixtures/login-bug-v1/

expected:
  # 自动判断标准
  tests_pass: ["pytest tests/test_login.py"]
  no_regression: ["pytest tests/"]
  # 人工复核说明
  review_notes: |
    修复应针对空 password 做校验，不应引入新的依赖。

步骤 2：运行 Agent

让 Agent 在隔离环境中执行任务，记录所有动作。

步骤 3：自动判断

根据 expected 中的标准自动打分。

步骤 4：人工复核

抽至少 10% 的案例人工检查：

• 自动判断是否准确？
• 有没有"看起来对但实际有问题"的情况？
• 失败案例归因到哪个层级？

步骤 5：归因分析

对每个失败案例分类：

根因层级	说明
Prompt	指令理解偏差、约束未遵守
RAG	读错文件、漏看关键上下文
Tool	工具调用参数错误、执行失败
Planning	任务拆解错误、顺序错误
Model	模型能力上限、上下文不足
Task	任务描述不清、期望不合理

---

5. 失败归因模板

## 任务: bugfix-001

### 结果
- 成功: 否
- 自动判断: 测试未通过

### 观察到的行为
Agent 修改了 `views.py`，但没有修改 `serializers.py`。

### 根因推断
RAG 层面：Agent 没有检索到 `serializers.py` 中 password 校验逻辑。

### 验证方式
手动给 Agent 提供 `serializers.py` 内容后重跑，任务成功。

### 改进建议
- 在 RAG 查询时同时搜索 views.py 和 serializers.py
- 在 prompt 中强调"检查所有相关文件"

---

6. 最小可运行示例

见 datasets/examples/ 中的 agent-eval-example.jsonl。

---

7. 参考

• SWE-bench
• Agentless
• LiveCodeBench