主题
第 13 章 Agent 的可观测性 · 面试能讲版
核心观点 + 逻辑框架 + 采集架构全景（治理篇第 1 章）
▍速览
一句话版（开场，约 20 秒）
Agent 可观测性不是看请求成不成功，而是还原 Agent 实际执行了什么：Session 管关联范围、Trace 管一次活跃执行、Span 管具体操作；三层采集通道（应用埋点插桩、Coding Agent 的 Hook+Daemon、eBPF 无侵入），Trace·Metrics·Log 互补；之上再做审计——用可复核的证据链，把原始事实→候选信号→已确认事件分层。
一段话版（展开，约 90–120 秒）
治理的前提是看见，看见的前提是定义执行语义。观测模型只有三层：Session 关联多次交互，Trace 承载一次外部输入触发的活跃执行，Span 是基本执行单元——并用统一执行语义（ENTRY/AGENT/STEP/LLM/TOOL/GUARDRAIL/HITL/COMPACTION 等 12 种）把不同框架的术语拉齐，跨请求等待时结束旧 Trace、恢复时新建 Trace 并用 Trace Link 关联。采集分三条通道：高代码 Agent 用 SDK 埋点（Entry/Agent/ReAct Step/LLM/Tool 层次，装饰器+中间件+框架回调）到进程级自动插桩再到 K8s 注入，进程内只保留一套 TracerProvider 避免重复插桩；Coding 与通用 Agent 用适配器+独立 Daemon，从原生回调、Hook、transcript 三类来源增量读取，按稳定标识把遥测事件映射成 Trace；eBPF 则完全无侵入，把模型调用看成网络请求、工具调用看成进程/文件/网络事件。指标与日志互补：Metrics 用低基数字段看趋势与告警，Trace 还原单次调用链，日志事件保存明细；Token 成本要按输入、输出、缓存分记，缓存命中率是独立口径。最上层是 Agent 审计：最小证据链（主体授权→意图→执行事实→结果证据）、分层检测（原始事实→候选信号→上下文研判→已确认事件，三态不能当安全结论）、调查处置闭环（检测与拦截分开建模）。基础设施层面，AI 网关观测模型访问与 MCP 调用，推理引擎用模型级信号+Pod/GPU 下钻+并发分析还原 Wait-Prefill-Decode 与 Continuous Batching 的相互影响，工具与沙箱用"工具语义与运行时事实"双层关联互证，支撑性能、成本、安全三类诊断。
- 一个命题：可观测性=运行可见+行为可解释；请求成功≠任务成功
- 三层模型：Session（关联范围）· Trace（活跃执行）· Span（基本单元）
- 三种接入：SDK 埋点 · 自动插桩/K8s 注入 · Hook+Daemon；eBPF 无侵入
- 四类指标：错误 · 延迟（TTFT/TPOT）· Token 成本 · 任务效果
- 审计闭环：可复核证据链 · 分层检测 · 调查处置（检测≠拦截）
一句话（收尾）
可观测性交付的是"可复核的证据"，不是"好看的报表"——它回答三个问题：Agent 实际做了什么、为什么这么做、是否产生了真实副作用。
▍逻辑框架（记忆卡片）
① 命题：Agent 可观测性的定义与边界
面向生产运行阶段的观测与审计能力：还原 Agent 执行路径、量化运行质量、支撑审计与归因——不是训练监控，也不是通用 AIOps 指标展示。Agent 不可观测的根源在于执行动态可变、任务质量难以界定、外部依赖不受控、跨会话关联困难、异构组件多，以及观测完整性、成本与安全难以平衡——Prompt、响应、参数与结果体量大且敏感，要在完整性、采集开销与数据安全之间平衡。回答三个问题：实际做了什么、为什么这么做、是否产生真实副作用。
观测挑战：任务质量难界定 · 动态路径 · 外部依赖受限 · 跨会话关联难 · 完整性/成本/安全平衡
② 观测模型：Session / Trace / Span
- Session：关联多次交互的范围（可跨多 Trace、可跨较长时间间隔）；Trace：一次外部输入触发的活跃执行；Span：基本执行单元（做了什么·花了多久·结果如何·由谁调用）
- 跨请求等待：等待超过阈值时结束旧 Trace，恢复时新建 Trace 并用 Trace Link 关联——把"挂起的业务"与"活跃执行"分开，避免把整个长任务压进一条会过期的 Trace
- 执行语义：ENTRY / AGENT / WORKFLOW / STEP / LLM / RETRIEVAL / MEMORY / TOOL / GUARDRAIL / COMPACTION / HITL / INTERRUPT——把框架术语统一成语义层，支持跨应用查询聚合
③ 采集架构：四层 + 三信号互补
- 被观测对象层：任务交互 / Agent 执行 / AI 基础设施；采集接入层：SDK 埋点·自动插桩·K8s 注入·Hook+Daemon·eBPF；统一处理层：统一采集网关做协议适配、批处理、规范化、采样、脱敏；存储分析层：Trace / Metrics / Log / Event 存储与分析
- Trace 还原单次调用链；Metrics 做趋势与告警，标签选可控低基数字段（业务来源·阶段·模型），禁用 Trace ID/请求 ID 等高基数字段；日志事件保存明细，最终用于审计
- 三级信号可关联：用指标发现异常，用 Trace 定位请求，用日志还原细节——采样策略需权衡成本与完整性
④ 高代码 Agent 三种接入方式
- SDK 手动埋点（语义最强）：Entry / Agent / ReAct Step / LLM / Tool 分层，装饰器 + 中间件 + 框架回调；调用级信息（输入输出摘要、Token、耗时）由埋点捕获
- 进程级自动插桩：loongsuite-distro / loongsuite-bootstrap，无需改代码自动生成执行 Span
- K8s 自动注入：Operator / ack-onepilot 注入探针；避免重复插桩：进程内只保留一套 TracerProvider，ID 生成、采样、属性合并只做一次
⑤ Coding / 通用 Agent：适配器 + 独立 Daemon
- 来源三类：原生回调 / Hook / transcript；独立 Daemon 在 Agent 运行环境外增量读取，降低对被测 Agent 的侵入
- 映射规则：按 agent/task id 关联，遥测事件→Trace 映射；LLM 配对、STEP 拆分仅在证据可靠时建立，other 与 agent.input 的兼容副本排除，不臆造父子关系
- 增量读取用游标与去重，但它不是 Checkpoint——Checkpoint 是业务可恢复状态，去重只是采集幂等
⑥ eBPF 无侵入观测（AgentSight）
- 模型调用 = 网络请求/响应：捕捉请求方向、模型地址、输入输出规模、耗时；工具调用 = 进程/文件/网络事件：捕捉执行的命令、读写、外联
- 对不可改代码、二进制或隔离较强的 Agent 是唯一可行路径；但缺业务语义——补不了 Agent 意图，须与应用侧埋点/审计互证
⑦ 指标与任务效果：错误 · 延迟 · 成本 · 质量
- 错误与稳定性：错误分类（工具/模型/配置）、首失败位置、端到端 P50·P95·P99、模型 TTFT 与 TPOT——用户感知 = 端到端，模型耗时只是其中一段
- Token 成本：输入、输出、缓存分记；缓存命中率是独立口径，不能混进"产出"；按低基数字段（模型/场景/任务类型）归因
- 任务效果：三层评价（最终结果 / 关键步骤 / 执行轨迹）+ 9 类评估器；LLM-as-a-Judge 是实现方式，不是天然权威，需人工抽样校准
⑧ Agent 审计：证据链 + 分层检测 + 闭环
- 最小证据链：主体授权（谁）→ 意图授权（要做什么）→ 执行事实（实际发生）→ 结果证据（产物/副作用）——四环缺一即不可复核
- 分层检测：原始事实（追加写、只记录）→ 候选信号（检测规则派生）→ 上下文研判 → 已确认事件——中间态不能当安全结论
- 调查处置闭环：检测与拦截分开建模——先确认事实再决定动作，处置动作本身也要留审计
⑨ 基础设施观测：网关 · 推理引擎 · 工具沙箱
- AI 网关：模型访问 7 方向 + MCP 调用 5 方向指标（流量/错误/延迟/Token），网关是统一观测点
- 推理引擎：模型级四类信号 → Pod/GPU 下钻 → 调用链 Wait-Prefill-Decode → 并发分析还原 Continuous Batching 相互影响（大 Prefill 阻塞同批 Decode / 并发突增排队）；P-D 分离时两阶段分池，用虚线关联同请求
- 工具与沙箱：工具语义（应用侧：名称/参数/意图）与运行时事实（沙箱侧：命令/进程/文件/网络）双层关联互证；六类观测（调用事实·生命周期·进程·资源·副作用·策略结果）+ 三类诊断（慢在哪/失败原因/成本与安全归因）
- 排障闭环：指标发现异常 → Trace 找慢请求 → 并发分析还原现场 → Pod/GPU 验证根因 → 优化后同口径对比验证
▍逻辑全景图（可观测性：从被观测对象到审计证据链）
四层采集管道 + 三种接入 + 三信号互补，上承指标与任务效果，下接审计证据链
- 观测模型/语义
- 采集与处理
- 指标/效果
- 审计证据链
示意 · 按第 13 章正文重构（采集四层 + 三信号 + 审计证据链；原书另有 13.2.1 采集架构图与 13.2.3-2 执行到 Trace 映射图）
▍书中关键图（SVG 重绘版 · 示意）
执行过程到 Trace 的映射：Coding/通用 Agent 采集的遥测事件如何进入语义 Span（对应原书图 13.2.3-2 语义）
示意 · 按正文重绘（原书图 13.2.3-2 的执行过程到 Trace 映射）
原书 Mermaid 图（可编辑）
以下图来自原书 Markdown，保留原始结构，便于修改和对照。