Apify MCP Server Agent Evals 实战：基于 Langfuse 的 MCP 工具族评测套件设计与故障诊断指南

本文介绍 Apify MCP Server 团队沉淀的 Langfuse Agent Eval 方法论：如何为一个 MCP 工具族（tasks、storage、runs、web-fetch 等）构建一套小型、经过校准的评测套件，并用它的失败来反哺修复工具本身。读完本文，你将掌握从"用户意图"出发设计用例、双数据集 CI 门禁编排、模型阶梯校准、Langfuse CLI 实操，以及一套"失败时按顺序归因"的诊断框架。

核心原则：评测从用户意图出发，而非从工具描述出发

这套方法论的第一条原则（也是贯穿全文的哲学）是：evals are designed from user intent, never from tool descriptions——评测定义的是"应该能正常工作的事"，而工具描述是事后为了让"朴素"的 Agent 能通过评测才去修复的东西。

这个顺序非常重要。如果写用例时盯着工具描述抄，你测的是 Agent 的"鹦鹉学舌"能力（parroting），而不是它对自然语言用户请求的理解与工具选择能力。描述是"被测对象"，绝不能被当成"出题依据"。

完整的命令、条目形态、探测模式与清扫查询（sweep queries）详见配套参考手册 reference.md。

整体流程：七步走

1. 盘点工具（Inventory the tools）

每个工具、每个参数组至少要有一个用例——最终由覆盖率矩阵（coverage matrix）来证明，而不是口头声明。

2. 先探测平台（Probe the platform first）

在编写任何依赖 API 行为的用例（必填字段、唯一性规则、限制、错误消息）之前，先用一个一次性的tsx脚本对着真实 API验证。绝不要基于假设的契约写用例——否则你会得到一堆被 schema 拒绝的输入值。

3. 两个数据集，每个 CI 门禁一个（Two datasets, one per CI gate）

每个条目必须在metadata.kind中声明自己的类型：

• "tool-call"：单轮，只断言第一次工具调用，无 judge，什么都不执行；
• "agent"：多轮，运行到完成，由 LLM judge 打分。

一个tool-call用例通过expectedTools（必填）固定工具名，通过expectedArgs（可选）固定参数——它是一个扁平对象，列出的每个 key 都必须与捕获到的调用中同名 key 深度相等，未列出的 key 忽略。需要把 MCP 与 MCP 之间的工具选择与 Claude Code 内置工具隔离开时，加mcpToolsOnly: true。

一个故意触发错误的agent用例（撞名、not-found、需求探索）必须设置metadata.expectedErrors，列出允许在该条目上失败的工具名——零工具错误门禁只豁免这些具名工具，因此它永远不会像"整库宽泛容错"那样掩盖无关的失败。

条目 id 必须是数据集前缀形态：pr 数据集中是pr/<tool>/<slug>，merge 数据集中是merge/<family>/<slug>，中间段是工具或工具族（search-actors、tasks、web-fetch等），<slug>是其余部分。

4. 分波次写用例（Write cases in waves）

2–3 个简单用例（单工具、输入明确）→ 1–2 个中等用例（跨工具链、运行选项）→ 2–3 个困难用例（含糊的用户语言、错误恢复、碰撞）。每一波写完先运行并评审，再写下一波——否则一个系统性的用例编写缺陷（比如"不可知的上下文"）会复制进每一个困难用例里。

5. 先用最强模型校准（Calibrate on the strongest model first）

先用 Opus 校准。在最强模型上的失败必然是用例缺陷或产品缺口，绝不可能是描述问题。只有一套校准过的套件（强模型 100% 通过）才能把弱模型上的失败归因于描述问题。

6. 逐级下调模型（Ladder down）

Sonnet → Haiku。"Opus 通过而 Haiku 失败"= 工具描述或输出没能承载一个朴素 Agent 的理解。这才是你构建这套评测想要捕获的信号。

7. 先修输出，再修描述（Fix tools via outputs before descriptions）

工具响应的 summary/nextStep 里的一句引导语，每次调用都会到达每个 Agent；而描述文本往往只是被 skim 一眼。原始构建中修复 Haiku 失败的两个输出修正（output nudge）都是响应文本的改动，而非描述改动。

数据集条目形态（Langfuse item shape）

一个agent用例的完整 JSON 形态如下（见 reference.md）：

{ "datasetName": "mcp-server-evals-merge", "id": "merge/<family>/<tool>-<difficulty>-1", "input": { "query": "<用户语言提示词，不得出现工具名>" }, "expectedOutput": "PASS only if <tool> was called with <args> and the final answer states <fact>. FAIL if <具体错误行为>.", "metadata": { "category": "<tool-or-chain>", "kind": "agent", "maxTurns": 10, "tools": ["<family>", "actors"] } }

关键约束：

• datasetName二选一：kind: "agent"条目用mcp-server-evals-merge，kind: "tool-call"条目用mcp-server-evals-pr。
• metadata是严格校验的（实现见 langfuse/dataset.ts）：未知 key 会在任何 LLM 花费之前就让本次运行失败。可用旋钮：category、kind、expectedTools、expectedArgs、expectedErrors、maxTurns、tools、failTools、mcpToolsOnly。
• category= 被测工具（--category过滤的依据）；难度写在 id 的<slug>半段。
• kind: "agent"必须有expectedOutput（多轮、judge 打分，expectedErrors/failTools/maxTurns生效）；kind: "tool-call"必须有非空expectedTools，并拒绝expectedOutput、expectedErrors、failTools、maxTurns（轮数固定为 2）。
• expectedArgs（可选，仅tool-call）：只在expectedTools只列出一个工具、或列出的每个工具都共享相同 key 与期望值时使用——扁平对象无法对不同工具施加不同期望。示例pr/call-actor/rag-web-browser：apify/rag-web-browser既可以解析到通用call-actor工具（{actor, input}），也可以解析到直接工具apify--rag-web-browser（{query, maxResults, ...}），两种参数形态互不兼容，所以该条目把两个工具都列进expectedTools，且不带expectedArgs。
• maxTurns参考：单工具 6–8，创建+验证 10，链式 12–18。要为 reference 允许的最长路径（探索→拒绝→回退）留预算，而不是为快乐路径；Actor 运行类用例要为轮询周期留出余量（run 可能超过等待上限）。
• 条目按idupsert。id 在项目内永久唯一，即使归档/在其他数据集删除重建也不会释放。退休用例 = upsert"status": "ARCHIVED"。
• failTools（仅agent）：harness 在到达服务器前强制失败的工具列表（如["call-actor"]），消息携带真实的report-problem引导语——用于确定性地产出"可触发 nudge 的失败"，这是真实服务器 + API 无法按需复现的场景。

运行评测：命令行实操

基本命令

# 默认数据集 mcp-server-evals-pr；门禁是聚合通过率 >= DEFAULT_PASS_THRESHOLD (0.9， # 依据见 runner/run.ts)。--pass-threshold 1.0 恢复严格的全通过门禁。 # 裸跑 = 快速 PR 门禁集：即 kind: "tool-call" 的条目。 pnpm run evals:mcp-agent --agent-model claude-haiku-4-5 --subscription # merge 集：kind: "agent" 条目，push 到 master 时运行 pnpm run evals:mcp-agent --dataset mcp-server-evals-merge --agent-model <m> --subscription # 按 id 前缀只跑一个族 pnpm run evals:mcp-agent --dataset mcp-server-evals-merge --id '^merge/<family>/' --agent-model <m> --subscription # 进一步收窄：--category <name>；--concurrency N；--tool-timeout secs；--iterations N (pass@k/pass^k)

命令在 package.json 中定义为pnpm run build && tsx evals/runner/run.ts（会先自动构建 MCP server），另有evals:mcp-agent:export-dataset、evals:mcp-agent:tasks-fixtures、evals:mcp-agent:schedules-fixtures三个配套脚本。

关键 flag 详解（实现见 evals/runner/run.ts）

• --subscription：从进程环境删除ANTHROPIC_API_KEY，让 Agent SDK 的 Claude Code 子进程使用本地登录凭据；不加则按 API key 计费。注意当--subscription未开启时该变量属于必填项，缺失会直接process.exit(1)。
• --claude-judge：让 judge 也跑在 Agent SDK 上（此时--judge-model接受 Anthropic 模型 id，默认claude-sonnet-5）；配合--subscription --claude-judge，一次运行只需APIFY_TOKEN+ Langfuse 三个 key，无需 OpenRouter key。注意：Claude judge 评 Claude agent 可能自我宽容（self-lenient）——要可比数字，优先用 OpenRouter judge。
• <m>模型阶梯：claude-opus-5（校准）→claude-sonnet-5→claude-haiku-4-5（CLI 默认，也是最敏感的探针）。默认配置见 evals/config.ts：agent 默认claude-haiku-4-5，judge 默认deepseek/deepseek-v4-flash。
• --pass-threshold：默认0.9（依据在 evals/runner/run.ts：pr 数据集里有两个 tool-call 条目被保留但 Haiku 大约每三次运行漏一次，失败本身就是信号而非用例缺陷）；--pass-threshold 1.0要求每个 trial 都过。
• --concurrency：默认 8，映射到 SDK 的maxConcurrency，是顺序批次执行而非滚动窗口——一个慢测试会拖住同批其他测试。
• --tool-timeout：默认 60 秒（DEFAULT_TOOL_TIMEOUT_SECONDS）；跑长时 Actor 时用--tool-timeout 600加大。
• 退出码：0= 聚合通过率（passed trials / requested trials）达到--pass-threshold；1= 未达标或 setup 失败。链式 shell 命令的退出码是最后一个run 的——读每个日志的📊行，而不是看整条链的状态。
• 已知 flakes：🔥 Never completed (task threw)（harness/SDK 进程问题）先单条目重试一次再诊断；远程/沙箱环境下 Agent 读到 "MCP servers still connecting" 而回退到内置工具（本地不重现）——单条目重试一次，本地机器上重复失败才是真的。

有状态族的 fixtures 脚本

创建命名资源的套件在两次运行之间要先跑 fixtures 脚本（pnpm run evals:mcp-agent:tasks-fixtures，按族适配）：删除遗留的eval-*资源并重新播种永久 fixture。纯 Web 目标族（如web-fetch、web-selection）不创建命名状态，无需 fixtures 脚本——在 README 里说明即可。

Langfuse 环境与 CLI 操作

环境变量

LANGFUSE_PUBLIC_KEY=pk-lf-... # 项目设置 → API keys LANGFUSE_SECRET_KEY=sk-lf-... LANGFUSE_BASE_URL=https://langfuse.apify.dev

这些放在仓库根目录的.env中（harness 通过 dotenv 加载，并在任何客户端构造前先做值清洗sanitizeProcessEnv()，见 evals/runner/run.ts）。Git worktree 不共享.env——先从主 checkout 复制一份（cp <main-checkout>/.env .env）。CLI 读的是LANGFUSE_HOST而非LANGFUSE_BASE_URL，所以两个都要导出。

Langfuse CLI 使用

npx在仓库内会被拒绝运行（pnpm 固定的devEngines）——从任意其他目录运行。CLI 调用前的标准 preamble：

cd /tmp && export $(grep -E '^LANGFUSE' <repo>/.env | xargs) && export LANGFUSE_HOST="$LANGFUSE_BASE_URL"

npx -y langfuse-cli api datasets list --json # 两个数据集已存在，无需创建 jq -c '.[0]' items.json | npx -y langfuse-cli api dataset-items create --body-file - # create = 按 id UPSERT：重发同 id 即可迭代用例 npx -y langfuse-cli api dataset-items get <id> npx -y langfuse-cli api dataset-items delete <id> # 不可逆，且不释放 id（id 已烧掉）——用归档代替（status: "ARCHIVED"）

每个用例的编辑循环：upsert 条目 → 用--id '<substring-regex>'只重跑该条目 → 读 transcript。

读取失败 transcript（judge 理由 + 每轮工具调用）。--from-start-time必填；条目的output字段是 JSON字符串——需要fromjson管道：

npx -y langfuse-cli api experiment-items list \ --experiment-name "<runName from console>" --from-start-time "<ISO>" --fields core,io --all --json \ | jq -r '.body.data[] | (.output | fromjson) as $o | $o.id + " " + $o.judgeResult.verdict + "\n" + ([$o.transcript[] | to_entries[] | " " + .key + ": " + (.value | tostring | .[0:300])] | join("\n"))'

运行后清扫意外错误。只读kind: "agent"条目：没有expectedErrors条目的 agent 运行必须贡献零行 ERROR；但每个通过的kind: "tool-call"trial 都会按设计产生一个 ERROR span（deny-all hook 拒绝了它正在测量的那次调用），而 tool-call 条目不能声明expectedErrors。

npx -y langfuse-cli api observations list --level ERROR \ --from-start-time "<run start ISO>" --fields core,basic,io --limit 100

API 探测模式（写平台依赖用例之前）

在evals/scripts/probe_*_tmp.ts放一个一次性脚本，用pnpm exec tsx运行，用完删除。用真实的apify-client精确探测用例将依赖的行为：必填字段、唯一性错误、发布要求、长度限制、密钥处理。捕获精确的错误消息和typeslug——reference 可以要求 Agent 对其作出反应（工具错误包含(API error type: <slug>)）。

import 'dotenv/config'; import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); // create the thing the case assumes, read it back, print the error/shape, delete it

对于实时 Web 用例：探测精确的目标 URL，验证抓取到的内容支持前提（状态、body、答案需要的事实）——并优先选稳定主机（rfc-editor.org、example.com）而非易挂的主机（httpbin.org 经常 503），凡是内容本身就是交付物的地方。

覆盖率矩阵（数据集的完成定义）

对每个工具：至少一个专属用例，加上每个参数组在某个用例中被覆盖（create: input/name/config；get: found + not-found；update: 每个可独立更新的组；生命周期工具：一个干净的快乐路径用例 + 一个带expectedErrors的需求发现用例）。一个工具仅作为其他用例的尾巴被练习（如 unpublish）也是可接受的，只要专属用例会与已有用例重复——报告覆盖率时要明确说明这一点。

诊断失败用例——按这个顺序归因

归因前永远先读 transcript。Judge 的一句话只是线索，不是诊断。

防止返工的规则

• Reference 必须是 judge 可检查的契约："PASS only if<tool>was called with<arg>and the final answer states<fact>。FAIL if …"。绝不写"the agent should handle it well"。
• Query 用用户语言。点名工具的 query 测的是鹦鹉学舌而不是描述；困难用例绝不能点名工具。
• Telemetry 要真实。绝不为隐藏预期错误而降级 span 级别——那会掩盖真实错误。改为在条目的metadata.expectedErrors中具名预期失败；门禁是tool_errors == 0，统计服务器（MCP）工具调用中除具名者之外的所有失败（失败的只读探测仍然算：猜 slug 而不是 search 就是失败；Agent 的内置工具豁免——它们的磕绊是客户端噪音，不是我们的）。
• 写 judge 盲区条款。Judge 看不到工具结果，所以 reference 必须预防误读：Agent 叙述怪癖（"count 读出来是 0 但 items 在那里"）不是承认失败；通过明确归属的回退交付的内容是"检索到了"而不是"编造了"；绝不要求叙述一个合法替代路径完全跳过的事件（一个 block、一个 error）。
• 惩罚虚假声称，而非惩罚沉默的成功。结果和诚实是两个轴；礼节（宣布切换工具、为绕路道歉）是加分项，绝不是 PASS 条件。
• tool-call 用例必须接受每个站得住脚的答案。expectedTools是列表，scorer 命中任一成员即通过——当第二个工具也合法地服务目标时（如fetch-apify-docs已加载时一个 Apify 文档 URL），把两个都列上，而不是让合法行为失败。优先选择只有被测工具适配的目标；做不到就放宽列表并跳过expectedArgs（其 key 必须对模型选中的任一工具都成立）。
• 探测目标，而不只是机制。实时 Web 用例要在编写时抓取精确 URL，检查内容支持前提（一个探测过可工作的 scraper 对一个后来发现是零帖子的 profile 依然返回了空）。
• 状态是账号全局的。固定的eval-前缀资源名 + fixtures seed/cleanup 脚本；每个对话自包含（创建 → 动作 → 清理）；纯 "get" 用例用一个永久只读 fixture。
• 数据集条目 id 永久项目唯一——不能在数据集间搬移，归档后也不能复用。"搬动"一个用例 = 新 id + 归档旧的。

红线——停下来重新思考

• 盯着工具描述写用例 → 你在测鹦鹉学舌。关掉文件。
• 一个故意触发错误的agent用例没有metadata.expectedErrors→ 在该条目上设置它；不再有运行级容错 flag，只有按条目、按工具的豁免。
• 一次重跑"修复"了你没诊断的失败 → 已知 harness flake（"task threw, never completed"）可以重试一次；judge 判 FAIL 永远不是 flake，读 transcript。
• 因为一个模型失败了一次就改工具 → 先复现或诊断；单次运行是随机的。
• Query 里出现明显假 URL（ftp.example.com、this-is-a-test.com）→ 模型会合理地拒绝"占位符"目标；用真实主机，需要抓取失败时用该主机上不存在的路径。
• 交付物要求逐字复述几百字以上 → 某些模型会在零工具调用的情况下以复述为由拒绝，无论许可如何；用例测的会变成拒绝阈值而非工具选择。
• 用例的支线任务不是被测轴（超大 payload 引诱文件交付或字节级校验）→ 让用户要求"在聊天内交付"并预先授权截断，为maxTurns预算恢复路径而非快乐路径。

常见错误

从发现修复工具：优先级排序

1. 响应 summary/nextStep 文本——例如"stored values are never returned…"、"to re-check publication state, use get-actor-task"。每次调用都会到达每个 Agent。Summary 绝不能陈述平台还无法背书结论（未验证的零计数应写成"reads 0, can lag"，而不是"no items found"）——Agent 会引用 summary 并据此放弃。
2. 参数 schema 约束 + describe()——把 API 限制编码进去（.max(60)），让非法调用在触达 API 之前就在客户端失败。参数描述在写参数时被读取，所以约束说明放那里比放描述尾部更有效——但它也有极限（一个弱模型在两者都修好后仍把 ftp:// 静默改写为 https://）；修完你拥有的每一层后，记录残余。
3. 字段重命名 / 形态对齐——字段名诱发误读或偏离 API 契约时，与 API 对象对齐（structuredContent改动必须为内部仓库的契约套件标记）。
4. 描述 USAGE 行——偏置-行动 nudge（"resolve loose Actor references with search-actors instead of asking"），条件依赖hasTool()。

任何工具改动后：pnpm run build会随evals:mcp-agent自动执行；先只重跑受影响的模型/用例对，最后再跑完整阶梯。

底层机制速览（源码级补充）

为帮助你理解命令与规则背后的实现，几个关键源码位置：

• 两条评测模式的分工：tool-call模式由 agent/claude_agent.ts 里的 deny-allPreToolUsehook 拒绝每次调用（拒绝措辞TOOL_CALL_DENY_REASON与固定轮数TOOL_CALL_MAX_TURNS = 2定义在 runner/tool_call_mode.ts），Agent 在报告"本会调用什么"后停止；评分函数resolveFirstToolMatch会跳过 Claude Code 的路由元工具ToolSearch，只测量第一个非 ToolSearch 调用，实现"名字在expectedTools内 + 列出的expectedArgskey 深度相等"的匹配逻辑（见 runner/tool_call_mode.ts）。
• Judge 的输入边界：judge 看到工具调用与参数、Agent 回复，但看不到原始工具结果（judge/judge.ts 的JUDGE_PROMPT_TEMPLATE明确写明 "Tool results are not shown (only tool calls and agent responses)"），这就是为什么 reference 只能要求"可观测"事实。
• 条目的严格校验：metadata用z.strictObject校验（evals/langfuse/dataset.ts），未知 key 直接让 run 在 LLM 花费前失败；kind专属字段的交叉约束（expectedOutput/expectedErrors/failTools/maxTurns仅限agent，expectedTools/expectedArgs仅限tool-call）在superRefine中强制（evals/langfuse/dataset.ts）。
• 通过率门禁：pass_rate = passedTrials / requestedTrials（requestedIds.length * iterations），所以被丢弃的 trial 会拉低比率而不是从统计中消失（evals/runner/experiment.ts）；默认阈值0.9及背后的理由记录在 evals/runner/run.ts。
• 数据集即真理之源：运行只读数据集、从不写入；用例在 Langfuse UI 编辑，evals:mcp-agent:export-dataset（scripts/export_dataset.ts）只是导出快照供离线阅读，运行时不读快照——完整的架构决策（进程隔离、Claude Agent SDK、judge 客户端共享等）记录在 evals/README.md。

更完整的评测系统背景（两个数据集的既有族、CI 门禁阈值、工具描述编写准则、常见问题排查）可进一步阅读 evals/README.md 与技能参考手册 reference.md。