Agent 可观测性落地手册：用 Langfuse 做全链路追踪

Agent 一旦进入生产，最先暴露的问题通常是“看不见”：

• 为什么同样请求有时成功有时失败？
• Token 成本为何突然上涨？
• 是检索问题还是推理问题？

可观测性不是锦上添花，而是生产可用性的基础。

最小可用观测模型

建议先建立三层数据：

1. Trace：一次用户请求的完整链路
2. Span：链路中的子步骤（检索、工具调用、重排、生成）
3. Score：人工或自动评估结果（准确性、相关性、可执行性）

只要这三层打通，排障效率会有明显提升。

接入策略

1. 先追关键路径

首批只接三类节点：

• 主模型调用
• 检索器调用
• 外部工具调用

不要一开始追踪所有细节，否则维护成本会反噬。

2. 统一会话与用户标识

• session_id：同一会话连续请求
• user_id：聚合用户维度行为
• request_id：单次请求唯一编号

这让你可以从“异常用户反馈”快速定位到具体 trace。

3. 成本与延迟要分层看

至少拆分：

• 模型推理耗时
• 检索耗时
• 外部 API 耗时
• 总响应时间

很多团队优化模型参数后发现收益有限，真正瓶颈反而是工具层接口。

评估闭环

推荐两条线并行：

• 在线轻评估：响应是否命中意图、是否触发重试
• 离线深评估：抽样回放 + 人工标注

评估指标可从三项开始：

• Answer Groundedness（是否有依据）
• Task Completion（任务是否完成）
• Tool Success Rate（工具调用成功率）

常见反模式

• 只记录原始文本，不记录结构化上下文
• 只盯整体延迟，不看步骤级耗时
• 有追踪无告警，异常只能靠人盯仪表盘

总结

对 Agent 系统来说，观测能力不是可选插件，而是“质量系统”的核心。Langfuse 非常适合作为第一层统一追踪平台，再按需接 Phoenix 或内部评估流水线。

---

落地建议：先选一个业务场景做 2 周观测基线，再做优化迭代，避免“边改边猜”。