LangGraph 完全指南 2026：构建有状态的 AI 智能体

LangGraph 将智能体建模为状态机：节点是函数（LLM 调用、工具、纯代码），边决定下一步运行什么，类型化的状态对象在图中流动。这种显式性正是其核心卖点——循环、分支、重试和人工审批都成为可见的图结构，而不是隐藏在提示词中的期望。它是 LangChain 生态系统中面向生产的智能体层，即使你跳过其余部分，也最值得学习。

安装

bash
pip install langgraph langchain-openai

30 秒速览：预构建的 ReAct 智能体

python
from langgraph.prebuilt import create_react_agent
from langchain_core.tools import tool
@tool
def get_weather(city: str) -> str:
    '获取某个城市的当前天气。'
    return f'{city} 华氏 72°F，晴朗'
agent = create_react_agent('openai:gpt-4o-mini', tools=[get_weather])
result = agent.invoke({'messages': [{'role': 'user', 'content': '巴黎的天气？'}]})
print(result['messages'][-1].content)

create_react_agent 用三行代码提供了标准的工具调用循环。在需要自定义控制流之前使用它——然后自己构建图：

真正的核心：显式图

python
from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, START, END, add_messages
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
class State(TypedDict):
    messages: Annotated[list, add_messages]   # reducer：追加而非覆盖
llm = ChatOpenAI(model='gpt-4o-mini').bind_tools([get_weather])
def agent_node(state: State):
    return {'messages': [llm.invoke(state['messages'])]}
def route(state: State):
    last = state['messages'][-1]
    return 'tools' if last.tool_calls else END
builder = StateGraph(State)
builder.add_node('agent', agent_node)
builder.add_node('tools', ToolNode([get_weather]))
builder.add_edge(START, 'agent')
builder.add_conditional_edges('agent', route)   # agent → tools，或结束
builder.add_edge('tools', 'agent')              # 工具结果循环回 agent
graph = builder.compile()

三个概念支撑了整个框架：

State + reducers —— Annotated[list, add_messages] 模式声明了更新如何合并（追加 vs 覆盖）。自定义状态字段（计划、重试次数、检索到的文档）与消息共存。

条件边 —— 路由函数返回下一个节点的名称。所有控制流（质量门控、失败重试、计划与执行分支）都位于此处，以可检查的 Python 代码形式存在。

编译后的图是可运行的 —— .invoke()、.stream()、异步变体，均为标准接口。

生产级的关键：持久化

这是 LangGraph 真正的差异化优势。传入检查点后，每一步的状态都会在线程 ID 下保存：

python
from langgraph.checkpoint.memory import MemorySaver   # 生产环境使用 Postgres/SQLite 保存器
graph = builder.compile(checkpointer=MemorySaver())
cfg = {'configurable': {'thread_id': 'user-42'}}
graph.invoke({'messages': [('user', '我叫 Alice')]}, cfg)
graph.invoke({'messages': [('user', '我叫什么名字？')]}, cfg)   # 记住——同一线程

持久化无需额外代码即可带来：多轮记忆（状态在调用之间保持）、崩溃恢复（从运行中途的最后一个检查点恢复）、以及时间旅行（检查或分叉任何历史状态以进行调试）。

人机协作：中断

在关键操作处暂停图，等待审批，然后恢复：

python
from langgraph.types import interrupt, Command
def execute_trade(state: State):
    decision = interrupt({'proposed': state['trade']})   # 图在此处暂停
    if decision == 'approve':
        return {'result': do_trade(state['trade'])}
    return {'result': '被人类拒绝'}
稍后，在人类审核后：
graph.invoke(Command(resume='approve'), cfg)             # 在节点中间恢复

由于状态已被检查点保存，暂停可以持续几秒或几天——恢复请求甚至可以来自不同的进程。这就是人机协作模式中的审批门控模式，在框架层面实现。

多智能体形态

监督者模式只是一个图：路由节点选择哪个专业子图处理下一步；专家返回给监督者；监督者决定完成还是继续。每个专家本身可以是一个编译后的图（子图可组合）。在评估 LangGraph 与 crew 风格框架时——参见 CrewAI vs AutoGen——权衡在于显式控制（LangGraph）与快速搭建（CrewAI）。

可观测性与服务化

追踪：设置两个 LangSmith 环境变量后，每个节点/边/LLM 调用都会被追踪——这是生态系统中最佳的调试体验（LangSmith vs Helicone vs Langfuse）。

服务化：将 graph.astream() 封装在 FastAPI SSE 端点中（配方）用于无状态部署；对于托管持久化/队列/定时任务，有 LangGraph Platform——构建 vs 购买的分析见 FastAPI vs LangServe。

流式模式：graph.stream(..., stream_mode='updates') 产生每个节点的状态增量——以类型化事件而非仅令牌的形式流式输出“搜索中…”、“找到 12 个结果”。

何时使用 LangGraph 与更简单的工具

需求工具

单次 LLM 调用，可能带工具直接使用提供商 SDK 线性流水线（提取 → 转换 → 写入）纯函数——无需框架 循环/分支/重试 + 持久化 + 人机协作LangGraph 重度 RAG，轻量编排LlamaIndex（对比）

诚实的代价：状态类型、reducer 和边函数是需要学习的真实概念，简单流程用图实现会显得过度工程化。但回报恰好出现在你的智能体需要经受重启、为人类暂停或通过追踪进行调试时。

FAQ

LangGraph vs LangChain agents？ LangGraph *就是*后继者——经典的 LangChain AgentExecutor 已过时；生态系统中新的智能体工作都在图上进行（LangChain vs LangGraph）。

TypeScript？ LangGraph.js 与 Python API 高度相似；对于 Next.js 原生替代方案，参见 Vercel AI SDK vs LangChain.js。

哪个模型？ 工具调用质量主导智能体可靠性——前沿模型在这方面明显更好；在模型库中比较。

---

*最后更新：2026 年 6 月。API 会变化——请对照 LangGraph 文档验证。*