2026 年 AI 代理可观测性：追踪每一步，评判每一条轨迹

代理与普通软件的失败方式不同。传统服务要么返回 200，要么抛出错误；而代理可能做了三次不必要的工具调用、一次语法上完全正确但方向错误的操作之后，返回一个自信、格式良好、却完全错误的答案。二进制的是/否监控对此视而不见。分析机构估计 2026 年初只有约 15% 的 GenAI 部署做了埋点，而 Gartner 预测到 2026 年底 40% 的企业应用将包含任务型代理——从不足 5% 起步。当代理开始替企业行动，「它为什么这么做」就不再是可选问题。答案需要逐步骤追踪、持续评估与 span 级成本核算。

1. 为什么代理需要自己的可观测性

确定性服务可以用经典三支柱观察：指标、日志、追踪。代理以两种方式同时打破这个模型。第一，同样的输入不一定产生同样的行为——温度、检索结果、工具可用性都会改变代理路径，同一提示词两次运行可能触发不同的工具序列，你需要观察行为的分布而非单个样例。第二，失败很少以错误的形式浮出水面：代理返回了内容，格式良好，甚至看似合理，但它是错的，或者绕了昂贵的弯路，或者调用了一个根本不需要的工具——这些都不会触发 500。这就是为什么步骤级追踪是地基。

// Span-per-tick: each reasoning step becomes a nested span.
// The four agent operation types from the OTel GenAI spec:
//   create_agent | invoke_agent | invoke_workflow | execute_tool
import { trace } from '@opentelemetry/api';
const tracer = trace.getTracer('agent');
export async function runAgent(task) {
  const workflow = tracer.startSpan('invoke_workflow', { kind: SpanKind.INTERNAL });
  const step = tracer.startSpan('execute_tool', {
    attributes: { 'gen_ai.tool.name': 'search', 'gen_ai.agent.name': 'researcher' }
  });
  const result = await search(task.query);
  step.end(); workflow.end();
  return result;
}
// A five-agent pipeline without this hierarchy is guesswork.

2. 逐 tick 追踪：把推理过程变成嵌套 span

核心机制是 span-per-tick：代理执行的每一个离散推理步骤生成分布式追踪里的一个 span，按层级嵌套——一次完整代理运行的父追踪包含每次 LLM 调用、工具调用、记忆读写的子 span。OTel GenAI 语义约定为此定义了四种代理 span 操作：create_agent、invoke_agent、invoke_workflow、execute_tool。微妙之处在于 span kind：代理在远端运行时 invoke_agent 是 CLIENT（如 OpenAI Assistants API），在自有进程内运行时是 INTERNAL（如 LangChain 代理）；多代理系统中，一个 INTERNAL invoke_workflow span 是包裹多个 invoke_agent 子 span 的父节点——正是这个层级让你能沿一条追踪跨代理交接追踪任务。

# Two histograms are effectively mandatory: export them or you
# cannot reason about cost or speed.
from opentelemetry import metrics
meter = metrics.get_meter("genai")
latency = meter.create_histogram("gen_ai.client.operation.duration",
    description="Latency of model operations", unit="s")
tokens = meter.create_histogram("gen_ai.client.token.usage",
    description="Token consumption, by input/output")
# For common providers, instrumentation is close to free:
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument()   # semconv spans, no manual code

3. 标准层：GenAI 语义约定与 MCP 追踪

这个领域最重要的进展不是某个产品，而是一份规范。OpenTelemetry GenAI 语义约定定义了 gen_ai.* 的通用属性词汇，覆盖六层：客户端模型调用 span、代理与工作流 span、MCP 约定、语义事件、指标、供应商专属属性。两个直方图指标是生产部署的事实标准：gen_ai.client.operation.duration（秒级延迟）与 gen_ai.client.token.usage（按输入/输出拆分的 token 消耗）——不导出它们就无法核算成本与速度。工具层曾是黑盒；OTel v1.39 为 MCP 添加了 mcp.method.name、mcp.session.id、mcp.protocol.version 等属性，且设计巧妙：检测到外层已追踪工具执行时，它只是丰富现有 execute_tool span，而不是创建重复 span。

// The tool layer used to be the black box in agent traces.
// OTel v1.39 added MCP semantic conventions: when MCP
// instrumentation detects an outer GenAI span already tracking
// the tool execution, it ENRICHES that span instead of
// creating a duplicate -- so an agent calling ten MCP servers
// traces as cleanly as one calling a local function.
execute_tool span attributes:
  gen_ai.tool.name: "filesystem"
  mcp.method.name: "tools/call"
  mcp.session.id: "sess_9f2a"
  mcp.protocol.version: "2026-07-28"
// Business metadata on every span (user_id, session_id,
// strategy_id) turns replay into query:
// "tool X failed for users in segment Y over 48h"

4. 持续评估：LLM 即评委

运行期追踪是离线评估的天然补充：评估在部署前拦截回归，追踪捕捉生产环境抛给你的一切。而连接两者的闭环是 LLM-as-a-Judge：对采样轨迹持续运行自动评委，检测语义漂移、事实错误与策略违规——而不是等用户投诉。典型的做法是每小时对 5-10% 的轨迹做评判，当滚动分数下降、工具失败率飙升或轨迹偏离预期工具序列时告警。Mlflow 等框架已把这一层做成开箱即用的结构化评估管线。

5. 成本可见性：把 token 花在刀刃上

span 级 token 追踪能指出哪些步骤吞噬了上下文窗口——一个范围不当的检索步骤可能在百万次运行中把成本放大一个数量级。可观测性让它在变成预算问题之前就暴露出来：按代理与工具维度聚合 gen_ai.client.token.usage，设置每日预算，超限分页告警。先于规模扩张设置 token 预算告警：每天 1,000 次运行表现正常的检索代理，到每天 100,000 次时可能迅速变得昂贵。

// Continuous evaluation: don't wait for user complaints. Run
// an LLM judge against SAMPLED production traces to catch
// semantic drift, factual errors, and policy violations.
const JUDGE_PROMPT = [
  "You are evaluating an agent trace.",
  "Score 1-5 on: (a) did the final answer satisfy the request,",
  "(b) were all tool calls necessary and correct, (c) is any",
  "claim unsupported by the retrieved context.",
  'Return JSON with "score" and "reason" fields',
].join(NEWLINE); // NEWLINE = the line separator constant
// Schedule: judge 5-10% of traces every hour; alert when the
// rolling score drops, when tool failure rate spikes, or when
// a trace drifts from the expected tool sequence.

6. 从第一周就把可观测性当控制机制的一部分

最常见的错误是把可观测性当作上线后再装的东西——结果总是同一个：一场无法解释的生产事故、一次以天计的调试、一份大家都同意「早该埋点」的复盘。有效的做法是把可观测性当作代理控制机制（harness）的集成部分：在关键代理路径上做 span-per-tick 追踪，从第一天就附加业务元数据（user_id、session_id、strategy_id），上线前至少接通一个自动化评估检查。SDK 追踪每个 span 只有个位数毫秒开销；而一次好追踪能把两天调试变成二十分钟。

// Cost guardrails: token usage at span level exposes the
// steps that burn context windows. A single poorly scoped
// retrieval step can inflate cost by an order of magnitude.
{
  "alerts": [
    { "metric": "gen_ai.client.token.usage", "aggregation": "sum",
      "by": ["gen_ai.agent.name", "execute_tool"],
      "condition": "> 2M tokens / 24h", "action": "page-oncall" },
    { "metric": "agent.tool.failure_rate", "condition": "> 0.15",
      "window": "15m", "action": "open-incident" }
  ],
  "budgets": { "retrieval-agent": "10M tokens/day", "coding-agent": "40M tokens/day" }
}
// Export the two mandatory histograms first, then add the
// business metadata. The floor is cost + speed visibility.