结论先说
- 只看图连没连对(静态可视化):编译后直接调
graph.get_graph().draw_mermaid()拿纯文本流程图,或调draw_mermaid_png()直接存成 PNG 图片。 - 在命令行快速查错(轻量 Debug):把
graph.invoke(...)换成graph.stream(..., stream_mode="debug"),终端会按步打印每个节点的进入、工具入参和返回的状态字典。 - 重度排错与中途改状态重跑(图形化 Studio):安装
langgraph-cli[inmem]后运行langgraph dev,无需安装 Docker 就能在浏览器里打开 LangGraph Studio,实时看节点高亮、加断点拦截并回放历史检查点。 - 注意断网环境的小细节:
draw_mermaid_png()默认会把图结构发给外部mermaid.ink接口生成图片;内网保密项目请改用纯本地字符串导出draw_mermaid()。

图:本站根据 LangGraph 官方文档 Studio 与 Visualization 整理的示意图
本文根据 LangChain / LangGraph 官方可视化与 LangGraph Studio 文档整理,核对日期 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 LangChain 官方网站。
适用于谁
- 搜「langgraph 如何可视化」「langgraph 如何 debug」「langgraph studio 怎么用」的人;
- 刚把几个节点和条件边连起来(基础写法见 /guides/langgraph-quickstart-install-first-graph),结果运行时走错分支或卡在循环里,光看最后一句返回根本不知道中间哪一步出了错的开发者;
- 以为用 LangGraph Studio 必须先装厚重的 Docker Desktop、想知道怎么纯本地轻量跑起来的人。
一、第一层:两行代码导出静态拓扑图(核对连线逻辑)
写完 add_edge 和 add_conditional_edges 后,甚至不需要消耗任何大模型 Token,就能先把编译后的图画出来肉眼检查「有没有孤岛节点」「条件边虚线是不是指到了预期分支」。
python
# 假设 graph = builder.compile() 已经编译完成
# 做法 A:纯离线输出 Mermaid 语法字符串(可贴进 Markdown、GitHub PR 或 VS Code 预览)
mermaid_code = graph.get_graph().draw_mermaid()
print(mermaid_code)
# 做法 B:直接把流程图保存为本地 PNG 文件(默认需联网调 Mermaid.ink)
png_bytes = graph.get_graph().draw_mermaid_png()
with open("my_graph.png", "wb") as f:
f.write(png_bytes)
在导出的图里,实线箭头代表无条件固定跳转(add_edge),虚线箭头代表条件分支(add_conditional_edges)。如果你在图里嵌套了子图(Subgraph),还可以传入 xray=True(即 graph.get_graph(xray=True))把子图内部的节点一并展开显示。
二、第二层:终端 stream_mode 与检查点历史(代码级排错)
当连线没问题,但运行时大模型传错了参数或状态字段被意外覆盖时,最快的命令行调试办法是打开流式输出与状态快照检查:
stream_mode="updates":每跑完一个节点,只打印「这个节点刚刚往 State 里返回了什么增量」,最清爽易读;stream_mode="debug":打印完整的内部调度任务 ID、节点输入快照与异常堆栈,适合抓隐蔽的类型转换报错;graph.get_state_history(config):只要编译时挂了检查点保存器(如InMemorySaver),跑完后就能传入同一个thread_id遍历每一步的历史快照,看清第 2 步和第 3 步之间State字段到底是怎么变的。
python
for event in graph.stream(
{"messages": [("user", "查一下库存并生成补货建议")]},
stream_mode="updates",
):
for node_name, state_patch in event.items():
print(f"=== 刚执行完节点: {node_name} ===")
print(state_patch)

图:本站根据 LangChain 官方文档 LangGraph Studio 整理的示意图
三、第三层:用 langgraph dev 打开 LangGraph Studio(交互式断点与时间旅行)
早期版本的 Studio 桌面客户端依赖 Docker 容器构建,现在官方提供了纯 Python 内存运行模式,几分钟就能搭起来。
第一步:安装带内存模式的 CLI
在你的项目虚拟环境里执行:
bash
pip install -U "langgraph-cli[inmem]"
第二步:在项目根目录放一份最小 langgraph.json
假设你的状态图定义在 src/agent.py 文件里,编译后的图变量名叫 graph(注意:交给 Studio 运行的图变量在 builder.compile() 里不要自己传 checkpointer,本地服务器会自动挂载持久化层):
json
{
"dependencies": ["."],
"graphs": {
"my_agent": "./src/agent.py:graph"
},
"env": ".env"
}
第三步:启动本地热重载调试并打开画布
在根目录终端敲:
bash
langgraph dev
终端会启动本地开发服务器(默认地址 http://127.0.0.1:2024),并直接打印出一行指向网页端 Studio 画布的本地连接地址。用浏览器打开后,你可以做三件纯命令行很难做的事:
- 实时点亮执行路径:发一条测试输入,看着画布上的节点随着推理和工具调用逐个变亮(包括通过 MCP 挂载的外部工具节点,配置见 /guides/langgraph-mcp-integration-guide);
- 加前置断点(Interrupt):在危险写操作节点前勾上断点,图跑到此处会自动挂起等你点确认;
- 在线改状态与时间旅行(Fork / Replay):如果第 4 步大模型理解偏了,不用从第 1 步重跑烧前序额度,直接点开第 3 步的快照手动改掉里面那句消息或业务变量,从第 3 步分叉继续往后跑。
在本地零成本反复验证调试链路时,你也可以把节点临时切到本机离线模型(见 /guides/langgraph-local-model-ollama-guide),或者对比其他 SDK 的追踪面板思路(见 /guides/openai-agents-sdk-guardrails-tracing)。日常配合网页端 Claude 或 ChatGPT 分析长报错堆栈时,个人订阅方案说明可参考 /chongzhi/claude-pro。
常见问题
Q:打开终端给的 Studio 网页链接提示连不上本地 127.0.0.1:2024 怎么办?
部分隐私增强浏览器(如 Safari 或开启了严格本地网络拦截的浏览器)会阻止公网 HTTPS 前端页面直接请求本机回环 HTTP 端口。优先换成 Chrome 打开该链接,或按官方 CLI 提示附加支持隧道的参数重新启动。
Q:在 Studio 里改了本地 .py 源码,需要关掉 langgraph dev 重启吗?
不需要。langgraph dev 默认开启了文件监听热重载(Hot Reload),保存 Python 文件后本地服务会自动重新加载新节点逻辑,直接在网页画布开一个新线程测试即可。
相关教程
- /guides/langgraph-quickstart-install-first-graph:LangGraph Python 安装与第一个状态图
- /guides/langgraph-mcp-integration-guide:LangGraph 接入 MCP 工具服务器
- /guides/langgraph-local-model-ollama-guide:LangGraph 对接本地 Ollama 离线调试
- /guides/openai-agents-sdk-guardrails-tracing:智能体护栏与链路追踪对比
参考资料
- LangChain / LangGraph 官方文档:Studio 与 Visualization — https://docs.langchain.com/
langchain-ai/langgraph官方 GitHub 仓库 — https://github.com/langchain-ai/langgraph
0 条评论
还没有评论,来抢沙发~