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

工作流怎样在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 后，可以看到整个界面大致由左侧、中间和右侧三个核心工作区构成：

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

可视化调试进阶指南

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

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

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

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

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

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

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

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

步骤 4：时光倒流 (Time-Travel Debugging)

假定你的 Agent 在第 3 步作出了极其愚蠢的决定，例如调用了错误的工具：

1. 在中间面板中选择第 2 步，也就是发生错误之前的那一步。
2. 这时，右侧将出现 "Edit" (编辑) 或 "Fork" (分叉) 按钮。
3. 点击修改当时的状态（比如，你手动把大模型的系统提示词改严厉一点，或者直接篡改它发出的工具调用参数）。
4. 要继续运行，请点击 "Proceed"。
5. 一条全新的分支记录将随之生成！Studio 会沿你篡改后的新现实向下重新执行，起点是第 2 步。

热重载 (Hot Reload)

因为它是带着 [inmem] 启动的，所以这个 Studio 会持续监听本地文件。当你在 Python 代码中修改某个节点的逻辑或新增一条连线后，只需按下 Ctrl+S 浏览器中的 Graph 拓扑图，会在保存操作完成后自动瞬间刷新