LangGraph 平台与 Studio

写完图、跑通逻辑只是第一步，真正要把智能体交付出去，你还需要「能可视化调试图、能在线干预状态、能一键部署」的工具。LangGraph 官方给出了两件套：LangGraph Platform（部署运行平台）与 LangGraph Studio（可视化调试桌面应用）。本篇带你把它们在本地跑起来，并理解它们和 LangSmith 的关系。

一、概念总览

1. LangGraph Platform / Cloud

LangGraph Platform 是官方提供的「运行 LangGraph 应用的平台」，分三种形态：

形态	说明	适用场景
LangGraph Cloud（托管）	官方 fully-managed，你只管推代码	快速上线、不想运维
Self-hosted（自托管 Server）	在自己服务器/云上跑官方 Server 镜像	数据合规、私有化
本地开发 Server	langgraph dev 起一个本地 Server	开发调试

三者共用同一套 API（/invoke、/stream、/threads 等），代码无需改动就能在三者间迁移。这一点对 Java 背景的同学很熟悉——类似于「同一个 Spring Boot 应用，开发跑本地，生产跑 K8s」。

2. LangGraph Studio

Studio 是一个桌面应用（基于 Tauri，Electron 风格），主要能力：

• 图可视化：自动按你在代码里定义的节点和边渲染成流程图
• 实时看状态：每跑一步，看每个节点输出的 state 快照
• 消息流：对话类智能体里每条 message 单独展示
• 断点与手动干预（HITL）：在指定节点暂停，手工改 state 后继续
• 时间旅行：回到历史某一步 fork 出新分支重跑

给 Java 同学

Studio 的定位类似 LangGraph4j 里的可视化调试，但官方原生、功能更全。LangGraph4j 目前没有等价物，需要自己写前端。

flowchart LR
    A[你的图代码 graph.py] --> B[langgraph.json 配置]
    B --> C[langgraph dev 本地 Server]
    C --> D[Studio 桌面应用]
    C --> E[REST API /invoke /stream]
    D -.可干预.-> C
    C -.上报 trace.-> F[LangSmith]

二、本地用 Studio 调试：完整步骤

1. 安装前置

Studio 需要 Node.js（>=18）来跑 npx，Python 端装好 langgraph：

# Windows / macOS / Linux 通用
pip install -U "langgraph[inmem]" -i https://pypi.tuna.tsinghua.edu.cn/simple
# 如需国内镜像装 npm 包，可配 npmmirror
npm config set registry https://registry.npmmirror.com

Windows 注意

PowerShell 执行 npx 若被策略拦截，先跑：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。

2. 写一个可被 Studio 加载的图

新建目录 studio_demo/，结构如下：

studio_demo/
├── langgraph.json      # 配置入口
├── my_graph.py         # 图代码
└── requirements.txt

my_graph.py（一个最小 ReAct）：

from typing import Annotated
from typing_extensions import TypedDict
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain_core.messages import HumanMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition

# 一个简单工具：计算平方
@tool
def square(x: float) -> float:
    """返回 x 的平方"""
    return x * x

tools = [square]
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

class State(TypedDict):
    messages: Annotated[list, add_messages]

def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

graph_builder = StateGraph(State)
graph_builder.add_node("chatbot", chatbot)
graph_builder.add_node("tools", ToolNode(tools))
graph_builder.add_edge(START, "chatbot")
graph_builder.add_conditional_edges("chatbot", tools_condition, "tools")
graph_builder.add_edge("tools", "chatbot")
graph_builder.add_edge("chatbot", END)

# Studio 通过这个变量名加载图，名字固定为 graph
graph = graph_builder.compile()

3. 配置 langgraph.json

这是 Studio 的「入口清单」，告诉 Server 去哪个文件、哪个变量加载图：

{
  "dependencies": ["."],
  "graphs": {
    "react_demo": "./my_graph.py:graph"
  },
  "env": ".env"
}

字段说明：

• dependencies：可安装的 Python 依赖路径（. 表示当前目录，会读 requirements.txt）
• graphs：键是「图的名字」（Studio 左上角下拉里会显示），值是 文件路径:变量名
• env：环境变量文件路径（放 OPENAI_API_KEY）

.env 文件：

OPENAI_API_KEY=sk-xxxxx
# 国内可加 base_url
OPENAI_BASE_URL=https://api.openai-proxy.com/v1

4. 启动 Studio

在 studio_demo/ 目录下：

npx @langchain/langgraph-cli@latest dev

首次跑会下载依赖、装 requirements.txt，耐心等。看到 Server started at http://127.0.0.1:2024 后，命令行会自动弹出浏览器版 Studio（也可装桌面版 App）。

桌面版 App

到 https://studio.langchain.com 下载 Windows/macOS 安装包，启动后填 Server URL http://127.0.0.1:2024 即可连上。

三、Studio 界面功能介绍

┌──────────────────────────────────────────────┐
│ [图选择 react_demo ▼]   [新建线程] [运行]    │
├────────┬─────────────────────────────────────┤
│        │   左：图可视化(可拖拽、可缩放)      │
│ 流程图  │   ┌─────┐    ┌────────┐    ┌─────┐ │
│ 区域    │   │START│───▶│chatbot │───▶│tools│ │
│        │   └─────┘    └────────┘    └─────┘ │
├────────┼─────────────────────────────────────┤
│ 右：   │  Messages（每条消息一张卡）         │
│ State  │  ┌────────────────────────────┐    │
│ 快照   │  │ Human: 3 的平方是多少      │    │
│ 列表   │  │ AI: 调用 square(3)         │    │
│        │  │ Tool: 9                   │    │
│        │  │ AI: 3 的平方是 9          │    │
│        │  └────────────────────────────┘    │
└────────┴─────────────────────────────────────┘

核心交互：

1. 图可视化：点击节点可看它在当前 state 里的输入输出
2. 断点：节点上右键 → Toggle Breakpoint，运行到此处会暂停
3. 手动改 state：暂停时在右侧 JSON 编辑器里改值，点 Resume 继续
4. 时间旅行：左下时间轴点任意一步，再点 Fork 可在该点另起一条线程
5. 消息流：消息类智能体自动渲染对话气泡

四、导出与分享

Studio 右上角有 Share / Export：

• 分享线程：生成一个链接，别人打开就能看到这条线程的完整运行记录（只读）
• 导出 state：把当前线程 state dump 成 JSON，方便 bug 复现

五、与 LangSmith 的关系

很多人会把 Studio 和 LangSmith 搞混，区分如下：

维度	LangGraph Studio	LangSmith
定位	开发期可视化调试	全生命周期可观测平台
时机	开发、本地调试	开发 + 测试 + 生产监控
数据	单条线程交互	海量 trace 聚合分析
关系	Studio 调试的每一步可上报到 LangSmith	LangSmith 是数据后端

简单说：Studio 是放大镜，LangSmith 是望远镜。配置好 LANGSMITH_API_KEY 后，Studio 里的每次运行会自动生成 trace，详见 监控日志与可观测。

六、完整示例：把 ReAct 跑起来

把上面 my_graph.py 和 langgraph.json 存好后，启动 dev，在 Studio 里：

1. 新建 Thread
2. 输入「3 的平方再加 5」
3. 观察图：START → chatbot → tools(square) → chatbot → END，tools 节点输出 9，chatbot 最终答 14
4. 在 chatbot 节点加断点，重跑，在第二跳前手动把 messages 里工具结果改成 100，看最终答案如何变化

这个「手动改 state」就是 HITL（Human-in-the-Loop）调试，详见人机交互与中断。

七、常见踩坑

1. langgraph.json 格式错 报错 Failed to parse langgraph.json：必须是标准 JSON（双引号、无注释、无尾逗号）。Windows 下用记事本另存为 UTF-8 无 BOM。

2. 端口被占Port 2024 is already in use：加 --port 2025 指定其他端口，Studio 连接时改对应 URL。

3. 图无法序列化 Studio 通过网络传 state，state 必须可 JSON 序列化。报 Object of type XXX is not JSON serializable：把不可序列化对象（如数据库连接、文件句柄）从 state 挪出来，放到节点闭包或模块级全局。

4. 找不到图变量KeyError: 'graph'：langgraph.json 里 ./my_graph.py:graph 的 graph 必须是该模块的模块级变量名，不能是函数内局部变量。

5. 国内 npx 拉不下来 用 npmmirror：npx --registry=https://registry.npmmirror.com @langchain/langgraph-cli@latest dev。

八、小结

• LangGraph Platform 提供「同一套 API、三种部署形态」，开发用 langgraph dev，生产可上 Cloud 或 Self-hosted
• Studio 是开发期可视化调试利器：图可视化、状态快照、断点干预、时间旅行
• 入口靠 langgraph.json 把「图变量名」暴露给 Server
• Studio 是放大镜（单线程调试），LangSmith 是望远镜（全量监控），二者协同

下一篇我们看怎么不用官方 Server，自己用 FastAPI 把图包成 HTTP 服务，适合对部署栈有完全掌控的团队。