构建你的第一个 LangGraph 程序
配套阅读:《LangGraph文档汇总.md》。本文带你从零写一个手写的 StateGraph 程序——不是调
create_agent的黑盒,而是亲手搭一个带条件路由、会话记忆、人工审批、流式输出的图,跑通 LangGraph 的全部核心概念。全程约 40 分钟,需要 Python 3.10+ 和一个大模型 API Key(OpenAI / Anthropic / 任意兼容模型均可)。
基于 LangGraph v1(本文在 1.2.x 实测)编写。
1. 我们要做什么
做一个名叫 first-graph 的程序,一个”带审批的智能助手”:
| 能力 | 用到的概念 | 对应步骤 |
|---|---|---|
| 状态在节点间流动、自动累积消息 | State + reducer | 第 1 步 |
| 按输入内容走不同分支 | 条件边 / Command(goto=...) |
第 2 步 |
| 模型自主决定调不调工具 | bind_tools + 工具循环 |
第 3 步 |
| 多轮对话记得上文 | Checkpointer + thread_id | 第 4 步 |
| 发邮件前先问你 | interrupt() / Command(resume=...) |
第 5 步 |
| 实时看到每个节点在干嘛 | stream / draw_mermaid() |
第 6 步 |
做完后你会拥有:一个 100 来行代码、涵盖 LangGraph 五大核心机制的完整程序——以后看任何 LangGraph 代码都只是在”认节点”。
2. 准备工作
2.1 环境要求
- **Python 3.10+**(
python --version确认) - 一个模型 API Key:
OPENAI_API_KEY或ANTHROPIC_API_KEY(本地模型可用 Ollama,见第 5 步注)
2.2 安装
# venv 隔离(推荐)
py -m venv .venv
.venv\Scripts\activate # Windows cmd
# source .venv/bin/activate # macOS / Linux
pip install -U langgraph langchain langchain-openai # 或 langchain-anthropic
说明:
langgraph会自动带上langgraph-checkpoint、langgraph-prebuilt等依赖;langchain提供init_chat_model和消息类型;模型 SDK 按需选装(openai / anthropic / google-genai);- 需要 SQLite 持久化时再装:
pip install langgraph-checkpoint-sqlite(本文先用内存版)。
2.3 配置 Key
# Windows cmd
set OPENAI_API_KEY=sk-...
# macOS / Linux
export OPENAI_API_KEY=sk-...
Key 永远走环境变量,不要写死在代码里(与《MCP动手制作第一个MCP.md》第 5.2 节的纪律一致)。
3. 第 1 步:最小的图——状态 + 节点 + 边
新建 first_graph.py,先跑通骨架:
"""
first-graph:我的第一个 LangGraph 程序
目标:一个带记忆和审批的智能助手,本文件逐步进化
"""
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
# ---------- 1. 状态:整张图的数据总线 ----------
class State(TypedDict):
# add_messages 是 reducer:节点返回消息时"追加"而非"覆盖"
messages: Annotated[list, add_messages]
# 无 reducer 的字段:谁最后写谁生效
need_reply: bool
# ---------- 2. 节点:读状态、返回增量更新 ----------
def chatbot(state: State) -> dict:
"""最笨的节点:复读用户的话。第 5 步会换成真模型。"""
user_text = state["messages"][-1].content
return {"messages": [{"role": "assistant", "content": f"你说的是:{user_text}"}]}
# ---------- 3. 组装:节点 + 边 + 编译 ----------
builder = StateGraph(State)
builder.add_node("chatbot", chatbot)
builder.add_edge(START, "chatbot") # 入口
builder.add_edge("chatbot", END) # 出口
graph = builder.compile() # 编译成 Runnable;之后图不可再改
# ---------- 4. 运行 ----------
if __name__ == "__main__":
result = graph.invoke({"messages": [{"role": "user", "content": "你好,LangGraph!"}]})
print(result["messages"][-1].content)
python first_graph.py
# 输出:你说的是:你好,LangGraph!
关于这份代码的几个关键点:
- **状态就是 TypedDict,节点返回”增量”**:
chatbot只返回{"messages": [...]},没写need_reply,那个字段就保持原样; add_messages是你最常用的 reducer:它把新消息追加进列表(同 id 消息则替换),这是”对话历史自动累积”的全部秘密;builder.compile()之后图就冻结了:要改图只能回到 builder 重新编译;- 编译产物是标准 Runnable:
invoke/stream/ainvoke全部可用,可以像普通函数一样被别的程序调用。
理解执行模型(30 秒版)
LangGraph 按 Pregel 超步执行:每一轮,所有”当前应该跑的节点”并行执行 → 各自返回增量 → reducer 合并进状态 → 存档 → 按边决定下一轮跑谁。单节点图就是一个超步接一个超步,直到没有出边。
4. 第 2 步:条件边——让图学会分叉
加一个路由节点:以 / 开头的输入走”命令”分支,否则走”聊天”分支。把 if __name__ 之前的组装部分改成:
from langgraph.types import Command
def route(state: State) -> Command:
"""节点内直接决定去哪 + 顺手改状态,比条件边更内聚"""
text = state["messages"][-1].content
if text.startswith("/clear"):
# Command 一步完成:清空历史 + 跳转
return Command(update={"messages": []}, goto="chatbot")
return Command(goto="chatbot")
def echo_node(state: State) -> dict:
user_text = state["messages"][-1].content
return {"messages": [{"role": "assistant", "content": f"你说的是:{user_text}"}]}
builder = StateGraph(State)
builder.add_node("route", route)
builder.add_node("chatbot", echo_node)
builder.add_edge(START, "route")
builder.add_edge("chatbot", END)
graph = builder.compile()
另一种等价写法——经典条件边(把”路由”做成独立函数,用 add_conditional_edges 挂在节点出边上):
def pick_next(state: State) -> str:
if state["messages"][-1].content.startswith("/clear"):
return "chatbot"
return "chatbot"
builder.add_conditional_edges("route", pick_next, {"chatbot": "chatbot"})
两种写法怎么选:
Command(goto=...):路由逻辑和状态更新在一起,还能顺便改状态——v1 推荐优先用这个;- **
add_conditional_edges**:路由是纯函数、可复用、不碰状态——适合路由规则独立演化的场景。
铁律:同一个节点的出边只用一种机制,两种混着写是路由 bug 的头号来源。
5. 第 3 步:接上 LLM——带工具的助手
现在把复读机换成真模型,并给它一个工具。替换 echo_node:
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
# ---------- 工具:普通函数 + @tool 装饰器 ----------
@tool
def get_now() -> str:
"""获取当前日期时间。当用户问'现在几点'之类的问题时调用。"""
from datetime import datetime
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
# ---------- 模型:绑定工具 ----------
llm = init_chat_model("openai:gpt-4o-mini") # 换 anthropic:claude-sonnet-4-5 亦可
llm_with_tools = llm.bind_tools([get_now])
import json
def chatbot(state: State) -> dict:
"""模型节点:调一次 LLM,把回复(可能含工具调用)追加进状态"""
reply = llm_with_tools.invoke(state["messages"])
return {"messages": [reply]}
from langgraph.prebuilt import ToolNode, tools_condition
builder = StateGraph(State)
builder.add_node("route", route)
builder.add_node("chatbot", chatbot)
builder.add_node("tools", ToolNode([get_now])) # 官方预构建的工具执行节点
builder.add_edge(START, "route")
builder.add_conditional_edges("chatbot", tools_condition) # 模型要调工具→tools;否则→END
builder.add_edge("tools", "chatbot") # 工具结果喂回模型,继续下一轮
builder.add_edge("chatbot", END)
graph = builder.compile()
这就是完整的 ReAct 循环,逐行读一遍你会发现问题全在”边”上:
START → route → chatbot ⇄ tools
↓(模型不再要求调工具时)
END
关键点:
tools_condition是官方预构建的路由函数:看最后一条 AI 消息有没有tool_calls,有就返回"tools",没有返回END。自己写也就五行,但没必要;- **
ToolNode负责”执行工具并把结果包成 ToolMessage 追加进状态”**,省掉所有消息格式手活; tools → chatbot的回边就是循环本体:工具结果回到模型,模型决定继续调工具还是给最终答案——Agent 的”自主性”完全来自这条边;- docstring 就是给模型看的工具说明书(与 MCP 的 Tool description 同理),写清楚”何时调用”能显著提升准确率。
本地模型:装好 Ollama 并
ollama pull qwen3后,init_chat_model("ollama:qwen3")即可,图代码一行不改。
6. 第 4 步:加记忆——checkpointer 与 thread_id
现在每句”你好”都是新会话。加两行,它就有记忆了:
from langgraph.checkpoint.memory import MemorySaver
checkpointer = MemorySaver() # ⚠️ 仅开发用,重启即丢
graph = builder.compile(checkpointer=checkpointer)
# 运行时指定线程,同一 thread_id 共享状态历史
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [{"role": "user", "content": "我叫小明"}]}, config)
graph.invoke({"messages": [{"role": "user", "content": "我叫什么?"}]}, config)
# → 模型能答出"小明":第二次 invoke 时状态里已有全部历史消息
关键点:
记忆不在模型里,在状态里:checkpointer 把每个超步后的完整状态存档,下次同 thread_id 的调用从存档恢复,消息列表(靠
add_messagesreducer)自动带着全部历史;同一个图,不同 thread_id = 不同会话,彼此完全隔离;
读/改历史状态:
graph.get_state(config)(含next、tasks)、graph.update_state(config, {...});生产环境换 checkpointer 只改一行:
from langgraph.checkpoint.sqlite import SqliteSaver # pip install langgraph-checkpoint-sqlite checkpointer = SqliteSaver.from_conn_string("checkpoints.db") # 云上生产: # from langgraph.checkpoint.postgres import PostgresSaverMemorySaver 永远别上生产——进程一重启全部会话蒸发,这是 LangGraph 文档反复强调的头号坑。
7. 第 5 步:人工审批——interrupt 与 Command(resume)
给助手加一个”危险操作”工具:发邮件前必须经过人工批准。加工具和审批节点:
from langgraph.types import interrupt, Command
@tool
def send_email(to: str, body: str) -> str:
"""发送邮件给指定收件人。这是高风险操作。"""
return f"已发送邮件给 {to}" # 演示用假实现
# ---------- 审批节点:图在这里暂停,等人 ----------
def human_approve(state: State) -> dict:
last = state["messages"][-1] # 最后一条是 ToolMessage?
# 更严谨的做法是检查最后的 AI 消息里的 tool_calls
decision = interrupt({ # ← 图在此暂停并持久化
"question": "即将发送邮件,是否批准?",
"tool_call": last.additional_kwargs.get("tool_calls"),
})
if decision.get("approved") is not True:
# 拒绝:写一条拒绝消息,跳过真正的发送
return {"messages": [{"role": "user",
"content": "(用户拒绝了本次邮件发送)"}], "need_reply": True}
return {}
把 tools 节点换掉、插入审批环节后重新编译,运行侧这样配合:
# 第一次 invoke:跑到 interrupt 处暂停,invoke 返回时结果里有 __interrupt__
result = graph.invoke(
{"messages": [{"role": "user", "content": "给 boss@corp.com 发封周报"}]},
config,
)
print(result["__interrupt__"]) # 看到 question / tool_call
# ……人看完后,随时恢复(进程重启了也行,状态在 checkpointer 里)
result = graph.invoke(Command(resume={"approved": True}), config)
print(result["messages"][-1].content)
关键点:
interrupt()是普通函数调用,暂停状态却持久化在 checkpoint 里——审批可以是 1 分钟后,也可以是第二天、甚至换个进程;这是 LangGraph 区别于手搓 Agent 最实用的能力;- **恢复时用
Command(resume=...)**:resume 的值就是interrupt()的返回值,审批结论由你来定义(布尔、结构体都行); - 拒绝路径用
Command(goto=...)或状态标记处理,别抛异常打断整张图——把”人说不”当成一条正常的图路径,而不是错误; - 1.2.20 起支持可选的严格恢复模式(
__pregel_strict_resume):resume 指向一个已不存在的 interrupt 时会显式报错而不是静默重跑,多 interrupt 场景建议开启。
8. 第 6 步:流式输出与图可视化
8.1 流式:先 stream 再 invoke
调试 Agent 行为的第一习惯——把 invoke 换成 stream:
for update in graph.stream(
{"messages": [{"role": "user", "content": "现在几点了?"}]},
config,
stream_mode="updates", # 每个节点结束时推一次增量
):
for node, patch in update.items():
print(f"[{node}] {patch}")
常用 stream_mode 一览:
| 模式 | 推送内容 | 典型用途 |
|---|---|---|
updates |
每节点的状态增量 | 调试:看每步干了什么 |
values |
每步后的全量状态 | 检查累积效果 |
messages |
LLM 的 token 级流式 | 前端打字机效果 |
custom |
节点内 get_stream_writer() 发的自定义进度 |
长任务进度条 |
多模式可叠加:stream_mode=["updates", "messages"]。
8.2 画图:一眼确认结构
print(graph.get_graph().draw_mermaid())
把输出贴进任何 Mermaid 渲染器(Typora、VS Code 插件、mermaid.live),就能看到整张图。改图之后先画一遍,确认拓扑和你想的一致,再谈行为。
9. 进阶方向
按实用性排序:
- 子图与多智能体:把本文的图当节点嵌进父图,supervisor 节点负责路由——多智能体系统的标准形态;
- 长期记忆(Store):checkpointer 管会话内,跨会话的用户档案/偏好用
InMemoryStore/ Postgres Store,按 namespace 存取; - 结构化输出:
response_format/ Pydantic schema,让最终回答是可解析的 JSON; - 并发控制:
builder.add_node时传retry=RetryPolicy(...);并行分支用Annotated[list, operator.add]这类 reducer 合并; - 部署:用 LangGraph Server/Platform 把图变成 REST 服务(自带持久化、cron、双写);或自己 FastAPI 包一层
ainvoke; - 高层 API 路线:标准工具循环不必手写,
langchain.agents.create_agent+ Middleware 五行起步,遇到特殊编排再降级到本文的StateGraph; - LangSmith:
LANGSMITH_TRACING=true一个环境变量,全部节点/工具调用上链路追踪。
10. 排障清单
| 症状 | 最可能原因 | 解法 |
|---|---|---|
ModuleNotFoundError: langgraph.checkpoint.sqlite |
sqlite 扩展是独立包 | pip install langgraph-checkpoint-sqlite |
| 多轮对话模型”失忆” | 没传 thread_id,或没配 checkpointer | 每次 invoke 带同一 config;编译时传 checkpointer |
| 重启后所有会话消失 | 用了 MemorySaver | 换 SqliteSaver / PostgresSaver |
| 节点里状态字段”莫名被清空” | 返回了全量而期望增量(无 reducer 字段被覆盖) | 节点只返回改动字段;需要累积的字段加 reducer |
| 消息没累积、每轮只剩一条 | messages 字段没挂 add_messages reducer |
按第 1 步的写法加 Annotated[list, add_messages] |
| 工具死循环调个不停 | 模型持续要求调用同一工具(常见于 docstring 模糊) | 写清”何时调用”;检查 tools→chatbot 回边与终止条件 |
GraphRecursionError |
循环超过默认步数上限(25) | config={"recursion_limit": 50};或修路由逻辑 |
interrupt 后 resume 无效、任务重跑 |
resume 指向了不存在的 interrupt / config 里 thread_id 变了 | 保持同一 config;需要严格校验时开 __pregel_strict_resume |
| 搜到的教程代码 import 报错 | v0.x 老 API(Graph、AgentState 旧写法) |
认准 from langgraph.graph import StateGraph, START, END |
| 条件边报”unknown node” | 映射表 key 与节点名不一致 / Command goto 拼错 | 先 draw_mermaid() 核对拓扑 |
| 想改图但报图已冻结 | 在 compile() 产物上 add_node |
回到 builder 重新编译 |
收尾检查清单
-
python first_graph.py最小图跑通,理解”节点返回增量 + reducer 合并” - 路由节点能按输入分叉(Command 和条件边两种写法都写过一遍)
- 问”现在几点”模型会自动调
get_now,且 docstring 决定了它何时调用 - 同一 thread_id 下模型记得你说过的话,换 thread_id 就失忆
- 发邮件流程会暂停在
interrupt(),Command(resume=...)能批准也能拒绝 -
stream_mode="updates"能看到每个节点的增量输出 -
draw_mermaid()画出的图和你脑子里的拓扑一致 - 代码里没有任何硬编码 API Key(走环境变量)
完成以上全部,你已经把 LangGraph 的状态、节点、边、条件路由、工具循环、记忆、人工审批、流式、可视化全部亲手跑过一遍。下一步建议:把本文的图当子图嵌进一个父图(加一个 supervisor 节点路由”闲聊/查天气/发邮件”),体会多智能体架构——那是 LangGraph 真正的威力所在。