质量用例回归

为业务 Agent 和个人 Agent 维护质量用例，并查看逐用例的真实回答、工具轨迹、断言和失败原因。

Tensor Agent 的业务 Agent（BA）和个人 Agent（PA）共用同一套质量用例回归流程：先在质量页维护并启用用例，再运行回归，最后查看每条用例的实际执行证据。

运行回归不会临时生成用例，也不接受内联用例或模式参数。页面、API、CLI 和 PA 模型测试读取的是同一条质量运行记录。

使用流程

维护质量用例
  ↓
启用待审核用例
  ↓
运行当前全部启用用例
  ↓
逐条执行真实 BA / PA
  ↓
查看回答、工具轨迹、断言、耗时和失败原因
  ↓
修复 Agent 或用例后重新运行

每个 Agent 有自己的默认质量用例集。回归启动时会冻结用例快照和 Agent 版本信息，因此历史结果不会被后续编辑覆盖。

质量用例

每条用例至少包含真实用户输入，并声明一种或多种验收标准：

expectedBehavior：期望业务行为，由语义断言检查
expectedTools：必须调用的工具
expectedKeywords：回答必须包含的关键词
forbiddenKeywords：回答不得包含的关键词
expectedRegex：回答或工具参数需匹配的正则
domainGraders：订单号、金额、多步完成等领域 grader

示例：

{
  "id": "case-order-a001",
  "type": "tool_specific",
  "question": "查订单 A001，告诉我当前状态和下一步动作",
  "expectedBehavior": "查询真实订单并给出当前状态与可执行的下一步",
  "expectedTools": ["call_api"],
  "expectedKeywords": ["A001"],
  "forbiddenKeywords": ["我猜"],
  "shouldSucceed": true,
  "source": "manual"
}

质量用例状态：

状态	含义
`pending`	来自反馈等来源，等待所有者检查
`approved`	已启用，会进入下一次回归
`rejected`	已归档，不参与回归

业务 Agent 可以从历史会话导入用例；个人 Agent 当前只支持手工添加。

回归结果

回归批次状态：pending、running、completed、failed、canceled。

逐用例状态：

状态	含义
`queued`	等待执行
`running`	正在调用 Agent
`passed`	所有验收断言通过
`failed`	Agent 已执行，但至少一项断言失败
`blocked`	运行时、依赖或基础设施阻止了有效验收
`canceled`	用户取消后未继续执行

批次 summary 只汇总 total / passed / failed / blocked / running。判断回归是否通过时，应检查 failed=0 且 blocked=0，并查看每条用例证据，不使用脱离用例的综合评分。

每个 items[] 项包含：

caseSnapshot：本次运行使用的用例快照
actualResponse：Agent 的真实回答
toolCalls：实际工具名、参数、结果摘要和耗时
assertionResults：每项验收标准的通过状态、期望值和实际值
durationMs：该用例总耗时
executionRef：对应会话、PA session 或 Agent run 引用
failureCategory / failureReason：失败或阻塞的业务分类与中文原因

REST API

以下示例使用 BA 路径。PA 使用同一契约，把 /api/agents/:agentId 换为 /api/personal-agents/:agentId。

获取用例集

GET /api/agents/:agentId/case-sets

响应包含默认用例集及 pending / approved / rejected 计数。

列出用例

GET /api/agents/:agentId/case-sets/:setId/cases?status=approved&limit=100&offset=0

可按 status 和 source 筛选。

添加并启用用例

POST /api/agents/:agentId/case-sets/:setId/cases
Content-Type: application/json

{
  "source": "manual",
  "caseData": {
    "id": "case-order-a001",
    "type": "tool_specific",
    "question": "查订单 A001",
    "expectedBehavior": "返回真实订单状态和下一步",
    "expectedTools": ["call_api"],
    "expectedKeywords": ["A001"],
    "shouldSucceed": true,
    "source": "manual"
  }
}

手工用例创建后直接为 approved。反馈生成的 pending 用例需通过 /approve 启用或通过 /reject 归档。

运行回归

POST /api/agents/:agentId/regression-runs
Content-Type: application/json

{}

请求体只能是空对象。传入临时用例、模式或其他字段会返回 400；没有已启用用例时不会启动空回归；同一 Agent 已有交互式回归运行时返回 409。

响应为 202 Accepted：

{
  "id": "regrun-xxx",
  "agentKind": "business",
  "agentId": "agent-1",
  "caseSetId": "case-set-1",
  "status": "pending",
  "summary": {
    "total": 2,
    "passed": 0,
    "failed": 0,
    "blocked": 0,
    "running": 0
  }
}

列出回归

GET /api/agents/:agentId/regression-runs?limit=20&offset=0

{
  "runs": [],
  "hasMore": false
}

查看逐用例证据

GET /api/agents/:agentId/regression-runs/:runId

{
  "id": "regrun-xxx",
  "status": "completed",
  "summary": {
    "total": 1,
    "passed": 1,
    "failed": 0,
    "blocked": 0,
    "running": 0
  },
  "items": [
    {
      "caseId": "case-order-a001",
      "status": "passed",
      "actualResponse": "订单 A001 当前待发货，下一步请确认出库时间。",
      "toolCalls": [
        {
          "toolName": "call_api",
          "arguments": { "path": "/orders/A001" },
          "latencyMs": 420
        }
      ],
      "assertionResults": [
        {
          "id": "expected-tool:call_api",
          "type": "expected_tool",
          "passed": true,
          "message": "已调用期望工具 call_api"
        }
      ],
      "durationMs": 1830,
      "failureCategory": null,
      "failureReason": null
    }
  ]
}

取消回归

POST /api/agents/:agentId/regression-runs/:runId/cancel

取消是协作式的：已进入终态的用例保持原结果，尚未执行的用例转为 canceled。

CLI

tagent regression run <agentId>
tagent regression list <agentId>
tagent regression get <agentId> <runId>
tagent regression cancel <agentId> <runId>

个人 Agent 增加 --kind personal。

旧评估 API、运行模式、自动生成用例和跨 Agent 临时用例集已退出运行链路。历史数据只作归档，不应作为新质量结果读取。

目录