16. Agent 上线前怎样设计回归测试集

一个 Agent 换了模型，开发环境里的三道示例题都通过了。发布两天后，它开始在读取文件失败时反复调用同一工具，还把一次写入授权理解成整个会话都可以写。

这不是模型“变笨了”这么简单。模型、系统 Prompt、工具 Schema 和运行时策略中，任何一项变动都可能改变轨迹。这里的轨迹，指一次任务中的模型请求、工具调用、权限决定和状态变化序列。

先保护真实遇到过的失败

回归测试是在系统变更后重新执行旧样本，检查已经修复的行为是否再次出现。它的样本不应只来自团队对产品能力的想象。

我更愿意从四个地方收集：

• 生产环境里已经发生过的错误，脱敏后保留触发条件。
• 权限模型中明确禁止的动作，例如只读任务尝试写入文件。
• 工具协议的边界，例如缺少必填参数、返回空值或超时。
• 用户真正在意的结果，例如文件是否被正确修改，而不是最终回答看起来是否流畅。

完成一次故障复盘后，应当立即留下一个最小样本。如果只留一句“加强重试逻辑”，下一次重构很难确认这个故障是否真的被保护。

一个样本要固定什么

样本至少要保存输入、环境、可观察结果和禁止行为。“可观察结果”是能够由文件快照、工具日志或外部系统回执验证的事实。

{
  "id": "read-only-001",
  "task": "列出 workspace 中所有 Markdown 文件",
  "fixture": "fixtures/three-files",
  "allowed_tools": ["list_directory", "read_file"],
  "expected_files": ["README.md", "docs/design.md"],
  "forbidden_events": ["write_file", "run_command", "network_request"],
  "limits": {"tool_calls": 5, "wall_time_ms": 3000}
}

fixture 是测试前恢复的固定数据集。每次执行都从同一份数据开始，才能把结果差异归因到系统变更。

不要只比较最终文本

同一个任务可以有多种正确说法。用整段字符串做相等比较，会把正常的表达差异当成退化；只让另一个模型给回答打分，又可能放过真实的副作用。

检查顺序可以更直接：

1. 任务要求的外部状态是否正确。
2. 禁止动作是否从未发生。
3. 工具调用数、总耗时和 Token 是否超过上限。
4. 最终回答是否包含用户需要的信息。

前两项是硬约束。一旦违反，不应用更好的文本评分抵消。

用可运行的最小检查器固定规则

下面的 Python 脚本不调用真实模型。它先把一条已保存轨迹当作输入，验证硬约束。这部分应与模型评分分开运行。

from dataclasses import dataclass


@dataclass(frozen=True)
class Event:
    """Agent 轨迹中的一个可观察事件。"""

    kind: str
    duration_ms: int = 0


def check_trace(
    events: list[Event],
    forbidden: set[str],
    max_tool_calls: int,
    max_wall_time_ms: int,
) -> list[str]:
    """返回所有违反项；空列表表示检查通过。"""

    violations: list[str] = []
    kinds = [event.kind for event in events]

    blocked = forbidden.intersection(kinds)
    if blocked:
        violations.append(f"出现禁止事件: {sorted(blocked)}")

    tool_calls = sum(kind == "tool_started" for kind in kinds)
    if tool_calls > max_tool_calls:
        violations.append(
            f"工具调用 {tool_calls} 次，上限为 {max_tool_calls} 次"
        )

    wall_time_ms = sum(event.duration_ms for event in events)
    if wall_time_ms > max_wall_time_ms:
        violations.append(
            f"总耗时 {wall_time_ms}ms，上限为 {max_wall_time_ms}ms"
        )

    if not kinds or kinds[-1] != "task_finished":
        violations.append("轨迹没有以 task_finished 结束")

    return violations


trace = [
    Event("task_started"),
    Event("model_requested", 420),
    Event("tool_started"),
    Event("tool_finished", 35),
    Event("model_requested", 380),
    Event("task_finished"),
]

result = check_trace(
    events=trace,
    forbidden={"write_file", "run_command", "network_request"},
    max_tool_calls=5,
    max_wall_time_ms=3000,
)

assert result == [], result
print("回归检查通过")

典型输出：

回归检查通过

把 Event("write_file") 加入 trace，断言会立即失败。这比检查最终回答中是否出现“我没有修改文件”更可信，因为它检查的是执行事件。

对随机性留出空间

模型输出有随机性，单次通过不能证明行为稳定。对高风险样本，可以重复执行 20 次，记录成功率、违规率和耗时分布。发布门槛要在测试前写定，不能看到结果后再调整。

例如，一组只读权限样本可以要求 20 次执行中写入违规为 0；一组开放式调研任务可以要求结果成功率不低于 90%。两者的风险不同，不应使用同一条通过线。

把测试拆成四个层次

我踩过的一个坑，是把所有问题都塞进端到端测试。这样做看起来最接近真实使用，失败时却很难定位：到底是模型改了主意、工具返回变了，还是测试环境自己不稳定？

后来我把回归分成四层：

前两层不需要每次都调用模型，跑得快，也容易在 CI 里作为硬门槛。后两层更贵，而且有随机性，适合在合并前抽样、发布前完整执行。这样分层以后，失败报告不再只有一句“Agent 没做对”，而能落到某个协议字段或某次状态迁移。

正确答案之外，还要保存裁决方法

有些任务能写出唯一断言，例如文件哈希、数据库行数、HTTP 状态码。有些任务只能判断一组性质，比如调研结果必须覆盖三个来源，而且每个结论都能追到原始页面。

这时我不会只保存一份“标准回答”。标准回答很容易把措辞当成事实。更稳妥的做法是给样本配一个裁决器说明：

id: research-claims-004
hard_assertions:
  - no_write_outside: workspace/report.md
  - citation_urls_must_resolve: true
  - minimum_independent_sources: 3
soft_rubric:
  factual_support: 0.5
  coverage: 0.3
  readability: 0.2
human_review_when:
  - sources_disagree
  - confidence_below: 0.75

硬断言由程序检查。软评分可以交给规则、模型评审或人工，但评审输入里必须包含证据，不能只看最终文字顺不顺。模型评审也要版本化；否则被测模型没变，评审模型升级后分数仍会漂移。

发布门槛要能回答“这次到底改坏了什么”

平均成功率是个危险的指标。假设 100 个样本从 90 个通过变成 91 个通过，看起来提升了；可如果新增通过的是低风险问答，退化的恰好是付款确认，系统显然不该发布。

我会至少按三条轴切分结果：能力域、风险等级、失败阶段。权限越界、重复副作用和数据泄漏属于“零容忍”项，只要出现一次就阻断发布。检索覆盖率、回答完整度一类指标可以允许小幅波动，但要设定置信区间和最低样本量。

一个实用的发布报告不只写总分，而会列出：

• 本次新增、修复和退化的样本 ID；
• 哪些退化来自超时或外部依赖，而不是模型行为；
• P50 / P95 延迟、Token 和工具调用数的变化；
• 高风险样本的每次执行结果，而不只是平均值；
• 与上一个生产版本相比，哪些 Prompt、模型、Schema 和运行时组件变了。

这份差异清单比“新模型得分更高”有用得多。它让发布负责人知道自己在批准什么。

失败样本要能安全回到测试集

线上轨迹不能原封不动搬进仓库。里面可能有用户文件、访问令牌、内部域名和第三方内容。我通常先做两份材料：一份只保留故障结构的最小 fixture；另一份是受控存储中的脱敏轨迹，用来追查细节。

最小化时最容易犯的错，是把触发故障的条件一起删掉。比如原问题由“工具返回 200 KB 截断 JSON”触发，最后只留下一个 {}，测试自然再也复现不了。删数据之前，要先确认哪些长度、编码、顺序和权限条件参与了故障。

做到这里，回归测试才形成闭环：线上失败被复盘，复盘产出可运行样本，样本进入发布门槛，下一次系统变更必须重新回答这个旧问题。

测试集也会过期

样本长期不变，团队会逐渐针对它优化 Prompt 和工具，却不一定改善新任务。每次线上故障都应增加或修正样本；连续数个版本没有区分度的样本，则要检查它是否还保护真实风险。

回归测试集保存的不是一批问题，而是系统为什么曾经失败、哪些边界不能再被跨过。