LangGraph Studio 可视化调试教程：从零配置 LangGraph + LangSmith 智能体工作流

作者：袖梨 2026-07-29

工作流怎样在LangGraph studio 中实现可视化查看？

项目根目录的配置文件清单

准备接入 Studio 的标准项目目录应当采用如下结构：

my_agent_project/├── .env#1. 环境变量配置（密钥）├── langgraph.json#2. Studio 核心配置文件（导航图）└── agent.py#3. 你的图逻辑代码（引擎）

配置步骤详解

第一步：设置密钥环境 (`.env` 文件)

使用 Studio 时，强烈建议单独存放密钥，以便 Studio 启动后自动读取。

在项目根目录创建一个名称为 .env 的文本文件，并写入你的配置：

# .env 文件内容DEEPSEEK_API_KEY=sk-da217ba... (你的真实密钥)# LangSmith 追踪配置 (强烈建议开启，Studio 严重依赖它)LANGSMITH_TRACING=trueLANGSMITH_API_KEY=lsv2_pt_... (你的真实密钥)

(在 Python 代码里，可以把 os.environ["..."] = "..." 那些硬编码删掉了。)

第二步：设置 Studio 导航仪 (`langgraph.json`)

这是启动 Studio 最核心的配置文件。它告诉 Studio 该去哪里加载代码、加载哪些依赖。（强烈建议就取名为Langgraph.json,大小写无所谓。这样LangStudio就会自动识别到）

在项目根目录中创建 langgraph.json，然后复制以下标准模板：

{"dependencies": ["."],"graphs": {"math_agent": "./agent.py:agent"},"env": ".env"}

深入解析配置项：

"dependencies": ["."]：项目运行依赖的位置是当前目录，Studio 会由此获知。
"graphs"：它是核心配置，可以将其理解成一个注册表。
- "math_agent"：图显示在 Studio 左上角下拉菜单时所用的UI 名称（可由你任意命名，比如 DeepSeek_Calculator）。
- "./agent.py:agent"：物理路径通过此处建立映射。Python 文件相对路径位于冒号前面，你代码中的内容则位于冒号后面 builder.compile() 被赋值的那个变量名称。
"env": ".env"：第一步配置的密钥文件，应由 Studio 按此项指定的位置读取。

第三步：在代码端配置“去记忆化” (`agent.py`)

为了让 Studio 接管可视化和时光倒流功能，你的代码在导出给 Studio 使用时，必须是“裸编译”的。

请确认你的 agent.py 文件底部采用以下配置：

# ... 前面的 Nodes 和 Edges 逻辑保持不变 ...builder = StateGraph(MessagesState)builder.add_node("llm_node", llm_node)# ... 其他连线 ...# 【关键配置】：不要加 checkpointer=MemorySaver()agent = builder.compile() # 上面这个叫 "agent" 的变量，必须和 langgraph.json 里冒号后面的名字完全一致！

最终启动与验证

1. 启动服务在项目根目录打开终端（进入到当前项目的父目录），输入：

langgraph dev

参考示例如下：输入cd graph_api

2. 进入界面在终端打印出的图案下方，找到 Studio UI 的链接：https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

按住 Ctrl (或 Cmd) 后点击它，浏览器便会自动打开。

Lang Studio 可视化面板

三个核心控制面板：

打开 Studio 后，可以看到整个界面大致由左侧、中间和右侧三个核心工作区构成：

左侧面板 (Threads & Config)：配置及会话中心
- Threads (线程)：你的“记忆”由这里负责管理。代码中通过 MemorySaver 实现的记忆会在此处变得直观。每新建一个 Thread，都相当于开启一个全新且干净的对话上下文。
- Configuration：如果你在代码里定义了可配置项（比如切换模型种类、系统提示词），可以在这里实时调整，无需改代码。
交互和时间轴所在区域：中间面板 (Interaction)
- 你可以在这个区域和 Agent 互动，其形式类似 ChatGPT 的聊天框。
- 关键细节：消息发送后，此处除了呈现最终结果，还会用时间轴逐一展示 Agent 所经历的每个步骤 (Steps)。
右侧面板 (Graph & State)：X 光机与全局视野
- Graph 视图：代码中的 Edges（连线）和 Nodes（节点）会在此得到完整渲染。
- 整个图当前的全局变量字典会实时出现在 State 视图中，因此这里最为重要！

可视化调试进阶指南

步骤 1：审查架构图 (Visualizing the Graph)

右侧的 Graph 标签页应先行查看，此时对话尚未开始。

检查连线逻辑与预期是否一致（例如你的 llm_node 是否通过一条条件边指向 tool_node，tool_node 以及是否再次指回 llm_node）。
提示：图中存在死循环或断头节点时，其表现会非常醒目。

第一次调用 (Invoking)：步骤 2

点击左侧的 "+"，创建一个新的 Thread。
在中间区域底部的输入框内填写初始状态数据。需要注意，此处要求使用 JSON 格式输入（与你的 MessagesState）。
- 例如，可以输入：{"messages": [{"role": "user", "content": "3乘以5等于多少？"}]}
单击 Submit。
查看方法：持续观察右侧的拓扑图，你将看到 START 节点开始闪烁，数据随后流入 llm_node，之后由条件边触发并跳转到 tool_node，最终再次回到 llm_node 并输出最终结果。

步骤 3：查看数据 (Inspecting State)

遇到大模型胡言乱语或工具发生报错时，应当如何处理？

查看中间面板的时间轴，然后点击发生报错或你认为存在疑点的 Step。
此时需要在右侧面板中选择 State 标签。
此时可以看到特定时间点的全局字典状态，其中包括全部历史消息、大模型生成的 tool_calls ID 以及工具的中间返回结果。与在 Python 中到处写 print() 相比，其效率要高出一万倍。