LangGraph 第15章：LangGraph Studio 可视化调试

概述

LangGraph Studio 是 LangGraph 官方提供的可视化开发和调试工具。它提供了一个图形化界面，让你可以实时查看图的执行过程、检查每个节点的状态、进行时间旅行调试等。相比于在代码中加 print 语句调试，LangGraph Studio 能显著提升开发效率。

CLI 安装与配置

LangGraph Studio 通过 LangGraph CLI 来启动。首先确保你的环境中已经安装了必要的依赖。

安装 LangGraph CLI

# 使用 pip 安装
pip install langgraph-cli

# 验证安装
langgraph --version

准备项目结构

一个标准的 LangGraph 项目结构如下：

my_agent_project/
├── src/
│   ├── agent.py          # 主图定义
│   ├── tools.py          # 工具定义
│   ├── state.py          # 状态定义
│   └── nodes.py          # 节点定义
├── langgraph.json        # LangGraph 配置文件
├── requirements.txt      # Python 依赖
└── .env                  # 环境变量（API Key 等）

langgraph.json 配置详解

langgraph.json 是 LangGraph Studio 的核心配置文件，告诉 CLI 如何加载和运行你的图。

基础配置

{
  "node_version": "20",
  "dockerfile_lines": [],
  "graphs": {
    "agent": "./src/agent.py:graph"
  },
  "env": ".env",
  "python_version": "3.11",
  "dependencies": [
    "./src"
  ]
}

配置字段说明

多图配置

如果你的项目有多个图，可以这样配置：

{
  "graphs": {
    "simple_chat": "./src/simple_chat.py:chat_graph",
    "research_assistant": "./src/research.py:research_graph",
    "multi_agent": "./src/multi_agent.py:supervisor_graph"
  },
  "dependencies": [
    "./src",
    "./requirements.txt"
  ]
}

这样在 Studio 中可以切换查看不同的图。

启动开发服务器

基本启动命令

# 在项目根目录执行
langgraph dev

启动成功后，你会看到类似这样的输出：

Ready!
- API: http://localhost:8123
- Studio UI: https://smith.langchain.com/studio?baseUrl=http://localhost:8123
- LangSmith: https://smith.langchain.com

常用启动参数

使用自定义端口

langgraph dev --port 8080 --host 0.0.0.0

启动后，在浏览器中打开 Studio UI 链接即可进入可视化界面。

实时可视化

LangGraph Studio 启动后，你会看到一个图形化界面，包含以下核心区域：

1. 图结构面板：左侧展示完整的图结构，节点和边的布局一目了然
2. 输入面板：左上角输入测试数据，点击运行
3. 状态检查器：右侧展示每个节点的输入/输出状态
4. 执行日志：底部显示执行过程中的详细日志
5. 线程管理：管理不同的会话线程

运行图

在图结构面板中：

1. 点击一个起始节点或图的入口点
2. 在输入面板中填入测试输入数据（JSON 格式）
3. 点击 "Run" 按钮
4. 观察执行过程：当前执行的节点会高亮显示，边上的箭头会流动

查看节点状态

运行过程中，点击任意节点可以查看该节点的执行详情：

• Input：该节点接收到的输入状态
• Output：该节点处理后返回的更新
• Duration：节点执行耗时
• LLM Calls：如果节点调用了 LLM，会显示调用详情（Token 消耗、响应内容等）

状态检查：节点输入输出

LangGraph Studio 最强大的功能之一就是可以逐节点检查状态。在调试复杂工作流时，这比在代码中到处加 print 语句高效得多。

查看完整状态链

执行完成后，你可以在右侧面板中看到每个节点执行前后的完整状态快照：

Thread: thread-123
├── Entry Point (input)
│   └── { "messages": [{"role": "user", "content": "你好"}] }
├── Node: chat_node
│   ├── Input: { "messages": [...] }
│   ├── Output: { "messages": [...] }
│   └── Duration: 1.2s
├── Node: tool_node (conditional edge)
│   ├── Input: { "messages": [...] }
│   └── Output: { "messages": [...] }
└── End (output)
    └── { "messages": [{"role": "assistant", "content": "你好！有什么可以帮助你的？"}] }

对比状态差异

Studio 会自动高亮状态中发生变化的部分，让你一眼看出每个节点具体修改了哪些字段。

时间旅行调试

时间旅行（Time Travel）是 LangGraph Studio 的一个独特功能，允许你回到过去的某个执行点，从那里重新执行。

使用场景

• 分支探索：在条件路由节点处，尝试不同的分支路径
• 错误恢复：回到出错节点之前的状态，修复问题后重新执行
• 对比分析：同一个输入，在某个节点使用不同的参数，对比输出差异

操作步骤

1. 运行一次完整的图执行
2. 在右侧的状态时间线中找到你想要回溯的状态点
3. 点击该状态点旁边的 "Branch" 按钮
4. 修改该节点的输入参数
5. 点击运行，从该节点重新开始执行

代码中的 checkpoint 支持

时间旅行功能需要 Checkpointer 支持：

from langgraph.checkpoint.memory import MemorySaver
from langgraph.checkpoint.sqlite import SqliteSaver

# 使用 SQLite 持久化，支持时间旅行
checkpointer = SqliteSaver.from_conn_string("checkpoints.db")

app = graph.compile(checkpointer=checkpointer)

热重载

LangGraph Studio 支持热重载（Hot Reload），当你修改代码后不需要重启服务器。

启用热重载

# 启动时添加 --reload 参数
langgraph dev --reload

或者直接使用默认方式启动，Studio 默认会监听文件变化。当检测到代码变更时：

1. 自动重新加载修改的模块
2. 更新图结构
3. 保留当前会话状态

这意味着你可以边修改代码边测试，开发效率大幅提升。

热重载注意事项

• 修改图结构（增删节点、边）后，需要重新运行当前执行
• 修改节点内部逻辑，热重载后立即生效
• 修改状态定义（TypedDict 的字段），建议重启服务器以确保类型一致
• 新增依赖后，需要重新执行 langgraph dev

断点调试

LangGraph Studio 支持图形化断点设置，你可以在任意节点之前或之后设置断点。

设置断点

在 Studio 界面中：

1. 右键点击任意节点
2. 选择 "Add Breakpoint Before" 或 "Add Breakpoint After"
3. 节点上会出现断点标记

代码级断点

也可以在代码中通过 interrupt_before 和 interrupt_after 参数设置断点：

# 在编译时设置断点
app = graph.compile(
    checkpointer=checkpointer,
    interrupt_before=["tool_node"],     # 进入 tool_node 前暂停
    interrupt_after=["chat_node"]      # 离开 chat_node 后暂停
)

断点交互

当执行遇到断点时：

1. 执行暂停，断点节点会闪烁提示
2. 你可以查看当前完整状态
3. 可以选择 "Continue" 继续执行
4. 或者 "Edit State" 修改状态后再继续
5. 甚至可以 "Branch" 创建一个新的执行分支

这种交互方式让 Human-in-the-Loop 模式的开发变得非常直观。

调试工作流示例

一个典型的调试过程如下：

1. 启动 Studio：langgraph dev
2. 输入测试数据：填入一个可能触发问题的输入
3. 运行观察：执行到出错或不符合预期的节点
4. 检查状态：查看该节点的输入/输出，确定问题原因
5. 修改代码：修复 bug
6. 热重载：代码自动生效，不需要重启
7. 重新执行：验证修复是否正确
8. 时间旅行：如果需要对比，回到之前的状态点重新执行

常见问题

Studio 启动失败

问题：langgraph dev 启动时报错

解决方案：

• 确认 langgraph.json 配置正确
• 检查依赖是否全部安装：pip install -r requirements.txt
• 确认 Python 版本兼容：python --version

图结构不更新

问题：修改代码后图结构没有变化

解决方案：

• 确认热重载正常工作
• 如果是新增节点或边，需要重新运行
• 尝试手动刷新 Studio 页面

端口被占用

问题：Address already in use 错误

解决方案：

# 使用其他端口
langgraph dev --port 8124

# 或者终止占用进程
lsof -i :8123
kill -9 <PID>

LangGraph Studio 是开发 LangGraph 应用的核心工具，掌握它将让你在构建、调试复杂工作流时事半功倍。下一章我们将总结 LangGraph 的最佳实践和常见问题的解决方案。