从零开始Agent可观测性实战：日志、轨迹与故障定位

你遇到过这种状况吗？Agent 莫名其妙就挂了，卡在哪一步完全摸不着头绪；手里只有零散日志，连完整执行链路都拼不出来；线上问题难以复现，修复效率低到令人崩溃。

这通常不是模型本身的问题，而是系统缺失了最关键的一环——可观测性。

如果把评测集当作回答“好不好”，那么可观测性要回答的就是“为什么”。它才是把故障定位从玄学变成科学的真正钥匙。

从零做 Agent 可观测性封面

一、可观测性到底观察什么？

对 Agent 而言，最小可观测对象需要覆盖三个层次：

1. 任务层（Task）：一次完整的执行单元
2. 步骤层（Step）：任务内的各个环节
3. 工具层（Tool）：每一步调用的具体工具

这三层必须全部打通，问题定位才能做到快、准、稳。缺少任何一层，都像拼图时少了一块关键碎片。

二、任务层：先把每次执行唯一标识起来

每次任务自始至终，至少需要记录以下字段：

• task_id —— 唯一标识
• user_goal —— 用户原始目标
• start_at / end_at —— 起止时间
• final_status —— 最终结果（success / failed / need_human）
• total_latency —— 总耗时
• total_cost —— 总成本

这一层解决的根本问题是：你看到的这次失败，究竟是哪次任务整体表现不佳，以及是否有其他类似任务同时出现问题。

三、步骤层：把 O-P-A-R 闭环拆开记录

每一个步骤都需要记录三样东西：输入摘要、输出摘要、决策原因。建议字段如下：

• step_name —— 步骤名称（observe / plan / act / reflect）
• input_digest —— 输入摘要
• output_digest —— 输出摘要
• decision_reason —— 决策原因
• step_latency —— 步骤耗时
• retry_count —— 重试次数

有了这一层，你就能逐帧回放：到底是计划阶段就错了，还是执行阶段出了岔子，抑或是反思阶段没能兜住错误。每个环节都会留下明确的痕迹。

四、工具层：错误必须结构化，而不是字符串

工具调用是 Agent 系统中故障发生频率最高的区域。每次调用至少需要记录：

• tool_name —— 调用了哪个工具
• params_digest —— 参数摘要（注意脱敏）
• result_status —— 调用结果状态
• error_code —— 错误码
• external_latency —— 外部耗时

这里的 error_code 必须标准化，不能用自由文本。建议像这样预定义：

• TOOL_TIMEOUT —— 工具超时
• AUTH_INVALID —— 认证无效
• RATE_LIMITED —— 频率限制
• SCHEMA_MISMATCH —— 参数模式不匹配

只有错误码标准化，你才能做聚合分析和告警，而不是靠人工逐条读取报错文本。这一点是自动化运维的基石。

五、一条完整故障定位路径

有了三层日志之后，故障定位的流程可以变得非常标准化：

1. 按 task_id 找到任务总览
2. 定位失败的步骤（step-level）
3. 下钻到具体工具调用（tool-level）
4. 确认根因分类：模型问题、工具问题、编排问题还是数据问题
5. 输出修复动作并沉淀为规则

目标是把“靠经验排查”变成“按流程排查”。经验丰富的工程师可以凭直觉快速定位，但团队里更多人需要的是可复制的排查路径。

六、最小日志结构示例

不必一开始就追求完美。从这三类日志开始就够用了：

• task.log —— 任务级
• step.log —— 步骤级
• tool.log —— 工具级

先保证三点：所有日志都包含统一的 task_id、时间戳格式一致、错误码参照同一套字典。有了这个基础，后面不管接 ELK、Grafana 还是搭建数据仓库，都会顺畅很多。

七、可观测性的四个关键指标

系统上线后，建议持续跟踪这四个指标：

1. 失败率（按步骤分布） —— 哪个环节最容易出问题
2. 平均定位时长（MTTD） —— 系统出故障后，多久能发现根因
3. 平均修复时长（MTTR） —— 从发现到修复需要多久
4. 重复故障率 —— 同一类故障是否反复出现

如果这四个指标持续下降，说明你的 Agent 系统正在从“能用”进化为“可维护”。这比任何花哨的功能都重要。

八、三个常见反模式

1) 只打成功日志

坏处很明显：失败场景的信息完全缺失，复盘根本无从下手。

2) 日志太全但无结构

表面上数据很丰富，但查询困难，告警无效。这就好比把整座图书馆的书随便堆在地上——信息都在，但找起来要命。

3) 有日志但无动作

发现问题了，但是没有闭环机制去修复和预防。系统不会自动变好，故障只会一次次重复出现。

正确的做法是：日志 → 分析 → 规则 → 自动防线。形成一个闭环，而不是止步于记录。

九、从零起步的 7 天落地计划

如果你现在还是“黑盒”，别怕，按照这个节奏一周就能升级：

• Day 1-2：补齐 task_id 与任务总览日志
• Day 3-4：接入步骤级日志（O-P-A-R 结构）
• Day 5：统一错误码字典
• Day 6：制作首版故障看板
• Day 7：复盘 Top 5 故障，固化为修复规则

一周之后，你的系统就从“黑盒”升级为“可定位系统”。别小看这七天，它是整个体系从混乱走向有序的第一步。

结语

可观测性不是为了“记录更多日志”，而是为了更快定位、更稳修复。当你能够快速回答这三个问题时——

• 哪个任务失败了？
• 失败在哪一步？
• 根因是什么，如何防止复发？

——你的 Agent 才算真正具备了生产可维护性。

下一篇我会写：《从零做 Agent 成本优化：模型路由、缓存与重试治理》。