LangSmith Studio 调试智能体

本文分享如何使用LangSmith Studio调试智能体。

一、Studio支持的智能体

LangSmith部署界面中的Studio（工作室）功能支持连接两种类型的图（Graph）智能体：

部署在云端或自托管环境中的图（Graph）
通过智能体服务器（Agent Server）在本地运行的图（Graph）

1. 已部署的图（Deployed Graphs）

在LangSmith用户界面中，可通过部署（Deployments）导航栏访问Studio功能。对于已部署的应用，你可以将Studio作为该部署的一部分进行访问。操作方法如下：在用户界面中导航至目标部署，然后选择Studio选项。此操作会加载与你的在线部署相连的Studio，使你能够对该部署中的对话线程（threads）、智能助手（assistants）和记忆（memory）执行创建、读取和更新操作。

2. 本地开发服务器

2.1 准备

若要使用Studio在本地测试应用程序，需满足以下条件：首先遵循本地应用快速入门指南操作。若不希望将数据追踪发送至LangSmith，可在应用程序的.env文件中设置LANGSMITH_TRACING=false。禁用追踪功能后，不会有任何数据从你的本地服务器传出。

2.2 环境搭建

安装LangGraph CLI

bash 复制代码

pip install -U "langgraph-cli[inmem]"
langgraph dev

此操作将在本地启动智能体服务器（Agent Server），并以内存运行模式（in-memory）运行。该服务器会启动监听模式，持续监听代码变更，一旦检测到变更便会自动重启。若需了解启动API服务器的所有可用选项，可查阅此参考文档。你将看到如下日志信息：

text 复制代码

> Ready!
>
> - API: [http://localhost:2024](http://localhost:2024/)
>
> - Docs: http://localhost:2024/docs
>
> - LangSmith Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

服务器启动后，系统会自动将你引导至Studio。

对于已在运行的服务器，可通过以下任一方式访问调试器（Dbugger）：直接导航至以下 URL：smith.langchain.com/studio/?bas... 在用户界面（UI）中导航至 "部署"（Deployments），点击某个部署上的 "工作室"（Studio）按钮，输入 http://127.0.0.1:2024 并点击 "连接"（Connect）。若你的服务器运行在其他主机（host）或端口（port）上，请更新 baseUrl 参数以匹配实际地址。

附加调试器若需通过断点（breakpoints）和变量检查（variable inspection）进行逐行调试，请执行以下操作：

bash 复制代码

# Install debugpy package
pip install debugpy
# Start server with debugging enabled
langgraph dev --debug-port 5678

然后附加你偏好的调试器,将以下配置添加到 launch.json 文件中：

json 复制代码

{
    "name": "Attach to LangGraph",
    "type": "debugpy",
    "request": "attach",
    "connect": {
      "host": "0.0.0.0",
      "port": 5678
    }
}

二、Studio的使用

本节介绍在"工作室"（Studio）中使用的核心工作流程，包括如何运行应用程序、管理智能助手（Assistant）配置以及处理对话线程（Thread）。每个部分均提供了"图模式"（Graph Mode，可完整查看图的执行过程）和"聊天模式"（Chat Mode，轻量级对话界面）两种模式下的操作步骤：

运行应用程序（Run application）：执行应用程序或智能体（Agent）并观察其运行状态。
管理智能助手（Manage assistants）：创建、编辑智能助手配置，并选择应用程序要使用的配置。
管理线程（Manage threads）：查看和整理对话线程，包括通过分支（fork）或编辑历史运行记录进行调试。

2.1 运行应用程序（Run application）

2.1.1 图模式（Graph）

1. 指定输入（Specify input）

在页面左侧、图界面下方的"输入"（Input）区域，定义图的输入内容。"工作室"（Studio）会根据图的已定义状态模式（state schema），尝试生成一个输入表单。若需禁用该表单，可点击"查看原始数据"（View Raw）按钮，此时将显示一个JSON编辑器。

点击"输入"（Input）区域顶部的上下箭头，可切换并使用之前提交过的输入内容。

2. 运行设置（Run settings）

（1）智能助手（Assistant）

若要指定运行时使用的智能助手，操作步骤如下：

点击左下角的"设置"（Settings）按钮。若当前已选中某个智能助手，该按钮还会显示该助手的名称；若未选中任何智能助手，按钮将显示"管理智能助手"（Manage Assistants）。
选择要运行的智能助手。
点击弹窗顶部的"启用"（Active）开关，激活该智能助手。

（2）流式传输（Streaming）

点击"提交"（Submit）按钮旁的下拉菜单，然后通过开关启用或禁用流式传输功能。

（3）断点（Breakpoints）

若要带断点运行图，操作步骤如下：

点击"中断"（Interrupt）按钮。
选择一个节点（Node），并指定是在该节点执行"前"还是"后"暂停。
在线程日志（Thread Log）中点击"继续"（Continue），恢复程序执行。

如需了解有关断点的更多信息，请参考"人机协同"（Human-in-the-loop）部分。

3. 提交运行（Submit run）

若要使用指定的输入内容和运行设置提交运行任务，操作步骤如下：

点击"提交"（Submit）按钮。该操作会在当前选中的线程中添加一条运行记录；若当前未选中任何线程，则会创建一个新线程。
若要取消正在进行的运行任务，点击"取消"（Cancel）按钮。

2.1.2 聊天模式（Chat）

在对话面板底部，指定你的聊天应用程序的输入内容。

点击 "发送消息"（Send message）按钮，将输入内容作为 "人类消息"（Human message）提交，随后会以流式传输方式返回响应。

若要取消正在进行的运行任务：

点击 "取消"（Cancel）按钮。
点击 "显示工具调用"（Show tool calls）开关，可在对话中隐藏或显示工具调用内容。

2.2 管理智能助手（Manage assistants）

"工作室"（Studio）支持查看、编辑和更新智能助手，也允许你使用这些智能助手配置来运行图。

2.2.1 图模式（Graph）

查看智能助手的操作步骤如下：

点击左下角的"管理智能助手"（Manage Assistants）按钮，将弹出一个弹窗，显示当前选中图的所有智能助手。
指定你想要标记为"启用"（Active）状态的智能助手及其版本。提交运行任务时，LangSmith 将使用该智能助手。

"默认配置"（Default configuration）选项处于启用状态，该配置与图中定义的默认配置一致。对该配置所做的编辑将用于更新运行时配置，但不会更新现有智能助手或创建新智能助手，除非你点击"创建新智能助手"（Create new assistant）按钮。

2.2.2 聊天模式（Chat）

聊天模式（Chat mode）允许你通过页面顶部的下拉选择器，在图（Graph）中的不同智能助手（assistants）之间进行切换。若需创建、编辑或删除智能助手，请使用图模式（Graph mode）。

2.3 管理线程（Manage threads）

"工作室"（Studio）提供工具，可查看服务器上保存的所有线程并编辑其状态。在"图模式"和"聊天模式"下，你均可创建新线程、切换线程以及修改历史状态。

2.3.1 图模式（Graph）

1. 查看线程（View threads）

在右侧面板顶部，点击下拉菜单，可查看所有现有线程。
选择目标线程后，该线程的历史记录将显示在页面右侧。
若要创建新线程，点击"+ 新线程"（+ New Thread）并提交运行任务。
若要查看线程中更详细的信息，将页面顶部的滑块向右拖动；若要减少显示的信息，将滑块向左拖动。此外，你还可以折叠或展开单个对话轮次（turns）、节点（nodes）以及状态（state）的关键字（keys）。
切换"美观模式"（Pretty）和"JSON模式"（JSON mode），可查看不同的渲染格式。

2. 编辑线程历史（Edit thread history）

若要编辑线程状态，操作步骤如下：

在目标节点旁，点击"编辑节点状态"（Edit node state）。
根据需求编辑节点的输出内容，然后点击"分支"（Fork）按钮确认。该操作将从选中节点的检查点（checkpoint）创建一个新的分支运行记录。

若你不想编辑状态，而是希望从某个检查点重新运行线程，可点击"从此处重新运行"（Re-run from here）按钮。该操作同样会从选中的检查点创建一个新的分支运行记录，适用于需要重新运行但无需修改状态的场景（例如更换选中的智能助手）。

2.3.2 聊天模式（Chat）

在页面的右侧面板中查看所有对话线程（thread）。
选择目标线程后，该线程的历史记录将显示在中央面板中。
若要创建新线程，点击 "+" 号并提交一次运行（run）任务。若要编辑线程中的人类消息（human message），操作步骤如下：
点击人类消息下方的 "编辑节点状态"（Edit node state）。
根据需求编辑消息内容并提交。此操作将创建一条对话历史的新分支（fork）。
若要重新生成 AI 消息（AI message），点击 AI 消息下方的重试图标（retry icon）。