用 Python 给 AI Agent 加可观测性：日志、指标与链路追踪的落地记录

一、为什么 Agent 比普通服务更难排查

传统接口出问题，看一条堆栈就能定位。AI Agent 不一样：一次用户提问可能触发十几轮模型调用、若干次工具执行和一次检索，最终答案不对时，你很难判断是提示词没写好、检索召回错了，还是模型在某一步被工具返回的脏数据带偏。可观测性要解决的正是这个问题：把 Agent 的每一次思考、每一次工具调用都变成可以回放的结构化数据。

二、用结构化日志记录每一步决策

日志不要打印成一段自然语言，而要用 JSON，并固定几个字段：trace_id、step、actor（planner 还是 executor）、tool_name、latency_ms、token_in、token_out、status。Python 里用 logging 配一个 JsonFormatter 就够了，写到 stdout 再由采集端收走。关键是 trace_id 必须在入口生成并一路透传，否则多轮会话的日志会搅在一起，排查时只能靠时间戳猜测。

三、把 token 与耗时变成可聚合的指标

日志适合排查单次问题，指标适合看趋势。至少埋四个指标：每分钟请求数、P95 端到端耗时、平均 token 消耗、工具失败率。用 prometheus_client 起一个 Counter 和一个 Histogram，暴露在 /metrics 端点即可。特别建议单独统计“每个请求的模型调用次数”，这个数字一旦从 3 涨到 12，通常意味着规划器在死循环里反复重试，是成本失控最早的信号。

四、链路追踪：把多轮调用串成一棵树

一次 Agent 请求天然是一棵树：根节点是用户问题，子节点是每一轮模型调用与工具执行。用 OpenTelemetry 的 Python SDK，在入口开一个 span，每次调模型或工具时开子 span，属性里带上模型名、工具名和返回状态。这样在追踪面板上能直接看到哪一层耗时最长。实践中最好把提示词的哈希值也写进 span 属性，既方便对比不同版本，又不会把敏感内容落到链路存储里。

五、在华为云上落地与几个坑

日志走云日志服务 LTS，按 trace_id 建索引后可以直接搜一个会话的全链路；指标接 AOM 做告警，比如工具失败率五分钟内超过 10% 就通知；链路数据用 APM 托管。踩过的坑有两个：一是采样率不要设成 100%，Agent 的 span 数量很容易把后端打满，按 10% 加错误全采样更划算；二是工具返回的超长文本必须截断后再进日志，否则一条记录几十 KB，检索会明显变慢。