# Agent Evaluation 实验指南

本指南配套 16 篇 Agent Evaluation 博客。订单 A1042、29900 分金额、租户和政策均为虚构教学数据。默认实验无网络、无真实退款；在线示例必须显式运行。

## 从离线闭环开始

使用 Python 3.10 或以上。下载 [suite.py](python/suite.py) 和 [mini_task_env.py](python/mini_task_env.py) 到同一目录，不需要第三方依赖：

```bash
# 比较两个确定性策略，报告写到当前目录。
python3 suite.py --output report.json
```

案例包括批准退款、未批准、质量未核实、他人订单和提交后响应丢失。baseline 故意把 29900 分变成 299 分，candidate 使用正确金额。按代码设计，baseline 应在两个允许退款的案例失败，candidate 应通过五个案例；这是静态预期，不是本轮实测结果。

查看报告时先读 `mode`，再看逐条 `checks`、业务余额、提交事件和错误字段。这个程序不理解自然语言，不包含真实模型或用户模拟器；通过率不能当作模型成绩。内存环境不支持跨进程恢复或并发事务，只演示稳定操作键的本地去重。

## 指标与 Judge 阈值

下载 [metrics.py](python/metrics.py) 与 [judge_calibration.py](python/judge_calibration.py)：

```bash
# 手算例子的代码形式：检索排序、编辑距离和配对 Bootstrap。
python3 metrics.py
# 在校准集选阈值，再在独立的教学验证集记录错误。
python3 judge_calibration.py
```

None 表示该分母下不可计算。Bootstrap 假定输入配对且采样单元合理；重复任务应先聚合或分组。Judge 示例的分数由人工构造，不是概率，四条样本不足以选择生产阈值。

## 可选：真实模型决策，本地模拟工具

另下载 [model_eval.py](python/model_eval.py) 与 [requirements-model.txt](python/requirements-model.txt)，放到 suite.py 同目录。在独立虚拟环境安装依赖，配置 `OPENAI_API_KEY` 和 `EVAL_MODEL` 后运行：

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-model.txt
# 模型须支持 Responses API 的函数调用；此命令会发生真实调用并产生费用。
python3 model_eval.py
```

模型读取公开请求，自行决定查询和退款调用；工具仅访问本地虚构数据。每个案例上限 8 轮、每轮输出上限 1200 Token，SDK 自动重试关闭；请求失败与评分失败分开记录。结果保存在 `model-report.json`，含模型标识、可观察工具调用、Token 用量、最终快照和评分。

本轮没有使用凭据或运行在线调用。API 接线依据[官方函数调用说明](https://developers.openai.com/api/docs/guides/function-calling)。依赖未声称经过完整兼容性验证；读者运行时应锁定实际安装的 SDK 与模型版本。模型输出即使格式正确，也必须由独立 oracle 核验。

## 可选：Ragas 裁判

下载 [ragas_example.py](python/ragas_example.py) 和 [requirements-ragas.txt](python/requirements-ragas.txt)，建议使用单独的 Python 3.12 环境。安装后设置服务凭据和 `EVAL_JUDGE_MODEL`：

```bash
pip install -r requirements-ragas.txt
# 向模型服务发送虚构政策和候选回答，会产生费用。
python3 ragas_example.py
```

代码固定 Ragas 源码提交。它只评价给定回答的证据支持，不运行被测 Agent，也不查询账本。NaN 显式转换为未评分，不能默默从总体报告删除。

## 可选：Promptfoo 本地 Provider

下载 [配置](promptfoo/promptfooconfig.yaml) 和 [Provider](promptfoo/provider.cjs) 到同一目录。具备对应版本要求的 Node.js 后，可以安装并运行指定版本 CLI：

```bash
# npx 会下载包；本地 Provider 本身不访问模型服务。
npx --yes promptfoo@0.123.0 eval -c promptfooconfig.yaml
```

源码阅读快照的 package.json 为 0.123.0；npm 包与该提交未做二进制等同性验证，本轮也未运行 CLI。需要严格复现源码行为时，应使用 SOURCES.md 中的提交并按项目构建说明安装。固定标签 equals 断言只适合这里的枚举状态，不能泛化到所有自然语言输出。

## Java 与旧示例

[Java 工程](java/README.md) 保留 AgentScope 工具注册及直接方法调用。它没有经过模型决策，也不验证完整工具调度。源文件补充了中文注释，帮助区分测试层级。

[旧 offline_eval.py](python/offline_eval.py) 保留原下载地址，依赖 [requirements.txt](python/requirements.txt)。它直接使用输入订单号运行固定 LangGraph 查询，不解析自然语言，不应被标成完整 Agent 能力评测。

## 迁移和验证

旧 00、01 分别进入新 01；旧 02 进入新 02；旧 03 进入新 06；旧 04 分散到新 07—09，主链接进入 07；旧 05 进入新 10；旧 06 进入新 11；旧 07、08 进入新 12；旧 09 进入新 13。新增统计、完整实践和三篇项目解读不依赖旧篇数。

源码固定点见 [SOURCES.md](SOURCES.md)，本轮实际检查范围见 [VALIDATION.md](VALIDATION.md)。

## 正文目录

1. [怎样判断一个 Agent 做得好：从回答正确到任务真正完成](/posts/agent_runtime/8.eval/01-what-evaluation-means/)
2. [评测数据集怎样建立：从业务问题到可信的测试案例](/posts/agent_runtime/8.eval/02-datasets-and-oracles/)
3. [评测指标怎样计算：准确率、召回率与平均分背后的问题](/posts/agent_runtime/8.eval/03-metrics-and-aggregation/)
4. [新版本真的更好吗：随机性、重复实验与统计比较](/posts/agent_runtime/8.eval/04-comparing-experiments/)
5. [怎样评测 Prompt 和模型回答：从格式检查到语义正确](/posts/agent_runtime/8.eval/05-prompt-and-response-evaluation/)
6. [怎样评测 RAG：找到证据、用对证据与回答完整是三回事](/posts/agent_runtime/8.eval/06-rag-evaluation/)
7. [怎样评测 Tool Calling：从选对工具到执行正确](/posts/agent_runtime/8.eval/07-tool-evaluation/)
8. [怎样评测完整 Agent：多轮对话、执行轨迹与业务结果](/posts/agent_runtime/8.eval/08-agent-trajectories/)
9. [Agent 出错以后还能完成任务吗：故障注入与安全评测](/posts/agent_runtime/8.eval/09-faults-and-security/)
10. [LLM-as-Judge 怎样工作：把主观要求变成可复核的评分](/posts/agent_runtime/8.eval/10-llm-as-judge/)
11. [怎样知道 Judge 值得信任：人工标注、偏差与校准](/posts/agent_runtime/8.eval/11-calibrating-judges/)
12. [生产中的评测系统怎样设计：从离线回归到线上反馈](/posts/agent_runtime/8.eval/12-production-evaluation/)
13. [多模态 Agent 怎样评测：文档、图片与实时语音](/posts/agent_runtime/8.eval/13-multimodal-evaluation/)
14. [读懂 Ragas：一个评测指标怎样变成可执行的评分过程](/posts/agent_runtime/8.eval/14-learning-from-ragas/)
15. [读懂 Promptfoo：怎样把案例、模型和断言组织成回归实验](/posts/agent_runtime/8.eval/15-learning-from-promptfoo/)
16. [读懂 τ-bench：怎样评测一个真正完成业务任务的 Agent](/posts/agent_runtime/8.eval/16-learning-from-tau-bench/)