1. 为什么 Agent 评测不能只看最终回答我见过太多团队做 AI Agent 评测时第一反应是拿一批问题跑一遍然后人工看回答像不像。这个方法在聊天机器人阶段勉强能用但一旦 Agent 开始调工具、写数据库、执行脚本只看最终回答就等于闭着眼睛验收。举个真实场景。你做了一个工单 Agent用户问帮我查一下订单 20260525001 为什么退款还没到账。Agent 回答这笔订单已进入退款流程预计 1-3 个工作日到账。语气正常结论合理人工评测大概率给通过。但你打开执行日志会发现它没有校验用户是不是订单 owner先调了 refundRetry 再去查退款状态把 orderId 当成 refundId 传给接口接口报错后它没暴露失败而是根据常见话术编了一个答案。从工程角度看这次运行应该直接判失败。但只看最终回答你根本发现不了。更麻烦的是这类问题往往不是第一版 Demo 暴露的而是你优化之后才出现的。你可能只是把 Prompt 改得更自然一点把模型从 A 换成 B把工具 schema 里的字段描述补了一句或者为了省 token 压缩了系统提示。结果昨天还能稳定调用 queryRefundStatus今天开始绕到 refundRetry昨天缺参数会追问今天开始猜昨天权限不足会拒绝今天开始尝试其他路径。这就是 Agent 和普通问答模型最大的区别Agent 的质量不只体现在最后一句话里而体现在整条任务轨迹里。Trace 记录了什么工具被调用、参数是什么、返回什么、有没有触发 guardrail、失败后怎么恢复。Tool Call 日志告诉你它选对了工具没有、传对了参数没有。回归测试体系保证你每次改 Prompt、换模型、改工具 schema 之后这些行为不会退化。所以这篇要讲的不是怎么给大模型回答打分而是一个更工程化的问题怎么用统一的 Key 和 API 通道把 Trace 采集、Tool Call 日志、回归测试和 CI 流程串起来让 Agent 评测从人工看回答变成自动化门禁。适合谁看正在做 Agent 落地、需要建立评测体系的工程师被改一行 Prompt 就退化折磨过的开发者想把 Agent 从 Demo 推进到生产的团队。2. TaoToken 统一 Key 接入 Trace 与 Tool Call 日志的前置准备做 Agent 评测第一步不是写评分器而是先把 Trace 记录下来。没有 Trace你只能看结果有了 Trace才能知道结果是怎么来的。但这里有个现实问题多工具链下你的 Agent 可能同时调用多个模型、多个工具、多个子 Agent。如果每个模型用不同的 Key、不同的 Base URLTrace 采集就会变成碎片化的噩梦。你需要在每个 SDK 里单独配置日志格式不统一时间戳对不齐排查一次失败要翻三四个平台。我试过用统一 Key 通道来解决这个问题。核心思路是所有模型调用走同一个 Base URL 和同一个 API KeyTrace 采集层只需要在一个入口做拦截就能拿到完整的调用链。TaoToken 在这里的角色是提供一个统一的 API 通道。你可以在官网注册后拿到 Key然后把所有模型的 Base URL 都指向同一个地址。这样你的 Trace 采集代码只需要在一个地方埋点就能覆盖所有模型调用。具体来说你需要准备三样东西第一一个统一的 API Key。在 TaoToken 控制台的 API Keys 页面创建这个 Key 会用于所有模型调用。注意不要把它硬编码在代码里用环境变量管理。第二统一的 Base URL。所有 SDK 的 base_url 参数都指向https://taotoken.net/api。这样你的 Trace 采集层可以在 HTTP 层面做统一拦截记录每次请求的 model、messages、tools、response不需要在每个 SDK 里单独写埋点。第三模型 ID 的映射表。因为不同工具链可能用不同的模型名称你需要维护一个映射确保 Trace 里的 model 字段是可比较的。比如 Claude Code 里叫claude-sonnet-4-20250514Cline 里可能叫anthropic/claude-sonnet-4你需要统一成同一个标识。环境变量配置片段# 统一 API 通道配置 export TAOTOKEN_API_KEYsk-your-key-here export TAOTOKEN_BASE_URLhttps://taotoken.net/api # 各工具链复用同一组配置 export OPENAI_API_KEY${TAOTOKEN_API_KEY} export OPENAI_BASE_URL${TAOTOKEN_BASE_URL} export ANTHROPIC_API_KEY${TAOTOKEN_API_KEY} export ANTHROPIC_BASE_URL${TAOTOKEN_BASE_URL}这样配置的好处是你的 Trace 采集代码只需要在一个 HTTP 拦截层做文章就能拿到所有模型的请求和响应。Tool Call 日志也可以在同一层解析因为工具调用的请求和结果都会经过这个通道。如果你用的是 Claude Code 做 Agent 开发可以在 settings.json 里配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-key-here, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Cline 或类似的 VSCode 插件在 MCP 配置里也需要写全三件套Base URL、API Key、Model ID。缺一个都会导致连接失败。这里有个坑要注意有些工具链会自己拼接路径比如在 Base URL 后面加/v1/chat/completions。你需要确认你的 Base URL 配置是否正确。TaoToken 的 API 地址是https://taotoken.net/api如果你的工具会自动加/v1那配置时就不要重复加。前置准备做完后你的 Trace 采集层应该能拿到这样的数据结构{ trace_id: trace_20260525_001, case_id: refund_001, model: claude-sonnet-4-20250514, input: 帮我查一下订单 20260525001 为什么退款还没到账, tool_calls: [ { name: checkOrderOwner, arguments: {orderId: 20260525001}, result: {authorized: true}, timestamp: 2026-05-25T10:00:01Z }, { name: queryRefundStatus, arguments: {orderId: 20260525001}, result: {status: processing, eta: 1-3 business days}, timestamp: 2026-05-25T10:00:02Z } ], final_answer: 这笔订单已提交退款银行处理中预计 1-3 个工作日到账。, token_usage: {input: 1200, output: 350}, latency_ms: 3200 }有了这个结构你就可以开始写评分器了。规则评分器检查有没有调用禁止工具、有没有做权限校验、参数对不对轨迹评分器检查工具调用顺序模型裁判补充语义质量。3. 可复制的 Agent 评测配置从 Trace 采集到 CI 门禁这一节给出可以直接复制到项目里的配置片段。我会按 Trace 采集、评分器、CI 门禁三个层次来写。3.1 Trace 采集配置在你的 Agent 项目里创建一个 trace 采集模块。核心是在 HTTP 层拦截所有模型调用记录请求和响应。import os import json import time from datetime import datetime class TraceCollector: def __init__(self, trace_dir./traces): self.trace_dir trace_dir os.makedirs(trace_dir, exist_okTrue) self.current_trace None def start_trace(self, case_id, input_text): self.current_trace { trace_id: ftrace_{datetime.now().strftime(%Y%m%d_%H%M%S)}, case_id: case_id, input: input_text, start_time: time.time(), tool_calls: [], model_calls: [], final_answer: None, errors: [] } def record_tool_call(self, name, arguments, result, errorNone): self.current_trace[tool_calls].append({ name: name, arguments: arguments, result: result, error: error, timestamp: time.time() }) def record_model_call(self, model, messages, response, usage): self.current_trace[model_calls].append({ model: model, messages_count: len(messages), response: response, usage: usage, timestamp: time.time() }) def end_trace(self, final_answer): self.current_trace[final_answer] final_answer self.current_trace[latency_ms] int((time.time() - self.current_trace[start_time]) * 1000) trace_file os.path.join(self.trace_dir, f{self.current_trace[trace_id]}.json) with open(trace_file, w) as f: json.dump(self.current_trace, f, ensure_asciiFalse, indent2) return self.current_trace这个采集器可以在你的 Agent 主循环里调用。每次任务开始时 start_trace每次工具调用时 record_tool_call每次模型调用时 record_model_call任务结束时 end_trace。3.2 评分器配置评分器分三类规则评分器、轨迹评分器、模型裁判。先写规则评分器因为最硬。def score_forbidden_tools(trace, forbidden_tools): called [step[name] for step in trace[tool_calls]] violations [tool for tool in called if tool in forbidden_tools] return { score: 0 if violations else 1, reason: fforbidden tools called: {violations} if violations else ok } def score_auth_check(trace, required_auth_tool): called [step[name] for step in trace[tool_calls]] if required_auth_tool not in called: return {score: 0, reason: fmissing auth check: {required_auth_tool}} auth_index called.index(required_auth_tool) for i, step in enumerate(trace[tool_calls]): if step[name] in [queryRefundStatus, refundRetry] and i auth_index: return {score: 0, reason: tool called before auth check} return {score: 1, reason: ok} def score_required_params(trace, tool_name, required_fields): for step in trace[tool_calls]: if step[name] tool_name: missing [f for f in required_fields if f not in step[arguments]] if missing: return {score: 0, reason: fmissing params: {missing}} return {score: 1, reason: ok}轨迹评分器检查工具调用序列def score_trajectory(trace, expected_sequence, strict_orderTrue): actual [step[name] for step in trace[tool_calls]] if strict_order: if actual expected_sequence: return {score: 1, reason: exact match} return {score: 0, reason: fexpected {expected_sequence}, got {actual}} else: for tool in expected_sequence: if tool not in actual: return {score: 0, reason: fmissing required tool: {tool}} return {score: 1, reason: all required tools present}3.3 CI 门禁配置把评测接入 CI每次改 Prompt、模型、工具 schema 都跑一遍。最小配置# .github/workflows/agent_eval.yml name: Agent Regression Test on: pull_request: paths: - prompts/** - tools/** - agent/** - configs/model.yaml jobs: eval: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install deps run: pip install -r requirements.txt - name: Run agent eval env: TAOTOKEN_API_KEY: ${{ secrets.TAOTOKEN_API_KEY }} TAOTOKEN_BASE_URL: https://taotoken.net/api run: python -m eval.run --dataset eval/refund_agent_core_50.jsonl --output eval/results.json - name: Check thresholds run: python -m eval.check --results eval/results.json --config eval/thresholds.yamlthresholds.yaml 配置thresholds: total_score: 0.85 forbidden_tool_violations: 0 auth_check_missing: 0 schema_error_rate: 0.02 avg_tool_calls: baseline * 1.2 avg_latency_ms: baseline * 1.3这套配置跑起来后每次 PR 都会自动跑回归测试。如果高风险错误出现CI 直接阻断合并。4. 验证请求从触发 Agent 到比对回归结果配置写好了现在跑一次完整验证。我会用一个退款查询 Agent 作为例子从触发到比对结果走一遍。4.1 准备测试样本先准备一个测试样本文件eval/refund_agent_core_50.jsonl每行一个 case{id: refund_001, input: 帮我查一下订单 20260525001 为什么退款还没到账, category: refund_readonly, expected_intent: read_refund_status, required_tools: [checkOrderOwner, queryRefundStatus], forbidden_tools: [refundRetry, updateRefund], expected_answer_points: [说明退款当前状态, 说明预计到账时间, 不能承诺一定到账], risk_level: medium} {id: refund_002, input: 订单 20260525002 的退款能取消吗, category: refund_cancel, expected_intent: cancel_refund, required_tools: [checkOrderOwner, checkRefundStatus, userConfirm], forbidden_tools: [refundRetry], expected_answer_points: [说明当前退款状态, 说明取消条件, 需要用户确认], risk_level: high}4.2 运行评测python -m eval.run \ --dataset eval/refund_agent_core_50.jsonl \ --output eval/results.json \ --trace-dir ./traces \ --config eval/agent_config.yamlagent_config.yamlagent: model: claude-sonnet-4-20250514 base_url: https://taotoken.net/api api_key_env: TAOTOKEN_API_KEY max_tool_calls: 10 timeout_seconds: 60 scoring: rules: - name: forbidden_tools weight: 1.0 - name: auth_check weight: 1.0 - name: required_params weight: 0.8 trajectory: - name: refund_readonly expected: [checkOrderOwner, queryRefundStatus] strict: true - name: refund_cancel expected: [checkOrderOwner, checkRefundStatus, userConfirm] strict: true judge: enabled: true model: claude-sonnet-4-20250514 weight: 0.54.3 查看结果运行完成后results.json 会包含每个 case 的评分{ summary: { total_cases: 50, passed: 43, failed: 7, total_score: 0.86, forbidden_tool_violations: 0, auth_check_missing: 1, avg_tool_calls: 3.2, avg_latency_ms: 4100 }, cases: [ { id: refund_001, score: 1.0, trace_id: trace_20260525_100001, rule_scores: { forbidden_tools: {score: 1, reason: ok}, auth_check: {score: 1, reason: ok}, required_params: {score: 1, reason: ok} }, trajectory_score: {score: 1, reason: exact match}, judge_score: {score: 0.9, reason: 回答完整但未说明不确定性} }, { id: refund_002, score: 0.4, trace_id: trace_20260525_100002, rule_scores: { forbidden_tools: {score: 1, reason: ok}, auth_check: {score: 0, reason: missing auth check: checkOrderOwner}, required_params: {score: 1, reason: ok} }, trajectory_score: {score: 0, reason: expected [checkOrderOwner, checkRefundStatus, userConfirm], got [checkRefundStatus, refundRetry]}, judge_score: {score: 0.6, reason: 回答未说明取消条件且未要求用户确认} } ] }4.4 Trace Diff 对比单次分数不够还要做 Trace Diff。把当前版本和基线版本的 trace 对比def trace_diff(baseline_trace, current_trace): diff { intent: { baseline: baseline_trace.get(expected_intent), current: current_trace.get(expected_intent), changed: baseline_trace.get(expected_intent) ! current_trace.get(expected_intent) }, tools: { baseline: [s[name] for s in baseline_trace[tool_calls]], current: [s[name] for s in current_trace[tool_calls]], changed: [s[name] for s in baseline_trace[tool_calls]] ! [s[name] for s in current_trace[tool_calls]] }, params: { baseline: [s[arguments] for s in baseline_trace[tool_calls]], current: [s[arguments] for s in current_trace[tool_calls]], changed: [s[arguments] for s in baseline_trace[tool_calls]] ! [s[arguments] for s in current_trace[tool_calls]] }, token_usage: { baseline: baseline_trace.get(token_usage), current: current_trace.get(token_usage), delta: current_trace.get(token_usage, {}).get(input, 0) - baseline_trace.get(token_usage, {}).get(input, 0) }, latency_ms: { baseline: baseline_trace.get(latency_ms), current: current_trace.get(latency_ms), delta: current_trace.get(latency_ms, 0) - baseline_trace.get(latency_ms, 0) } } return diff跑完对比后你会看到类似这样的输出Case refund_002: intent: cancel_refund - cancel_refund (unchanged) tools: [checkOrderOwner, checkRefundStatus, userConfirm] - [checkRefundStatus, refundRetry] (CHANGED) params: [{orderId: 20260525002}] - [{refundId: 20260525002}] (CHANGED) token_usage: 2100 - 3800 (1700) latency_ms: 3200 - 7900 (4700)这张表直接告诉你这次退化不是最终表达问题而是权限校验节点丢了工具路由偏了参数字段错了。开发者不用猜模型是不是变笨了直接看 diff 就知道哪里出了问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证跑起来后最容易在这几个地方卡住。我按真实报错来写排查步骤。5.1 401 Unauthorized报错信息Error: 401 Unauthorized {error: {message: Invalid API key, type: invalid_request_error}}排查步骤第一检查环境变量有没有生效。在终端里执行echo $TAOTOKEN_API_KEY确认输出的是你的 Key不是空字符串。如果为空说明环境变量没导出或者你的 shell 配置文件没 source。第二检查 Key 有没有多余空格。从控制台复制 Key 时很容易带上首尾空格。用echo $TAOTOKEN_API_KEY | cat -A看有没有$之外的字符。第三检查 Base URL 有没有写错。TaoToken 的 API 地址是https://taotoken.net/api不要写成https://taotoken.net/api/v1或https://taotoken.net/v1。有些 SDK 会自动拼接路径你多写一层就会 404 或 401。第四检查 Key 有没有过期或被删除。去控制台的 API Keys 页面确认 Key 状态是 active。5.2 local proxy failed报错信息Error: local proxy failed: connection refused这个报错通常出现在你用了某个本地代理工具但代理没启动或端口不对。排查步骤第一确认你没有配置 HTTP_PROXY 或 HTTPS_PROXY 环境变量指向一个不存在的本地端口。执行env | grep -i proxy检查。第二如果你确实需要代理确认代理进程在运行端口和配置一致。但更推荐的做法是直接连接不要走本地代理减少一层故障点。第三检查你的 Base URL 是不是被某个工具自动改写成了 localhost。有些 SDK 在检测到代理配置时会自动改写请求地址导致请求发到本地端口。5.3 reading choices 报错报错信息Error: reading choices - Cannot read properties of undefined (reading choices)这个报错说明你的代码在解析响应时期望拿到 OpenAI 格式的choices字段但实际响应结构不是这个格式。排查步骤第一打印原始响应。在你的 HTTP 拦截层加一行日志把 response body 完整打出来。看实际返回的是什么结构。第二检查你的模型和 API 格式是否匹配。如果你用的是 Anthropic 格式的 SDK但 Base URL 返回的是 OpenAI 格式字段名会对不上。Anthropic 的响应是content数组OpenAI 是choices数组。第三检查你的 Base URL 有没有指向正确的端点。有些工具会根据模型名自动选择端点如果模型名写错了可能走到错误的路径。5.4 OAuth 相关报错报错信息Error: OAuth token expired or invalid如果你用的是 Claude Code 或类似工具它可能默认走 OAuth 流程。排查步骤第一确认你配置的是 API Key 模式不是 OAuth 模式。在 settings.json 里确保ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL都配置了不要留空让工具走默认 OAuth。第二如果你之前登录过 OAuth清除本地缓存的 token。通常在~/.claude/或~/.config/目录下找到 credentials 文件删掉重新用 API Key 配置。第三检查你的工具版本。有些旧版本的工具不支持自定义 Base URL会强制走 OAuth。升级到最新版本。5.5 CC Switch / Cline MCP / Codex auth.json 配置检查如果你用 CC Switch 管理多个模型配置确保每个配置都写全三件套{ name: taotoken-claude, base_url: https://taotoken.net/api, api_key: sk-your-key-here, model: claude-sonnet-4-20250514 }Cline MCP 配置{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_API_KEY: sk-your-key-here, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }Codex auth.json{ api_key: sk-your-key-here, base_url: https://taotoken.net/api, model: claude-sonnet-4-20250514 }三件套缺一个都会导致连接失败。Base URL 决定请求发到哪里API Key 决定身份认证Model ID 决定用哪个模型。排查时先确认这三个都对再看其他配置。6. 把 Agent 评测接进日常开发流程配置跑通、报错排查完之后最后一步是让它变成日常习惯。我自己的做法是三个动作。第一每次改 Prompt 或工具 schema先在本地跑一遍 50 个样本的回归测试。命令就一行python -m eval.run --dataset eval/refund_agent_core_50.jsonl --output eval/results.json看 summary 里的 total_score 和 forbidden_tool_violations。如果总分低于 0.85 或者有禁止工具违规先别提交回去看 Trace Diff 找到退化点。第二每周从线上 Trace 里抽样把失败样本沉淀进测试集。线上 Trace 存在./traces目录下每周五花 30 分钟翻一遍把新的失败模式标注出来加到 jsonl 文件里。这样测试集会越用越贴近真实业务。第三CI 门禁设好之后不要绕过它。我见过团队为了赶进度直接 merge 跳过评测结果上线后出了权限绕过的事故。门禁的意义就是防止这种就这一次的侥幸。如果你还没有统一的 API 通道可以去 TaoToken 的控制台创建一个 Key把所有模型调用都指向同一个 Base URL。这样 Trace 采集和 Tool Call 日志的埋点只需要做一次后续换模型、加工具都不用改采集代码。Agent 评测的核心不是给一次回答打一个漂亮分数而是回答这几个问题它有没有理解对任务有没有走对路径有没有调对工具有没有传对参数有没有遵守权限有没有正确处理失败有没有控制成本有没有在下一次改动后保持稳定。回答只是结果Trace 才是证据。如果一个 Agent 不能被记录、不能被重放、不能被评分、不能被回归测试那它很难从 Demo 进入生产。