第 17 章 AI AgentAgentic Patterns可观测性

第 17 章可观测性：看见 Agent 在想什么、在干嘛

评测验得了已知，看不见未知

第 16 章把评测基建搭起来了。但评测是对着已知用例验，生产里还有大量看不见的失败：Agent 走了个错误方向没人发现，推理过程里藏着不该外泄的草稿，一次"bug"其实是提示词歧义。没有可观测性，这些全靠事后翻日志，痛苦且低效。

这一章讲四个模式，从"看得见"到"防泄漏"到"能干预"：

LLM Observability（LLM 可观测）：span 级追踪 Agent 工作流。
Evidence-Layered Evaluation（证据分层评估）：把评估证据分层存，失败可诊断。
Reasoning-Token Firewall（推理 token 防火墙）：结构上只取答案流，不泄漏思维链。
Chain-of-Thought Monitoring & Interruption（CoT 监控与中断）：实时盯推理，走偏就拦。

模式一：LLM 可观测（LLM Observability）

问题

Agent 带来非确定性：同样的输入可能产出不同输出。Agent 干了件次优的事，用户会把它当成"bug"报上来，哪怕只是提示词歧义。调试这类问题要穿过多步工作流追踪，但标准日志（CloudWatch、Lambda 日志）翻起来极其痛苦。工程师需要轻松访问工作流执行细节来快速调试，否则 Agent 根本不会被采用。

方案

接入 LLM 可观测平台（Datadog LLM Observability、LangSmith 等），提供 Agent 工作流的 span 级追踪。不是去原始日志里大海捞针，而是有一个可视化 UI 显示 Agent 执行的每一步。

关键能力：

Span 可视化：看到每次 LLM 调用、工具使用、中间结果。
工作流链接：从用户输入一路追踪到所有子步骤再到最终输出。
仪表盘：成本、延迟、成功率的聚合指标。
可访问的调试：非工程师不用日志权限也能调试。
事件溯源：结构化日志支持重放、状态重建、验证。

从标准日志的演进（Will Larson 的三步）：

Print to stdout：输出到 Lambda 日志（难访问）。
Slack 频道：发运行摘要 + AWS 日志链接（好一点，还是捞日志）。
LLM 可观测：可视化 span 追踪，轻松导航。

Agent 运行 → 可观测 SDK → Span: LLM调用1 / Span: 工具使用 / Span: LLM调用2
    → 追踪 UI → 调试视图

证据

证据等级：提出（proposed），来自 Will Larson（Imprint）。
相关研究：OpenAI 的 CoT 监控研究（2025）、ESAA（2026）把事件溯源用到自主 Agent、Korbak 等人（2025）讨论 CoT 的可监控性。

怎么用

接入步骤：

选平台：Datadog LLM Observability、LangSmith、Arize 等。
装 SDK：加到 Agent 代码里（往往就一两行）。
配追踪：给工作流、用户、环境打标签。
开访问控制：给更大范围的团队（不只是工程师）。

from ddtrace import tracer

# 自动追踪 LLM 调用
@tracer.wrap("agent_workflow")
def run_agent(query):
    result = agent.run(query)
    # 每次 LLM 调用、工具使用都变成一个 span
    return result

最佳实践： 全部打标签（工作流名、用户 ID、环境 prod/staging）；让可观测 UI 能从聊天里点开；别只给工程团队开权限，工作流创建者也需要可见性；监控聚合指标（成功率、延迟、成本随时间）；用结构化格式（JSONL + schema 版本化）给长期系统；在写入时聚合，日志富化在捕获时做，而不是查询时。

取舍

好处：快速调试，可视化导航复杂工作流；非工程师无日志权限也能调试；看跨很多运行的聚合模式；span 级细节，能钻进执行任何一步。
代价：供应商依赖，被锁在可观测平台上；企业级可观测可能很贵；有开销（延迟，通常很小）；可见性和安全之间要平衡。
什么时候别用：简单确定性的工具（没有 Agent 行为）；单步操作（标准日志够用）；预算紧张付不起可观测费用。

模式二：证据分层评估（Evidence-Layered Evaluation for Interactive Agents）

问题

交互式 Agent 到达错误结果的原因很多：烂计划、点错了、站点瞬时响应、或者评估器观察不到相关状态。一个单一的成功/失败分数把这些原因全藏起来了，让回归难以复现，尤其是任务跑在实时网站或桌面应用上时。

方案

分层捕获评估证据，同时把任务结果作为主决策信号。一次运行记录：(1) 最终状态或请求级断言，(2) 按顺序执行的动作，(3) 截图或其它视觉状态，(4) 时机重要时的会话重放，(5) 浏览器状态不够时的网络请求，(6) 导致每个动作的 Agent 消息。验证器报告结果，并把结果链接到能解释它的最小证据层。

流水线：

任务 + 策略 → 隔离运行 → 动作/视觉/网络/消息捕获
                        ↓
                   结果验证器
                        ↓
              分数 + 证据包

各层要带时间戳，用运行 ID 关联。隐私敏感的任务可以禁用某些采集器，但评估器要声明哪些层可用，而不是把缺失证据默默当成成功运行。

证据

证据等级：中（medium），来自 ClawBench（TIGER-AI-Lab）。
有价值发现：分离证据层支持对规划、交互、环境失败的诊断；请求级断言能验证视觉上没暴露的状态转换；可重放的证据包让人工裁决和回归分析变得可行。
未验证：每层相对价值取决于任务和站点；没有通用的层排序或存储预算。

怎么用

运行前先定义任务级成功断言（状态变化或拦截到的请求）。
在隔离的浏览器或桌面环境里跑 Agent，给每个事件挂稳定的运行 ID。
默认记录动作和 Agent 消息；截图、视频、网络捕获在它们能回答已知的可观测性缺口时再加。
先评断言，再用证据包给失败分类、裁决模糊结果。
保留一个紧凑的 manifest（时间戳、harness/模型版本、任务版本、启用的证据层），让另一个评估者能复现对比。

取舍

好处：失败分析更可行动；回归分流更容易；同时支持自动化验证和人工审查；让"真实任务上的表现"这个说法可审计。
代价：每加一层都增加存储和插桩开销；网络和消息日志可能含敏感数据；时钟漂移和不完整捕获会搞乱关联；证据更丰富不保证评估器更正确。

模式三：推理 token 防火墙（Reasoning-Token Firewall）

问题

推理模型在一条响应里发出两类 token：私有的思维链和最终答案。当 harness 从整个流里拼"结果"，然后用字符串启发式事后剔除推理，迟早会泄漏。 推理没有稳定的分隔符，形状随模型和版本变化，漏掉一个情况，原始思维链就被提交进文件、记忆存储、通知、或链上下一个 Agent 的上下文。

这个泄漏不是表面问题。思维链里常有半成形的结论、被丢弃的计划、敏感的草稿数据。一旦落进持久化产物，它就和真正的答案无法区分，膨胀记忆和上下文，还可能暴露模型从没打算发布的内容。

方案

把响应当成带类型的事件，做"选择"，不做"剔除"。 提供商已经标注了哪些块是推理、哪些是答案（type: "thought" vs type: "text"、reasoning_content vs content、thinking 块 vs text 块）。只拼接 answer 类型的事件来组装结果。 推理类型的事件根本不会被读进结果路径，所以防火墙是组装时的结构性保证，不是对混合文本的事后过滤。

result = ""
for event in stream:
    if event.type == ANSWER:      # 例如 "text" / content / text-block
        result += event.data
    # 推理事件 ("thought" / reasoning_content) 在这里永远不会被读
emit(result)

设计要点：

选择是答案类型事件的白名单，不是推理标记的黑名单。黑名单在遇到第一个没见过的标记时就"打开"了；白名单是"关闭"的。
在产物组装的唯一咽喉点强制它，这样每个下游消费者（文件写入、记忆、通知、下一个 Agent）都免费继承这个保证。
跨 harness 归一化。每个 harness 的通道标签不一样，在 adapter 里把它们全部映射到内部统一的"答案 vs 推理"区分，让下游任何 skill 或 Agent 都无法重新引入泄漏。

证据

证据等级：中（medium），来自 Aeon 的 harness-adapter（生产验证）。
有价值的发现：公开的多 harness adapter（aeonfun/aeon）里，xAI 路径只用 type=="text" 块拼 .result，从不读 type=="thought"；Mistral-Vibe 路径只取 assistant 的 content，不取 reasoning_content；Codex 路径取最终 agent_message，不是推理。一个防火墙，六个 harness。
那个项目的历史记录泄漏思维链，正是发生在"从整个流拼结果"的时候。切到结构性答案选择后，泄漏作为一类问题被消除，而不是一个案例一个案例地补。
未验证：这个泄漏在其它框架的普遍程度；每个提供商是否在每种模式（流式 vs 非流式、工具调用、拒绝）下都保证干净的 type 标签。

怎么用

只要 harness 把推理暴露成独立流通道（OpenAI 推理模型、Anthropic extended-thinking 块、DeepSeek reasoning_content、xAI thought 块），并且答案会被持久化或转发，就用它。
前置条件：能标注事件类型的流式或 JSON 模式；每个 harness 一个组装函数。
把防火墙放在把各 harness 归一化成你内部信封的 adapter 里。下游 skill 之后想意外重新引入泄漏都做不到。
加一个回归测试：喂一个含推理块的流，断言这些文本绝不出现在输出的结果里。

取舍

好处：消除一整类思维链泄漏 bug，而不是一个个补；对模型和版本变化稳健，因为它靠提供商的事件类型，不靠脆弱的推理分隔符；单点强制，记忆和产物保持干净、更小。
代价：依赖提供商正确标注通道，一个标错块就能击穿它；如果确实想要推理（调试、透明性），需要单独的 opt-in 通道；非流式或未类型化的响应没法用结构性选择，只能退回更弱的启发式。

模式四：CoT 监控与中断（Chain-of-Thought Monitoring & Interruption）

问题

AI Agent 可能沿着误导性的推理路径跑很久才产出最终输出。等开发者发现方向错了，时间和 token 已经浪费在一个根本错误的方向上。传统的"发射后不管"式 Agent 执行，没有早期纠偏的机会。

方案

对 Agent 的中间推理步骤做主动监视，具备在跑完整个执行序列之前中断和重定向的能力。实时监控思维链输出、工具调用、中间结果，保持"手指放在扳机上"，尽早抓住错误方向。

关键机制：

实时推理可见性：

把 Agent 的思考过程实时暴露出来。
显示工具使用决策和中间结果。
在代码执行前显示规划步骤。

低摩擦中断：

快速暂停能力（键盘快捷键、UI 控件）。
中断时保留部分工作（KV 缓存检查点）。
允许执行中途注入上下文。

中断触发：

手动干预（用户发起）。
置信度阈值（模型自信时提前退出）。
预算限制（token/时间约束）。
安全违规（检测到有害推理）。

早期检测信号：

选错文件。
初始工具调用里就有错误假设。
第一步推理就误解了需求。

开发者 ← Agent 显示推理: "我要改 auth.ts..."
Agent → 工具: 开始读文件
开发者 → Agent: 中断!（文件错了）
开发者 → Agent: "改用 oauth.ts"
Agent → 工具: 读 oauth.ts
Agent → 开发者: 显示更新后的推理
注: 第一次工具调用内就完成了纠偏

证据

证据等级：新兴（emerging），来自 Tanner Jones（Vulcan）。
相关研究：Princeton 等人（2025）的 "thinking intervention"（在生成期间策略性插入/修改思考 token）；Dynamic Early Exit（2025）用置信度提前停止，约 75% 的样本存在提前退出机会。
要警惕的坑：当前模型的 CoT 经常不反映真实推理（Claude 3.7 约 25%、DeepSeek R1 约 39% 的忠实度），所以别把推理当绝对真相。

怎么用

什么时候用：

复杂重构，选错文件代价高。
需要深入理解代码库的任务。
高风险操作（数据库迁移、API 变更）。
Agent 可能误解含糊需求时。
迭代速度重要的开发工作流。

实现途径：

框架级：LangGraph 的 interrupt() + MemorySaver 检查点，支持静态断点（interrupt_before/interrupt_after）和动态事件驱动中断；LlamaIndex 的 AgentRunStepStartEvent/AgentRunStepEndEvent 事件日志；AgentScope 的带上下文保留的优雅取消。
UI 级：实时流式显示 Agent 推理；提供醒目的中断/停止控件；尽可能在执行前显示工具使用；允许不重启的内联纠偏。
CLI 级：流式输出推理；Ctrl+C 中断并保留上下文；能带额外上下文重定向；纠偏后能恢复。

最佳实践：

密切盯第一次工具调用，最初的行动暴露理解。
注意假设声明（"基于 X，我打算做 Y"这种话）。
尽早中断，别等错误序列跑完。
给具体纠正，帮 Agent 明白错在哪。
用澄清问题，有时暂停问清楚比重定向更好。

取舍

好处：防止时间浪费在根本错误的方向上；从昂贵的模型调用里榨出最大价值；支持人机协作解决问题；减少看着可避免的错误发生时的挫败感；在初始工具调用内就抓住误解。
代价：需要人类持续注意（不是全自主）；过早触发会打断有价值的探索；可能让日常任务依赖人工监督；监视 Agent 推理增加认知负担；有过度纠正、扼杀合理创造性方法的风险；忠实度低，当前模型的 CoT 常常不是真实推理，别全信。

四个模式怎么选

场景	推荐模式
想可视化调试多步 Agent 工作流	LLM 可观测
交互式 Agent 失败，原因难定位	证据分层评估
推理模型输出会被持久化 / 转发	推理 token 防火墙
想实时盯推理，走偏就拦	CoT 监控与中断

四个模式是可观测性的四个层次：LLM 可观测解决"看得见每一步"，证据分层解决"失败能诊断"，推理防火墙解决"该看的才看得见，不该看的绝不外泄"，CoT 监控解决"看的同时还能干预"。前两个是事后看，后两个是运行时管。

实践清单

接 LLM 可观测平台，span 级追踪 LLM 调用、工具使用、中间结果
全部打标签（工作流名、用户 ID、环境），写入时聚合，结构化日志带 schema 版本
交互式 Agent：分层捕获证据（断言 / 动作 / 截图 / 重放 / 网络 / 消息），用运行 ID 关联
评估器声明哪些证据层可用，别把缺失当成功
推理模型：只拼 answer 类型事件组装结果，推理 token 结构性丢弃（白名单，非黑名单）
防火墙放 harness 归一化的咽喉点，加回归测试断言推理文本不出现在结果里
高风险任务开 CoT 监控：实时显示推理、低摩擦中断、保留部分工作
密切盯第一次工具调用，尽早中断，给具体纠正
记住 CoT 忠实度低（25%-39%），别把推理当绝对真相

本章小结

LLM 可观测：span 级追踪 + 可视化 UI + 聚合指标，调试不再大海捞针。
证据分层评估：断言 + 动作 + 视觉 + 网络分层存，失败可诊断可复现。
推理 token 防火墙：只选 answer 类型事件，思维链结构性不落地，消灭一整类泄漏。
CoT 监控与中断：实时盯推理，走偏就拦，错误方向不再白烧 token。
可观测性是可靠性的眼睛：评测告诉你"坏没坏"，可观测告诉你"为什么坏、坏在哪"。

下一章讲韧性工程：系统总会有部分失效，怎么让它扛得住？熔断器、模型回退、金丝雀发布、Dead-Man's Switch。

第 17 章 可观测性：看见 Agent 在想什么、在干嘛