进阶第 10 章：可观测性与遥测

业务问题

生产级 Agent 不能只有“好像失败了”。需要知道模型看到了什么、工具为什么失败、系统在哪里变慢。

交互图解：Session Log、Surface 与多种投影 · 查看图解导读

核心原理

可观测性包含：

• 日志：发生了什么。
• 指标：多快、多少、失败率。
• trace：一次任务经过哪些服务。
• 回放：能否重建历史状态。

Agent 场景尤其需要记录：

• 用户输入。
• 模型请求。
• 流式 token。
• 工具调用和结果。
• 权限决策。
• 错误和取消。

真实项目中的映射

客服 Agent 的可观测性可以回答：

• 这个用户为什么没有收到正确回答？
• 知识库检索到了什么？
• 模型是否调用了错误工具？
• 某次退款操作是否被批准？
• 前端断线后服务端是否继续执行？

DeepSeek Harness 对应实现

DeepSeek Harness 使用：

• SessionEvent 作为可回放事实。
• JSONL / SQLite 作为持久化后端。
• session-projection 从事件流计算当前视图。
• session-telemetry-otel 上报 OpenTelemetry。

模型可见内容必须可从日志重建，这是可观测性的基础。

进一步阅读：

• packages/session/session-persistence/README.md
• packages/session/session-projection/README.md
• packages/session/session-telemetry-otel/README.md

代码示例

interface TraceEvent {
  sessionId: string
  seq: number
  type: string
  data: unknown
}

class EventTimeline {
  private events: TraceEvent[] = []

  append(event: TraceEvent): void {
    this.events.push(event)
  }

  findByType(type: string): TraceEvent[] {
    return this.events.filter(event => event.type === type)
  }
}

前端可以把这个时间线渲染成可展开的执行轨迹。

面试追问

问：Agent 可观测性和普通后端有什么不同？

回答要点：

• Agent 有非确定模型输出。
• 工具调用链更长。
• 上下文会影响结果。
• 必须能回放模型看到的内容。

问：如何定位一个错误回答？

回答要点：

• 先看用户输入。
• 再看检索或工具结果。
• 再看模型请求和输出。
• 最后判断是上下文、工具还是模型问题。

问：前端如何展示 trace？

回答要点：

• 时间线展示事件。
• 可展开工具详情。
• 可查看模型请求头。
• 可复制 session id 供排查。

实践任务

为一个客服 Agent 设计 trace 数据结构，包含消息、工具、权限和错误事件。

验收标准

• 能解释日志、指标、trace、回放。
• 能定位错误回答的可能来源。
• 能设计前端事件时间线。