0. 如何使用这份手册

导学 · 45～60 分钟

学习目标

建立 Agent Evaluation 的正确预期
理解贯穿整本手册的证据优先原则
建立个人 Eval Lab 与实验记录方式

前置知识

能阅读 Python / JSON / YAML
了解最基本的 LLM 与 Tool Calling

本章产物： 创建 agent-eval-lab/ 实验目录和第一份 Eval Report。

0.1 先建立正确预期

Agent Evaluation 不是“给回答打一个 0～10 分”。当系统具备工具、环境、记忆、循环和外部副作用后，最终文本只是可观察结果中的一小部分。

一个典型 Agent Run 可以抽象成：

Task / Goal用户目标与成功条件

Agent State上下文、记忆、权限与当前状态

Plan / Decision下一步计划与策略选择

Action / Tool Call工具、参数与副作用意图

Environment Transition外部世界发生的状态变化

Observation工具结果、错误与环境反馈

Re-plan根据反馈修正计划或重试

Final Answer + Final State用户可见结果与最终状态

因此你至少要回答六类问题：

结果对不对？ —— Task Outcome。
真实世界是否被正确改变？ —— State。
工具是否选对、参数是否正确？ —— Tool Use。
过程是否违规、循环或走捷径？ —— Trajectory / Policy。
同一任务重复运行是否仍然可靠？ —— Reliability。
成本、延迟和风险是否可接受？ —— Efficiency / Safety。

不要把公开 Benchmark 当成生产验收

公开 Benchmark 的价值是可比较、可复现和研究交流；你的生产 Eval 的价值是回答“这个版本能否在我的用户、工具、数据、权限和 SLA 下上线”。

二者应该同时存在：

Public Benchmark  → 能力参考
Private Eval      → 产品真实质量
Production Replay → 长尾与回归

0.2 三条学习线并行推进

学习线	核心问题	实践
方法论	什么算成功？什么证据可信？	Success Criteria、EvalCase、Rubric
评测技术	如何自动判断结果和过程？	State、Tool、Trajectory、Judge
工程线	如何持续跑、比较、回归、发布？	Inspect、Experiment、Release Gate

0.3 证据优先原则

每次评测尽量保存：

Case Version
Agent Version
Model / Prompt / Tool Version
Environment Version
Raw Trace
Final State
Scores
Cost / Latency
Failure Type
Conclusion Boundary

如果只有一个“87.3 分”，但无法回到逐样本结果解释为什么是 87.3，这个 Eval 的工程价值有限。

0.4 建立实验目录

agent-eval-lab/
├── cases/
├── datasets/
├── agents/
├── scorers/
├── environments/
├── traces/
├── reports/
├── baselines/
└── experiments/

不要只保存聚合指标。建议逐 Run 写 JSONL：

{
  "case_id": "order-cancel-001",
  "agent_version": "v0.8.3",
  "run_id": "run-...",
  "task_success": true,
  "state_score": 1.0,
  "tool_score": 0.92,
  "safety_score": 1.0,
  "latency_ms": 8400,
  "tool_calls": 4,
  "failure_type": null
}

0.5 学完后的验收标准

完成整本手册后，你应该能够：

把一个模糊业务需求改写为可执行 EvalCase；
区分 Outcome、State、Trajectory、Tool 与 Safety；
说明什么时候使用确定性 Scorer，什么时候必须使用 Judge；
设计多次运行可靠性实验；
构建历史失败回归集；
使用 Inspect AI 运行一个 Agent Eval；
设计 Release Gate；
解释 Benchmark 自身为什么也需要被验证。

0.6 第一次学习会话

第一次不要安装十几个框架。只做：

阅读第 0～3 章；
选择一个已经存在的简单 Agent；
写 10 个 EvalCase；
明确每个 Case 的成功证据；
手工执行 3 个 Case 并记录 Trace；
观察“最终回答正确”和“最终状态正确”是否完全一致。

0.7 导学验收

为什么 Agent Eval 不能只看最终回答？
为什么公开 Benchmark 不能替代私有生产 Eval？
为什么逐样本结果比单个平均分更重要？
一次 Eval Run 至少应该保留哪些可复查信息？

本章依据

原理性结论优先来自原始论文和官方文档。论文中的实验数字只属于论文声明的模型、数据、环境和评测设置，不能直接外推为你的生产结论。