可观测性与轨迹回放

Agent 系统中的 trace、日志、指标、成本、错误聚合和轨迹回放。

这个页面用于承载 Agent 可观测性。评测告诉我们质量是否变化，可观测性告诉我们一次具体任务为什么成功或失败。

建设边界

Trace 字段：用户目标、模型输入输出、工具调用、状态变化、错误、人工接管。
日志分层：业务日志、模型日志、工具日志、系统日志、安全审计日志。
指标：成功率、任务耗时、token 成本、工具调用次数、重试次数、人工接管率。
回放：timeline、DAG、diff、错误聚合、失败样例沉淀。
发布监控：灰度、告警、回滚、成本异常。

三类信号

OpenTelemetry 把可观测数据分成 traces、metrics、logs 三类。Agent 系统也可以沿用这个分法：

信号	Agent 中的含义	用途
Trace	一次任务从用户目标到工具调用、验证、交付的完整路径	回放、排障、评测样例沉淀
Metrics	成功率、耗时、token、工具调用次数、重试率、人工接管率	告警、灰度、成本控制
Logs	模型请求摘要、工具输入输出、错误、权限决策、安全事件	审计、问题定位、合规

Trace 解释“这一单为什么这样走”，metrics 解释“整体是否变差”，logs 提供细节证据。三者需要共享 traceId 或任务 ID。

Agent Trace 字段

一个可回放 trace 至少应包含：

{
  "traceId": "task_20260710_001",
  "userGoal": "补充核心概念文档并推送",
  "model": {
    "provider": "openai-compatible",
    "name": "example-model",
    "promptVersion": "concept-docs-v1"
  },
  "steps": [
    {
      "index": 1,
      "type": "tool_call",
      "tool": "read_file",
      "inputSummary": "读取 concepts/index.mdx",
      "outputSummary": "当前页面 18 行，缺少实践和检查清单",
      "ok": true,
      "durationMs": 42
    }
  ],
  "cost": {
    "inputTokens": 12000,
    "outputTokens": 1800
  },
  "stopReason": "success"
}

不要在 trace 中永久保存完整敏感输入。可以保存摘要、hash、路径、权限决策和可复核引用。

轨迹回放页面

一个面向工程团队的轨迹回放页应优先展示：

任务目标、提交人、开始结束时间、最终状态。
时间线：模型调用、工具调用、人工确认、错误和重试。
每一步的输入摘要、输出摘要、耗时、token、错误码。
文件 diff、命令输出、截图或引用证据。
失败归因：模型、工具、权限、上下文、外部依赖还是用户输入。
可沉淀动作：加入评测集、调整工具 schema、增加告警、补文档。

回放页不是为了展示“模型想了什么”，而是为了让团队能判断“系统为什么这样行动”。

指标设计

指标	为什么重要
task_success_rate	衡量端到端任务完成率
first_pass_success_rate	衡量是否需要人工或重试
tool_call_success_rate	找出工具层可靠性问题
schema_validation_error_rate	发现模型输出与接口契约不匹配
human_intervention_rate	观察风险、权限或体验问题
p50/p95_latency	评估交互体验和长任务瓶颈
token_cost_per_success	用成功任务而不是总 token 衡量成本
repeated_failure_count	发现循环和不可恢复失败

指标要按任务类型分组。把研究型 Agent、编码 Agent、客服 Agent 混在一个成功率里，通常没有诊断价值。

告警与发布

发布新模型、新提示词或新工具后，至少观察：

成功率是否下降。
schema 错误和工具失败是否上升。
token 成本和延迟是否异常。
人工接管率是否变化。
高风险工具是否出现异常调用。
用户取消、重试或投诉是否增加。

如果没有这些信号，灰度发布只是“先放一部分用户试试”，不是工程上的灰度。

检查清单

是否每个任务都有 traceId。
是否记录 model、prompt version、工具版本和代码版本。
是否能按失败类型聚合：模型、工具、上下文、权限、外部依赖。
是否对敏感输入做摘要、脱敏或最小保存。
是否能从一次失败 trace 生成新的评测样例。
是否有成本和延迟告警。