Agent 回归测试的困境：场景包与集成层的工程教训

我以为难点在于评分。

写干净的 YAML。定义预期行为。运行智能体。比较分数。捕捉回归。满怀信心地发布。

这个思维模型在实际智能体现场测试了一个下午就崩塌了。

出问题的地方不是评判器。不是评分标准设计。而是意识到一个场景包的可信度，取决于你的测试工具和一个真实的、混乱的、第三方智能体之间路径的诚实程度——那个智能体在模块作用域就导入 ffmpeg，硬编码 gpt-3.5-turbo，一旦你碰它就往 /root 写文件。

这是关于 EvalForge 的系列第二篇文章，EvalForge 是一个用于工具型 AI 智能体的开源评测工具。第一篇文章论证了智能体评测是一个不同于模型评测的问题，因为路径重要，不只是答案。发布文章是智能体代码公开后教会我的那些真实经验的长故事。这一篇更聚焦：我构建的场景包、基线和评分这三件具体的事，以及最先坏掉的那一件。

场景包是一份契约，不是一个测试文件

在讲哪里出问题之前，我需要展示我实际构建了什么，因为包格式中的设计决策才是工程所在。

这是发布包中的一个场景。二十个之一。它看起来很干净。确实干净：

# scenarios/core-launch.yaml — launch-01-account-policy
# https://github.com/deghosal-2026/agent-eval-forge/blob/main/scenarios/core-launch.yaml
- id: "launch-01-account-policy"
  title: "Account policy lookup"
  goal: "Retrieve a specific policy detail using one tool call"
  input: "What is the return policy for premium customers?"
  allowed_tools:
    - name: "policy_lookup"
  disallowed_tools: []
  expected:
    type: exact
    value: "Premium customers receive a 60-day return window with free return shipping."
  metrics:
    task_completion: {threshold: 1.0}
    output_correctness: {threshold: 0.8}
    tool_correctness: {threshold: 1.0}
    step_efficiency: {threshold: 0.7}
  tags: [retrieval, single-tool]
  difficulty: easy
  budget: {max_steps: 3, max_tokens: 300}

v0.1 发版了二十个场景，分布在十个家族中：单工具检索、多工具综合、结构化提取、工具参数精度、拒绝、歧义澄清、预算约束、失败恢复、编码智能体回归，以及分类。安全方向再加八个：提示注入、数据泄露、SSRF、沙箱逃逸。

架构很直接：CLI 通过核心运行器运行场景包。运行器委托给适配器。适配器与智能体通信。评分器评估轨迹。评判器填补语义空白。差异引擎将结果与保存的基线进行对比。

ground-truth 边界

场景包格式中最重要的设计决策在 YAML 里是看不到的。它是智能体永远看不到的东西。

expected 和 metrics 字段仅供评测使用。它们在智能体收到任何内容之前就被剥离了。适配器基类中的 build_invocation_payload 函数是执行点：

# src/evalforge/adapters/base.py — build_invocation_payload
def build_invocation_payload(scenario: Scenario, run_id: str) -> dict[str, Any]:
    return {
        "schema_version": "evalforge.invocation_payload.v1",
        "run_id": run_id,
        "scenario_id": scenario.id,
        "input": scenario.input,
        "context": scenario.context,
        "allowed_tools": [tool.model_dump() for tool in scenario.allowed_tools],
        "disallowed_tools": [tool.model_dump() for tool in scenario.disallowed_tools],
        "budget": scenario.budget.model_dump() if scenario.budget else {},
    }

注意这个字典里没有的东西。没有 expected。没有 metrics。没有 threshold。没有 goal。智能体收到 input、工具界面和一个预算。它拿不到答案。因为看不到，所以无法作弊。

这不是便利性设计——这是正确性边界。如果 ground truth 泄露到智能体的上下文中，每一个分数都值得怀疑。Scenario 模型在文档字符串中明确记录了这一点："expected/metrics 仅供评测使用，绝不发送给智能体。" Baseline 模型和 ComparisonEngine 都依赖于这个边界的维持。如果它破了，回归故事也就跟着破了。

同一个文件中还有第二个边界，它是那种没人会提、直到咬你一口才会意识到的东西。_sanitize_agent 函数在把适配器配置写入运行产物之前，会从中剥离 API 密钥和令牌。在适配器配置中传入 api_key——它永远不会到达产物存储。 Secrets 不会持久化。我愿意称之为功能，仅仅是把它叫作功能意味着它是可选的。它不是。

第三个：适配器解析智能体输出时，一个"已完成"但没有任何输出的运行会被视为错误，而不是通过。_artifact_from_envelope 中的注释很直接："空完成通常意味着入口点已死或工具结果为空，绝不能算作通过。" 空完成是穿着通过 costume 的失败。测试工具拒绝统计它。

这三个边界——ground-truth 剥离、密钥清理、空完成拒绝——如果我不得不从头重建，我会为保留它们而抗争。其他一切都可以商量。这些不行。

如果你正在构建一个评测工具，我想知道：你的 ground-truth 边界在哪里？是在一个函数中强制执行的，还是依赖于每个适配器都记得做正确事情的约定？

适配器问题在评分还没跑之前就开始了

然后我从 GitHub 采购了 19 个开源智能体——11 个 LangGraph、8 个 PydanticAI——使用了星级桶策略。高星仓库代表成熟度信号，中等星级代表真实世界的混乱，低星级用于看工具在混乱代码库中是否添加任何信号。采购方法记录在 docs/hard-won-lessons.md 中。

九次通过。95 个场景-智能体组合中。

不是每个智能体九次。是总共九次。

看到九次通过时的本能反应是怪罪评判器。换掉 gpt-4o-mini 用 gpt-4o。调优评分标准。加更多评分维度。

我在两个评判层级上跑了相同的通过——gpt-4o-mini（便宜）和 gpt-4o（更好）。两次结果一样。九次通过。更贵的评判器没有发现一个更便宜的评判器遗漏的回归或改进。瓶颈根本不在评分层。

瓶颈在于测试工具能否先跑起这个智能体。

五种真实智能体破坏适配器的方式

我在 hard-won lessons 文件中记录了这些，但这些是实际遇到的模式：

导入时绝对路径写入。 几个智能体在它们的 __init__.py 里就往 /root/something 写东西。测试工具运行在一个锁定的沙箱中。导入在任何评测代码执行之前就失败了。修复方案不太优雅：重定向 HOME、TMPDIR 和 XDG_CACHE_HOME 到每个智能体专属的 .cache 目录。仍然写绝对路径的智能体被隔离了。

网关绑定导入。 多个智能体在模块作用域做 ChatOpenAI(api_key=os.getenv("OPENAI_API_KEY"))。如果密钥缺失，模块本身就会抛出异常。你没法导入它。你没法评测它。变通方案是为本地层级注入虚拟 env 变量。需要真实网关连接性的智能体被隔离，不参与本地运行。

硬编码模型名。 在模块作用域写 ChatOpenAI(model="gpt-3.5-turbo")。我把 OPENAI_BASE_URL 指向运行 Qwen3.5-9B-MLX-4bit 的本地 OMLX 服务器。智能体仍然请求 gpt-3.5-turbo。OMLX 不提供那个模型。404。修复方案是在智能体模块导入之前用 monkeypatch 替换 ChatOpenAI.__init__——我吃足了苦头才知道 Pydantic v2 字段默认补丁对此无效。必须是 __init__。必须在 import 之前运行。

Typed StateGraph 没有聊天界面。 一些 LangGraph 智能体使用带内部域状态字段的 typed StateGraph。测试工具发送聊天消息。智能体期望的是带类型键的 AgentState。没有桥接。我不得不为每个智能体写薄的 evalforge_wrapper.py 模块来做翻译。这不是测试工具的 bug。是设计差距：测试工具假设了一个消息界面，而 typed-graph 智能体不暴露这个界面。

导入时数据库引导。 在模块作用域做 create_async_engine(DATABASE_URL) 和 FAISS.load_local(...)。测试工具不应该为一个智能体的整个基础设施引导打补丁。我学会了按导入时副作用对智能体分类——无基础设施、需要 DB/keys/files、需要运行中服务器——然后跳过我无法本地运行的那些。继续。不要和数据库较劲。

我得到的教训是：场景包在测试你的适配器之前先测试你的智能体。如果测试工具无法忠实地运行一个随机的第三方智能体，那我测量的信号其实是集成摩擦，而不是智能体质量。摩擦是真实的，值得测量。只是不是一回事，把它们混为一谈是团队发布他们实际并不理解的智能体的方式。

如果我重新构建会怎么做不同

目前这个测试工具将 AI 智能体分为三个层级——本地、Docker、隔离——然后继续执行。这种分类对于第一轮筛选是有效的，但掩盖了一个真正的架构选择。

现在默认的适配器会将 AI 智能体代码直接导入测试工具进程内。python_import 适配器承担导入工作，isolated 适配器将其包装在子进程中以提供一定的安全性。但边界本质上仍然是"共享 Python 进程"。

一个更清晰的设计应该是：测试工具永不直接导入 AI 智能体代码。它始终通过严格的 stdin/stdout 契约进行通信。子进程适配器已经存在并且已经以这种方式工作。每个 AI 智能体都有一个良好定义的协议：invoke(input, tools, budget) → trajectory。测试工具不关心 AI 智能体使用什么语言编写、导入了什么内容、或向磁盘写入了什么。

基于导入的适配器在最初的 19 个 AI 智能体上接线更快。我本应该从一开始就将子进程边界作为唯一正确的路径，并将基于导入的适配器作为对已信任进程的 AI 智能体的选择性优化。

这是我一直在反复思考的问题：测试工具是否应该与被测对象共享进程？还是进程隔离是诚实度量的最低门槛？我倾向于隔离，但我想听听任何做过相反权衡的人的经验。

基线问题（这才是回归测试真正存在的地方）

一旦适配器运行，你就有了轨迹产物。现在你需要对比版本。

我在大多数评估设置中看到的默认方法是隐式的。运行新版本。它产生分数。用肉眼观察数字。做出决定。没有显式的基线。没有结构化的 diff。只有最新的 JSON 文件和你的直觉。

假设你的 AI 智能体在 20 个场景中得分为 0.92。不错。可以发布。下周你改了提示词。平均分降到 0.89。仍然不错。再次发布。又进行了两次提示词修改后，平均分为 0.84。每次个别下降都很小。没有单一变化触发警报。但从 0.92 到 0.84 的累积漂移是真实存在的，而"以最后运行结果为准"的策略永远捕捉不到它，因为参考点不断在重置。

EvalForge 采用相反的方法：显式黄金基线。你显式保存一个基线，并在此之前一直以它为基准评判一切，直到你有意提升一个新基线：

evalforge run --pack core-launch.yaml --agent python:my_agent.py
evalforge baseline save --name v1.3.0 --run .evalforge/runs/latest

基线模型捕获的不仅仅是分数。它快照完整的产物集、冻结的分数状态、git SHA、AI 智能体元数据和信任级别。当你进行对比时，你是在与一个已知良好的参考进行比较，而这个参考可以追溯到确切的源代码：

@dataclass
class Baseline:
    name: str                # "v1.3.0"
    pack: str                # "core-launch-pack"
    pack_version: str        # "1.2.0"
    runs: list[RunArtifact]  # One artifact per scenario
    score_snapshot: dict     # Frozen scores for fast CI comparison
    agent: dict              # Framework, version, model
    git_sha: str | None      # Traceable to exact source
    created: str             # ISO-8601

三级对比

ComparisonEngine 在三个层级上进行对比。

按场景。回归的定义是狭义的：基线是"通过"而候选版本不是"通过"。如果某个场景已经失败，新版本不能对其"回归"。这是一个深思熟虑的产品决策。引擎的工作是发布门控。它问一个问题：这次变更是否让目前正常工作的东西停止工作了？

# src/evalforge/comparison/engine.py — the regression classification
"regressed": (
    base_ss is not None and cand_ss is not None
    and base_ss.status == "passed" and cand_ss.status != "passed"
),
"improved": (
    base_ss is not None and cand_ss is not None
    and base_ss.status != "passed" and cand_ss.status == "passed"
),
"new_failure": (
    base_ss is None and cand_ss is not None and cand_ss.status != "passed"
),

按家族。场景被打上标签：检索、安全、多工具、综合。引擎按标签分组 delta。如果安全家族下降了 0.15 而检索家族上升了 0.18，那么总体 +0.03 的 delta 是没有意义的。汇总数字是给仪表盘看的。家族细分才是用于做决策的。

按包。总计数：回归、改善、不变、新失败、新通过。加上基线运行和候选运行之间的美元成本 delta。

存在两种对比模式。快照模式将保存的基线分数与候选分数进行比较——不需要新的 judge 调用，快速且对 CI 友好。重新评分模式在基线和候选产物上重新运行 judge。当你怀疑基线分数已过期或 judge 模型发生变化时使用重新评分。快照是务实的默认选择，因为它避免了 CI 中的 token 成本。

我需要指出按场景定义中的一个微妙之处我想提出来讨论：一个已经失败的场景不能"回归"。它只能保持失败或改善。这意味着一个导致失败场景以不同方式失败的版本变更——比如说，从超时变成幻觉——在对比中显示为"不变"。这是正确的做法吗？我认为对于发布门控来说是这样，因为发布问题是"有没有正常工作的东西坏掉了？"而不是"有没有坏掉的东西换了种方式坏？"但我可以理解将失败模式变化单独跟踪的论点。如果你有意见，我想听听。

评分：确定性优先，只在必要时使用 Judge

当适配器让我感到沮丧时，评分设计比我预期的更稳健。以下是它包含的内容——以及它有意不做什么。

v0.1 版本附带 17 个确定性评分器。它们是免费的、可重现的，并且在每个产物上运行。ToolCorrectnessScorer 计算对已知工具调用的比例。ZeroDisallowedActionsScorer 检查是否调用了禁止的工具——并返回 blocking=True，无论答案质量如何都强制该场景失败。这是一个安全决策，而不是评分的便利设计。

两个指标使用混合 gate+judge 策略：policy_adherence 和 retry_discipline。确定性 gate 首先运行。如果通过，跳过昂贵的 LLM 调用。如果失败，升级到 judge。Judge 结果按场景 ID、judge 模型和产物哈希进行缓存，这样相同的输入不会在多次运行中被重新评判。

退出码层次结构编码在 ScoringEngine._resolve_exit_code 中：

# src/evalforge/scoring/engine.py — _resolve_exit_code
def _resolve_exit_code(self, scenario_scores, safety_violations):
    if safety_violations:
        return 4   # Safety — always blocking, highest priority
    if judge_errors:
        return 3   # Judge failure (API timeout, etc.)
    if any(ss.status != "passed" for ss in scenario_scores.values()):
        return 1   # Standard failure
    return 0        # Clean pass

安全违规是退出码 4，优先级最高，覆盖一切。Judge 错误是 3。标准失败是 1。干净通过是 0。如果 AI 智能体调用了禁止的工具，答案正确与否无关紧要。流水线会被阻塞。没有阈值协商的空间。

评分层明确不做自动优化、不在生产环境运行、不承诺覆盖率。20 个场景可以捕捉明显的回归。它们不能捕捉每种失败模式。没有任何离线评估可以。

评分层有一个我想提出的设计张力：WARN 频段。分数超过阈值是 PASS。超过阈值的 0.7 倍是 WARN。低于这个是 FAIL。WARN 频段的存在是为了在近失误变成回归之前捕捉它们。但 WARN 在 CI 中默认不会阻塞——退出码 1 只在实际失败时触发。所以一个从 0.95 降到 0.72（刚好在 0.7 WARN 截止线上方）的场景在比较引擎中显示为"通过"，因为基线和候选都有"通过"状态。回归对发布门控是不可见的。这可以接受吗？我认为 WARN 级别的漂移应该在比较报告中可见，即使它不会阻塞。目前还没有。这是需要填补的空白。

什么能让这个系统更稳健

EvalForge v0.1 可以工作。它运行、评分、对比、门控。但"可以工作"和"稳健"是不同的标准。以下是我知道的差距，大致按关闭每个差距能在多大程度上改变我对系统的信任程度排序。

将失败分类法接入比较报告。src/evalforge/analytics/ 中的分类法已经将失败分类到桶中——safety_violation、hallucination、tool_error、budget_exceeded、agent_crash。它只是没有连接到比较引擎。所以 regressed: true 是一个没有诊断的信号。我希望系统生成的句子是："场景 launch-06-disallowed-tool 回归了，因为新提示词导致 AI 智能体调用了 delete_customer——这是一个之前它会避免的禁止工具。"这个功能还没有构建。应该是我要添加的第一件事。

轨迹步级评分。评分在场景级别报告。你知道某个场景发生了回归，但不知道是智能体决策序列中的哪一步导致的。步级评分能让回归诊断更快。它也会让失败分类更精确——"第 3 步调用了错误的工具"比"工具正确性下降"更具可操作性。

将子进程适配器设为默认。导入式适配器很方便，但它们与智能体共享进程。这意味着一个发生段错误的智能体也会拖垮测试工具链。一个写入 sys.path 的智能体会污染测试工具链的导入状态。子进程适配器可以避免所有这些问题。它应该是默认选项，而不是可选的。

精确测量评判成本。scoring/engine.py 中的成本表使用的是提供商页面的估算价格。来源被标记为"估算"，因为尚未从评判 SDK 获取 token 使用量。改为精确测量成本是一个小改动但信号价值高——它会使比较引擎中的成本 delta 报告从近似值变为可信值。

CI 中的包版本漂移检测。Baseline 模型在保存时捕获 pack_version。BaselineStore.validate() 方法会在包版本不一致时发出警告。但该检查尚未接入 CI 退出码路径。如果你修改了包但忘记重新建立基准线，比较会静默地针对一个过时的包版本运行。这应该是一个硬失败，而不是警告。

将重运行方差作为一等指标。一个在相同输入上走完全不同路径的智能体，比路由稳定的智能体更难信任。目前测试工具链每次只运行一个场景。运行每个场景 N 次并报告方差，会暴露出单次运行评分遗漏的不稳定性。这是我最想添加但尚未实现的指标。

适配器真实性、金色基准线、多维评分。它们看起来像三个独立的功能。但它们是同一个问题的三个层次：让智能体评估足够诚实，以支撑发布决策。

适配器决定了你是否在测试真实的智能体，而不是一个经过 sanitized 的导入。基准线决定了你是否在比较一个已知的良好参考，而不是一个移动目标。评分层决定了你是否在测量工具纪律、安全性、成本和轨迹——而不仅仅是最终答案。 ground-truth 边界决定了智能体能否对看不见的东西进行博弈。

失去其中任何一个，你拥有的只是一个仪表盘。保持所有，你拥有的才是一个发布关卡。

EvalForge v0.1 已经全部实现，但适配器层仍然是最薄弱的环节——九次通过 / 95 次总次数，说明集成差距是真实存在的。评分层和基准线层在成熟度上领先于适配器。这不是我进去之前预测的顺序。干净的故事版本中，评分是难题。实际构建过程否定了这个假设。

你希望接下来往哪个方向发展？

我仍在积极构建这个系统，随着系统变得越来越真实，决策也变得越来越困难。三个方向，选一个：

适配器真实性——评估工具链是否应该与它评估的智能体共享进程？还是子进程隔离是最低门槛？你在基于导入与基于子进程的适配器方面的经验是什么？

回归基准线——每个场景的回归定义是"已经失败的场景不能再回归"。对于发布关卡来说这是正确的做法吗？还是应该单独跟踪失败模式的变化？你如何在 CI 中处理 WARN 波段的漂移？

轨迹评分——步级评分与场景级评分。额外的细粒度值得复杂性吗？在哪里你发现了场景级评分遗漏的信号？

下一篇文章我将写这三个话题中引发最多讨论的那个。

For further actions, you may consider blocking this person and/or reporting abuse