学习目标：能观察每次 Agent 执行的模型调用、工具调用、RAG 检索、失败点、成本和任务成功率，并能用基准集做轨迹级评测和回归。 重点度：必会（10 分） 前置要求：Ch5 Agent Runtime、Ch6 工作流编排

概述#

Agent 最大的问题不是能不能跑，而是能不能知道它为什么成功或失败。

传统 LLM 应用：输入 → 输出，看输出好不好就行。 Agent：输入 → 思考 → 调工具 → 思考 → 再调工具 → ... → 输出，最终结果只是冰山一角——轨迹里每一步都可能是失败原因。

Agent Eval 比普通 LLM Eval 复杂得多：要评工具选择、参数填写、轨迹合理性、成本、延迟、任务成功率，不能只看最终答案。

Step#

Trace 三层结构#

text
Run (一次完整 Agent 任务)
├── Step 1: Agent 推理
│   ├── LLM Call: 思考"该读 README"
│   ├── Tool Call: read_file("README.md")
│   └── Tool Result: "..."
├── Step 2: Agent 推理
│   ├── LLM Call: 思考"该看 package.json"
│   ├── Tool Call: read_file("package.json")
│   └── Tool Result: "..."
├── Step 3: Agent 推理
│   ├── LLM Call: 思考"信息够了,总结"
│   └── Final Answer: "..."
└── Run Metadata: 总 token / 总成本 / 总时长 / 状态

Run（运行）#

一次完整的 Agent 任务执行，包含：

run_id / user_id / task_id
输入任务描述
完整 Step 序列
最终输出
总成本 / 总时长 / 状态（success/failed/cancelled）

Step（步骤）#

Agent 的一次"思考+行动"循环：

step_index
LLM 调用（input/output tokens）
工具调用（如果有）
工具结果
持续时间

LLM Call Trace / Tool Call Trace#

每个 Step 内部的细粒度 trace：

text
LLM Call:
  - model: gpt-4o
  - input_tokens: 1200
  - output_tokens: 80
  - latency: 1.2s
  - cost: $0.003
  - messages: [...]  ← 完整请求
  - response: "..."  ← 完整响应

Tool Call:
  - tool: read_file
  - args: {"path": "README.md"}
  - result: "..."
  - latency: 50ms
  - success: true

Trace 工具栈#

LangSmith#

LangChain 官方 trace 平台：

自动捕获 LangGraph / LangChain 调用
可视化 Run/Step/Tool 树
支持 Eval / Dataset / Annotation
商用 SaaS

Langfuse#

开源可观测平台：

模型无关（不只 LangChain）
自托管友好
Trace + Eval + Prompt Management
支持 OpenTelemetry

OpenTelemetry GenAI Semantic Conventions#

2026 新兴标准：用 OTel 通用 trace 体系 + GenAI 语义约定：

text
Span: llm.chat
  attributes:
    gen_ai.system: "openai"
    gen_ai.request.model: "gpt-4o"
    gen_ai.usage.input_tokens: 1200
    gen_ai.usage.output_tokens: 80

优势：与现有可观测体系（Jaeger/Tempo/Prometheus）打通。

选型#

需求	推荐
LangChain 重度用户	LangSmith
自托管 / 多框架	Langfuse
已有 OTel 体系	OTel GenAI
国内合规	Langfuse 自托管

Part 2：Trajectory Evaluation（轨迹级评测）#

为什么轨迹级评测重要#

只看最终结果会漏掉关键问题：

text
任务: "查询 Q3 营收并生成报告"

最终结果: 报告正确 ✓

但轨迹:
  Step 1: 调 search_web → 失败 (网络)
  Step 2: 重试 search_web → 失败
  Step 3: 重试 search_web → 成功
  Step 4: 调 read_file("Q3_report.pdf") → 成功
  Step 5: 生成报告

→ 表面成功, 但:
  - 浪费 2 次失败调用 (成本)
  - 重试逻辑可优化 (改用 search_db?)
  - 总延迟高 (用户体感差)

轨迹级评测能发现这些隐藏问题。

评测维度#

维度	含义	评测方法
任务成功率	最终是否完成任务	人工 / 规则 / LLM-as-a-Judge
工具成功率	每次工具调用是否成功	工具返回 success/fail
工具选择准确率	选对工具了吗	标注 golden tool
参数填写准确率	参数对吗	标注 golden args
轨迹合理性	步骤顺序/数量合理吗	LLM-as-a-Judge
效率	步数 / token / 成本	直接统计
延迟	总时长 / 各阶段时长	trace 时间戳
失败归因	失败时是什么原因	人工 / 自动分类

Task Success Rate / Tool Success Rate#

Task Success Rate#

任务级别的成功率：

text
总任务: 1000 个
成功: 850 个 (85%)
失败: 150 个 (15%)
  ├─ 工具失败: 60 个
  ├─ 模型决策错: 50 个
  ├─ 预算超限: 25 个
  └─ 其他: 15 个

实战坑：定义"成功"很难。任务"生成报告"——报告长度够算成功吗？内容正确算成功吗？必须事先定义清晰的成功标准。

Tool Success Rate#

工具调用级别的成功率：

text
工具: search_web
  调用次数: 500
  成功: 450 (90%)
  失败: 50 (10%)
    ├─ 超时: 30
    ├─ 限流: 15
    └─ 参数错: 5

按工具维度统计，能定位到哪个工具是瓶颈。

LLM-as-a-Judge#

原理#

用一个 LLM 来评价另一个 LLM 的输出：

python
judge_prompt = """
你是评审专家。请评价以下 Agent 回答的质量。

任务: {task}
Agent 回答: {answer}
参考答案: {reference}  # 可选

评分维度:
1. 正确性 (1-5)
2. 完整性 (1-5)
3. 清晰度 (1-5)

输出 JSON: {"correctness": 4, "completeness": 3, "clarity": 5, "reason": "..."}
"""

evaluation = llm.generate(judge_prompt.format(...))

优势 vs 劣势#

优势	劣势
自动化、可扩展	评审模型本身可能不准
可评模糊维度（合理性、清晰度）	有偏好（倾向长答案、自家模型）
比人工便宜	难评专业领域

实战要点#

用强模型评弱模型：GPT-5 评 GPT-4o，不要反过来
多 judge 投票：多个模型/多次评审取平均，减少偏差
校准：人工标注一小部分，校准 LLM judge 的准确性
prompt 要清晰：评分标准要明确，避免 judge 自由发挥

Human Annotation#

何时需要人工#

LLM judge 不准的维度（专业领域、创意判断）
关键评测（影响产品决策）
校准 LLM judge
标注 golden answer

标注流程#

text
设计标注 schema (评什么、怎么评)
标注员培训
双盲标注 (2+ 人独立标)
一致性检查 (Cohen's Kappa)
分歧仲裁
数据集固化

工具#

Argilla（开源标注平台）
Label Studio
Langfuse Annotation
自研

Cost / Latency（★与预算治理打通）#

成本统计#

text
Run 成本 = Σ LLM Call 成本 + Σ Tool 成本 + 基础设施成本

LLM Call 成本:
  input_tokens * input_price + output_tokens * output_price

Tool 成本:
  - 调用外部 API 费用 (如搜索 API)
  - 计算资源 (如运行 sandbox)

→ 按 run/user/feature/team 维度统计
→ 与 Ch5 预算治理打通, 实时监控

延迟统计#

text
Run 总延迟 = Σ (LLM 延迟 + Tool 延迟 + 其他)

关键指标:
  - TTFT (首字延迟)
  - 总延迟 (任务完成时间)
  - P50 / P95 / P99
  - 各阶段延迟占比

Regression Dataset（线上失败 → 转 eval case）#

反模式#

很多团队只在开发期跑 eval，上线后就不管了——线上出 bug 才临时排查。

正确做法#

text
线上 Run 失败
  ↓
自动 trace → 抽取 input + 期望 output
  ↓
人工标注 golden answer
  ↓
加入回归数据集
  ↓
下次发版前必跑这个数据集
  ↓
保证同样的 bug 不再发生

数据集管理#

text
datasets/
├── regression/
│   ├── bug-2026-07-01-tool-selection/  ← 某 bug 的回归集
│   ├── bug-2026-07-05-context-overflow/
│   └── ...
├── unit/                               ← 单元级 eval
├── integration/                        ← 集成级 eval
└── benchmark/                          ← 对标基准 (见下)

★ Agent 基准谱系#

为什么需要基准#

自己写的 eval 容易"自欺欺人"——题目都是自己出的。业界标准基准能横向对比：

text
我的 Agent: 75% success on my dataset
vs
业界基线: 60% on τ-bench
我的 Agent: 65% on τ-bench

→ 我的 Agent 在业界基准上确实优于基线

主流基准#

SWE-bench / Terminal-Bench（编程类）#

SWE-bench：让 Agent 修复真实 GitHub 项目的 issue
Terminal-Bench：命令行任务
评估：是否真的修了 bug（跑测试验证）

τ-bench（tau-bench，工具调用/对话任务）#

模拟客服/销售对话场景
Agent 要调用工具完成任务（订票/退款/查询）
评估：任务是否完成 + 是否符合业务规则

GAIA（通用助手任务）#

通用 AI 助手能力
多步推理 + 工具使用 + 多模态
难度分级（Level 1/2/3）

WebArena（浏览器/网页任务）#

真实网页操作任务
Agent 要导航、点击、输入、提交
评估：是否完成网页任务

基准对比#

基准	类型	难度	适用
SWE-bench	编码	高	Coding Agent
Terminal-Bench	命令行	中	Coding Agent
τ-bench	工具调用	中	通用 Agent
GAIA	通用助手	高	通用 Agent
WebArena	浏览器	中	Browser Agent

评测平台设计#

完整评测平台架构#

text
┌──────────────────────────────────┐
│  Trace 收集 (Run/Step/Tool)      │ ← 来自 Ch5 Runtime
└─────────────┬────────────────────┘
              ↓
┌──────────────────────────────────┐
│  Trace Storage                   │
│  - 按 run_id/user_id/task_id 索引│
└─────────────┬────────────────────┘
              ↓
┌──────────────────────────────────┐
│  Eval Engine                     │
│  - Task Success Rate             │
│  - Tool Success Rate             │
│  - Trajectory Eval (LLM Judge)   │
│  - Cost / Latency                │
└─────────────┬────────────────────┘
              ↓
┌──────────────────────────────────┐
│  Regression Dataset              │
│  - 线上失败 → eval case          │
│  - 发版前必跑                    │
└─────────────┬────────────────────┘
              ↓
┌──────────────────────────────────┐
│  Benchmark Integration           │
│  - τ-bench / SWE-bench / GAIA    │
└──────────────────────────────────┘

阶段产出#

完成本章后应该能：

设计 Trace 三层结构（Run / Step / LLM·Tool Call）
选型并接入 LangSmith / Langfuse / OTel GenAI
实现 Trajectory Evaluation（不只看最终结果）
计算 Task Success Rate / Tool Success Rate / 工具选择准确率
用 LLM-as-a-Judge（含校准、多 judge 投票）
设计 Human Annotation 流程（双盲、一致性、仲裁）
统计 Cost / Latency 并与 Ch5 预算治理打通
实现 Regression Dataset（线上失败 → eval case → 发版必跑）
接入基准谱系（τ-bench / SWE-bench / GAIA / WebArena）

下一章 Ch10 进入安全护栏与权限治理——Agent 一旦能调用工具和操作系统，风险就从"回答错误"升级为"错误执行"。