1. 为什么 Agent 系统测试总在“看起来没问题”时翻车

Agent 系统测试和普通 LLM 测试最大的区别在于：你评估的不是一句话，而是一条执行轨迹。普通 LLM 应用是单轮结构，输入 prompt、拿到 response、判断对错就结束了。Agent 不一样，它会读任务、拆计划、调用工具、读取工具返回、更新环境状态，最后才输出结果。中间任何一步漂移，最终结果都可能完全不同。

我见过太多团队在 demo 阶段一切顺利，一上生产就出问题。同一个任务跑三次，工具调用顺序不一样；改了一句 prompt，A 问题解决了，B 问题悄悄冒出来；Agent 说“退款已完成”，但数据库里根本没有退款记录。这些问题的共同点是：只看最终文本输出，根本发现不了。

这就是 Agent 系统测试的核心难点——最终回答正确，不代表过程可靠；过程看起来合理，也不代表最终状态正确。一个 coding agent 说“漏洞已修复”，但测试没跑过；一个研究 Agent 给出漂亮报告，但关键引用来自低质量网页。这些都需要 eval 体系来兜底。

Anthropic 在《Demystifying evals for AI agents》里把 Agent eval 拆成了一条工程流水线：Task 是测试题，Trial 是一次运行，Grader 是打分逻辑，Transcript 是完整执行记录，Outcome 是最终环境状态，Eval harness 是跑评测的基础设施，Agent harness 是让模型具备 Agent 行为的框架。这些术语听起来多，但落到工程上就是一件事：把手工测试固化成可重复执行的流程。

没有 eval 的 Agent 开发，本质上是在凭感觉调系统。你改了一个 prompt，觉得“好像好了一点”，但到底好了多少、有没有引入回归，完全说不清。这篇文章要解决的，就是怎么用 TaoToken 统一 Key 接入测试链路，把 Agent 系统测试和 eval 落地成一套可复制、可回归的工程流程。

适合谁看：正在做 Agent 产品、需要建立质量验证流程的工程团队；已经有一套手工测试流程、想把它自动化的开发者；以及被“demo 能跑、生产不稳”折磨过的同学。

2. TaoToken 统一 Key 接入 Agent eval 链路的前置准备

在讲具体配置之前，先说清楚为什么 Agent eval 需要一个统一的 API 通道。Agent 测试和普通单轮测试不一样，它会在一次 Trial 里产生大量 API 调用：模型决策、工具调用、结果读取、状态更新，每一步都可能触发一次请求。如果测试环境里 Key 散落在各个脚本、各个 CI job 里，排查问题时会非常痛苦——你甚至不知道某次失败是模型行为漂移，还是某个环境的 Key 配额打满了。

TaoToken 在这里的角色是统一入口。你只需要一个 Base URL 和一个 Key，就能让 eval harness、agent harness、grader 里的模型调用都走同一条通道。这样做的好处有三个：第一，测试链路里的所有模型调用可以统一观测；第二，切换模型或调整参数时不用改多处配置；第三，CI 环境里只需要注入一个 Key，减少配置泄漏面。

前置准备分三步。

第一步，拿到 Key。访问 https://taotoken.net/api-keys 创建 API Key。建议给 eval 环境单独建一个 Key，不要和线上生产 Key 混用。命名上可以带eval或ci前缀，方便后续在控制台区分。

第二步，确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api，所有兼容 OpenAI 或 Anthropic 协议的客户端都指向这个地址。注意这里不要加 UTM 参数，API 调用需要的是干净的基础地址。

第三步，确定你要接入的模型 ID。Agent eval 里通常至少涉及两类模型调用：一类是 agent 本身用的模型，一类是 LLM judge 用的模型。建议在配置里把这两个角色分开写，方便后续单独调整。比如 agent 用claude-sonnet-4-20250514，judge 用claude-haiku-3-5-20241022，具体可用模型以控制台列表为准。

如果你用的是 Claude Code 或类似的 Agent 框架，还需要确认它的配置文件路径。Claude Code 的配置通常在~/.claude/settings.json，Cline 的 MCP 配置在.cline/mcp.json或全局设置里，Codex 的认证信息在~/.codex/auth.json。这些文件里都需要写全三件套：Base URL、API Key、Model ID。少一个都会导致 401 或 model not found。

还有一个容易被忽略的点：eval 环境最好和开发环境隔离。你可以用同一个 TaoToken 账号下的不同 Key 来区分，也可以在配置里加一个env字段标记当前运行环境。这样当 CI 里出现失败时，你能快速判断是测试用例本身的问题，还是环境配置的问题。

3. 可复制的 Agent eval 配置：从 settings 到 grader 断言

这一节给出可以直接复制修改的配置片段。我会按“Agent 接入配置 → eval 任务定义 → grader 断言”三层来写，每一层都对应真实工程里的一个文件。

3.1 Agent 接入配置：settings.json 与 auth.json

如果你用 Claude Code 作为 agent harness，配置文件在~/.claude/settings.json。核心是把 API 通道指向 TaoToken：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的eval专用Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": ["Read", "Edit", "Bash"] } }

如果你用的是 Codex 风格的 agent，认证信息写在~/.codex/auth.json：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的eval专用Key", "model": "claude-sonnet-4-20250514" }

Cline 的 MCP 配置里同样需要三件套。在.cline/mcp.json中：

{ "mcpServers": { "eval-agent": { "command": "npx", "args": ["-y", "@your/eval-agent"], "env": { "BASE_URL": "https://taotoken.net/api", "API_KEY": "sk-你的eval专用Key", "MODEL_ID": "claude-sonnet-4-20250514" } } } }

这三个配置的共同点是：Base URL 统一指向https://taotoken.net/api，Key 用 eval 专用，Model ID 明确写死。不要用“默认模型”这种模糊配置，否则模型升级时你的 eval 结果会不可比。

3.2 eval 任务定义：task 与 grader 的 YAML 结构

下面是一个 coding agent 的 eval 任务定义，参考了 Anthropic 原文里的结构，但做了工程化精简：

task: id: "fix-auth-bypass_1" desc: "修复密码字段为空时的认证绕过漏洞" 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

这个结构里，graders是打分逻辑，tracked_metrics是观测指标。注意不是每个 grader 都必须用，实际项目里通常以 deterministic_tests 为主，llm_rubric 为辅，static_analysis 和 state_check 按需添加。

3.3 grader 断言策略：代码型、模型型、人工型的分工

Grader 不能只有一种。我的经验是：硬指标用代码，软质量用模型，高风险用人工抽检。

代码型 grader 负责确定性验证：测试是否通过、静态检查是否干净、数据库状态是否变更。这类断言不应该交给 LLM judge，因为 LLM 判断“测试是否通过”本身就是不可靠的。

模型型 grader 负责语义质量：代码可读性、对话语气、报告连贯性。这类判断用 LLM rubric 更合适，但 rubric 本身需要人类专家校准。一个常见的坑是 rubric 写得太模糊，比如“代码质量好”，这种断言不同 judge 模型会给出完全不同的分数。

人工型 grader 负责高风险场景抽检。不是所有任务都需要人工，但涉及资金、权限、安全边界的任务，建议保留人工 review 环节。

对话 Agent 的 grader 配置示例：

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

这里state_check验证最终环境状态，tool_calls验证关键过程，transcript约束对话轮数，llm_rubric评估沟通质量。四个维度合在一起，才能表达“这个对话 Agent 到底做得好不好”。

4. 验证请求与成功结果：跑通第一条 eval 链路

配置写完之后，下一步是验证整条链路能不能跑通。不要一上来就跑全量 eval suite，先用一条最小任务确认 API 通道、agent harness、grader 三部分都正常工作。

4.1 最小验证：单次 API 调用确认通道

先用 curl 确认 TaoToken 通道可用：

curl -X POST https://taotoken.net/api/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-你的eval专用Key" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 128, "messages": [ {"role": "user", "content": "回复 OK 两个字母即可"} ] }'

如果返回里有content字段且文本是OK，说明 Base URL、Key、Model ID 三件套都正确。如果返回 401，检查 Key 是否复制完整；如果返回 model not found，检查 Model ID 是否和控制台列表一致。

4.2 跑通一条 task：从 trial 到 transcript

确认通道后，用 eval harness 跑一条 task。假设你的 harness 是 Python 写的，核心逻辑大概是这样：

import os import json from anthropic import Anthropic client = Anthropic( base_url="https://taotoken.net/api", api_key=os.environ["TAOTOKEN_EVAL_KEY"], ) def run_trial(task): transcript = [] messages = [{"role": "user", "content": task["desc"]}] for turn in range(task.get("max_turns", 10)): response = client.messages.create( model="claude-sonnet-4-20250514", max_tokens=2048, messages=messages, ) transcript.append(response) if response.stop_reason == "end_turn": break messages.append({"role": "assistant", "content": response.content}) return transcript def grade(task, transcript): results = {} for grader in task["graders"]: if grader["type"] == "deterministic_tests": results["tests"] = run_tests(grader["required"]) elif grader["type"] == "llm_rubric": results["rubric"] = judge_with_llm(transcript, grader["rubric"]) elif grader["type"] == "state_check": results["state"] = check_state(grader["expect"]) return results

跑完之后，你会得到一份 transcript 和一组 grader 结果。成功的结果不是“全绿”，而是每个 grader 都返回了明确的 pass/fail 和理由。如果某个 grader 返回unknown或error，说明 grader 本身需要修，不是 agent 的问题。

4.3 看 pass@k 和 pass^k：稳定性比单次成功更重要

Agent 系统有非确定性。同一个 task 跑 10 次，可能 7 次成功、3 次失败。这时候只看一次结果很危险。

pass@k 衡量的是：跑 k 次，只要有一次成功就算成功。这个指标适合“多试几次总能找到答案”的场景，比如代码生成候选方案。

pass^k 衡量的是：跑 k 次，每一次都必须成功。这个指标更适合用户真正关心稳定性的产品场景。

如果一个 Agent 单次成功率是 75%，跑 3 次时，至少一次成功的概率会变高，但连续 3 次都成功的概率只有大约 42%。这就是很多 demo 看起来能用、生产里却不稳定的原因。

在 eval 报告里，建议同时输出这两个指标。只看 pass@k 会高估系统稳定性，只看 pass^k 又可能对探索型任务过于苛刻。

5. 本篇常见错误排查：401、local proxy failed、reading choices、OAuth

这一节列出 Agent eval 接入 TaoToken 时最常见的几类报错，以及对应的排查路径。

5.1 401 Unauthorized：Key 没写对或没注入

报错长这样：

{ "error": { "type": "authentication_error", "message": "invalid x-api-key" } }

排查顺序：第一，确认ANTHROPIC_API_KEY或api_key字段里的 Key 是完整的，没有多余空格；第二，确认这个 Key 是在 https://taotoken.net/api-keys 创建的，且没有过期；第三，确认 CI 环境变量确实注入到了运行 eval 的那个进程里，而不是只写在了.env文件里但没被加载。

一个常见坑是：本地跑通了，CI 里 401。原因通常是 CI 的 secret 名字写错，或者 secret 只在某个 job 里注入，eval job 没继承。

5.2 local proxy failed：Base URL 写错或网络策略拦截

报错通常是：

Error: local proxy failed: connection refused

这个报错的关键词是“local proxy”，说明客户端在尝试走本地代理，但代理没起来。排查方向：第一，确认ANTHROPIC_BASE_URL写的是https://taotoken.net/api，不是http://localhost:xxxx；第二，确认环境变量没有被其他工具的配置覆盖；第三，如果公司网络有出口策略，确认taotoken.net在允许列表里。

注意：这里不要尝试用任何网络代理工具去“绕过”，正确做法是确认 Base URL 配置正确，以及网络策略允许访问目标域名。

5.3 reading choices：响应结构不匹配

报错长这样：

KeyError: 'choices'

或者：

TypeError: Cannot read properties of undefined (reading 'choices')

这个报错说明客户端在按 OpenAI 的响应结构解析，但实际返回的是 Anthropic 格式。TaoToken 同时支持两种协议，但客户端需要和请求协议匹配。如果你用的是 Anthropic SDK，请求会走/v1/messages，返回结构是content数组；如果你用的是 OpenAI SDK，请求走/v1/chat/completions，返回结构才是choices。

排查方法：确认你用的 SDK 和 Base URL 路径匹配。Anthropic SDK 配https://taotoken.net/api即可，OpenAI SDK 需要配https://taotoken.net/api/v1。

5.4 OAuth 相关报错：认证方式不匹配

如果你用的是 Claude Code 或类似工具，可能会遇到：

OAuth token expired or invalid

这是因为工具默认走 OAuth 流程，但你的配置里写的是 API Key。解决方法是在 settings.json 里明确用ANTHROPIC_API_KEY，不要同时保留 OAuth 相关字段。如果工具同时支持两种认证方式，优先用 API Key，因为 eval 环境需要可重复、可脚本化的认证。

5.5 配置检查清单

每次接入新环境时，按这个清单过一遍：

6. 把 eval 变成长期资产：从 capability 到 regression

Agent eval 不是一次性项目，而是长期资产。它很像单元测试，但维护成本更高，因为模型会变、工具会变、产品需求会变、用户行为也会变。

一套健康的 eval suite 应该持续加入新样本：线上真实失败案例、用户投诉和 bad case、新功能对应的能力测试、曾经修过的问题回归测试、高风险业务路径。

当某个 capability eval 已经接近 100% 通过率，它就应该变成 regression eval。也就是说，它不再用来衡量“能不能做到”，而是用来保证“以后别退化”。

这里有个很重要的工程习惯：不要只看分数，要读 transcript。如果分数没提升，可能是 Agent 真不行，也可能是任务写错、grader 写死、环境不稳定。只看 aggregate score，很容易做错判断。

自动化 eval 只是质量体系的一层。上线前用自动化 eval 做快速迭代和回归保护，上线后用生产监控发现真实分布漂移，关键场景人工抽查 transcript 校准 LLM judge，重大改动用 A/B 测试验证真实用户效果。没有任何一层能捕获所有问题，但多层叠加能把漏网概率降到可接受范围。

如果你还在手工测试阶段，建议从 20 到 50 条真实失败或手工测试路径的任务开始。不需要等样本完美，先把已经在手工点的流程固化下来，再逐步覆盖正例和反例。只测“应该搜索时能不能搜索”，会训练出一个什么都搜索的 Agent；也要测“不该搜索时能不能不搜索”。

接入配置上，统一用 TaoToken 的 Base URL 和 eval 专用 Key，把 agent harness、grader、CI 脚本都指向同一条通道。这样当 eval 失败时，你能快速区分是模型行为问题、配置问题，还是测试用例本身的问题。

模型对话调试入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=eval_guide&utm_campaign=rewrite

长期跑 Agent eval 和 coding agent 回归，建议用 Coding Plan 统一管理调用额度：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=eval_guide&utm_campaign=rewrite

接入文档和协议细节：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=eval_guide&utm_campaign=rewrite

Claude Code 接入配置参考：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=eval_guide&utm_campaign=rewrite