Agent 可观测性：把每一次运行看清楚

Agent 跑起来像个黑箱：它调了什么、为什么这么答，你一眼看不见。没有可观测性，线上出问题你只能盲猜，优化更是无从下手。

快速结论

• 可观测性让 Agent 的每一步调用、决策、耗时都看得见。
• 核心三件套：链路记录、指标监控、单步追踪。
• 它既是排障工具，也是优化依据。
• 上线前就把日志埋好，别等出事再补。

为什么 Agent 特别需要被看见

传统程序逻辑固定，错了能顺着代码查。Agent 靠模型动态决策，同输入可能走不同路径，失败原因藏在”它当时为什么这么选”里。看不见这一步，排障就像猜谜。

而且 Agent 常串多个工具、多轮调用，任何一环超时或误判都会传导到最终结果。没有逐环记录，你只知道结果错了，却不知错在第几环。可观测性，是把黑箱打开的灯。

链路记录记什么

一次完整运行要记：接收了什么输入、模型决定了调哪个工具、填了什么参数、工具返回了什么、模型据此怎么继续、最终输出什么。把这条链原样留存，复盘才有据。

记录粒度要到”每一步”，而不是只存首尾。只存首尾你会发现”中间模型调了个奇怪的函数”却查不到原因。粒度决定定位速度，别为了省存储只留两头。

指标监控看哪些

日常盯四个数：任务成功率、平均耗时、单次调用的工具次数、失败率。成功率掉、耗时长、调用次数暴涨，都是系统变坏的前兆，比用户投诉早得多。

还要分场景看，别被总平均糊弄。某类任务成功率悄悄下滑，总平均可能还稳，等发现已影响一片用户。按任务类型拆指标，异常才藏不住。

单步追踪怎么帮排障

当用户报”这次答错了”，你拿请求标识调出整条链路，逐环看：是检索捞错了资料，还是模型误读了参数，还是工具返回了脏数据。定位从小时级降到分钟级。

追踪还能发现隐性坏步：比如某工具近三天失败率悄悄升高，还没人察觉。把追踪和指标打通，坏步自己会浮出来。排障从救火变体检。

告警要喊在人前面

指标异常要主动告警，而不是等人发现。设阈值：成功率低于某值、耗时超某倍、失败率突破某线就通知负责人。告警让问题在扩大前被按住。

告警也要防狼来了：阈值太敏会刷屏被无视，太钝又漏事。按业务容忍度调，关键链路严、边缘链路宽。好的告警是被信任的哨兵，不是噪音源。

和成本监控连起来

Agent 每次调用都烧 token，可观测性顺带把成本看清：哪类任务最贵、哪个工具调用最频繁、是不是有死循环空转烧钱。成本异常往往也是逻辑异常的影子。

把成本和成功率叠看更有价值：某任务成本翻倍但成功率没涨，多半是链路绕远或重复调用。可观测性让”贵得有没有道理”一目了然，省钱靠的是看见。

隐私与日志的权衡

记录链路可能含用户输入甚至敏感内容，全量存原文有合规风险。做法是敏感字段脱敏后再存，或只存结构不存原文，既保留排障所需又不泄密。

还要定留存期：日志不是越久越好，既占存储又增风险。按合规要求设保留天数，到期自动清理。可观测和隐私保护，要一起设计而非二选一。

落地的小步做法

别等系统复杂了才埋点。从第一个 Agent 起就把链路和指标接上，哪怕简单。早期成本低、习惯易养成，等规模上来时观测体系已在那里。

选一个能串起日志、指标、追踪的平台或自建，别三套各管各的。数据打通，排障时才能从指标跳到链路再跳到单步。观测碎片化，等于没观测。

常见三个坑

坑一：只存首尾不存每一步，排障时卡在中间。坑二：告警阈值乱设，要么刷屏要么漏事。坑三：日志含敏感原文，埋下合规雷。

三者都靠”记到步、告警有度、数据脱敏”化解。可观测性不是接个日志库就完，而是一套让系统可被理解的设计。

衡量观测到不到位

看两个硬指标：平均排障时长是否短、能否在用户大面积感知前发现异常。两者都好，说明观测真正在起作用，而不是摆设。

再补一个软信号：团队敢不敢改 Agent。观测到位，改动出错能立刻看见回滚；不到位，谁改都心虚。敢改，才是可观测性的终极价值。

观测数据反哺优化

可观测性攒下的链路与指标，是优化的金矿。谁被频繁调用、哪步常失败、哪类任务最贵，这些从日志里长出来的结论，比拍脑袋定的优化方向准得多。

做法是定期回看观测报告，把高频失败点排进改进队列，改完再看指标是否回落。让数据驱动优化闭环，Agent 才会随每次迭代更稳更省，而不是原地打转。

能力	作用	注意
链路	留存全流程	记到每一步
指标	盯成功率耗时	按场景拆
追踪	定位坏步	凭标识调出
告警	异常喊人	阈值有度

延伸阅读：什么是 MCP（模型上下文协议）、什么是 Prompt（提示词）。

下一步行动清单

• 从第一个 Agent 起就埋好链路与指标。
• 链路记录到每一步，不只存首尾。
• 盯成功率、耗时、调用次数、失败率四项。
• 设分场景告警阈值，异常主动喊人。
• 日志脱敏并定留存期，兼顾合规。