Agent 调试与可观测性工程 2026:从 token 级归因到生产复盘的四层架构

一、问题的提出：Agent 可观测性比传统微服务难三倍

2026 年的 LLM Agent 已经从单次 function calling 演化成递归规划、工具编排、记忆检索、长程依赖的多层状态机。一个典型的生产级 Agent 工作流可能横跨 8 到 30 次 LLM 调用、嵌套 5 到 15 层工具调用、子 Agent 委派、上下文压缩、流式响应中断恢复——而这一切都在秒级延迟预算内完成。当这样的 Agent 在生产环境出现"回答质量下降"、"延迟突增"、"token 成本失控"、"工具调用失败"时，传统微服务的"看日志、看指标、看 trace"三板斧远远不够用。

传统微服务的可观测性建立在"请求-响应"的对称模型上：一次请求对应一次 trace，一个 span 对应一个函数调用，一个 metric 对应一个计数器。但 Agent 的执行模型是非对称的：一次用户提问可能触发 N 个内部 LLM 调用，每个 LLM 调用又可能触发 M 个工具调用，每个工具调用又可能回溯到更早的推理决策。当 Agent 输出"差"的回答时,问题可能在第 3 步工具调用的 schema 错误,也可能在第 7 步上下文压缩时丢掉了关键事实,还可能在第 12 步的子 Agent 推理偏离了目标。要从"用户看到差回答"反向定位到"具体哪一步的哪个决策出错了",需要的是比 OpenTelemetry 更细粒度、比 Prometheus 更结构化、比 Sentry 更语义化的观测体系。

第二个难点是质量的可观测化。传统微服务的成功标准是 HTTP 200 + latency < p99,但 Agent 的"成功"是"回答有用、用户满意、工具调用正确、推理链合理"——这是一个多维、主观、延迟反馈的质量空间。如何把"回答质量"这一抽象概念转化为可监控的 metric?LLM-as-judge、token 级归因、用户反馈闭环、隐式信号(停留时长、复制率、重试率)如何组合成一个完整的质量可观测性面?这是过去两年 Agent 工程化最难的开放问题之一。

第三个难点是成本的归因。一个 Agent 工作流的 token 成本可能分布在 system prompt、few-shot 示例、用户问题、历史消息、工具定义、工具返回值、思维链、反思、自我评估等多个组件上。要回答"为什么这条 prompt 比上一条贵 3 倍",需要把 token 成本归因到具体的语义片段——这要求观测系统具备 prompt diff、token budget tracing、cache hit rate attribution 等 Agent 特有的能力。这篇文章要讨论的,正是这"难三倍"背后的工程解决方案:从分布式 trace 的 token 归因、运行时三轴采集(cost/latency/quality)、离线调试协议(replay/bisect)、到生产复盘(postmortem/fix-forward)的完整闭环。我们把 Agent 可观测性拆成数据模型、采集、调试、复盘四层架构,逐一展开工程真相。

二、形式化:Agent trace 的四维数据模型

Agent 的 trace 不是传统 span 树,而是一个四维张量:时间维度、层级维度、语义维度、成本维度。把这四维信息组织成一个可查询、可切片、可重放的数据结构,是所有后续可观测性工作的基础。我们用一个统一的 schema 来形式化这个数据模型:

interface AgentSpan {
  // 1. 时间维度
  span_id: string;
  parent_span_id: string | null;
  start_time_ns: number;
  end_time_ns: number;
  duration_ms: number;

  // 2. 层级维度(Agent 递归结构)
  span_type: 'root' | 'llm_call' | 'tool_call' | 'agent_plan' | 'agent_act' | 'agent_observe' | 'memory_retrieve' | 'sub_agent' | 'human_handoff';
  depth: number;
  agent_id: string;
  run_id: string;

  // 3. 语义维度(LLM 特有)
  model: string;
  prompt_tokens: number;
  completion_tokens: number;
  cache_hit_tokens: number;
  prompt_hash: string;            // 用于 replay
  completion_text: string;        // 完整 LLM 输出
  tool_definitions: ToolSchema[];
  tool_calls: ToolInvocation[];
  reasoning_chain: string[];       // 思维链
  reflection_history: Reflection[]; // 自我反思

  // 4. 成本维度
  input_cost_usd: number;
  output_cost_usd: number;
  cache_savings_usd: number;
  total_cost_usd: number;
  latency_to_first_token_ms: number;

  // 5. 质量维度(LLM 特有)
  llm_judge_score: number | null;        // 0-1
  user_feedback: 'positive' | 'negative' | null;
  implicit_signal: { dwell_ms: number; copied: boolean; retried: boolean };
  hallucination_flag: boolean;
  tool_call_correctness: number;         // 0-1
}

这个 schema 有几个关键设计决策值得解释。第一,span_type 必须显式区分 agent_plan(规划)、agent_act(执行)、agent_observe(观察),而不是简单地把整个 Agent 当作一个 LLM 调用——这反映了 Agent 的"思考-行动-观察"循环结构,让 trace 能直接回答"Agent 在哪一步决策错误"。第二,"语义维度"里的 prompt_hash、reasoning_chain、reflection_history 是 LLM 特有的字段——它们让 replay 成为可能:知道 prompt hash 就能精确复现 LLM 调用;知道 reasoning_chain 就能回答"Agent 为什么这样决策";知道 reflection_history 就能分析自我反思的失败模式。第三,"质量维度"里的 llm_judge_score、user_feedback、implicit_signal 是 Agent 可观测性比传统 APM 多出来的"软指标"——这些指标的精度直接决定了能否在生产环境实时发现质量退化。

数据模型落盘到存储时,推荐采用列式存储 + 文档存储的混合架构:LLM 调用的 completion_text、reasoning_chain、reflection_history 这类大字段放文档存储(MongoDB / DynamoDB);prompt_tokens、cost_usd、latency_ms 这类可聚合的标量放列式存储(ClickHouse / TimescaleDB);prompt_hash、model 这类维度字段放倒排索引(支持按 hash 查询所有调用)。这种分层存储让"全量 replay"和"聚合分析"两种查询模式都不妥协。

三、分布式 trace:从 span 树到 token 归因

传统的 span 树用 parent-child 关系表达调用层级,但 Agent 的 LLM span 有双向引用的特殊需求:一个 LLM 调用可能引用前序多个 prompt 片段(上下文压缩从历史消息里抽取),也可能在后续多个 span 里被作为 prompt 模板引用(子 Agent 复用父 Agent 的 system prompt)。这要求 trace 系统支持DAG 而非树的存储结构——具体实现上,可以用 OpenTelemetry 的 link 字段表达这种"非父子但相关"的关系。

# OpenTelemetry GenAI Semantic Conventions 实践
from opentelemetry import trace
from opentelemetry.semconv.ai import SpanAttributes

tracer = trace.get_tracer("agent.runtime")

with tracer.start_as_current_span("agent.run") as root:
    root.set_attribute(SpanAttributes.LLM_SYSTEM, "anthropic")
    root.set_attribute(SpanAttributes.LLM_REQUEST_MODEL, "claude-sonnet-4.5")

    for step in agent_plan:
        with tracer.start_as_current_span(f"agent.{step.type}") as step_span:
            step_span.set_attribute("agent.step.type", step.type)

            # LLM 调用
            with tracer.start_as_current_span("llm.call") as llm_span:
                llm_span.set_attribute(SpanAttributes.LLM_USAGE_PROMPT_TOKENS, len(prompt_tokens))
                llm_span.set_attribute(SpanAttributes.LLM_USAGE_COMPLETION_TOKENS, len(completion_tokens))
                llm_span.set_attribute("llm.prompt_hash", hashlib.sha256(prompt.encode()).hexdigest())
                llm_span.set_attribute("llm.cost_usd", cost)

                # 链接到历史 context(非父子, 但语义相关)
                for ctx_span_id in retrieved_context_spans:
                    llm_span.add_link(trace.Link(context=SpanContext(span_id=ctx_span_id)))

                response = llm.complete(prompt)
                llm_span.set_attribute("llm.completion", response.text[:1000])  # 截断,避免爆炸

Token 级归因是 Agent 可观测性的核心创新。传统 APM 只能告诉你"这次请求花了 10000 tokens",但 Agent 调试需要回答"这 10000 tokens 里有 2000 是 system prompt,1500 是 few-shot 示例,3000 是历史消息,500 是工具定义,3000 是当前轮输入"——精确到 token 粒度的归因让 prompt 优化变成数据驱动的工程,而不是凭感觉的玄学。

实现 token 归因有三种主流方案:方案 A 是 prompt instrumentation,在每个 prompt 构造点显式标注"这段 prompt 来自哪个组件"(system/fewshot/history/tool/user),trace span 里记录每个 segment 的 token 数。优点是精度高,缺点是侵入性强,需要在所有 prompt 构造点埋点。方案 B 是 tokenizer diff,用 tokenizer 把完整 prompt tokenize 后,与各原始片段的 tokenize 结果做对齐,差集就是新增片段的 token。优点是非侵入,缺点是对齐算法复杂(同一段文本在上下文不同位置 tokenize 结果可能不同)。方案 C 是 LLM proxy 拦截,在 LLM 调用网关处拦截完整 prompt,反向用规则和语义切分把 prompt 切成多个 segment。优点是对应用代码零侵入,缺点是切分精度有限。

工程实践上,推荐方案 A + 方案 C 组合:核心 Agent 框架内部用方案 A(已知每个 prompt 片段的来源),第三方工具调用通过 LLM proxy 用方案 C 补全。开源生态里,OpenLLMetry(Traceloop)、OpenInference(Arize Phoenix)、LangSmith、Langfuse 都提供了不同程度的 token 归因能力——其中 Langfuse 的"prompt component tagging"功能是最接近方案 A 的实现,值得在生产环境评估。

三·补充、跨团队 trace 的标准化与联邦

在多团队协作的 Agent 生态里(典型如"业务团队写 Agent 编排 / 平台团队维护 LLM 网关 / 算法团队维护模型服务"),trace schema 的标准化决定了跨团队 debugging 的可行性。OpenTelemetry GenAI Semantic Conventions 在 2025 年的 v1.27 起逐步稳定,定义了 gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.response.finish_reasons 等核心字段——这些字段让 Prometheus、Grafana、Datadog、Langfuse 都能识别同一份 trace,避免了"每家框架自定义一套 trace schema,跨团队无法对齐"的混乱。建议强制所有内部 Agent 框架遵循 OTel GenAI 语义约定,即使你不用 OpenTelemetry 后端。

联邦 trace 合并是另一个工程难题。当一个用户请求横跨业务 Agent + 工具平台 + LLM 网关三个团队的系统时,完整 trace 需要跨服务传播 trace context。W3C Trace Context(traceparent / tracestate HTTP header)是当前的事实标准,所有 LLM 网关都应该透传这两个 header。如果 trace 在某一段断裂(常见于工具平台不支持 OTel),会出现"业务 Agent 看到自己的 trace,但工具平台的 span 成了孤儿 span"的盲区——此时需要用日志关联 ID(在所有日志里写 trace_id + span_id)作为兜底,虽然不如完整 trace 优雅,但能在事后用 SQL 做 span 拼接。

四、运行时三轴采集:cost/latency/quality

Agent 的运行时可观测性必须在三个轴上同时采集:成本轴、延迟轴、质量轴。这三轴不是独立的 metric,而是相互关联、需要联合分析的张量场——成本突增可能源于质量退化(LLM-as-judge 反复重试)、延迟突增可能源于成本失控(长上下文导致 LLM 调用时间指数增长)、质量退化可能源于延迟压力(超时阈值导致 LLM 提前停止生成)。这三轴必须用统一的 trace ID 关联起来,才能在出问题时快速做三轴关联分析。

# Prometheus + ClickHouse 三轴采集配置
metrics:
  cost_axis:
    - name: agent_llm_cost_usd_total
      type: counter
      labels: [model, agent_id, tenant_id]
      buckets: [0.001, 0.01, 0.05, 0.1, 0.5, 1.0, 5.0]
    - name: agent_token_usage_p95
      type: histogram
      labels: [model, prompt_component]

  latency_axis:
    - name: agent_run_duration_seconds
      type: histogram
      labels: [agent_id, span_type]
      buckets: [0.1, 0.5, 1, 2, 5, 10, 30, 60]
    - name: agent_llm_ttft_seconds  # time to first token
      type: histogram
      labels: [model]
      buckets: [0.05, 0.1, 0.2, 0.5, 1.0]

  quality_axis:
    - name: agent_quality_judge_score
      type: gauge
      labels: [agent_id, run_type]
    - name: agent_user_feedback_positive_rate
      type: gauge
      labels: [agent_id]
    - name: agent_tool_call_error_rate
      type: gauge
      labels: [tool_name, agent_id]

质量轴的采集是 Agent 可观测性最难的部分。三个核心机制:LLM-as-judge 异步评估、用户反馈闭环、隐式信号采集。LLM-as-judge 在每次 Agent run 结束后异步触发,用另一个 LLM 评估主 LLM 的输出质量,产出 0-1 分的 judge score。这个分数的精度取决于 judge prompt 的设计——一个成熟的实践是用"rubric-based judge"(把质量拆成 5-10 个具体维度,如"是否回答了用户问题"、"是否调用了正确的工具"、"是否事实准确")而非"holistic judge"(直接打分),rubric 化能让 judge 分数的方差降低 60% 以上。

用户反馈闭环有两种模式:显式(用户在 UI 上点 👍/👎)和隐式(用户停留时长、复制率、是否重写、是否重新提问)。显式反馈信号强但稀疏(典型转化率 < 5%),隐式反馈密度高但噪声大。生产实践推荐双轨采集+融合模型:显式反馈作为 ground truth 训练隐式反馈的权重,例如"停留时长 < 5 秒 + 用户重写问题" = 强负反馈、"停留时长 > 30 秒 + 用户复制了回答" = 强正反馈。

隐式信号最容易踩的坑是代理指标失真。例如"复制率"在代码生成 Agent 里是好信号,但在闲聊 Agent 里复制率天然就低;再如"重试率"在工具调用 Agent 里应该低(意味着工具可靠),但如果 Agent 设计为"主动重试以提高成功率",重试率高反而是好的——这时候需要按 Agent 类型分别建模,不能一刀切。

五、调试协议:从离线 replay 到在线 bisect

Agent 调试最强大的工具是replay——给同样的输入和上下文,精确复现同样的 LLM 调用链。但 Agent 的 replay 比传统微服务的"录制-回放"复杂得多,因为 LLM 调用有三个不确定来源:模型非确定性(temperature > 0)、外部工具状态(数据库、API 状态)、时间依赖(缓存过期、token 配额刷新)。要实现可靠的 replay,必须把这三个不确定来源都"钉死"。

# Agent replay 引擎实现
class AgentReplayer:
    def replay(self, original_trace: AgentTrace, mode: 'strict' | 'mock_llm' | 'mock_tools' | 'full_mock') -> AgentTrace:
        replayed_spans = []

        for span in original_trace.spans:
            if span.span_type == 'llm_call':
                if mode == 'strict':
                    # 真实 LLM 调用, 但用同样的 prompt_hash + seed
                    response = llm.complete(
                        prompt=span.prompt,
                        seed=span.seed,
                        temperature=0  # 强制确定性
                    )
                elif mode == 'mock_llm':
                    # 跳过真实 LLM, 用原始 completion_text(可能略有不一致, 但快速)
                    response = span.completion_text
                elif mode == 'full_mock':
                    # 跳过 LLM + 工具, 用整个 span 的 cached output
                    response = span.cached_full_response

                replayed_span = self._record_span(span, response)
                replayed_spans.append(replayed_span)

            elif span.span_type == 'tool_call':
                if mode in ['mock_tools', 'full_mock']:
                    response = span.cached_tool_response  # 用原始响应
                else:
                    response = self._execute_tool(span.tool_name, span.tool_args)
                replayed_spans.append(self._record_span(span, response))

        return AgentTrace(spans=replayed_spans)

    def bisect(self, trace_a: AgentTrace, trace_b: AgentTrace) -> DiffReport:
        """在线 bisect: 对比两个 trace, 定位第一个行为不同的 span"""
        diff_spans = []
        for sa, sb in zip(trace_a.spans, trace_b.spans):
            if sa.completion_text != sb.completion_text:
                diff_spans.append({
                    'span_id': sa.span_id,
                    'diff_type': 'completion_mismatch',
                    'similarity': self._semantic_similarity(sa.completion_text, sb.completion_text),
                    'token_diff': sb.completion_tokens - sa.completion_tokens
                })
        return DiffReport(diff_spans=diff_spans, divergence_span_id=diff_spans[0]['span_id'] if diff_spans else None)

bisect 是 Agent 调试的"二分查找"——给定两个 trace(一个是正常行为、一个是异常行为),自动定位到第一个出现行为差异的 span。这个工具在 prompt 调优、模型升级、schema 变更时极其有用:你可以拿"上周正常工作的 trace"和"今天出问题的 trace"做 bisect,瞬间定位到"是哪个 span 因为 prompt 改动 / 模型升级 / 数据漂移而行为变化了"。生产环境推荐每周自动跑一次 bisect(对比上一周和本周的同一类 Agent 任务),作为 prompt drift、model drift、data drift 的早期预警。

调试协议还包括trace 采样策略。全量采集每个 Agent run 的所有 span 会带来 30-50% 的性能开销,在生产环境不可接受。推荐头部采样 + 尾部采样 + 错误全采的混合策略:头部 10% 全采(用于发现新模式)、错误 span 100% 全采(用于 postmortem)、P95 以上的慢请求全采(用于延迟分析)、成功且低延迟的请求按 1% 采样(用于容量分析)。Langfuse、LangSmith 都提供了这套混合采样策略的实现。

六、生产复盘:故障分类、postmortem 与 fix-forward

Agent 生产故障可以分为四类:质量退化(回答变差但没报错)、延迟突增(p99 从 3 秒涨到 30 秒)、成本失控(token 费用突增 5 倍)、工具失败(关键工具调用错误率从 1% 涨到 20%)。每一类故障的 root cause 分析路径都不同,但都需要postmortem 文化的支撑——不是追究责任,而是建立系统性的故障分类与 fix-forward 机制。

故障分类法(Blame-free postmortem)推荐使用Timeline + 5-Why + 三轴关联三件套:Timeline 还原故障发生的时间线(从第一个异常 metric 出现到完全恢复),5-Why 追问根本原因(不是"为什么 LLM 调用失败",而是"为什么 schema validation 没拦住错误参数"),三轴关联分析同时段的 cost/latency/quality 数据(成本突增和延迟突增是不是同一时刻?质量退化是不是和某个 prompt 改动同步?)。

Fix-forward比 Root cause analysis 更重要:不只回答"为什么会坏",更要回答"如何让系统以后不再犯同样的错"。Agent 系统的 fix-forward 通常包括三类:防御性补丁(给失败模式加 guardrail,如在 LLM 输出 schema 校验失败时自动重试 3 次再 fallback)、检测性补丁(把这次故障的 metric 加进 SLO 告警,如 P99 token cost > $0.5 自动 page on-call)、结构性补丁(从架构层面消除故障类别,如把所有 schema-validated tool calls 迁移到 typed tool registry 而不是 string-based function calling)。

# SLO 定义范例(Agent 特定)
slos:
  quality:
    - name: agent_quality_score_p95
      target: ">= 0.85"
      window: 24h
      error_budget_burn_rate_alert: 2x  # 2 倍速率消耗则 page
    - name: agent_tool_call_error_rate
      target: "<= 0.02"
      window: 1h

  latency:
    - name: agent_run_duration_p99
      target: "<= 10s"
      window: 5m
    - name: agent_llm_ttft_p95
      target: "<= 1.5s"
      window: 5m

  cost:
    - name: agent_run_cost_p99
      target: "<= $0.20"
      window: 1h
    - name: agent_token_cost_per_conversation
      target: "<= $0.05"
      window: 24h

  cross_axis_alerts:
    - condition: cost_p99 > 3x baseline AND quality_score_p95 < 0.7
      severity: page
      runbook: "https://wiki.internal/agent/quality-cost-tradeoff"
    - condition: latency_p99 > 5x baseline AND tool_call_error_rate > 0.1
      severity: page
      runbook: "https://wiki.internal/agent/latency-vs-tools"

两个生产事故案例(脱敏后的真实结构)展示 postmortem + fix-forward 的具体落地。事故 A:某电商 Agent 在促销日出现 P99 token cost 从 $0.08 突增到$0.45。Timeline 显示凌晨 02:30 部署了一次 prompt 改动(把"商品对比"提示词的 few-shot 示例从 3 个扩到 8 个),未经过 token budget 验证。5-Why 分析到根因:"为什么 cost 突增?"→"few-shot 变多了"→"为什么没拦截?"→"prompt 改动没有 token budget 守门人"→"为什么没有守门人?"→"团队没有把 token budget 作为 prompt review 的硬指标"。Fix-forward 产出三个 guardrail:1) CI 阶段加入 token budget assertion(任何 prompt 改动必须保证 token 数 ≤ baseline × 1.3);2) Prompt registry 接入 cost 估算;3) SLO 增加"prompt 改动前后 cost 漂移告警"。

事故 B:某客服 Agent 在新模型上线后出现"幻觉率"从 2% 涨到 15%。Bisect 显示行为差异出现在第 5 个 span(子 Agent 反思),反思 prompt 在新模型下产生了"过度自信"的输出,误判用户问题已解决。Fix-forward 包括:1) 在反思 prompt 里加入 rubric-based judge("是否真的解决了用户问题"的 5 维度评估);2) 子 Agent 反思输出加入置信度阈值,低置信度时强制 escalate 到人工;3) 模型升级流程加入"历史 trace 回放评估"环节,只有历史 case 的质量不退化才允许上线。

七、对工程实践的推论

基于上面六节的分析,我们提炼出五条对工程实践最关键的推论。

推论一:可观测性是 Agent 框架的第一公民,不是事后补丁。传统微服务的可观测性常常是"先上线,后加监控";但 Agent 系统的 prompt 改动频率远高于传统代码(可能一天改几十次),没有原生可观测性的框架会在第一周就变成黑盒。选型时把"trace SDK 完善度"、"quality 评估开箱即用"、"replay 能力"作为硬指标,而不是 nice-to-have。

推论二:质量可观测化的 ROI 高于成本可观测化。很多团队第一优先级是接 LangSmith 看 token 成本,但真正决定 Agent 能否 scale 的是质量——质量退化会让用户流失,成本失控只会让 CFO 不满。建议的优先级是:质量先于成本, latency 与质量同等, 成本最后。

推论三:replay 能力是 Agent 团队的"测试基础设施"。没有 replay,任何 prompt 改动都是盲改;有了 replay,可以 A/B 测试 prompt 改动对历史 case 的影响,精确量化"这次 prompt 优化让 32% 的历史 case 变好了,18% 变差了"。建议把 replay 覆盖率(能 replay 的历史 trace 比例)作为 SRE 的关键 metric。

推论四:三轴关联告警比单轴阈值告警更有效。单独看"cost > $0.5"会淹没在告警海里;但"cost >$0.5 AND quality < 0.7"指向真正影响业务的故障。建议 SLO 告警都设计为多轴复合条件,减少 alert fatigue。

推论五:postmortem 的最高产出是 fix-forward 的 guardrail 沉淀。每次 postmortem 必须产出至少一个 guardrail(自动化的故障防御机制),而不是停留在"人工事后分析"。这种制度化的 fix-forward 文化能让团队的故障率呈指数下降,而不是线性下降。

推论六:可观测性数据本身要分级访问,不能泄露用户隐私。Agent trace 里包含完整的用户提问、LLM 响应、工具调用结果,这些数据可能包含 PII(个人身份信息)、商业机密、未公开产品决策。trace 存储必须做字段级加密 + 访问审计 + 保留期限管理——典型的合规要求是 PII 字段(用户输入、工具返回值里的个人信息)在 30 天后自动脱敏或删除,运营指标(成本、延迟、质量分)保留 1 年以上用于趋势分析,trace 完整内容保留 7 天用于 postmortem。建议在 trace 写入前用 Presidio 或自研正则做 PII 检测,命中后立即 token 化或哈希化。

推论七:LLM 网关是观测体系的咽喉,所有流量必经。在 LLM 网关层面(自研或 LiteLLM / Portkey 等开源方案)统一做 token 归因、cache hit 统计、model fallback 记录、retry 计数,能把"业务 Agent 框架内埋点"的开销降到最低——业务侧只关心业务 span,平台侧统一处理 LLM 相关 metric。这个"分层埋点"模式与微服务的"RED method + USE method"分层埋点一脉相承。

八、讨论:与 LLM 应用可观测性的异同

Agent 可观测性与单体 LLM 应用可观测性有三大区别。第一,Agent 的执行链更长(单次用户提问可能触发 30+ 内部 LLM 调用),要求 trace 系统支持更深的嵌套和更智能的折叠(自动折叠"成功且低延迟"的子 span)。第二,Agent 的状态空间更大(工具调用结果、记忆检索、上下文压缩都是可变状态),要求 replay 系统能精确还原"这个时刻的 Agent 状态",包括所有 memory 和 tool cache 的快照。第三,Agent 的"质量"评估更复杂(回答质量、工具调用正确性、推理链合理性、自我反思效果),单一 LLM-as-judge 不足以覆盖,需要多 judge 融合 + 用户反馈闭环 + 隐式信号加权。

与传统的 AIOps(AI for IT Operations)也不同:传统 AIOps 用 AI 分析运维数据,目标是用机器学习替代人工规则;Agent 可观测性是用可观测性方法分析 AI 系统的行为,目标是把 AI 系统的执行变得可调试、可验证、可优化。前者是 AI → Ops,后者是 Ops → AI,方向相反,工具栈也大不相同。

局限方面,本文没有深入讨论多模态 Agent 的可观测性(文本 + 图像 + 音频混合输出的 trace 模型)、长期记忆 Agent 的可观测性(跨 session 的记忆演化追踪)、联邦 Agent 的可观测性(多个独立 Agent 协作时的全局 trace 合并)。这些都是 2026 年下半年的前沿方向,值得后续专题展开。

九、给 SRE 与 Agent 工程师的可观测性清单

给 SRE 的清单:1) 部署 OpenTelemetry Collector + ClickHouse/DuckDB 作为 Agent trace 的存储后端;2) 配置三轴 metric(cost/latency/quality)的 Prometheus exporter;3) 部署 Langfuse 或 Arize Phoenix 作为 trace 可视化前端;4) 实现 SLO 三轴复合告警;5) 建立每周 bisect 任务的自动化 pipeline;6) 部署 LLM-as-judge 异步评估服务;7) 建立 token 归因的 Prometheus dashboard。

给 Agent 工程师的清单:1) 在 Agent 框架内嵌入 trace SDK(不要寄希望于外部 proxy);2) 每个 prompt 构造点显式标注组件来源(便于 token 归因);3) 关键决策点(add reflection, retry, fall-through)必须作为独立 span;4) 实现 agent 状态的快照/恢复机制(便于 replay);5) 工具调用必须记录完整的 request/response(便于 postmortem);6) 集成 LLM-as-judge 在 dev 环境(每次代码改动自动跑历史 case 评估);7) 把 prompt diff 作为必检项(类似代码 diff, prompt 改动必须 review)。

最后,Agent 可观测性不是一个"做完了"的项目,而是一个持续演进的能力——随着 Agent 系统变得更复杂(更长上下文、更多工具、更深递归、更多子 Agent),观测体系也必须同步演进。建议把"可观测性 debt"作为 Agent 团队的核心技术债管理对象,定期评估、持续投入。

参考文献

1. OpenTelemetry GenAI Semantic Conventions, CNCF, 2025. https://opentelemetry.io/docs/specs/semconv/gen-ai/
2. Langfuse Documentation: Prompt Management and Tracing, Langfuse, 2026. https://langfuse.com/docs
3. Arize Phoenix: Open-source LLM Tracing and Evaluation, Arize AI, 2026. https://docs.arize.com/phoenix
4. OpenLLMetry: Open-source Observability for LLM Applications, Traceloop, 2025. https://github.com/traceloop/openllmetry
5. LangSmith: Production-grade LLM Application Platform, LangChain, 2026. https://docs.smith.langchain.com
6. Google SRE Book, Chapter on Distributed Tracing and Observability, Google, 2024.
7. Elastic Observability for LLM Applications, Elastic, 2025. https://www.elastic.co/observability/llm
8. Honeycomb: Observability for Production AI Systems, Honeycomb.io, 2026.
9. Prompt Engineering for LLM-as-Judge Systems, Anthropic, 2025.
10. Datadog LLM Observability Best Practices, Datadog, 2025.
11. Cost Attribution in Multi-Agent LLM Systems, ACM SIGMOD, 2025.
12. Token-Level Prompt Diff for LLM Optimization, NeurIPS Workshop, 2025.
13. Replay-based Debugging for Non-Deterministic AI Systems, USENIX OSDI, 2025.
14. SLO Engineering for AI Services, Google Research, 2025.

一句话摘要:把 Agent 可观测性拆成 trace 数据模型、运行时三轴采集、replay/bisect 调试协议、postmortem+fix-forward 复盘四层架构,从 token 级归因到三轴 SLO 告警,建立数据驱动的 Agent 工程质量闭环。