Anthropic Agent 工程实战笔记（五）评测与 Eval

本模块主要参考（官方）

$1\] [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)（Anthropic Engineering，Jan 2026）$
$3\] [Designing AI-resistant technical evaluations](https://www.anthropic.com/engineering/AI-resistant-technical-evaluations)（Anthropic Engineering）$

本模块在整体中的位置

前四模块都在讲「怎么建 Agent」；若没有评测，改进就是盲飞------不知道是变好还是变坏、是模型问题还是环境问题。Agent 的评测和单轮模型不同：要看 outcome （任务结束时的环境终态，如 DB 是否真有预订）、transcript （单次运行的完整轨迹，含 tool 调用与推理）、多种 graders （对 transcript 或 outcome 打分的逻辑，可为代码/模型/人），还要控制 infrastructure 噪声（资源、时间等环境差异对分数的影响）。本模块先建立评测的术语与结构（§1--§3）→ 再给从零到一的路线图（§4）→ 再讲 infra 噪声与按 Agent 类型的要点（§5--§6）。学完这里，模块六的「故障复盘」里「evals 未覆盖」的教训才会更具体。

逻辑线索（本模块阅读顺序）

概念：suite （为一类能力设计的一组评测任务）、harness （让模型以 Agent 方式运行的逻辑）、outcome、transcript、grader、trial （单次尝试）；capability vs regression（能力评测「能多难」vs 回归评测「还会不会」防退化）。
Graders ：code / model / human 的取舍；评结果不评路径；partial credit（部分得分，多组件任务可部分通过即给部分分）。
非确定性 ：pass@k （k 次中至少一次成功）与 pass^k（k 次全部成功）分别回答「至少成功一次」与「每次都成功」。
路线图：尽早开始、从手工检查抽 task、无歧义+参考解、平衡正负例、稳定环境。
Infra：资源 floor 与 kill 上限分开；❤️% 差距谨慎解读。

本模块总流程图：Eval 从零到一 [1]

改 harness/任务
收口
定义 Task
Agent Harness
Run Trial
Outcome + Transcript
Graders
Score
迭代?
进 Regression Suite

1. 评测结构 [1]

概念	含义
Eval suite	为测某类能力/行为而设计的一组 task
Agent harness	让模型以 Agent 方式运行的逻辑；评测的是「harness + 模型」整体
Evaluation harness	跑 evals 的基础设施：并发、记录、打分、汇总
Outcome	任务结束时的环境终态（如 DB 里是否真有预订），而非仅对话内容
Transcript	单次 trial 的完整记录（含 tool 调用、推理、中间结果）
Grader	对 transcript 或 outcome 打分的逻辑；可多 grader、多 assertion
Trial	单次尝试；因非确定性通常多 trial
Capability vs Regression	Capability：能做到多难的事；Regression：原来会的现在还会吗，应近 100%

高通过率的 capability （能力）题可「毕业」进 regression（回归）套件，持续防退化。

结构关系示意 [1]：
Single Trial
Eval Suite
Task 1
Task 2
Task ...
Input
Agent Harness + Model
Outcome
Transcript
Graders
Score

2. Graders 类型与使用

2.1 三类 Grader 对比 [1]（原文表格整理）

类型	方法举例	优点	缺点
Code-based	字符串/正则、单元测试、静态分析、outcome 检查、tool 调用检查、transcript 分析（轮数、token）	快、便宜、可复现、易调试、可验证具体条件	对合理变体脆弱、缺乏 nuance、部分主观任务难覆盖
Model-based	多评委共识、参考输出、成对比较、自然语言断言、rubric 打分	可处理自由形式与开放任务、有 nuance、可扩展、灵活	需与人类校准、更贵、非确定
Human	校准 model grader、A/B、抽检、专家评审、众包	可校准 model grader、贴近专家判断、质量标杆	慢、贵、难规模化

同一 task 可组合多种 grader；打分方式可以是加权（加权后达阈值即过）、全过（所有 grader 都过）或混合。

2.2 使用建议 [1]

据 [1]，能确定性的先用确定性；必须用 LLM 时做 rubric（评分标准/维度）、分维度单独评、提供「Unknown」出口防幻觉。
评结果而非路径 [1]：不锁死「必须先调 A 再调 B」；Agent 有多条合理路径，锁步骤会误伤。
多组件任务支持 partial credit [1]（例如客服：身份验证过了但退款没做成，也应体现部分得分）。

3. 非确定性：pass@k 与 pass^k [1]

因 Agent 行为非确定，同一 task 多轮跑结果会不同；需要区分两种指标 [1]：

指标	含义	k 增大时	典型用途
pass@k	k 次中至少一次成功的概率	分数升高（更多「射门」机会）	「只要有一次成功即可」如部分 coding、生成多方案选一
pass^k	k 次全部成功的概率	分数降低（一致性要求更高）	面向用户的 Agent，需要每次都可预期

k=1 时两者相等（都是单次成功率）。
k=10 时二者「讲相反的故事」：pass@10 趋近 100%，pass^10 可能趋近 0%。
选哪个取决于产品：重「能否做到」用 pass@k，重「是否稳定」用 pass^k。

示例：pass@k 与 pass^k 计算 [1]

同一 task 跑 k 次 trial，得到 k 个布尔结果；两种指标计算方式如下：

python 复制代码

def pass_at_k(trial_results: list[bool]) -> bool:
    """pass@k：k 次中至少一次成功。"""
    return any(trial_results)

def pass_all_k(trial_results: list[bool]) -> bool:
    """pass^k：k 次全部成功。"""
    return len(trial_results) > 0 and all(trial_results)

# 例如 k=5 的 5 次 trial： [True, False, True, False, False]
# pass@5 = True,  pass^5 = False
trials = [True, False, True, False, False]
print("pass@5:", pass_at_k(trials))   # True
print("pass^5:", pass_all_k(trials))  # False

4. 代码示例：Eval 配置（原文 YAML）

4.1 Coding Agent

下面是一段示意性 的 eval 配置 [1]：给 Agent 一个「修认证绕过漏洞」的 task（评测任务），用多种 grader 与指标。实际不必全上，按需选用。

yaml 复制代码

task:
  id: "fix-auth-bypass_1"
  desc: "Fix authentication bypass when password field is empty and ..."
  graders:
    - type: deterministic_tests
      required: [test_empty_pw_rejected.py, test_null_pw_rejected.py]
    - type: llm_rubric
      rubric: prompts/code_quality.md
    - type: static_analysis
      commands: [ruff, mypy, bandit]
    - type: state_check
      expect:
        security_logs: { event_type: "auth_blocked" }
    - type: tool_calls
      required:
        - { tool: read_file, params: { path: "src/auth/*" } }
        - { tool: edit_file }
        - { tool: run_tests }
  tracked_metrics:
    - type: transcript
      metrics:
        - n_turns
        - n_toolcalls
        - n_total_tokens
    - type: latency
      metrics:
        - time_to_first_token
        - output_tokens_per_sec
        - time_to_last_token

原文强调：实践中 coding eval 通常以单元测试 验证正确性 + LLM rubric（用 LLM 按评分标准打分的 grader）看代码质量为主，其它按需加。

4.2 可运行代码示例：最小 Eval 单次 Trial [1]

下面用纯 Python 跑一次「单 task + 单 code grader」的 trial，不依赖外部 API，可直接复制运行。实际工程中会把 harness 换成真实 Agent 调用、outcome 换成真实环境终态。

python 复制代码

# 最小 eval：一个 task，一个 code-based grader，单 trial
# 运行：python eval_one_trial.py

def agent_harness(task_input: str) -> tuple[str, dict]:
    """模拟 Agent 一次 trial：返回 (final_reply, outcome)。
    真实实现里这里调用模型 + 工具，并记录 transcript。"""
    # 占位：实际应跑 Agent 得到 transcript 与 outcome
    reply = "The quick brown fox jumps over the lazy dog."
    outcome = {"reply_contains_fox": "fox" in reply.lower(), "length_ok": len(reply) > 10}
    return reply, outcome

def grader(outcome: dict) -> bool:
    """Code-based grader：评 outcome 不评路径 [1]。"""
    return outcome.get("reply_contains_fox", False) and outcome.get("length_ok", False)

def run_one_trial(task_id: str, task_input: str) -> bool:
    reply, outcome = agent_harness(task_input)
    passed = grader(outcome)
    print(f"Task {task_id} => passed={passed}, outcome={outcome}")
    return passed

if __name__ == "__main__":
    task = ("demo_1", "Say a sentence that contains the word 'fox'.")
    run_one_trial(*task)

扩展方向：多 task 循环、多 trial 算 pass@k / pass^k、将 outcome 换为真实 DB/文件状态或 transcript 再交给 LLM rubric。LangGraph 1.0 下 pass@k、pass^k 与单次 trial（agent_harness / grader）的等价实现见 <further-reading.md> 的「五、LangGraph 1.0 对照代码」§5.5。

4.3 Conversational Agent

客服场景 [1]：处理「沮丧客户要退款」，需同时看结果（工单解决、退款完成）和交互质量（共情、说清政策、是否基于工具结果回答）。

yaml 复制代码

graders:
  - type: llm_rubric
    rubric: prompts/support_quality.md
    assertions:
      - "Agent showed empathy for customer's frustration"
      - "Resolution was clearly explained"
      - "Agent's response grounded in fetch_policy tool results"
  - type: state_check
    expect:
      tickets: { status: resolved }
      refunds: { status: processed }
  - type: tool_calls
    required:
      - { tool: verify_identity }
      - { tool: process_refund, params: { amount: "<=100" } }
      - { tool: send_confirmation }
  - type: transcript
    max_turns: 10
tracked_metrics:
  - type: transcript
    metrics:
      - n_turns
      - n_toolcalls
      - n_total_tokens
  - type: latency
    metrics:
      - time_to_first_token
      - output_tokens_per_sec
      - time_to_last_token

实践中 conversational 常用 model-based grader 同时看任务完成度与沟通质量，因为「正确」答案往往不唯一。

5. 从零到一的 Evals 路线图 [1]

据 [1]，实践建议如下：

尽早开始：20--50 个来自真实失败的简单 task 就够起步；等系统复杂后再补 evals 成本高。
从现有手工检查开始：把发布前的手动检查、用户常见路径变成 task；从 bug 与工单里抽失败用例。
任务要无歧义 ：两个领域专家应对同一任务给出相同 pass/fail；配参考解（参考答案/正例，证明任务可解且 grader 配置正确）。0% pass@100 多为 task 或 grader 有问题，而非模型完全不行。
平衡正负例：既要「该做时做了」，也要「不该做时没做」（如搜索：该搜的题 + 不该搜的题），避免单边优化。
稳定环境：每次 trial 干净环境、隔离；避免共享状态导致相关失败或虚高；资源限制要明确（见下节）。
Partial credit：多组件任务应支持部分得分。

6. Infrastructure 噪声 [2]

据 [2]，Agentic coding 类评测中：

运行环境会显著影响分数：资源约束（CPU/RAM 的 floor vs kill 阈值）、时间限制等会改变「测的是什么」。
问题：若把「保证分配」和「超限即杀」设为同一值，瞬时内存尖峰会导致本可成功的任务被 OOM kill。
建议 [2]：分开保证值与硬上限，留出缓冲。文中 3x 缓冲在 Terminal-Bench 上既降 infra 错误又控制分数膨胀；具体倍数因 benchmark 而异，应报告。
资源给得越多，部分任务会从「不可行」变「可行」（如大依赖、重测试）；资源配置应作为实验变量记录与固定 [2]。
消费结果时 [2]：对 ❤️% 的排行榜差距保持怀疑，直到配置一致可复现；几分之差可能来自更大 VM 或不同时间点，而非纯模型能力。

7. 按 Agent 类型的评测要点 [1]

据 [1] 整理的按 Agent 类型评测时需关注要点：

类型	要点
Coding	确定性 grader（单元测试、静态分析）+ 可选 LLM rubric；SWE-bench Verified、Terminal-Bench 等；环境与资源要稳定
Conversational	常需「用户模拟」第二 LLM；多维度：状态检查、轮数约束、LLM rubric（语气、是否接地）；τ-Bench / τ2-Bench 等
Research	结合 groundedness、覆盖度、来源质量；有客观答案时可精确匹配；主观部分用 LLM rubric 并与人校准
Computer use	真实或沙箱环境；验证 outcome（URL、后端状态、文件系统等）；DOM vs 截图在 token/延迟上的权衡

8. 实战自检清单

是否已有 20--50 个来自真实失败或核心路径的 task？是否配了参考解？
是否区分 capability 与 regression 套件？是否评结果而非路径？
多组件任务是否支持 partial credit？LLM grader 是否分维度、有 Unknown 出口？
环境是否每 trial 隔离？资源是否明确「保证值 + 硬上限」并记录？是否对 ❤️% 差距谨慎解读？

9. 本模块要点回顾（便于自检与分享）

概念：评测的是「Agent harness + 模型」；outcome 是环境终态，transcript 是完整轨迹；capability 测「能多难」，regression 测「还会不会」。
Graders：确定性优先；LLM grader 要 rubric、分维度、Unknown 出口；评结果不评路径；多组件用 partial credit。
指标：pass@k（至少一次成功）vs pass^k（全部成功），按产品选。
路线图：早起步、从真实失败抽 task、无歧义+参考解、平衡正负例、环境隔离、资源明确。
Infra：资源「保证值」与「硬上限」分开；排行榜 ❤️% 差距需谨慎、配置一致才可比较。

参考文献（本模块）

编号	来源	链接
[1]	Anthropic, Demystifying evals for AI agents	https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents
[2]	Anthropic, Quantifying infrastructure noise in agentic coding evals	https://www.anthropic.com/engineering/infrastructure-noise
[3]	Anthropic, Designing AI-resistant technical evaluations	https://www.anthropic.com/engineering/AI-resistant-technical-evaluations

10. 延伸

AI-resistant evaluations [3]：防「刷题」、抗 AI 的题目设计，见原文。
GitHub ： claude-agent-sdk-demos 等示例中可参考 trial/outcome 的收集方式；索引 <index.md> 有「GitHub 与官方源码」汇总。
上一模块：<04-long-running-multiagent.md> · 下一模块：<06-security-production.md>。