LLM Observability

LLM Observability — AI Agent 可观测性设计

为 AI Agent 系统设计可观测性方案，覆盖传统 APM 无法触及的 Agent 决策质量维度。

核心洞察： 系统可以是基础设施健康的，同时完全错误。Agent 可以在幻觉的同时返回 200，在保持延迟阈值内的同时运行循环。传统监控不够。

Goal

为 AI Agent 系统设计可观测性方案。覆盖决策追踪、上下文健康监控、工具调用审计、成本追踪和异常告警

Trigger

• 用户说"agent 监控"、"LLM 可观测性"、"agent tracing"、"agent 日志"
  • 为 Agent 系统构建监控
  • 调试为什么 Agent 在长对话中退化
  • 需要了解生产环境中 Agent 的决策质量

工作流程

识别 Agent 生命周期 → 定义追踪 Schema → 埋点决策点 → 配置仪表盘 → 配置告警

Step 1: Agent 生命周期模型

将 Agent 执行分解为可观测的阶段：

用户输入
  → [1] 提示构建（组装系统提示 + 历史 + 用户输入）
  → [2] LLM 推理（发送到模型、获取响应）
  → [3] 决策解析（提取工具调用或最终回答）
  → [4] 工具执行（调用工具、获取结果）
  → [5] 结果整合（将工具结果反馈给 LLM 或返回用户）
  → [6] 上下文管理（压缩、摘要、清理）
  → 循环 [2]-[5] 直到完成

每个阶段都需要独立埋点，因为不同阶段的失败模式完全不同：

• 阶段 1 失败 → 提示拼接错误
• 阶段 2 失败 → 模型超时/限流
• 阶段 3 失败 → 响应解析错误
• 阶段 4 失败 → 工具调用失败（最常见的 Agent 失败模式）
• 阶段 5 失败 → 结果整合错误
• 阶段 6 失败 → 上下文退化

Step 2: 决策追踪 Schema

每个 Agent 执行步骤生成一条追踪记录：

{
  "trace_id": "唯一追踪ID",
  "session_id": "会话ID",
  "step_number": 3,
  "timestamp": "2026-05-29T10:30:00Z",
  "input": {
    "context_tokens": 4500,
    "context_utilization": 0.45,
    "relevant_history_steps": [1, 2]
  },
  "llm_call": {
    "model": "claude-sonnet-4",
    "input_tokens": 3200,
    "output_tokens": 450,
    "latency_ms": 1850,
    "cost_usd": 0.0165
  },
  "decision": {
    "type": "tool_call",
    "tool_name": "search_documents",
    "tool_params": {"query": "2024 Q3 report"},
    "confidence": 0.92
  },
  "tool_execution": {
    "latency_ms": 340,
    "success": true,
    "output_tokens": 1200,
    "error": null
  },
  "output": {
    "type": "tool_result",
    "tokens": 1200
  },
  "context_health": {
    "total_tokens_used": 8350,
    "window_utilization": 0.42,
    "compression_events": 0,
    "oldest_context_age_steps": 3
  }
}

完整 JSON Schema 见 references/trace-schema.json

Step 3: 上下文健康指标

上下文退化是长任务 Agent 的头号杀手。需要持续监控以下指标：

上下文退化检测

每步检查:
  if context_utilization > 0.8:
    触发压缩/摘要
    记录压缩事件

  if oldest_referenced_context > 20 steps:
    标记 "引用可能已过时"

  if 连续 3 步的决策置信度下降:
    标记 "可能正在退化"
    建议：重新注入任务目标

详细检测清单见 references/context-health-checklist.md

Step 4: 工具调用审计

工具调用是 Agent 最常见的失败点。需要独立审计每个工具调用：

审计维度

循环检测

对最近 N 次工具调用:
  if 存在连续 3+ 次相同工具 + 相同参数:
    标记 "疑似循环"
    触发断路器

Step 5: 告警配置

Agent 专用告警规则

预置告警规则模板见 references/alert-rules.md

Step 6: 仪表盘模板

Agent 监控仪表盘布局

第一行：概览指标（4 个卡片）

• 活跃会话数
• 平均任务完成率
• 平均每会话成本
• 平均响应延迟

第二行：趋势图（2 个图表）

• 工具调用成功率趋势（按小时）
• 上下文利用率分布（直方图）

第三行：详情表（2 个表格）

• 工具调用详情（工具名、调用次数、成功率、P95 延迟、成本）
• 异常事件列表（时间、类型、严重程度、详情）

第四行：单会话追踪

• 选择特定 session_id，展示完整的决策链路
• 每步显示：输入上下文、LLM 调用、决策、工具调用、输出
• 高亮异常步骤（错误、高延迟、循环）

快速使用

用户：我的客服 Agent 在长对话中越来越不靠谱，经常忘记之前的对话内容
助手：使用 /llm-observability 分析上下文健康、设置退化检测告警、追踪决策质量

边界情况

• 流式 Agent — 需要在流式传输过程中捕获中间状态，不能等到完成后再记录
• 多 Agent 系统 — 每个 Agent 独立追踪，通过 session_id 关联跨 Agent 调用
• 有外部记忆的 Agent — 外部记忆检索也需要埋点，追踪检索结果的相关性
• 高频 Agent — 大量并发会话时，追踪数据量巨大，需要采样策略

MTTD 目标

Mean Time to Detect（平均检测时间） 是衡量可观测性的核心指标：

与其他技能的协作

• agent-eval — 可观测性数据喂入评估，评估标准反向定义"观测什么"
• log-analyzer — 扩展服务器日志模式到 Agent 决策日志
• tool-use-patterns — 工具调用指标是可观测性的核心维度
• task-loom — 复用 Ledger 模式存储决策追踪