第 15 课  建立可观测性

Agent 完成一次任务，可能需要多次调用模型、检索资料、使用工具，甚至把部分工作交给其他 Agent。同一个问题，也可能因为上下文或工具返回结果不同，走出不同的执行路径。

只保存用户的问题和最终回答，往往不足以解释问题发生在哪里。我们还需要知道：它看到了什么信息，调用了什么工具，各步骤返回了什么结果。Langfuse 官方文档 ↗

例如，在一个虚拟电商客服场景中，用户问：“这件商品还能退吗？”Agent 给出了错误答案，可能有不同原因：

• 订单查询工具返回了错误的签收时间。
• 检索到了已经失效的退货规则。
• 正确信息已经提供给模型，但模型判断错误。
• 工具调用失败后，Agent 仍然给出了确定的回答。

这些问题需要不同的改进方法。记录执行过程，才能缩小排查范围。

接口正常返回、程序没有报错，只能说明技术流程可能正常，不能证明用户的问题已经解决。

例如，客服 Agent 顺利完成了所有调用，却错误地承诺可以退款。这次运行在技术上没有异常，在业务上却失败了。

因此，需要同时关注两类结果：

• 运行结果：是否报错、超时、重复调用或异常终止。
• 业务结果：回答是否正确、操作是否符合要求、用户的问题是否得到解决。

业务结果需要结合明确的规则、实际业务状态、人工检查或评测来判断，不能只依赖 Agent 自己报告“任务已完成”。

可观测性也用于发现整体变化：换模型后是否更慢，修改提示词后是否增加了工具调用，某类任务是否更容易失败。

有了历史记录和版本信息，团队才能比较变化前后的表现，确定优先改进的环节，并在出现异常时及时处理。

理解执行记录，可以先认识三个概念：

这些记录通过标识关联起来，才能看出步骤之间的顺序、依赖和耗时。多轮对话还需要会话标识，把同一会话中的多次请求联系起来。OpenTelemetry 基础概念 ↗、LangSmith 数据结构 ↗

前面的退货咨询，可以记录为：

用户提出退货问题
  → 模型决定查询订单
  → 订单工具返回签收时间
  → 检索工具返回适用规则
  → 模型生成判断和解释
  → 返回用户

查看这条链路时，应当能展开每个步骤，看到相应的输入、输出、状态和耗时。对于并行执行的工具或子 Agent，也要保留它们与主任务的关系。

这里记录的是系统实际发生的操作和可获取的信息，不能把模型生成的解释直接当成它内部推理过程的完整记录。

下面是一份适合起步的记录清单，可根据业务增减。

自动接入通常能覆盖部分模型和框架调用；业务审批、订单状态变化、自定义工具等环节，仍可能需要开发人员补充记录。LangSmith 接入说明 ↗

单次记录帮助排查具体问题，汇总指标帮助判断整体表现。起步时可以关注四组指标：

每个指标都需要明确口径。例如，“任务成功率”要先定义什么算成功，不能把“生成了一段回答”作为所有任务的成功标准。

耗时除了看平均值，也可以看 P95：即约 95% 的请求耗时不超过这个值，用来了解较慢请求的体验。交互型 Agent 还应区分系统处理时间与等待用户、等待审批的时间。

指标要结合场景解释。例如，人工接管率上升可能意味着能力退化，也可能是系统正确识别了更多高风险任务。

输入、输出和工具结果中可能包含用户资料、订单信息或内部文档。应明确哪些内容可以保存、哪些需要脱敏、谁能查看，以及保留多久；密码和密钥不应进入日志。

流量较大时，可以对普通请求的详细链路进行采样，对失败、超时和重要业务操作设置更高的保留优先级。计算整体成功率和错误率时，要使用完整计数或经过正确校正的数据，避免把偏向保留失败请求的样本当成全部流量。

• OpenTelemetry：生成、采集和传输观测数据。
• Tempo：存储和查询调用链路。
• Prometheus：采集和查询指标。
• Loki：汇总和查询日志。
• Grafana：展示看板，并关联查询相关数据。

OpenTelemetry 本身不提供完整的数据存储和分析界面，需要与后端工具配合。OpenTelemetry ↗、Tempo ↗、Prometheus ↗、Loki ↗