Agent 轨迹评测区分工具错误与模型错误

Agent 任务失败时，最容易出现的误判是把所有红色错误都算到模型头上。更稳妥的做法是沿着轨迹把“模型决定了什么”“工具实际收到了什么”“工具返回了什么”和“环境最后变成什么”分开记录。只有当工具输入满足契约、工具响应和环境状态都没有异常，而模型仍选择了错误动作时，才适合标成模型错误。

工具返回 404、权限拒绝或参数校验失败，优先归入工具或环境侧；工具已经成功返回可用事实后，模型仍错误解释、遗漏约束或没有采取必要的下一步，才归入模型侧。证据不足时使用“混合错误”或“待复核”，不要强行二选一。

本文讨论的是轨迹评测中的可观测归因，不把一段 trace 当成模型内部思维的完整记录。Hugging Face 的 Agent Traces 文档说明，原始 JSONL 会保留会话、消息、工具调用和结果等可视化所需的数据；官方入口如下：

官方地址：https://huggingface.co/docs/hub/en/agent-traces

先把轨迹分成四层

一条智能体轨迹至少要拆成四个观察层：任务输入与约束、模型决策、工具调用与响应、环境状态与最终结果。评测器不需要猜模型“真正想了什么”，只需要比较相邻层的契约是否满足。

升级评测表：从二分类改成证据标签

旧式评测常只有一个 passed 或 failed 字段，迁移到轨迹评测后至少要增加错误层、证据类型和置信度。否则同一条工具 401 既可能被统计为“模型不会调用 API”，也可能被统计为“服务权限配置错误”。

旧代码风险：只看最终输出会漏掉什么

如果评测器只读取最终文本，就会漏掉三种重要信息：模型是否调用了正确工具、工具有没有真实返回、以及最终状态是否被外部系统接受。相反，只看工具调用也不够，因为模型可能拿到正确响应后错误地总结，或者在工具成功后没有完成写入。

Hugging Face 的 Session Traces Format 使用 JSONL，每行描述会话或消息；消息还可以关联工具调用和工具结果。这个格式适合保留原始事实，业务评测则应在其上生成一份脱敏后的派生记录。

格式说明：https://huggingface.co/docs/hub/session-traces-format

新写法：用最小记录保存证据链

下面的结构不是某个平台的强制 schema，而是一个可以落到数据库或 JSONL 的最小字段集合。input_evidence 和 output_evidence 只保存必要摘要，密钥、完整提示词、个人数据和私有路径应在进入评测集前脱敏。

from dataclasses import dataclass
from typing import Literal

ErrorLabel = Literal["tool_error", "model_error", "environment_error", "mixed_or_unknown"]

@dataclass
class EvalRecord:
    span_id: str
    layer: str
    input_evidence: str
    output_evidence: str
    error_label: ErrorLabel
    confidence: float
    redaction: str
    regression_case: str

def classify(record: EvalRecord) -> ErrorLabel:
    # 工具已返回可用结果，但模型仍给出错误动作，才归入模型侧。
    if record.layer == "model" and record.output_evidence == "usable" and record.input_evidence == "wrong_decision":
        return "model_error"
    # 服务异常、权限拒绝或响应不符合契约，优先保留为工具侧证据。
    if record.layer == "tool" and record.output_evidence in {"timeout", "5xx", "schema_error", "permission_denied"}:
        return "tool_error"
    # 无法证明单一根因时保留混合标签，避免污染统计结果。
    return "mixed_or_unknown"

示例中的判断故意保守：它不试图从一行自然语言推断模型能力，只使用已经记录的层、输入证据和输出证据。真实项目还应把错误码、HTTP 状态、重试次数、环境快照摘要和最终状态分别存储，避免把多个事实压成一段字符串。

回归检查：用对照样本检验归因是否稳定

完成字段迁移后，不要只拿失败样本检查。至少准备四组对照样本：工具明确超时、工具成功但模型参数错误、工具和模型都异常、轨迹缺少关键 span。每组都应有预期标签和允许的置信度范围。

1. 先检查原始 span 是否能按稳定 ID 关联到工具调用和工具结果。
2. 再检查工具响应是否满足声明的 schema、状态码和错误码约定。
3. 最后检查环境最终状态，不把“调用成功”当成“任务成功”。
4. 对人工复核存在分歧的样本保留原始证据和修订理由，回写为下一轮回归用例。

评测运行时还要固定模型、工具版本、提示模板、数据集和采样策略。否则同一错误标签的变化可能只是运行条件变了，不代表模型真的改进。Hugging Face 的 smolagents 文档也强调，复杂 agent run 需要通过 tracing 记录后再分析，而不是只凭控制台最后一行判断。

运行追踪说明：https://huggingface.co/docs/smolagents/tutorials/inspect_runs

迁移清单

• 把 passed/failed 拆成层、标签、证据和置信度。
• 把工具输入、工具响应和环境结果作为不同事件保存。
• 为 401、超时、schema 错误、错误参数和缺失 span 准备对照样本。
• 明确脱敏规则，不把 token、私有路径和个人数据送入公共评测集。
• 对无法定责的轨迹使用 mixed_or_unknown，并允许人工复核。

相关问题

工具返回 200，为什么仍可能是工具错误？

HTTP 成功只说明请求被处理，不代表响应满足业务 schema，也不代表环境状态已经改变。应继续检查字段、语义和最终状态。

能不能只用模型评分器判断错误归因？

不建议。状态码、schema、文件变化等确定性条件应优先用代码判断；语义争议再交给模型评分器或人工复核。

缺少工具结果时应该算模型错吗？

不应直接算。先标为 mixed_or_unknown，确认是采集丢失、工具未执行还是模型没有等待结果后再更新标签。

归因的目标不是给每次失败贴上一个看似精确的名字，而是让下一次修复有可靠方向：工具团队看工具契约和环境，模型团队看决策与恢复动作，评测团队看证据是否足够。