介绍 Sentry 团队如何利用 agent 追踪和 AI 对话视图，诊断基于 LLM 的搜索查询助手中的故障。
AI translation, not an official translation. Refer to the original for technical details.
Adapted from @sentry# 使用 agent 追踪调试我们的 AI 搜索助手 为了让用户充分利用发送到 Sentry 的数据，我们必须让他们能够轻松找到这些数据。 我们的团队致力于开发帮助用户浏览数据的功能，使其能够通过搜索查询和过滤器找到特定事件。 搜索栏允许用户通过指定搜索词来查找数据。 搜索功能使用 Sentry 搜索语法，这对用户来说可能是一道门槛。因此，部分用户更倾向于像使用其他工具那样，以自然语言来指定搜索词。为此，我们构建了搜索查询助手，将自然语言提示转换为 Sentry 语法搜索词。（https://docs.sentry.io/concepts/search/#query-syntax） 由于其输出具有不确定性，我们使用评估（evals）来构建和衡量响应的性能。 这需要两个步骤：针对核心用户场景编写评估，然后运行评估以查看 agent 生成正确查询的表现。 当 agent 持续生成我们预期的查询时，很好！继续推进下一个场景。 当查询结果有误时，就需要调试 agent 看到了什么、做了什么，以及我们如何引导它给出正确答案。 ## 调试失败的评估 有时，可以在本地复现并调试评估。当评估不依赖特定数据的存在，或者模拟工具调用足以诊断并修复问题时，这种方式就能奏效。 在这种情况下，简单的工具就足以查看结果，例如查看来自 LLM 生成或工具调用的 JSON 输出。 但有时行为会更加复杂——它可能基于工具调用返回的特定数据、所使用的不同版本 LLM 模型，甚至是由于基础设施错误引起的。 对于这些情况，使用 Sentry 的 AI 对话视图已成为帮助调试的重要工具。（https://docs.sentry.io/product/agents/conversations/） ## 一个真实的查询生成 Bug 在进行端到端测试时，我们注意到当指定字段为自定义数值属性时，查询返回了空结果。 例如，一个购物服务可能会在用户购买时发送带有自定义属性的事件，该属性用于统计购物车中的商品数量。用户可能希望查看所有商品数量大于 10 的购买事件。但当他们使用搜索助手时，却没有返回任何事件。 ## 找到 AI 对话记录 如果我们在调试 API 端点中的错误，通常会先去 Sentry 找到对应事件并查看捕获的数据。 尽管这是一个由 LLM 生成的错误，我们仍然能够遵循相同的流程。 在本例中，我们导航到 Agents 视图，并使用过滤器找到了对应的交互记录。在这里，我们可以按时间范围、所使用的 agent（本例中是用于 traces 的 agent）以及我们自己的邮箱进行过滤，从而找到对应的 trace。 从那里，我们可以查看交互的时间线，这比查看一个 JSON 数据块要直观得多。 通过时间线，我们可以看到系统提示、LLM 生成内容以及为生成该（错误）响应而进行的工具调用。 了解工具调用为何返回特定数据通常十分重要。在这个视图中，我们可以跳转到对应的 trace，从而查看 agent 发出的后端 API 调用——就像我们调查前端 Bug 等非 AI 错误一样。 通过查看时间线和追踪数据，我们找到了根本原因。问题出在我们如何使用工具调用结果（来自我们自己的 API 端点）来生成系统提示上。 该提示在展示可用字段时，直接使用了字段名本身 bug__predictions_count，而非 Sentry 搜索语法所要求的 tags[bug_predictions_count, number] 格式。 这为我们提供了足够的信息，让我们能够创建一个新的评估场景来复现并修复该问题。 ## 在生产环境中验证 虽然我们可以看到本地评估在修复后通过了，但能在生产环境中验证其正常运行同样令人欣慰。 部署完成后，我们发出了相同的查询，并看到返回了正确的数据。 随后，我们回到 AI 对话视图，找到对应的追踪记录，确认系统提示中已包含修正后的信息。我们还可以看到传入 API 调用的参数，并确认其返回了正确的数据。 ## 现已融入本地开发流程 事实证明这一能力极为实用，因此我们也对本地评估运行进行了埋点，将数据同样发送至 Sentry。这意味着我们可以在本地迭代评估，并在提交 Pull Request 之前就能在 Sentry 中看到结果。 ## 熟悉的工具降低摩擦成本 通过将 AI 对话追踪与其他事件数据一同置于 Sentry 中，我们可以（https://sentry.io/product/tracing/ai-agent/） - 利用熟悉的工具查找相关的对话追踪记录 - 避免在不同工具之间来回复制/粘贴 ID 或数据 - 直接跳转至 Agent 调用我们自有 API 以生成响应时所涉及的相关工具调用 总体而言，将这些 Agent 追踪与其他数据放在一起，使得调试此类问题变得更加轻松。现在，每当我们需要深入分析某个需要改进的查询响应时，这里都是我们第一个查看的地方。 如果您正在构建自己的 AI Agent，请查阅 Sentry 的 Agent 追踪文档，了解如何在您自己的追踪中获得同等的可见性。（https://docs.sentry.io/product/agents/）
