Agent 可观测性：生产级 AI 项目必修的工程能力

事件概述

随着 Agent 基础执行能力的成熟，越来越多 AI 产品走向生产环境。但由于 Agent 每次执行路径、输出和工具选择都可能不同，传统后端系统的指标、日志、链路追踪三件套无法直接适用。作者在开发 Mini-Openclaw 项目时，发现模型将工具参数错误地塞入 _raw 字符串导致工具调用失败，补全可观测能力后才精准定位问题，由此验证了可观测性的必要性。

核心信息

可观测性的基础逻辑：明确模型能力边界

• AI Max 模式：能用 AI 的地方全部使用 AI，虽简单但无法量化问题、无法沉淀优化方法。
• AI Min 模式：仅在泛化场景（如语义识别、关键词提取）使用 AI，其余用传统工程实现。可观测性仅在 AI Min 模式下可行，核心是接受模型不可能完美，但必须知道错在哪、为什么错，并形成可重复的优化框架。

核心组成模块

1. 原始数据记录：每个会话保存 jsonl 日志，记录模型调用与结果、工具调用与结果、上下文变化、观测系统生成的事件（异常/评估）。优先两部分：模型输入输出 + Agent 执行流程。
2. 核心指标聚合：基于原始数据计算工具错误率、模型调用耗时、Token 消耗、上下文压缩频率、成本评估。指标可提示异常位置，无法直接定位具体错误。
3. Trace 调用树：Agent 执行是树状结构，通过 model_call_id、tool_call_id、delegation_id 关联请求与响应、工具调用与结果、子 Agent 节点。清晰展示调用链路，大幅提升问题排查效率。
4. 决策归因：在 System prompt 中要求模型在推理中输出固定格式决策块（目标、候选动作、最终选择、原因、预期结果），解析后挂载到对应模型调用节点。方便排查跑偏环节，同时提升模型决策正确率。
5. 任务状态显式化：为每个会话创建根任务，委派子 Agent 时创建子任务。任务状态机包括 pending、planning、running、waiting_child、succeeded、failed、cancelled，将无序对话转化为可追踪的任务系统。
6. 异常检测：通过预设规则（重复失败、接近迭代上限、空响应循环、压缩频繁、未知工具）在运行中识别异常，写入 anomaly 事件，快速定位。
7. 评估：三种方式——用户反馈（点赞/点踩）、启发式评估（失败信号检测）、LLM-as-judge 评估。确保优化可量化验证。
8. 回放与对比：抓取失败 case，修改配置（prompt、工具描述等）后重新执行，对比两次 Trace 调用树，结构化对齐节点变化，形成“发现问题-定位-修改-验证”闭环。

值得关注

Mini-Openclaw 项目已搭建完成 Agent 可观测性的基础能力，覆盖八个核心部分。该框架强调将模型的不确定性纳入工程化管理，为生产级 AI 应用提供可量化的稳定性保障和持续优化路径。