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"：你可以随便起的UI 名称（比如，会显示在 Studio 左上角的下拉菜单里，用来代表你的图 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)：以时间轴呈现交互
   • 类似于 ChatGPT 的聊天框，你与 Agent 的互动就在这个区域完成。
   • 神级细节：这里会逐一列出 Agent 经历的每一个步骤 (Steps)，并用时间轴呈现；消息发送后的最终结果也会显示。
3. 右侧面板 (Graph & State)：全局视角与 X 光机
   • Graph 视图：代码里写下的 Edges（连线）和 Nodes（节点），都会被完美渲染出来。
   • State 视图：当前整个图的全局变量字典会在此实时显示，这里最重要！

进阶指南：调试过程可视化

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

先查看右侧的 Graph 标签页，再开始对话。

• 确认连线逻辑是否符合预期（比如你的 llm_node 是否通过一条条件边指向 tool_node，tool_node 是否随后又指回 llm_node）。
• 提示：图中若存在死循环或断头节点，通常会十分显眼。

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

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 拓扑图会在保存后自动瞬间刷新