从零做 Agent 可观测性：日志、轨迹与故障定位

你是否遇到过这种场景：

• • Agent 失败了，但不知道失败在哪一步
• • 只能看一堆零散日志，无法还原执行链路
• • 线上问题复现困难，修复效率很低

这不是模型问题，而是 可观测性缺失。

如果说评测集解决的是“好不好”，那可观测性解决的是“为什么”。

从零做 Agent 可观测性封面

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

对 Agent 来说，最小可观测对象有 3 层：

1. 1. 任务层（Task）
2. 2. 步骤层（Step）
3. 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

这层解决的是： 到底是计划错了，还是执行错了，还是反思阶段没兜住。

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

工具调用是故障高发区。

每次调用至少记录：

• • tool_name
• • params_digest（脱敏）
• • result_status
• • error_code
• • external_latency

尤其是 error_code，必须标准化，比如：

• • TOOL_TIMEOUT
• • AUTH_INVALID
• • RATE_LIMITED
• • SCHEMA_MISMATCH

这样你才能做聚合分析和告警，而不是靠人工读报错文本。

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

有了三层日志后，定位流程可以标准化：

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

目标是把“经验排查”变成“流程排查”。

六、最小日志结构示例

你可以从这 3 类日志开始：

1. 1. task.log
2. 2. step.log
3. 3. tool.log

先保证：

• • 都包含统一 task_id
• • 时间戳统一格式
• • 错误码统一字典

有了这一层，后面接 ELK/Grafana/数据仓库都很顺。

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

上线后建议持续跟踪：

1. 1. 失败率（按步骤分布）
2. 2. 平均定位时长（MTTD）
3. 3. 平均修复时长（MTTR）
4. 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 成本优化：模型路由、缓存与重试治理》。