如何使用可观测性调试和评估 AI 智能体——LangChain 指南

来源: https://www.langchain.com/blog/agent-observability-powers-agent-evaluation 抓取时间: 2026-07-21 16:24:54

概念指南

智能体可观测性驱动智能体评估

Harrison Chase 2026年1月27日 16 分钟返回博客创建智能体分享

关键要点

你无法在不了解智能体如何推理的情况下构建可靠的智能体，你也无法在没有系统评估的情况下验证改进。本文解释了智能体可观测性的原语，如何在不同粒度上评估智能体，以及生产追踪如何成为持续改进的基础。摘要

在实际运行智能体之前，你不知道它们会做什么——这意味着智能体可观测性与软件可观测性不同，而且更重要
智能体经常执行复杂、开放式的任务，这意味着评估它们与评估软件不同
由于追踪记录了智能体行为的出现位置，它们以多种方式为评估提供支持

当传统软件出现问题时，你知道该怎么做：检查错误日志、查看堆栈跟踪、找到失败的代码行。但 AI 智能体改变了我们调试的内容。当智能体在两分钟内花费 200 步完成任务并在某个地方犯错时，这是一种不同类型的错误。没有堆栈跟踪——因为没有代码失败。失败的是智能体的推理。

从调试代码到调试推理

你仍然编写代码来定义你的智能体，例如存在哪些工具、可用的数据是什么。你编写提示和工具描述来指导智能体的行为，但在运行它之前，你不会知道 LLM 将如何解释这些指令。因此，真实来源从代码转移到显示智能体实际做了什么的追踪。智能体工程是一个迭代过程，而追踪 + 评估是你闭环的方式。在这篇文章中，我们将探讨为什么智能体可观测性和评估从根本上不同于传统软件，你需要哪些新的原语和实践，以及可观测性如何以使它们不可分割的方式为评估提供支持。

智能体可观测性 ≠ 软件可观测性

在 LLM 出现之前，软件在很大程度上是确定性的——给定相同的输入，你会得到相同的输出。逻辑被编纂成法典。你可以阅读代码并确切地知道系统的行为方式。当出现问题时，日志会指向哪个服务或函数失败，然后你返回代码以了解为什么会发生这种情况并修复它。 **AI 智能体打破了决定论和代码作为真实来源的假设。**随着我们从传统软件转向 LLM 应用程序，再转向智能体，每一步都引入了更多的不确定性。LLM 应用程序对带有上下文的 LLM 进行单次调用，引入了自然语言固有的「模糊性」，但仍然局限于单次 LLM 调用。然而，智能体在循环中调用 LLM 和工具，直到它们确定任务完成——并且可以跨数十或数百步进行推理，调用工具，维护状态，并根据上下文调整行为。在构建智能体时，你尝试在代码和提示中推荐应用逻辑。但在实际运行 LLM 之前，你不会知道这个逻辑会做什么。传统软件 vs. LLM 应用程序 vs. 智能体当出现问题时，你不是在寻找失败的单行代码。相反，你在问：

为什么智能体在 200 步中的第 23 步决定调用 edit_file 而不是 read_file？
什么上下文和提示指令影响了该决定？
在这个两分钟、200 步的轨迹中，智能体在哪里偏离了轨道？

传统的追踪工具无法回答这些问题。一个 200 步的追踪对于人类来说太大了，无法解析，而且传统的追踪不会捕获每个决定背后的推理上下文；它们只捕获调用了哪些服务以及每个服务花费了多长时间。

智能体评估 ≠ 软件评估

传统软件测试依赖于确定性断言：编写检查 output == expected_output 的测试，验证它们通过，然后交付。在线评估（A/B 测试、产品分析）单独衡量业务影响。评估智能体与评估软件在几个关键方面不同： 1. 你在测试推理，而不是代码路径 传统软件在不同粒度级别（单元、集成、端到端）进行测试，测试你可以阅读和修改的确定性代码路径。智能体也需要在不同级别进行测试，但你不再测试代码路径——你在测试推理：

单步：智能体在这个时刻做出了正确的决定吗？
完整轮次：智能体在端到端执行中表现良好吗？
多轮：智能体在对话中保持了上下文吗？

2. 生产成为你的主要老师 在传统软件中，你可以通过离线测试（单元测试、集成测试、预发布）捕获大多数正确性问题。你仍然通过金丝雀部署和功能标志在生产中进行测试，但目标是捕获你错过的边缘情况和集成问题。对于智能体，生产扮演着不同的角色。由于每个自然语言输入都是唯一的，你无法预料用户将如何表达请求或存在哪些边缘情况。生产追踪揭示了你无法预测的故障模式，并帮助你了解对于真实用户交互，「正确行为」实际上是什么样子。这改变了你对评估的看法：**生产不仅仅是你捕获遗漏错误的地方。它是你发现离线要测试什么的地方。**生产追踪成为测试用例，你的评估套件从现实世界的示例中持续增长，而不仅仅是工程场景。

智能体可观测性的原语

智能体可观测性使用三个核心原语来捕获非确定性推理：

运行：单个执行步骤（一次 LLM 调用及其输入/输出）
追踪：完整的智能体执行，显示所有运行及其关系
会话：多轮对话，随时间分组多个追踪

这些使用与传统可观测性相同的概念（例如，追踪、跨度），但捕获推理上下文，而不是服务调用和时序。

运行：捕获 LLM 在单步中做了什么

运行捕获单个执行步骤。这对于捕获 LLM 在特定时间点的行为最有用。这捕获了 LLM 调用的完整提示，包括所有指令、使用的工具和上下文。这些运行具有双重目的：智能体运行及其组件的示例

用于调试：准确查看智能体在任何步骤的想法。提示中有什么？可用的工具是什么？为什么它选择了这个动作？
用于评估：针对此运行编写断言。智能体调用了正确的工具吗？使用了正确的参数吗？

追踪：捕获轨迹

追踪通过链接在一起发生的所有运行来捕获完整的智能体执行。推理追踪捕获：

关于在每个步骤进入模型的所有信息，捕获为构成追踪的运行
所有工具调用及其参数和结果
嵌套结构，显示步骤如何相互关联

智能体追踪非常庞大。虽然典型的分布式追踪可能只有几百字节，但智能体追踪可能大几个数量级。对于复杂、长时间运行的智能体，追踪可以达到数百兆字节。这种上下文对于调试和评估智能体的推理是必要的。示例追踪及其组件

会话：多轮对话上下文

单个追踪捕获一次智能体执行，但智能体通常跨涉及多个与用户或系统交互的会话运行。会话将多个智能体执行（追踪）分组到单个对话会话中，保留：

多轮上下文：按时间顺序排列的用户与智能体之间的所有交互
状态演变：智能体的内存、文件或其他工件如何在各轮中变化
时间跨度：对话可以持续几分钟、几小时或几天

捕获多轮对话的会话示例考虑调试一个编码智能体，它在 10 轮中工作正常，但在第 11 轮突然开始出错。孤立的第 11 轮追踪可能显示智能体调用了一个合理的工具。但是当你检查完整会话时，你会发现在第 6 轮，智能体用一个不正确的假设更新了它的内存，到第 11 轮，那个坏上下文已经复合成错误的行为。会话对于理解智能体行为如何随时间演变以及上下文如何在交互中积累（或降级）至关重要。

这如何影响智能体评估

智能体行为仅在运行时出现，并且仅由可观测性（运行、追踪和会话）捕获。这意味着要评估行为，你需要评估你的可观测性数据。这提出了两个关键问题：

你在什么粒度上评估智能体？在运行、追踪还是会话级别？
你什么时候评估智能体？如果行为只有在你运行智能体时才出现，你能像评估软件一样离线评估它们吗？

在不同粒度级别评估智能体

**你可以在不同粒度级别评估智能体，这些级别与可观测性原语一一对应。**你在评估什么决定了你需要哪个原语：

单步评估验证单个运行 → 智能体在特定步骤做出了正确的决定吗？
完整轮次评估验证完整追踪 → 智能体是否正确执行了完整任务？
多轮评估验证会话 → 智能体在对话中保持了上下文吗？

单步 vs. 完整轮次 vs. 多轮评估模式

单步评估：决策的单元测试

有时，你需要在不运行整个智能体的情况下验证特定决策点。你可能想看看智能体在特定场景中是否选择了正确的工具，或者它是否使用了正确的参数。这就像智能体推理的单元测试：设置特定状态（对话历史、可用工具、当前任务），运行智能体一步，并断言它做出了正确的决定。单步评估验证运行，即单个 LLM 调用。 示例：测试日历智能体的工具选择 调度智能体需要在调度之前找到可用的会议时间。你想验证它首先检查可用性，而不是立即尝试创建会议：你的单步测试：

设置状态：对话历史 = 用户说「明天早上安排与 Harrison 的会议」，可用工具 = [find_meeting_times、schedule_meeting、send_email]
运行一步：智能体生成下一个动作
断言：智能体选择了 find_meeting_times（而不是 schedule_meeting）

为什么你需要运行：单步测试通常来自出错的真实生产案例。为了重现这些，你需要在该步骤之前智能体的确切状态。详细的运行捕获是获得这个的唯一方法！单步评估效率高，并在单个决策点捕获回归。在实践中，大约一半的智能体测试套件使用这些单步测试来隔离和验证特定的推理行为，而没有完整智能体执行的开销。

2. 完整轮次评估：端到端轨迹评估 其他时候，你需要查看完整的智能体执行。完整轮次评估验证追踪，即具有所有运行的完整智能体执行，并让你测试多个维度：轨迹：智能体调用了必要的工具吗？对于修复错误的编码智能体，你可能会断言：「智能体应该已经调用了 read_file，然后是 edit_file，然后是 run_tests。」确切的顺序可能会有所不同，但必须调用某些工具。 最终响应：输出是否正确且有用？对于像研究或编码这样的开放式任务，最终答案的质量通常比采取的特定路径更重要。 状态变化：智能体创建了正确的工件吗？对于编码智能体，你会检查它写入的文件并验证它们包含正确的代码。对于有内存的智能体，你会检查它是否存储了正确的信息。测试智能体记住用户偏好也需要验证三件事：

轨迹：智能体是否在其内存文件上调用了 edit_file？
最终响应：智能体是否向用户确认了更新？
状态：内存文件是否确实包含了偏好？

每个断言都需要追踪的不同部分。如果不捕获完整的轨迹和状态变化，你就无法评估这些维度。

3. 多轮评估：真实对话流 某些智能体行为仅在多轮中出现。智能体可能在 5 轮中正确维护上下文，但在第 6 轮失败，或者可以很好地处理单个请求，但在请求相互构建时遇到困难。多轮评估验证会话，即具有多个智能体执行的对话会话。你测试智能体是否正确积累了上下文，跨轮维护状态，并处理建立在先前交换之上的对话流。例如，测试上下文持久性：

第 1 轮：用户分享偏好（「我更喜欢 Python 而不是 JavaScript」）
第 2 轮：用户提出基于该偏好的问题（「给我看一个例子」）
第 3 轮：测试该偏好是否持续存在（「为此编写一个脚本」）

智能体应该在第 2 轮和第 3 轮提供 Python 示例，而不是 JavaScript。这需要跨轮维护上下文。挑战是保持多轮测试在轨道上。如果智能体在第 1 轮偏离了预期路径，你硬编码的第 2 轮输入可能没有意义。使用条件逻辑在每轮后检查智能体的输出，如果偏离轨道则提前失败。多轮评估需要会话将多个智能体执行（追踪）分组到单个对话中。当多轮测试失败时，你需要显示所有轮次的会话来理解出了什么问题以及在哪里。

如何选择评估智能体的粒度级别

没有单一正确的方法来选择评估智能体的粒度级别。我们看到的一些启发式方法：

**通常最容易想出追踪级（完整轮次）评估的输入。**这些是给你的智能体的输入，所以想出预期的输入非常容易（也是必要的）。也就是说，想出预期的输出和/或以编程方式验证它们的方法可能更难。这意味着可能有一段时间你自动化智能体在这些数据点上的运行，但不自动化评分。
**最容易完全自动化运行级（单步）评估的评分。**这只是单个模型调用，并且通常可以通过检查是否调用了工具来评估。一个警告：根据你改变智能体内部的频率（哪些工具可用，调用工具的正确顺序），这些评估可能会很快过时并需要更新。出于这个原因，我们通常看到团队只有在通用智能体架构相对稳定后才构建这些。
**会话级评估（多轮）难以有效实施。**它们涉及想出一系列输入，但通常该序列只有在智能体在输入之间以某种方式表现时才有意义。它们也很难自动评估。这是我们看到的最不常见的评估类型。

大多数生产智能体使用组合：核心工作流的完整轮次测试，生产中发现的已知故障模式的单步测试，以及有状态交互的多轮测试。

何时评估智能体

智能体行为在你在生产中运行之前不会完全出现，这意味着你何时评估智能体也不同于传统软件。

**离线评估：**这相当于在交付之前运行单元测试。要运行这些测试，你需要收集输入数据集，以及可选的地面实况输出进行比较。根据在该数据集上运行和评估智能体的成本，你可以在每次提交时运行这些评估，或者只是在推送到生产之前。如果你经常运行离线评估，你需要设置某种缓存，这样你就不会不必要地调用模型。注意：当大多数人谈论「评估」时，他们可能指的主要是离线评估。
在线评估：由于你在运行智能体之前不知道它的表现如何，你可能希望「在线」运行评估，当智能体在生产数据上运行时。这样做时，这些评估器定义上需要是「无参考」的。在线评估器通常在生产数据摄取时运行。
临时评估：智能体的输入和行为非常无界，所以你并不总是提前知道你想测试什么。如果你在生产中有很多追踪，你可能希望在它们已经被摄取之后**测试它们。这种探索性数据分析对于理解你的智能体至关重要。像 LangSmith 中的洞察智能体这样的系统可以帮助你做到这一点。

关键转变：**离线评估是必要的，但还不够。**在生产中评估你的智能体很重要，因为你无法预料用户将与你的智能体交互的所有方式。

智能体可观测性如何驱动智能体评估

你为AI 可观测性生成的追踪与驱动你评估的追踪相同，形成了统一的基础。

追踪 → 手动调试

当你在临时查询上本地运行智能体并手动检查结果时——这仍然是一种（手动）评估形式！追踪为这个工作流提供支持，因为它们允许你逐步进入流程的每个步骤，并准确找出哪里出了问题。

追踪 → 离线评估数据集

生产追踪自动成为你的评估数据集。例如，当用户报告错误时，你可以在追踪中看到：确切的对话历史和上下文，智能体在每个步骤决定了什么，以及它具体在哪里出错。 示例工作流：

用户报告不正确的行为
找到生产追踪
在故障点提取状态
从该确切状态创建测试用例
修复并验证

因此，你的离线评估测试套件可以由真实数据点形成。

追踪 → 在线评估

为调试生成的相同追踪驱动持续的生产验证。在线评估在你已经捕获的追踪上运行。你可以在每个追踪上运行检查或进行战略性抽样：

轨迹检查：标记不寻常的工具调用模式
效率监控：检测性能下降趋势
质量评分：在生产输出上运行 LLM 作为裁判
失败警报：在用户报告之前浮出水面错误

这实时浮出水面问题，验证开发行为在生产中保持不变。

追踪 → 临时洞察

当追踪包含 100,000 多行数据或会话跨数十轮时，手动检查变得不可能。这就是 AI 辅助分析帮助你查询追踪和会话以：

在许多智能体执行中浮出水面使用模式
识别常见故障模式和低效率
解释特定决策：「为什么智能体在这个步骤调用这个工具？」
比较成功与失败的执行以找到模式

例如，最近我们在调查为什么智能体采取低效路径。我们没有手动阅读 150 步追踪，而是使用 AI 助手，它识别出智能体在同一个文件上多次调用 read_file，而不是在上下文中存储内容。修复是一个简单的提示调整（而手动发现这个模式需要几个小时）。

这对构建智能体的团队意味着什么

交付可靠智能体的团队已经接受了从调试代码到调试推理的转变。传统软件将追踪（用于调试）和测试（用于验证）分开。现在我们正在调试跨长时间运行、有状态过程的非确定性推理，这些实践融合在一起。你需要推理追踪来评估智能体行为，并且你需要系统评估来理解追踪。从第一天就一起采用这两种实践的团队将是那些交付真正有效的智能体的团队。