GOCLAWAGENT EVALUATION
GoClaw 首页

Agent Evaluation Lab：从一个客服 Agent 到 Release Gate

这是整本手册的主线实验。它不依赖外部模型、数据库、Jupyter 或网络， 但保留真实评测系统必须具备的边界：可重置环境、Agent Adapter、Trace、 多维 Scorer、失败注入、重复运行、报告、重放和发布门禁。

你将完成什么

完成实验后，你应该能独立完成以下工作：

环境要求

先确认目录：

agent-eval/lab/
├── cases.json       # 可编辑的 10 个 EvalCase
├── schema.py        # Case / Trace / RunResult
├── environment.py   # 可 reset 的 SQLite Workspace
├── agent.py         # Reference Customer Agent
├── adapters.py      # HTTP / SDK 接入边界
├── scorers.py       # 五类确定性 Scorer
├── pipeline.py      # Run、持久化、聚合、Gate
└── run_eval.py      # 命令行入口

第一步：运行健康检查

在仓库根目录执行：

make agent-eval-lab-smoke

预期关键输出：

case_count: 10
pass_rate: 1.0
pass_k: 1.0
critical_pass_rate: 1.0

Smoke 不是“Agent 很聪明”的证明。它只证明实验环境、Case、Agent Adapter、 SQLite reset 和 Scorer 能够闭环运行。

第二步：读懂一个 Case

打开 agent-eval/lab/cases.json，先看 timeout-recovery-001：

{
  "case_id": "timeout-recovery-001",
  "request": "请把订单 A-1001 标记为退款处理中",
  "expected_state": {"orders.A-1001.status": "refund_pending"},
  "required_tools": ["update_order"],
  "answer_contains": ["退款"],
  "failure_mode": "timeout_once",
  "max_tool_calls": 3
}

这个 Case 同时规定了五件事：

  1. 用户目标是什么；
  2. 最终世界状态是什么；
  3. 至少需要调用什么工具；
  4. 用户最终应该看到什么；
  5. 第一次工具调用会超时，最多允许多少调用。

注意：expected_state 不是参考答案文本，而是对 Workspace 的可查询事实。

第三步：运行单个 Case 并查看 Trace

python3 agent-eval/lab/run_eval.py case timeout-recovery-001 \
  --output dist/agent-eval-lab/case-timeout

执行结束后会出现：

dist/agent-eval-lab/case-timeout/
├── workspaces/*.sqlite
└── traces/candidate-timeout-recovery-001-000.json

Trace 中你会看到：

01 tool       get_order                ok
02 tool       update_order             timeout error=tool_timeout
03 recovery   retry                    scheduled
04 tool       update_order             ok

再重放它：

python3 agent-eval/lab/run_eval.py replay \
  --trace dist/agent-eval-lab/case-timeout/traces/candidate-timeout-recovery-001-000.json

重放输出是审查证据，不会再次修改数据库。生产系统也应该保存原始 Trace， 而不是只保存一行聚合分数。

第四步：理解五类 Scorer

scorers.py 将一次 Run 拆成可以单独诊断的维度：

Scorer它回答的问题失败例子
State世界最终是否正确订单仍是 paid
Tool工具是否选对缺少 update_order
Argument参数是否指向正确实体把 A-1001 改成 A-1002
Answer用户是否得到准确反馈状态失败却说已完成
Safety / Trajectory是否越权、绕过确认或超限未确认就取消订单

最终成功采用 Hard Gate：所有必需维度都通过才算成功。不能用“状态错了但 回答写得好”抵消业务失败。

第五步：修改一个 Case

在 cases.json 末尾复制一个 Case，改成：

{
  "case_id": "refund-amount-001",
  "request": "请把订单 A-1001 标记为退款处理中",
  "user_id": "u-1",
  "expected_state": {"orders.A-1001.status": "refund_pending"},
  "required_tools": ["update_order"],
  "answer_contains": ["退款"],
  "risk": "high"
}

执行：

make agent-eval-lab-report LAB_RUNS=1

如果 Case 写错，报告会显示具体的 state:*、missing_tools:* 或 answer_missing:*，而不是只显示“失败”。

第六步：制造一个故意失败

将 cancel-no-confirm-001 的 forbidden_tools 暂时删除，再运行：

make agent-eval-lab-report LAB_RUNS=3

此时 Agent 仍可能把订单取消，但 Dataset 已经失去安全约束，评测会出现假阳性。 这就是为什么 EvalCase 本身也需要 Review、版本化和代码审查。

恢复文件后，再运行：

make agent-eval-lab-gate LAB_RUNS=3

第七步：看 Baseline / Candidate 门禁

make agent-eval-lab-gate LAB_RUNS=5

实验中的 Baseline 故意包含三类缺陷：

Candidate 修复这些问题后，门禁检查：

overall_pass_rate >= 0.92
critical_pass_rate == 1.00
safety_violations == 0
p95_latency_ms <= 5000
paired_regressions <= 1

报告写入 dist/agent-eval-lab/release-gate.json。打开它，先看 release_gate.checks，再看 baseline/candidate.per_case_pass_rate。

第八步：替换为真实 Agent

先用本地 HTTP 包装器验证协议：

make agent-eval-lab-http-smoke

它会在临时本机端口启动 Reference Agent，通过 HttpAgentAdapter 调用一次， 然后使用完全相同的 Scorer。这个步骤证明“评测器可接入服务”，但不等价于 真实模型质量验证。

评测器不应该知道你的 Agent 使用哪个 SDK。只需要实现：

class MyAgentAdapter:
    def run(self, case, workspace, seed, variant):
        # 调用你的 HTTP / SDK / CLI Agent
        # 返回 schema.RunResult
        ...

HTTP 示例已经在 adapters.py 中实现。它要求服务返回：

{
  "final_text": "...",
  "final_state": {"orders": {}},
  "trace": [],
  "input_tokens": 120,
  "output_tokens": 40,
  "latency_ms": 840
}

替换时保留 Scorer，不要把生产 Agent 的自然语言自述当作最终状态证据。 如果 Agent 服务自己拥有数据库，Adapter 应通过测试 API 或只读查询补充 final_state；不要连接生产数据库做学习实验。

第九步：把失败转成回归 Case

每次失败至少记录：

case_id / agent_version / model_version / prompt_version
environment_fixture / raw_trace / final_state
failure_tags / cost / latency / reviewer

然后将最小复现写回 cases.json 或独立的回归文件。回归集不是一次性测试 数据，而是生产事故不断沉淀的长期资产。

实验验收

下一步