LangSmith 推出 Deep Agents 调试方案:集成 AI 助手 Polly 解析复杂代理决策链与执行轨迹

原标题:Debugging Deep Agents with LangSmith
42AI 研判分

LangChain 团队发布 LangSmith 针对“深度智能体”(Deep Agents)的调试增强功能,旨在解决多步推理与工具调用中的错误定位难题。该更新引入了名为 Polly 的 AI 辅助调试器,能够自动分析代理的执行轨迹、决策逻辑及中间状态,帮助开发者快速识别并修复复杂代理系统中的故障。

报道正文

本文目录7 个章节

Deep AgentsLangSmith可观测性与评估

使用 LangSmith 调试 Deep Agents

LangChain 团队2025年12月10日6分钟返回博客创建智能体创建智能体

调试是发现并修复错误的过程。这是软件工程中的关键步骤,在智能体工程中更是至关重要。LangSmith的核心能力之一,就是为 LLM 应用提供调试工具。

今天,我们加倍投入,致力于解决当前新兴的“深度智能体”(deep agents)开发浪潮中的这一难题。

在这篇博客中,我们将:

  • 解释为什么调试深度智能体与调试更简单的 LLM 应用有所不同
  • 介绍 Polly(一款用于智能体工程的 AI 助手),以协助在 LangSmith 中调试深度智能体
  • 发布 langsmith-fetch,这是一款 CLI 工具,旨在为 Claude Code 或 DeepAgents CLI 等编码智能体赋予调试能力

深度智能体与简单 LLM 应用的区别

与简单的 LLM 调用或短工作流不同,深度智能体的运行时间长达数分钟,涉及数十甚至数百个步骤,并且通常包含与用户的多轮交互。

因此,单次深度智能体执行产生的追踪数据(traces)可能包含海量信息,远超人类轻松浏览或推理的能力范围。当出现问题时,往往难以直观判断究竟是哪个决策、提示词指令还是工具调用导致了当前的行为表现。

这正是使用 LangSmith 进行追踪——并利用 AI 分析这些追踪数据——变得至关重要的原因。那么,具体而言,是什么让深度智能体变得更加复杂呢?

  • 更长的提示词: 深度智能体(Deep Agents)的提示词通常长达数百甚至数千行——一般包含通用角色设定、工具调用指令、重要准则以及少样本示例。当行为表现下降时,很难确定是提示词的哪一部分导致了问题。
  • 更长的执行轨迹: 深度智能体可能运行数十甚至数百个步骤(耗时数分钟才能完成)。面对如此庞大的轨迹数据,人类需要解析的内容显著增加,难以快速定位有意义的部分。
  • 多轮交互: 深度智能体默认支持人在回路(human-in-the-loop)的工作流。与深度智能体进行有意义的对话通常涉及多次来回交互。为了理解智能体的操作并查看其完整轨迹,你需要跨越多轮交互进行分析。

Tracing 捕获相关信息

要调试智能体,你需要对其内部运行情况具备可见性。这就是 Tracing(追踪)发挥作用的地方。

我们使用 Tracing 这一统称来描述将智能体执行数据记录到 LangSmith 的过程。数据格式由 Runs(运行)、Traces(轨迹)和 Threads(线程) 组成。

  • Runs: 智能体执行的单个步骤。例如 LLM 模型调用和工具调用。Runs 以树状结构嵌套。
  • Traces: 智能体的一次完整执行。一个 Trace 由一组 Runs 构成的树组成。
  • Threads: 多个 Traces 的集合。一个 Thread 代表用户与应用之间的一次完整对话。

设置 Tracing 非常简单——你可以按照此指南在几分钟内完成配置。

一旦应用数据进入 LangSmith,你就可以利用 AI 分析完整的智能体轨迹,以查明问题所在,并随后建议更新提示词。主要有两种方法可以实现这一点。

Polly - 面向智能体工程的 AI 助手

Polly 是一项新的应用内功能,允许你通过与智能体聊天来分析你的线程和轨迹数据。请观看我们的视频概览。

以下是几种与 Polly 聊天的方式!

在 Trace 视图中

你可以使用 Polly 来调试、分析并理解 Trace 中发生的事情。你无需手动扫描几十甚至上百个步骤,而是可以直接向 Polly 提问,例如:

  • “Agent 是否有可以做得更高效的地方?”
  • “Agent 是否犯了任何错误?”

这对于 Deep Agents(深度智能体)尤其有帮助,因为它们的 Trace 通常较长,且故障模式可能分散在多个步骤中。

在 Thread 视图中

这与单个 Trace 类似,但在此处,Polly 可以访问整个 thread 的信息。Thread 跨越多个对话轮次,有时甚至持续数小时或数天。对于人类而言,很难保持对所有这些上下文的全面感知。

在 Prompt Playground 中

Deep Agent 最重要的组成部分之一是系统提示词(system prompt)。Polly 经过调优,是一位出色的提示词工程师!你只需用自然语言描述期望的行为,Polly 就会相应地更新你的提示词。Polly 还可以帮助你在模型调用中定义结构化输出或模拟工具。

LangSmith Fetch CLI - 让你的编码代理成为专家级代理工程师的工具

如果你更倾向于在 IDE 或代码代理(例如 DeepAgents、Claude Code 等)中工作,我们提供了一个 CLI LangSmith Fetch,它可以轻松连接到 LangSmith traces 或 threads。无论你是在调试 agent、分析对话流程,还是从生产环境的 traces 构建数据集,这个 CLI 都能提供快速、灵活的访问方式,获取你的 LangSmith traces 和 threads。

它弥合了 LangSmith UI 与你本地工作流之间的差距。当你确切知道需要什么时,可以通过 ID 获取 trace 或 thread;当你需要抓取刚刚发生的内容时,可以通过时间范围获取。该工具支持多种输出格式(人类可读的面板视图、美化后的 JSON 或紧凑的原始 JSON),从而适应不同的使用场景——无论你在终端中检查数据、通过管道传递给 jq,还是将结果输入 LLM 进行分析。

它支持两个关键工作流。首先是“我刚运行了某个任务”的工作流,用于获取最近的线程:你执行你的 agent 后,立即运行 langsmith-fetch threads ./my_data 即可抓取项目中最新的 traces,而无需在 UI 中查找 ID。你可以添加时间过滤器如 --last-n-minutes 30 来缩小搜索范围,或使用 --project-uuid 定位到特定项目。

BASH
# 刚运行了你的 agent?立即抓取最新的 trace
langsmith-fetch traces --project-uuid <your-uuid> --format json

# 或者抓取最后 5 个 traces
langsmith-fetch traces --project-uuid <your-uuid> --limit 5

其次是批量导出工作流:当你需要为评估或分析准备数据集时,像 langsmith-fetch threads ./my-data --limit 50 这样的命令可以抓取多个线程并将每个线程保存为独立的 JSON 文件,非常适合批处理或构建测试集。

BASH
# 或者从特定项目中抓取最后 5 个 traces
langsmith-fetch traces --project-uuid <your-uuid> --limit 5

当然,你也可以直接指定所需的 thread 或 trace ID。输出格式可根据需求调整:使用 --format pretty 通过 Rich 面板在终端中查看,使用 --format json 获取可读的结构化数据,或使用 --format raw 将数据管道传输到其他工具。

LangSmith 让调试和改进 Deep Agents 变得轻松

Deep Agents 功能强大,但相比简单的 LLM 工作流,它们运行时间更长且更为复杂。要理解并改进它们,你需要洞察 Deep Agents 的实际行为。

借助 LangSmith,你可以追踪你的 Deep Agents 并观察其内部运作——然后与 Polly 对话以分析你的 Deep Agent 的行为,并利用 AI 帮助你优化 prompts。如果你更倾向于使用 Claude Code 或其他 coding agent 进行分析,可以使用 LangSmith Fetch 为你的 coding agents 配备所有必要的调试工具。

只需几分钟即可设置好 tracing,今天就在 LangSmith 上与 Polly 聊天,调试并改进你的 Deep Agents!

看清你的 Agent 到底在做什么

LangSmith 是我们的 agent 工程平台,帮助开发者调试每一个 agent 决策、评估变更,并实现一键部署。

试用 LangSmith 预约演示