Agent Observability（Agent 可观测性）

Agent Observability 指：把 Agent 的每一轮运行——模型调用、工具调用、MCP server 调用——记录成可检索的分布式 trace，使工程团队能回答"这个 Agent 刚才做了什么、为什么慢、为什么失败、花了多少钱"。它和 Evals（评估）共同构成 Agent 从"偶尔成功"进入"可持续改进"的基础设施。

它同时是权限扩张的前提。Anthropic 把信任与观测的关系表述为：先 trace 再放权——给 Agent 更大的访问权限之前，先审查它的 trace；随着它在 trace 中证明可靠，再逐步放宽权限。这与 Agent Guardrails（Agent 护栏）的分级审批是同一个风险思路的两面：护栏约束"能做什么"，可观测性回答"做了什么"。

标准化：OpenTelemetry GenAI 语义约定

Agent trace 的关键工程决策是采用标准而非私有格式。OpenTelemetry（OTel）为生成式 AI 定义了 GenAI semantic conventions，使 Claude 和其他 provider 的 trace 数据能进入同一套工具和 dashboard，Agent trace 得以和应用其余部分的 logs、metrics 落在同一个时间线上。

一次 Agent turn 的典型 span 层级：

flowchart TB
    A["Agent span\n整个 turn"] --> C["API call span"]
    C --> M1["Model span"]
    C --> T["Tool use span"]
    C --> M2["Model span"]
    A --> M3["Model span"]
    A --> D["Database span"]

trace 中携带 latency、token 数和各类 ID；span 按来源着色区分——你的应用、Claude、其他 provider 可以出现在同一条 trace 里，这是多 provider 混合调用栈能被整体归因的原因。

几个反复出现的 GenAI 属性名：

属性	用途
`gen_ai.tool.name` + `status`	按工具和错误状态过滤，定位失败根因
`gen_ai.usage.input_tokens`	按请求、按 session 核算 token 成本
span 来源标签	区分应用代码、模型 provider、其他 provider 的耗时归属

三个用途

生产 trace 的消费方式大致分三类，第三类是它与 Evals（评估）的接口：

flowchart LR
    T["OpenTelemetry\n生产 traces"] --> Db["Debug failures\n按工具 / 错误状态\n过滤定位根因"]
    T --> Co["Track costs\n按请求 / session\n核算 token"]
    T --> Im["Improve agents\n标记真实 traces\n转成 evals"]
    Im -.->|"改进飞轮"| T

Debug：Agent trace 和应用的其他服务 trace 并排，慢步骤或失败步骤能直接归因到具体服务。
Cost：token 用量按团队、按 session 聚合，安全与平台团队可以据此发现异常用量。
Improve：把生产中的真实 trace 标记出来转成 eval 样本，再用改动后的指标验证是否真的变好——即 Loop Engineering（循环工程）里"失败 trace → 回归样本"路径的数据入口。

落地形态：Claude Platform 原生导出

2026 年 10 月，Anthropic 在 Claude Platform 上把 OpenTelemetry trace 导出做成了原生能力（public beta）：

覆盖 Managed Agents、Messages API 和 Claude SDK（Claude Agent SDK 的 trace 自动导出，Managed Agents 与 Messages API 需在 Claude Console 配置一个 destination）。
与 Claude Code、Claude Cowork 已有的 trace 汇入同一批可观测性工具。
除列名集成（Grafana Cloud、Honeycomb、Sentry、Splunk 属调试向；Arize、Braintrust、Datadog、Langfuse、LangSmith、New Relic、PostHog 属 eval 与质量向；Databricks Unity Gateway 属组织级用量治理向）之外，任何接受标准 OTLP endpoint 的工具都可接入。

一线证据

Ramp：自建 Reflect 系统，对 Langfuse trace 打分、找出反复出现的失败并提议修复；部分 Agent 已借此把 token 用量降低 10–20%、session 提速 30%。其结论是"改进系统只能看见它观测到的东西"，原生 OTel 导出免掉了自建埋点。
FloQast：管账的 Agent 要求可审计。原生导出让每次模型调用与其所在的对账 / 分录工作流出现在同一条 trace 上，prompt 版本、工具调用、latency、token 花销并列，审计提问可从单条时间线作答。
Foxglove：把 Agent 交互 trace 与产品使用数据同放在 PostHog 分析，定位 Agent 在真实机器人调试任务中的短板。

与其他词条的关系

Evals（评估） — 可观测性是 eval 的数据上游：没有生产 trace，改进飞轮没有原料
Agent Engineering Roadmap（Agent 工程路线图） — 可观测性与 eval、护栏、沙箱同属第七层"改进飞轮"
Harness Engineering（驾驭工程） — trace 是生产 harness 暴露的核心观测面
Agent Loop（智能体循环） — trace 的 span 结构就是 loop 一次迭代的调用树
Model Context Protocol — MCP server 调用是被 trace 的一等公民
Agent Guardrails（Agent 护栏） — 护栏约束行为边界，可观测性提供事后追责与信任积累
Durable Execution（持久化执行） — 长任务的可恢复性依赖同样这层运行时记录