构建你的第一个 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!

关于这份代码的几个关键点:

  1. **状态就是 TypedDict,节点返回”增量”**:chatbot 只返回 {"messages": [...]},没写 need_reply,那个字段就保持原样;
  2. add_messages 是你最常用的 reducer:它把新消息追加进列表(同 id 消息则替换),这是”对话历史自动累积”的全部秘密;
  3. builder.compile() 之后图就冻结了:要改图只能回到 builder 重新编译;
  4. 编译产物是标准 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

关键点:

  1. tools_condition 是官方预构建的路由函数:看最后一条 AI 消息有没有 tool_calls,有就返回 "tools",没有返回 END。自己写也就五行,但没必要;
  2. **ToolNode 负责”执行工具并把结果包成 ToolMessage 追加进状态”**,省掉所有消息格式手活;
  3. tools → chatbot 的回边就是循环本体:工具结果回到模型,模型决定继续调工具还是给最终答案——Agent 的”自主性”完全来自这条边;
  4. 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 时状态里已有全部历史消息

关键点:

  1. 记忆不在模型里,在状态里:checkpointer 把每个超步后的完整状态存档,下次同 thread_id 的调用从存档恢复,消息列表(靠 add_messages reducer)自动带着全部历史;

  2. 同一个图,不同 thread_id = 不同会话,彼此完全隔离;

  3. 读/改历史状态:graph.get_state(config)(含 next、tasks)、graph.update_state(config, {...});

  4. 生产环境换 checkpointer 只改一行:

    from langgraph.checkpoint.sqlite import SqliteSaver      # pip install langgraph-checkpoint-sqlite
    checkpointer = SqliteSaver.from_conn_string("checkpoints.db")
    
    # 云上生产:
    # from langgraph.checkpoint.postgres import PostgresSaver

    MemorySaver 永远别上生产——进程一重启全部会话蒸发,这是 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)

关键点:

  1. interrupt() 是普通函数调用,暂停状态却持久化在 checkpoint 里——审批可以是 1 分钟后,也可以是第二天、甚至换个进程;这是 LangGraph 区别于手搓 Agent 最实用的能力;
  2. **恢复时用 Command(resume=...)**:resume 的值就是 interrupt() 的返回值,审批结论由你来定义(布尔、结构体都行);
  3. 拒绝路径用 Command(goto=...) 或状态标记处理,别抛异常打断整张图——把”人说不”当成一条正常的图路径,而不是错误;
  4. 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. 进阶方向

按实用性排序:

  1. 子图与多智能体:把本文的图当节点嵌进父图,supervisor 节点负责路由——多智能体系统的标准形态;
  2. 长期记忆(Store):checkpointer 管会话内,跨会话的用户档案/偏好用 InMemoryStore / Postgres Store,按 namespace 存取;
  3. 结构化输出:response_format / Pydantic schema,让最终回答是可解析的 JSON;
  4. 并发控制:builder.add_node 时传 retry=RetryPolicy(...);并行分支用 Annotated[list, operator.add] 这类 reducer 合并;
  5. 部署:用 LangGraph Server/Platform 把图变成 REST 服务(自带持久化、cron、双写);或自己 FastAPI 包一层 ainvoke;
  6. 高层 API 路线:标准工具循环不必手写,langchain.agents.create_agent + Middleware 五行起步,遇到特殊编排再降级到本文的 StateGraph;
  7. 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 真正的威力所在。