Agent 评测数据集怎么做？从真实任务、轨迹日志到回归测试

上周还能生成日报的 Agent，模型升级后仍给出”看似正确”的最终总结，但轨迹里漏掉了权限校验和数据刷新工具。客服 Agent 最终回复没错，但调用了错误的退款工具参数；公开 benchmark 看不出这个风险。一次事故复盘里已经有 traceId、tool call、approvalId、state event 和人工判定，但没有被固化成下次发布前必跑的测试。

这类退化不能靠换个模型或跑一次 demo 兜住。Agent 评测数据集要来自真实任务分布和生产失败轨迹，包括工具调用、参数格式、状态转移、审批记录和人工标注，再接入 CI 门禁做回归测试。接下来把重点放在失败案例和真实场景：如何构建可持续运行的 eval dataset，守住每次发布的质量边界。

一、为什么公开 benchmark 不够

1.1 公开 benchmark 的局限

公开 benchmark 测的是模型能力，不是你的业务任务质量。AgentBench、WebArena 这类评测集提供了标准任务，但它们无法覆盖团队特有的工具链、权限模型和状态机。

比如，你的报表 Agent 需要调用 check_permission、refresh_data、generate_report 三个工具，并按”检查→刷新→生成”顺序执行。公开 benchmark 不会测试这个流程，因为它不知道你的工具 schema 和权限边界。

模型在公开 benchmark 上分数好看，不代表业务任务不会退化。Agent 评测数据集要测的是你的真实任务分布，而不是通用的推理能力。

1.2 自建数据集的核心价值

自建 eval dataset 能捕获公开 benchmark 看不到的风险。以下是典型场景对比：

场景	公开 benchmark	自建 eval dataset
报表 Agent 漏权限校验	看不出，无此工具和权限模型	捕获轨迹约束：必须调用 check_permission
客服 Agent 调错退款参数	无此工具，无退款 schema	预期工具调用列表 + 参数格式约束
模型升级后状态转移变差	无此状态机	状态轨迹断言：检查→审批→执行顺序
事故复盘未固化成测试	无事故数据	失败案例进入 negative cases

公开 benchmark 选模型，自建数据集守住发布门禁。两者互补，不能互相替代。如果你已经读过Agent 评估基准对比，知道哪些公开评测集适合选型，这里就不再重复；重点是如何从自己的生产环境构建评测数据。

二、Agent eval dataset 的核心字段

2.1 必选字段

Agent eval dataset 不是简单保存用户输入和期望答案，而是要记录工具调用轨迹、状态转移和人工判定。以下是必选字段：

字段	说明	来源
input	用户任务描述	生产 trace / 手工设计
expected output	预期最终答案	人工标注 / golden set
expected tool calls	预期工具调用列表	轨迹分析，如 ["check_permission", "refresh_data"]
trajectory assertions	轨迹约束（必须/禁止/顺序）	状态机 + 审批流程
human labels	人工判定（正确/错误/部分）	事故复盘 / 标注队列

LangSmith 在 Evaluation concepts 中建议 Agent 评测应覆盖工具选择、参数格式和执行轨迹，而不是只看最终答案。OpenAI Agents SDK Tracing 提供了 trace_id、workflow_name、span 等字段用于记录工具调用和状态事件，但这些原始字段需要先脱敏和抽取，不能直接入库。

2.2 可选字段

以下字段根据业务需求添加：

字段	说明	用途
approval records	审批记录（审批人、时间、结果）	权限模型中需审批的工具调用
state transitions	状态转移序列	状态机约束，如 ["init", "check", "approve"]
metadata	traceId、环境、模型版本	复盘定位和版本对比

如果你读过 Agent 权限模型（N157）和人工审批设计（N155），会知道 approval records 应记录审批步骤、审批人和审批结果，用于验证高风险操作是否经过审批。

2.3 脱敏与隐私

生产 trace 不能原样进入评测集。OpenAI Agents SDK Tracing 文档提醒，有些 span 会捕获模型输入输出或函数工具输入输出，需配置是否包含敏感数据。

必须脱敏字段：PII（姓名、邮箱、手机号）、secret（API key、数据库密码）、客户数据（订单号、交易金额）。

保留字段：traceId、span_id（用于定位）、workflow_name（用于分类）、工具名、状态名（用于断言）。

脱敏方法包括替换为占位符（如 <user_id>）、哈希处理或直接删除。Phoenix 在 Running Evals on Traces 文档中提到，trace 可以被转成评测输入，但仍需要 label/score/rubric，不能把完整原始 trace 直接放进评测集。

三、从生产 trace 到 eval example

3.1 数据采集流程

从生产 trace 构建 eval example，需要经过脱敏、标注、分层和入库四个步骤。这不是一次性工程，而是持续运营。

步骤清单：

1. 从监控平台导出失败 trace（参考Agent 监控与失败恢复）。
2. 按失败类型分类：工具调用错误、参数格式错误、状态转移错误、最终答案错误。
3. 脱敏处理：删除 PII/secret/客户数据，保留 traceId、span_id、workflow_name。
4. 人工标注：正确/错误/部分正确 + 失败原因。
5. 分层入库：golden set / negative cases / edge cases。

Phoenix datasets 文档指出，examples 可从 production、staging、evaluations 或 manual 收集。生产环境提供真实任务分布，但 staging 环境的测试用例也能补充边界场景。

3.2 分层标准

层级	标准	用途
golden set	100% 正确 + 高频任务	发布门禁必过，pass rate 阈值
negative cases	典型失败模式	回归测试告警，防止相同错误重现
edge cases	长尾/边界场景	补充覆盖，酌情纳入

标注维度（对应 LLM-as-judge rubric）：工具选择正确性、参数格式正确性、执行顺序正确性、最终答案质量、人工标注对齐度。

OpenAI 在 Evaluation best practices 中建议测试数据包括 typical、edge、adversarial cases，并用 human expert labellers。这里提到的分层标准与之对应，但强调高频任务和典型失败模式，因为评测集的目的是守住发布门禁，而不是覆盖所有场景。

四、Trajectory assertions 写法

4.1 轨迹约束类型

Trajectory assertions 定义 Agent 必须遵守的工具调用、参数格式、状态转移和审批规则。以下是五种约束类型：

约束类型	示例	失败条件
必须调用工具列表	["check_permission", "refresh_data", "generate_report"]	缺少任意工具
禁止调用工具列表	["delete_user", "drop_table"]	用了禁止工具
参数格式约束	{"refund_amount": "number", "user_id": "uuid"}	参数类型错误
状态转移顺序	["init", "check", "approve", "execute"]	状态跳跃或重复
审批步骤存在性	["need_approval", "approval_granted"]	缺少审批事件

LangSmith 在 Evaluation concepts 中提到 Agent 评测应评估 trajectory、tool selection 和 argument formatting。Phoenix 在 Running Evals on Traces 文档中用 span_id 关联评测结果到具体执行片段，说明轨迹断言可以定位到失败 span。

如果你读过 Agent 规划能力评测（N158）和状态机与提示词边界，会知道状态轨迹字段来自状态机的 state/event/checkpoint，用于验证状态转移是否符合预期顺序。

4.2 代码示例

以下是 trajectory assertions 的伪代码示例，适用于通用 Agent 评测：

# trajectory assertions 示例
def assert_trajectory_correct(result):
    # 提取工具调用列表
    tools_called = [call.tool for call in result.tool_calls]

    # 必须调用工具
    required_tools = ["check_permission", "refresh_data"]
    for tool in required_tools:
        assert tool in tools_called, f"Missing required tool: {tool}"

    # 禁止调用工具
    forbidden_tools = ["delete_user"]
    for tool in forbidden_tools:
        assert tool not in tools_called, f"Called forbidden tool: {tool}"

    # 参数格式约束
    for call in result.tool_calls:
        if call.tool == "refund":
            assert isinstance(call.args["refund_amount"], (int, float)), "refund_amount must be number"
            assert len(call.args["user_id"]) == 36, "user_id must be uuid format"

    # 状态转移顺序
    expected_states = ["init", "check", "approve", "execute"]
    actual_states = [event.state for event in result.state_events]
    assert actual_states == expected_states, "State transition order mismatch"

    # 审批步骤存在性
    approval_events = [e for e in result.state_events if e.type == "approval"]
    assert len(approval_events) >= 1, "Missing approval step"

这段代码展示了如何检查必须调用工具、禁止调用工具、参数格式、状态转移顺序和审批步骤。实际实现时，可以用 LangSmith 的 trajectory assertion 或 Phoenix 的 trace eval，但核心逻辑一致。

如果你读过Agent 规划能力评测，会知道规划轨迹也可以变成回归样本，用于验证任务分解和自我纠错能力。

五、LLM-as-judge 的分层 rubric

5.1 为什么总分不够

LLM-as-judge 如果只给总分，波动大，难以定位问题。总分 80 分，可能是工具选择错了但答案凑巧对，也可能是答案错了但格式好看。无法区分是 prompt、工具 schema、检索还是状态机问题。

LangSmith 在 Evaluation concepts 中建议为 Agent 的关键组件定义质量标准：correct tool selection、proper argument formatting、trajectory。每个组件单独评分，才能在模型升级或 prompt 变化后快速定位退化点。

如果你读过Prompt 工程高级实践，会知道 DeepEval 也强调分层指标，如 TaskCompletenessMetric，而不是只看最终输出。

5.2 分层评分表格

以下 rubric 将 Agent 评测拆成五个维度，每个维度 0-2 分：

维度	0 分	1 分	2 分
工具选择正确性	错误工具	部分正确	完全正确
参数格式正确性	类型错误	部分字段错误	完全正确
执行顺序正确性	状态跳跃	顺序偏差	完全正确
最终答案质量	不满足需求	部分满足	完全满足
人工标注对齐度	与专家判断矛盾	部分一致	高度一致

rubric 配置示例（可用于 LangSmith 或 Phoenix）：

rubric:
  dimensions:
    - name: tool_selection
      weight: 0.3
      criteria:
        0: "调用了错误的工具"
        1: "调用了部分正确的工具"
        2: "工具选择完全正确"

    - name: argument_formatting
      weight: 0.2
      criteria:
        0: "参数类型错误"
        1: "部分字段格式错误"
        2: "参数格式完全正确"

    - name: execution_order
      weight: 0.2
      criteria:
        0: "状态转移跳跃或重复"
        1: "执行顺序有偏差"
        2: "执行顺序完全正确"

    - name: final_answer_quality
      weight: 0.2
      criteria:
        0: "不满足用户需求"
        1: "部分满足需求"
        2: "完全满足需求"

    - name: human_alignment
      weight: 0.1
      criteria:
        0: "与专家判断矛盾"
        1: "部分一致"
        2: "高度一致"

工具选择权重最高（0.3），因为 Agent 的核心是调用正确的工具。人工标注对齐度权重最低（0.1），用于校验 LLM-as-judge 与专家判断的一致性。

六、发布门禁与回归测试

6.1 CI 集成步骤

Agent eval dataset 的价值在于接入 CI，变成发布门禁。以下是集成步骤：

步骤清单：

1. 在 CI pipeline 中添加 eval 运行步骤（如 pytest、LangSmith offline eval、Phoenix experiments）。
2. 配置 pass rate 阈值（如 90%）。
3. 设置 golden set 全部通过条件（100%）。
4. 配置 negative cases 告警规则（触发后不阻断，但通知团队）。
5. 设置版本对比（improvement/regression），对比基线版本和当前版本。
6. 定义门禁触发时机（PR / merge / canary）。

LangSmith 在 Evaluation concepts 中提到 offline evaluations 可用于 regression testing、unit testing、backtesting，目标是 datasets 中的 examples。Phoenix experiments 文档说明 experiments 可比较 prompt、LLM 或应用逻辑变化，判断 improvement/regression。DeepEval 宣称 pytest-native eval，可在 CI/CD 或 Python scripts 运行，并用 LLMTestCase 和 TaskCompletenessMetric 对 Agent trace 逐层评分。

6.2 阈值配置表格

指标	阈值	失败动作
pass rate	≥ 90%	阻断合并
golden set	100% 通过	阻断合并
negative cases	触发告警	不阻断，但通知团队负责人
version comparison	无 regression	阻断合并

CI 配置示例：

evaluation:
  triggers:
    - pull_request
    - merge_to_main
    - canary_deployment

  conditions:
    pass_rate: 0.9
    golden_set: 1.0
    no_regression: true

  notifications:
    on_failure: ["team-lead", "on-call"]
    on_negative_alert: ["team-lead"]

门禁触发时机包括 PR（阻止问题代码进入主干）、merge（确保合并后仍满足条件）、canary（在生产流量前验证）。如果你读过成本控制与模型路由（N156），会知道成本阈值也可以作为门禁条件，这里先聚焦评测阈值。

七、真实案例复盘

7.1 场景描述

日报 Agent 上周能正常生成报告：调用 check_permission 校验权限，调用 refresh_data 刷新数据，再调用 generate_report 生成报表。模型升级后，Agent 仍给出”看似正确”的最终总结，但轨迹里漏掉了 check_permission 和 refresh_data。

用户拿到的是一份没有权限校验、数据过期的报表，但表面上看不出来。公开 benchmark 测不出这个风险，因为它没有你的工具 schema 和状态机。

7.2 问题定位

从监控平台导出失败 trace（参考Agent 监控与失败恢复）。分析轨迹发现：工具调用列表缺少 check_permission 和 refresh_data、状态转移从 init 直接跳到 execute、缺少 check 和 approve 步骤、最终答案看起来正确但数据源没有刷新。

标注为：工具选择错误 + 状态转移跳跃。

7.3 数据集更新

将失败案例加入 negative cases。同时补充 golden set：找到上周成功的日报任务，包含完整工具调用序列，标注为正确案例。

更新 trajectory assertions：必须调用工具列表添加 check_permission 和 refresh_data、状态转移顺序断言为 ["init", "check", "approve", "execute"]。

7.4 CI 门禁拦截

下次 PR 触发 eval 运行。negative case 触发告警：缺少 check_permission 工具调用。golden set 全部通过，说明成功案例没问题。

定位到是 prompt 问题：升级后的模型对”生成报表”指令的理解更偏向直接执行，忽略了前置校验和刷新步骤。

7.5 修复与回归

修复 prompt，强调”生成报表前必须先校验权限和刷新数据”。重新运行 eval：pass rate 从 85% 提升至 95%、negative case 通过无告警、golden set 全部通过、版本对比显示 improvement 无 regression。

合并上线。CI 门禁守住了这次退化。

7.6 字段映射表格

阶段	使用的字段
问题定位	traceId、span_id、tool_calls、state_events
数据集更新	input、expected tool calls、trajectory assertions、human labels
CI 门禁	pass rate、golden set、negative cases
修复验证	pass rate、version comparison

这个循环展示了从生产失败到回归测试的完整流程。每次事故复盘后，把 traceId、tool call、approvalId、state event 和人工判定固化成 eval example，下次发布前就不会再踩同一个坑。

八、下一步阅读

• Agent 状态机与提示词边界：理解状态转移约束和轨迹断言字段来源
• Agent 权限模型：理解审批记录字段和高风险工具调用规则
• 人工审批设计：理解 approval records 和审批流程固化
• 成本控制与模型路由：理解成本阈值作为门禁条件
• Agent 监控与失败恢复：理解失败 trace 导出和事故复盘循环