# 🧩 PRD: Agent 可观测系统

> 状态: Draft  
> 负责人: evan.guo  
> 更新时间: 2026-03-18  
> Design: [agent-tracing-system-design.md](../design/agent-tracing-system-design.md) 
---

## 📌 1. 背景（Background）

- 当前现状：
  - 现有可观测体系主要覆盖 HTTP、RPC、数据库等传统请求链路，能够回答“请求是否成功”和“耗时在哪里”，但不能解释 Agent 在执行期间的推理、工具选择和知识来源。
  - Agent Runtime(Dolphin) 已经具备模型调用、工具调用、检索增强等基础能力，但缺少统一的链路记录规范、查询入口和可视化调试视图。
  - 平台方案已明确采用 OpenTelemetry、Collector、可插拔存储和统一查询层，具备建设统一追踪能力的基础架构条件。

- 存在问题：
  - 当 Agent 结果错误、响应慢或行为异常时，研发和无法快速定位是推理决策、工具执行还是知识检索导致问题。
  - 结果缺少知识证据链，导致结果可信度不足、可追溯性弱，排障、审计和效果复盘仍依赖人工比对日志。
  - 不同业务系统和 Agent Runtime 对链路数据的记录方式缺少统一标准，后续接入增多后，容易出现数据字段不一致、指标统计口径不统一的问题，影响统一查询、分析和跨系统对比。

- 触发原因 / 业务背景：
  - 企业内 Agent 场景从单轮问答演进到多步骤自治执行，平台需要提供可解释、可追溯、可调试的基础设施，支撑线上稳定性治理、问题定位和模型效果优化。
  - 统一采用 OpenTelemetry 和 OTLP 协议的架构方向已经明确，需要在此基础上补齐 Agent 专属语义和产品化追踪能力。

---

## 🎯 2. 目标（Objectives）

- 业务目标：
  - 使核心 Agent 请求中可追溯到完整执行链路的请求占比在一期上线后达到 100%。
  - 使核心 Agent 请求中可追溯到知识证据链路的请求占比在一期上线后达到 10%。
  - 提供可观测数据查询接口，支持完整执行链路和部分知识证据链路的查询能力，为后续支撑执行失败定位、工具异常定位、知识来源追溯等核心场景做好准备。

- 产品目标：
  - 支持按 Agent、Conversation、对话轮次和时间范围查询执行链路，查询成功率 ≥ 99%。
  - 支持四层链路的统一记录与展示，请求链路覆盖率 ≥ 95%，推理/工具/知识链路覆盖率 ≥ 90%。
  - 新产生的 trace 数据在 5 分钟内可查询的比例 ≥ 95%。

---

## 👤 3. 用户与场景（Users & Scenarios）

### 3.1 用户角色

| 角色 | 描述 |
|------|------|
| 终端用户 | 间接受益于更稳定、更可信的 Agent 回答，但不是一期直接使用追踪系统的主要操作者 |
| 开发者 | 负责 Agent Runtime、工具接入和业务应用开发，需要通过链路定位执行错误、超时和字段异常 |
| 管理员 | 平台运维、SRE、算法平台负责人，需要观察系统健康度、容量、错误率和跨租户接入情况 |

---

### 3.2 用户故事（User Story）

- 作为平台研发，我希望查看一次 Agent 请求的完整执行链路，从而快速判断问题发生在推理、工具调用还是知识检索阶段。
- 作为算法工程师，我希望看到模型每一步的决策过程和证据来源，从而分析为什么 Agent 选择某个工具并优化策略。
- 作为运维或管理员，我希望按时间范围和 Agent 维度查看执行异常与性能指标，从而及时发现平台级风险并采取治理措施。

---

### 3.3 使用场景

- 场景1：用户反馈 Agent 回答错误，研发通过 trace 查看推理步骤、工具输入输出和知识来源，定位错误根因。
- 场景2：某个工具调用失败率升高，管理员按工具维度检索异常 trace，快速确认影响范围和调用上下文。
- 场景3：算法团队复盘一个复杂任务的执行过程，分析模型为何多次搜索、为何选择特定工具以及最终答案引用了哪些证据。

---

## 📦 4. 需求范围（Scope）

### ✅ In Scope

- 定义并落地 Agent 四层链路模型：请求链路、推理链路、工具链路、知识链路。
- 基于 OpenTelemetry 产出统一埋点规范和关键字段 schema。
- 支持业务系统通过 OTel SDK实现零侵入、低侵入埋点并接入 Collector。
- 支持链路数据接收、基础增强、批处理、采样、路由和导出。
- 提供按关键维度检索 trace 的查询能力。
- 提供 Agent 执行路径，包括推理步骤、工具调用和知识来源关联。
- 提供日志、指标、trace 的统一查询抽象，兼容 OpenSearch 优先落地方案。

### ❌ Out of Scope

- 不建设完整的通用可视化 observability 产品。
- 不做完整的 Execution Replay 回放能力，仅预留数据模型和演进空间。
- 不做模型质量自动评估，如 hallucination score、faithfulness 评分。
- 不绑定特定存储层，但是会优先考虑 OpenSearch 存储层。

---

## ⚙️ 5. 功能需求（Functional Requirements）

### 5.1 功能结构

    Agent 可观测系统
    ├── 埋点规范与数据接入
    │   ├── OTel 埋点 SDK/约定
    │   ├── OTLP 接入
    │   └── 字段标准化
    ├── 链路采集与处理
    │   ├── Collector 处理管道
    │   ├── 属性增强与采样
    │   └── 存储路由
    ├── 链路查询
    │   ├── Agent 列表与 Conversation 检索
    │   └── Trace 检索（Agent 执行路径 + 知识证据链）

---

### 5.2 详细功能

#### 【FR-1】四层链路记录

**描述：**  
系统必须为每次 Agent 请求生成统一 trace，并记录请求链路、推理链路、工具链路和知识链路的核心事件与属性。

**用户价值：**  
让研发、算法和平台团队能够从一次请求中还原 Agent 的关键执行路径，避免只看到最终结果而无法解释过程。

**交互流程：**
1. 业务系统收到用户请求并创建 root span。
2. Agent Runtime 在推理、工具调用和知识检索阶段按规范写入 span、event 或 structured log。
3. OTLP Exporter 将 trace、log、metric 发送给 Collector。
4. 系统将关联后的链路数据落入存储并建立可查询索引。

**业务规则：**
- 每次请求必须具备唯一 `trace_id`。
- 四层链路必须通过 `trace_id`、`span_id`、`parent_span_id` 形成父子关联。
- 推理、工具、知识链路需要带上 `agent.trace.type` 区分语义层级。
- 结果相关的知识来源必须可映射到文档、URL 或工具返回结果。

**边界条件：**
- 对于未接入完整推理埋点的历史系统，至少要求请求链路和工具链路可用。
- 对于大体积 prompt、response 或证据原文，只保存对象存储引用和摘要索引，不直接写入高成本字段。

**异常处理：**
- 若链路字段缺失，系统将记录 schema 校验告警并标记该条数据为 `partial_trace`。
- 若下游存储暂时不可用，Collector 必须按配置重试并输出错误日志，避免静默丢数。

---

#### 【FR-2】统一查询能力

**描述：**  
系统必须支持按 Agent、Conversation、对话轮次和时间范围查询链路数据，并返回统一的 trace、log、metric 与证据视图。

**用户价值：**  
让使用者能够从真实业务对象出发定位目标请求，不需要预先知道 `trace_id` 等底层技术标识，也不需要直接操作底层索引或依赖存储实现细节。

**交互流程：**
1. 用户进入 Agent 列表，按名称、业务线或时间范围筛选目标 Agent。
2. 用户点击某个 Agent，查看其关联的 Conversation 列表和历史多轮对话。
3. 用户进入某个 Conversation，查看对话轮次、时间、状态和摘要信息。
4. 用户点击某一轮对话后，系统根据该轮对话关联的 `trace_id` 打开对应 trace 详情视图。

**业务规则：**
- 查询入口必须屏蔽底层索引名和特定存储 DSL。
- 统一支持分页、排序、过滤和时间范围约束。
- Agent 列表、Conversation 列表和对话轮次列表必须返回基础摘要信息，至少包括名称、时间、状态、耗时和异常标记。
- 对话轮次需与唯一 `trace_id` 建立关联，供详情页跳转使用。

**边界条件：**
- 一期重点支持 OpenSearch 落地，后端可替换能力通过 Vega Connector 和数据资源抽象承载。
- 对超长时间范围查询应限制默认返回量，避免查询层雪崩。

**异常处理：**
- 查询参数非法时返回可读错误提示并给出可用过滤条件。
- 底层存储超时或不可用时返回失败状态，并记录查询侧错误日志与监控指标。

---

#### 【FR-3】执行路径可视化

**描述：**  
系统必须提供面向 Agent 场景的链路详情视图，展示请求生命周期、推理步骤、工具调用和知识证据链。

**用户价值：**  
帮助用户直观理解 Agent 的行为路径和关键决策节点，降低排障和复盘成本。

**交互流程：**
1. 用户打开某条 trace 的详情页。
2. 系统按时间顺序展示 root span 和子链路结构。
3. 用户展开某一步查看工具输入输出摘要、推理决策和知识来源。
4. 用户切换不同视角查看时间线、树状链路或证据列表。

**业务规则：**
- 详情页必须支持时间线和层级结构两种视角。
- 工具调用需要展示名称、状态、耗时、输入输出摘要。
- 知识链路需要展示来源类型、来源标识、链接或文档片段引用。
- 推理链路必须展示步骤顺序、决策摘要和是否触发工具执行。

**边界条件：**
- 原始敏感数据默认脱敏展示，需按权限控制查看明文。
- 详情页只展示摘要内容，原始大对象通过引用跳转查看。

**异常处理：**
- 某些子链路缺失时详情页需要显式显示“链路不完整”，不能默认渲染为成功。
- 若单个步骤数据解析失败，页面仍需展示其余链路并标记异常节点。

---

#### 【FR-4】调试与问题定位

**描述：**  
系统必须支持从 trace 中识别失败步骤、超时环节和可疑决策节点，辅助研发和算法团队排障。

**用户价值：**  
缩短问题发现到问题定位的路径，提升 Agent 平台的稳定性治理效率。

**交互流程：**
1. 用户在链路列表中筛选失败或高耗时请求。
2. 系统高亮异常节点并展示错误摘要。
3. 用户查看相关工具调用、推理步骤和证据来源。
4. 用户导出定位结论或转交给研发、算法或运维处理。

**业务规则：**
- 失败节点必须至少包含错误码、错误消息、发生阶段和时间戳。
- 高耗时节点必须展示阶段耗时和链路总耗时占比。
- 支持按工具失败率、请求耗时、Agent 维度进行聚合分析。

**边界条件：**
- 一期不支持真正的执行回放，只支持基于已有链路的静态还原。
- 若某些业务仅上报 trace 不上报 log，则问题定位能力会受限，系统需提示数据缺口。

**异常处理：**
- 聚合分析失败时保留 trace 明细查询能力，避免完全不可用。
- 无权限查看明细时，系统仅返回摘要信息并记录审计日志。

---

#### 【FR-5】埋点规范与接入治理

**描述：**  
系统必须定义统一的 Agent 追踪属性模型、命名规范和接入约束，并为业务系统提供标准接入方式。

**用户价值：**  
避免多团队各自定义字段，降低后续查询、治理和横向分析成本。

**交互流程：**
1. 平台发布统一 schema、span 命名和属性规范。
2. 接入方使用 OTel SDK、自动埋点或统一封装层接入。
3. Collector 对接入数据做基础校验、增强和路由。
4. 平台通过监控面板跟踪接入覆盖率和 schema 合规率。

**业务规则：**
- 推荐 span 命名必须包含 `agent.request`、`agent.reasoning.step`、`agent.tool.invoke`、`agent.knowledge.retrieve`、`agent.response.compose`。
- 请求链路、推理链路、工具链路、知识链路的关键属性必须按统一前缀命名。
- Collector 只负责协议统一、基础增强和路由，不承担首次领域建模。

**边界条件：**
- 历史系统允许通过兼容层渐进接入，但不作为默认架构。
- 不同业务租户的字段扩展必须保留公共字段，扩展字段不得污染公共 schema。

**异常处理：**
- schema 不合规的数据进入告警清单并通知接入负责人修复。
- 接入侧版本不兼容时，平台提供回退策略和兼容文档。

---

## 🔄 6. 用户流程（User Flow）

    平台用户 → 查看 Agent 列表 → 进入某个 Agent 的 Conversation 列表 → 打开历史多轮对话 → 点击某轮对话 → 系统关联对应 trace 详情 → 分析执行链路与知识证据链路 → 输出排障结论或优化动作

---

## 🎨 7. 交互与体验（UX/UI）

### 7.1 页面 / 模块
- Agent 列表页
- Conversation 列表页
- 对话详情 / 多轮对话页
- Trace 详情页
- 工具调用详情抽屉
- 知识证据链面板
- 平台指标概览页

### 7.2 交互规则
- 点击行为：点击 Agent 进入 Conversation 列表；点击 Conversation 进入多轮对话页；点击某轮对话进入 trace 详情；点击步骤节点展开上下文；点击证据来源跳转到引用详情或外链。
- 状态变化：查询中显示 loading；查询成功展示列表或详情；查询失败展示 error 和错误原因；无结果展示 empty state。
- 提示文案：当链路不完整、字段缺失、无权限或数据延迟时，页面必须显示明确提示，不允许默默降级。

---

## 🚀 8. 非功能需求（Non-functional Requirements）

### 8.1 性能
- 单条 trace 精确查询响应时间 ≤ 1 秒（P95）
- Trace 详情页首屏加载时间 ≤ 2 秒（P95）
- 新写入链路数据 5 分钟内可查询比例 ≥ 95%
- 支持并发查询 ≥ 200 QPS

### 8.2 可用性
- 查询服务 SLA ≥ 99.9%
- 数据接收链路可用性 ≥ 99.95%

### 8.3 安全
- 权限控制：RBAC
- 数据保护：敏感字段脱敏存储，跨租户数据隔离，访问高敏字段需审计

### 8.4 可观测性
- 支持 tracing
- 支持日志
- 支持指标监控

---

## 📊 9. 埋点与分析（Analytics）

| 事件 | 目的 |
|------|------|
| agent_trace_ingested | 统计链路接收量、接入覆盖率和异常写入比例 |
| agent_trace_query | 分析查询频次、常用过滤维度和查询成功率 |
| agent_trace_detail_view | 评估详情页使用频率和排障入口价值 |
| agent_tool_error_detected | 统计工具异常分布，识别高风险工具 |
| agent_knowledge_reference_view | 分析证据链使用率和知识追溯价值 |

---

## ⚠️ 10. 风险与依赖（Risks & Dependencies）

### 风险
- 业务侧埋点不完整会直接影响四层链路覆盖率，导致平台能力无法闭环。
- 推理和证据数据可能涉及敏感信息，若脱敏策略不完善会带来合规风险。
- 不同 Runtime 的字段规范不一致，可能导致查询口径和可视化结果不一致。
- 高体积日志和原始模型输出若写入不受控，会显著推高存储成本和查询延迟。

### 依赖
- 外部系统：OpenTelemetry 生态组件、OpenSearch 或其他可插拔存储、Vega Connector
- 内部服务：Agent Runtime、统一埋点 SDK、查询引擎、权限中心、对象存储

---

## 📅 11. 发布计划（Release Plan）

| 阶段 | 时间 | 内容 |
|------|------|------|
| 需求评审 | 2026-03-18 | 评审 PRD、确认范围、确定一期量化指标与负责人 |
| 开发 | 2026-03-19 至 2026-03-25 | 完成埋点规范、Collector 管道、查询接口 |
| 测试 | 2026-03-26 至 2026-03-27 | 完成功能测试、性能测试和 2 个试点 Agent 接入验证 |
| 发布 | 2026-03-30 | 面向线上灰度发布并开始收集使用反馈 |

---

## ✅ 12. 验收标准（Acceptance Criteria）

    Given 业务系统已经按统一 schema 接入 OTel 埋点
    When 用户发起一次 Agent 请求
    Then 系统能够生成包含请求链路、推理链路、工具链路和知识链路的完整 trace
    --------------------(以下偏交互侧能力咱不考虑，只需要保证查询接口能正常返回数据)------------------------------
    Given 平台用户进入某个 Agent 的 Conversation 历史
    When 用户点击某一轮对话
    Then 系统能够打开该轮对话关联的 trace 详情，并展示对应链路结构

    Given 某个工具调用发生失败
    When 用户打开 trace 详情页
    Then 页面能够高亮失败节点并展示错误信息、耗时和上下游上下文

    Given Agent 回答引用了外部知识或检索结果
    When 用户查看知识链路
    Then 系统能够展示来源类型、来源标识和证据引用信息

    Given 非授权用户尝试查看敏感链路字段
    When 用户访问 trace 详情
    Then 系统只返回脱敏摘要并记录审计日志
    --------------------------------------------------

---

## 🔗 附录（Optional）

- 相关文档：

- 参考资料：
