X-Financial/document/development/Agent链路追踪中心/CONCEPT.md

Agent链路追踪中心 概念文档

功能一句话

为 Orchestrator 全链路运行提供统一 trace 采集、查询和前端回放入口，让管理员能按 run_id 或 conversation_id 还原一次 Agent 对话从意图识别到最终回复的全过程。

背景与问题

• 当前现状：系统已有 agent_runs、agent_tool_calls、semantic_parse_logs 和对话消息，但它们分散在运行记录、工具调用、语义解析与系统日志中。
• 用户痛点：线上 Agent 回答异常时，只能看局部日志或 Hermes 工作记录，难以判断问题出在意图路由、知识检索、规则引擎、数字员工任务还是回复生成。
• 业务影响：Agent 链路越长，排障成本越高；没有可重放视图会影响交付、演示和运维可信度。

目标与非目标

目标

• [G1] 后端沉淀统一的 Agent trace 事件模型，按运行顺序记录关键阶段输入、输出、状态、耗时和错误。
• [G2] 提供 trace 查询接口，支持按 run_id 查看单次运行，按 conversation_id 查看多轮会话链路。
• [G3] 前端新增 Agent Trace Center 入口，展示运行时间线、工具调用、语义解析、路由上下文和最终回复。
• [G4] 保留现有 Agent Run / ToolCall 数据结构，避免破坏数字员工工作记录和系统日志页面。

非目标

• [NG1] 本轮不做重新执行真实业务动作的“调试重跑”，只做历史重放。
• [NG2] 本轮不接入 OpenTelemetry、Jaeger 等外部分布式追踪系统。
• [NG3] 本轮不改造总账、预算、报销审批等业务语义。
• [NG4] 本轮不做跨服务链路采样策略和海量归档策略。

用户与场景

• 目标用户：系统管理员、财务系统运维、Agent 能力开发者、实施顾问。
• 使用入口：系统日志详情、数字员工工作记录、报销助手消息中的 run_id、新增 Trace Center 页面。
• 核心场景：
  • 管理员打开某次异常回复，查看每一步输入输出和耗时。
  • 实施人员按会话查看多轮上下文，判断上下文是否被错误继承。
  • 开发者定位工具调用失败、语义识别降级或路由选错 Agent 的原因。
• 异常场景：
  • 运行失败但没有工具调用时，仍展示已记录的 orchestration 阶段。
  • 旧数据没有 trace event 时，接口回退展示 agent_runs、semantic_parse、tool_calls。

功能能力

• [C1] 输入能力：接收 run_id、conversation_id、Agent、状态、来源、关键字等查询条件。
• [C2] 采集能力：记录 received、context_hydrated、semantic_parsed、agent_selected、capability_selected、tool_invoked、response_built、conversation_updated、failed 等事件。
• [C3] 输出能力：返回 trace 摘要、事件时间线、工具调用、语义解析、路由 JSON、最终回复和关联会话消息。
• [C4] 状态与权限：复用现有登录与页面权限，管理员/可访问设置页用户可查看全量 trace。
• [C5] 边界与降级：旧运行没有 trace events 时，按现有 run/tool/semantic 数据合成最小时间线。

方案设计

前端

• 页面/组件：
  • 新增 AgentTraceCenterView 或设置页内 Trace Center 分区。
  • 新增 trace 详情组件，复用现有日志详情的直角企业级视觉。
  • 从日志详情、数字员工工作记录、报销助手操作反馈中可跳转到 trace 详情。
• 交互状态：
  • 列表支持关键字、状态、Agent、来源筛选。
  • 详情展示左侧时间线、右侧输入输出 JSON、顶部摘要。
  • 支持加载、空态、错误态和刷新。
• 展示规则：
  • 事件按 started_at、sequence 升序展示。
  • 失败事件突出错误信息。
  • 大 JSON 使用可滚动代码块，避免撑破页面。

后端

• 接口/服务：
  • GET /api/v1/agent-traces：查询 trace 列表。
  • GET /api/v1/agent-traces/{run_id}：读取单次运行 trace。
  • GET /api/v1/agent-traces/conversations/{conversation_id}：读取会话 trace。
• 权限与校验：
  • 复用当前 API 依赖和系统登录态。
  • 不允许通过 trace 接口修改业务数据。
• 持久化：
  • 新增 agent_trace_events 表。
  • 通过 AgentTraceService 封装记录、查询、合成旧数据时间线。

算法与规则

• 规则输入：Agent 运行阶段、工具调用结果、语义解析结果和会话消息。
• 规则流程：
  • 采集阶段按固定事件名记录。
  • 查询阶段按事件序列合并 run、semantic、tool、conversation。
  • 无事件时从历史 run 数据合成 fallback timeline。
• 结果解释：
  • 每个事件输出 title、summary、status、duration_ms、input_json、output_json、error_message。

算法与公式

当前功能不涉及评分、预算或风控公式，只涉及耗时统计：

duration\_ms = finished\_at - started\_at

变量说明：

• $duration_ms$：阶段耗时，单位毫秒。
• $finished_at$：阶段结束时间。
• $started_at$：阶段开始时间。

测试方案

• 单元测试：覆盖 AgentTraceService 记录事件、查询详情、旧 run fallback 时间线。
• 接口测试：覆盖 trace 列表、单 run 详情、会话详情。
• 前端交互测试：覆盖 trace 数据归一化、状态文案、空态和错误态。
• 端到端测试：通过一次 Orchestrator 用户消息生成 run_id，验证详情接口能返回语义解析、路由和至少一个事件。
• 回归测试：确认原 agent-runs 接口、数字员工工作记录、系统日志详情不破坏。
• 手工验证：在浏览器打开 Trace Center，检查列表、详情和 JSON 展示。

指标与验收

• [A1] 功能验收：一次 Orchestrator 调用后，能通过 run_id 查询到完整 trace 详情。
• [A2] 性能指标：单次 trace 详情查询在常规数据量下不引入明显慢查询；默认列表限制数量。
• [A3] 质量指标：后端定向测试在 Docker x-financial-main 容器内 60s 超时内通过。
• [A4] 安全/权限指标：trace 接口只读，不触发业务动作或副作用。
• [A5] 可观测性：失败运行也能看到最后成功事件和失败事件。

风险与开放问题

• 风险：当前工作树已有大量未提交改动，本轮实现必须避免覆盖既有业务改动。
• 已处理依赖：新增 trace 模型已纳入 Base 导入，AgentTraceService.ensure_storage_ready() 会按需创建 trace 事件表。
• 待确认：后续是否需要接 OpenTelemetry、跨容器 trace 或长期归档策略。
• 降级策略：没有 trace event 的旧 run 通过 semantic_parse、tool_calls 和 route_json 合成只读时间线。

本轮实现记录

• 后端已完成 AgentTraceEvent、AgentTraceService 和 /api/v1/agent-traces 只读接口。
• Orchestrator 已在接收请求、会话补全、语义识别、路由、工具调用、会话写回、最终回复和失败路径写入 trace event。
• 前端已在系统设置中新增 Agent Trace Center，并从日志详情、数字员工工作记录跳转到指定 run_id。
• 本轮保持非目标不变：不做真实业务重跑、不接 OpenTelemetry、不处理 GL/总账体系和前端统一状态管理。