LangGraph 的图形化界面与可视化

约 1918 字大约 6 分钟

LangGraphLangGraph StudioAI Agent

2026-09-10

LangGraph 把工作流建模成一张图，那这张图能不能「看见」？答案是可以，而且官方提供了不止一种方式。但它们的定位差别很大——有的是画图工具，有的是调试器，有的干脆是给终端用户用的聊天界面。先把它们分清楚，再谈怎么用。

四种方式一览

工具	定位	用在什么阶段	是否需要起服务
`draw_mermaid()` / `print_ascii()`	代码内导出图结构	随时，写文档	否
LangGraph Studio	可视化调试 IDE	开发调试	是（`langgraph dev`）
LangGraph Builder	拖拽画图生成代码骨架	架构设计	否（纯 Web）
Agent Chat UI	面向终端用户的对话前端	交付演示	是（连 deployment）

一句话概括：调试选 Studio，设计选 Builder，写文档用 draw_mermaid()，给别人演示用 Agent Chat UI。

一、代码内可视化：最轻量的方案

不需要任何服务，编译完的图对象直接就能导出结构。核心入口是 graph.get_graph()，它返回一个可绘制的图对象，后面接不同的 draw_* 方法。

导出 Mermaid

graph = builder.compile()

# 拿到 Mermaid 源码字符串，可以直接贴进 Markdown
print(graph.get_graph().draw_mermaid())

输出大致长这样：

graph TD;
    __start__([START]) --> chatbot;
    chatbot -.-> tools;
    chatbot -.-> __end__([END]);
    tools --> chatbot;

写技术文档时这个最实用——纯文本、可 diff、渲染交给 Markdown 引擎。

渲染成 PNG

from IPython.display import Image, display

display(Image(graph.get_graph().draw_mermaid_png()))

draw_mermaid_png() 返回的是 PNG 字节流。需要注意的是，它默认会把图的 Mermaid 源码发到 mermaid.ink 这个在线服务去渲染，也就是说：需要联网，且图结构会离开本机。如果介意这点，可以切成本地渲染：

from langchain_core.runnables.graph import MermaidDrawMethod

png = graph.get_graph().draw_mermaid_png(
    draw_method=MermaidDrawMethod.PYPPETEER  # 本地起 headless 浏览器渲染
)
with open("graph.png", "wb") as f:
    f.write(png)

PYPPETEER 方式需要额外装 pyppeteer 并下载 Chromium，第一次会比较慢，但完全离线。

终端 ASCII 图

graph.get_graph().print_ascii()

依赖 grandalf（pip install grandalf）。没有图形环境、纯 SSH 上开发时挺方便。

展开子图

如果图里嵌套了子图（一个节点本身是另一张编译好的图），默认只会显示成一个普通节点。加 xray 参数可以把内部结构展开：

graph.get_graph(xray=True).draw_mermaid_png()   # 展开一层
graph.get_graph(xray=2).draw_mermaid_png()      # 展开两层

多 Agent 架构里这个参数几乎是必开的，否则只能看到几个孤零零的方块。

提示

draw_* 系列只能画出静态结构，画不出运行时状态。想看「这次跑到哪个节点了、state 变成什么样了」，需要下面的 Studio。

二、LangGraph Studio：可视化调试 IDE

这是 LangGraph 真正意义上的图形化界面，也是日常调 Agent 用得最多的那个。

它能做什么

图结构可视化，运行时高亮当前执行到的节点，能看到条件边实际走了哪条分支
每一步的 state 快照——输入什么、输出什么、状态怎么被 reducer 合并的，全部展开可见
时间旅行（time travel）：跳回任意一个历史 checkpoint 重新执行
改 state 再继续跑：在界面里直接编辑某个 checkpoint 的状态，然后 fork 出一条新的执行分支。调 Agent 时不用为了复现某个中间状态而反复跑整条链路，这是最省时间的一个功能
Human-in-the-loop 交互：图里 interrupt() 暂停后，可以在界面上决策再放行
Prompt 快速迭代：对接 LangSmith 的 Playground 改 prompt 后直接重跑节点

怎么起

Studio 现在是 Web 版，托管在 LangSmith 上（早期那个 macOS 桌面 App 已经废弃了）。使用方式是本地起一个开发服务，浏览器连过去：

pip install -U "langgraph-cli[inmem]"
langgraph dev

终端会输出类似这样的地址：

🚀 API: http://127.0.0.1:2024
🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

点开第二个链接就是 Studio。虽然界面由 LangSmith 托管，但图和数据都跑在本地的 2024 端口，代码不会上传。

前置条件：langgraph.json

langgraph dev 要求项目根目录有一个 langgraph.json，用来告诉 CLI 图在哪：

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

字段	含义
`dependencies`	依赖来源，`["."]` 表示当前项目
`graphs`	图的注册表，`名字: 文件路径:变量名`
`env`	环境变量文件路径

graphs 里的变量必须是编译后的图（即 builder.compile() 的结果），而不是 StateGraph 构建器。可以注册多个图，Studio 左上角能切换。

另外需要一个 LANGSMITH_API_KEY 写进 .env——即使只在本地跑，Studio 的界面本身也需要 LangSmith 账号登录。

热重载

langgraph dev 自带热重载，改完节点代码存盘，Studio 里直接重跑即可，不用重启服务。

三、LangGraph Builder：拖拽画图生成代码

地址是 build.langchain.com，定位在 Studio 的上游——不是调试已有的图，而是设计还没写的图。

用法是在画布上拖节点、连边、标注条件分支，画完导出 Python 或 TypeScript 的代码骨架。

要注意它只生成结构：StateGraph 的声明、add_node / add_edge / add_conditional_edges 的调用、以及空的节点函数签名。节点内部的逻辑还是得自己写。

# Builder 导出的大致是这种东西
def chatbot(state: State) -> dict:
    ...  # 逻辑留空，等你填

builder = StateGraph(State)
builder.add_node("chatbot", chatbot)
builder.add_conditional_edges("chatbot", router, {...})

适合两种场景：跟别人讨论架构时快速把图画出来对齐；或者图的分支比较绕，先在画布上理顺再动手。日常写小图其实直接敲代码更快。

四、Agent Chat UI：给终端用户的界面

langchain-ai/agent-chat-ui 是官方开源的 Next.js 前端，填入一个 LangGraph 的 deployment URL 和 graph id 就能对话。

它和 Studio 的区别在于面向的人不同：Studio 是给开发者看图和 state 的调试器，Agent Chat UI 是给使用者的聊天窗口——看不到图，只看到对话。

它支持的特性包括流式输出、工具调用过程展示、interrupt() 的人工确认交互，以及 Generative UI（节点直接推送 React 组件到前端渲染）。做 Demo 或者给非技术同事演示时，比让人对着 Studio 的图讲解要合适得多。

五、和 LangSmith / Langfuse 的区别

这三者容易混，但看的东西完全不是一回事：

	看什么	关注点
LangGraph Studio	图结构 + 每步 state	这次执行怎么走的、状态怎么变的
LangSmith	调用链路 trace	每次 LLM 调用的 prompt、token、耗时、成本
Langfuse	同上（开源自托管方案）	同上，另有 Prompt 管理、评测

Studio 回答的是「我的图逻辑对不对」，trace 类工具回答的是「线上跑得好不好、贵不贵」。开发阶段用 Studio，上线之后看 trace，两者是接力关系而非替代关系。

具体的 trace 用法可以看 Langfuse 追踪。

别和 LangFlow / Flowise 搞混

LangFlow、Flowise 这类是零代码拖拽平台——在界面上搭完整条链路直接就能跑，节点逻辑也在界面里配。它们的目标用户是不写代码的人。而 LangGraph Builder 只负责生成骨架，逻辑仍然回到代码里写，Studio 更是纯粹的调试器。定位完全不同。

怎么选

写文档、发 PR：draw_mermaid()，纯文本可 diff
日常调 Agent：langgraph dev + Studio，尤其是需要反复复现中间状态的时候
设计复杂分支：Builder 画完再导出
给人演示：Agent Chat UI
上线后排查：LangSmith 或 Langfuse

最低成本的组合其实是：开发时挂着 langgraph dev，写文档时补一行 draw_mermaid()，其余按需引入。

Claude Code

OpenAI

Qwen Code

LangGraph

Langfuse