LangGraph

LangGraph 是目前 Python 生态里事实标准的 Agent 编排框架。它不是"又一个 Agent 库"，而是一套把 Agent 执行建模为图状态机的运行时：你把流程拆成节点和边，状态在节点间流动，框架负责持久化、断点恢复、流式输出和人机协作这些"脏活"。

本页基于 2026 年 8 月的 LangGraph v1.x 官方文档撰写。2025 年 10 月 LangChain/LangGraph 双双发布 v1.0（官方发布说明），核心图 API 从此冻结稳定，网上大量 2024 年的教程里那些 AgentExecutor、create_react_agent 写法都已过时——看到请先警惕。

一、定位：LangChain 生态中的 Agent 编排层

先看版本时间线，理解它为什么长成今天这样：

时间	事件
2024-01	LangGraph 随 LangChain v0.1 公告首次亮相，定位"用 graph 构建 language agents"
2024-06	v0.1 发布，同时推出 LangGraph Cloud
2024-08	v0.2：独立出 checkpointer 库，强化 session memory、断点恢复、human-in-the-loop
2025-02	v0.3 系列：引入 Command、Send 等控制流原语
2025-05	LangGraph Platform GA（商业化部署产品）
2025-10	v1.0 GA；LangGraph Platform 更名为 LangSmith Deployment；LangChain v1 的 create_agent 改建于 LangGraph 之上
2026 年	v1.x 持续打磨稳定性与类型安全，核心 API 无破坏性变更

v1.0 之后，官方对三个产品的分工表述得非常清楚：

┌─────────────────────────────────────────────────────┐
│ LangChain  (v1)                                     │
│  = Agent API 层：create_agent + middleware          │
│  快速起手的标准 Agent 循环                           │
├─────────────────────────────────────────────────────┤
│ LangGraph                                           │
│  = Agent Runtime：StateGraph / Node / Edge          │
│  持久化、流式、人机协作、自定义编排                   │
├─────────────────────────────────────────────────────┤
│ LangSmith                                           │
│  = 工程平台：tracing / eval / LangSmith Deployment  │
└─────────────────────────────────────────────────────┘

一句话：LangChain 是集成与抽象层，LangGraph 是执行与编排层，LangSmith 是观测与部署层。create_agent 底层就跑在 LangGraph 运行时上——你先用 LangChain 快速搭起来，需要精细控制时再下沉到 LangGraph，两者不是竞争关系。关于这个分层如何对应 Agent 的通用解剖结构，可以对照全景解剖和 Agent Loop 两页。

二、核心概念

LangGraph 的全部 API 面积可以收敛到四个原语：State、Node、Edge，加上管理状态的 Checkpointer。

2.1 State 与 Reducer

State 是一个 TypedDict（或 Pydantic model、dataclass），代表图在任意时刻的完整快照。关键点在于 reducer：每个 state 字段可以声明一个合并函数，决定节点返回的部分更新如何写入全局状态。

from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import MessagesState          # 内置 messages 字段
from langgraph.graph.message import add_messages   # 按消息 ID 去重合并

class State(MessagesState):
    # messages: Annotated[list, add_messages] 已由 MessagesState 提供
    documents: list[str]          # 无 reducer → 默认整值覆盖
    retry_count: int

• 不声明 reducer，节点返回值直接覆盖该字段；
• add_messages 是消息字段的标准 reducer：新消息追加、同 ID 消息覆盖，还能自动把 dict 反序列化成 Message 对象；
• 图按 Pregel 风格的 super-step 执行：同一 super-step 内并行跑多个节点，全部结束后才进入下一步。

2.2 Node、Edge 与条件路由

Node 就是普通 Python 函数：接收 state，干活，返回部分更新。Edge 决定"下一步去哪"。路由有三种写法：

builder = StateGraph(State)
builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))   # prebuilt 工具执行节点

builder.add_edge(START, "agent")              # 固定入口
builder.add_conditional_edges("agent", route) # 动态路由
builder.add_edge("tools", "agent")            # 固定边

• add_conditional_edges("agent", route_fn)：route_fn 返回下一个节点名（或节点列表——返回多个则并行 fan-out）。
• Command：当节点想同时更新状态并决定去向时，直接 return Command(update={...}, goto="next_node")，不必拆成节点 + 路由函数两件套。注意要标注返回类型 Command[Literal["next_node"]]，否则图渲染不出来。
• Send：map-reduce 场景用，在路由函数里动态扇出任意数量的并行分支，每个分支携带各自的子状态。
• 子图：一个编译好的 graph 可以直接作为另一个图的节点，共享字段自动贯通；子图内可以用 Command(goto=..., graph=Command.PARENT) 跳回父图节点——这是实现 multi-agent handoff 的官方姿势。

2.3 Checkpointer 持久化

这是 LangGraph 区别于"裸写 while 循环"的核心价值之一。编译时挂一个 checkpointer，每个 super-step 结束都会自动落盘：

from langgraph.checkpoint.memory import InMemorySaver          # 开发用
# 生产用 langgraph-checkpoint-sqlite / langgraph-checkpoint-postgres
checkpointer = InMemorySaver()
graph = builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [("user", "你好")]}, config)

thread_id 就是你的持久化游标：同一个 ID 再次 invoke 会从上次 checkpoint 继续，进程崩了、机器重启了都能恢复。围绕它还衍生出 time travel（回到任意历史 checkpoint 分叉执行）和断点调试（interrupt_before / interrupt_after）。

2.4 interrupt：人机协作

interrupt() 是 v1 推荐的人机协作原语（旧的静态断点仍在，但动态 interrupt 灵活得多）：

from langgraph.types import interrupt, Command

def human_review(state: State):
    # 暂停图，把 payload 抛给调用方，直到有人 resume
    answer = interrupt({"question": "是否批准这笔转账？", "amount": state["amount"]})
    return {"approved": answer == "yes"}

# 第一次调用：返回 {"__interrupt__": [...]}，图挂起
result = graph.invoke(input, config)
# 人工决策后恢复：interrupt() 的返回值就是 "yes"
graph.invoke(Command(resume="yes"), config)

interrupt 的三个坑（官方"rules of interrupts"）

• 不要用 try/except 包住 interrupt：它靠抛特殊异常暂停，被你 catch 就静默失效。
• resume 时节点从头重跑：interrupt 之前的代码会再执行一遍，所以副作用（写库、调 API）要么幂等，要么放到 interrupt 之后或独立节点。
• 同一节点内多个 interrupt 的顺序必须确定：resume 值按索引匹配，条件性跳过某个 interrupt 会错位。

这套机制配合 checkpointer，让"审批流挂起三天后人工点确认"这种场景变成几行代码，详见人机协作页的模式总结。

三、一个完整的 v1 代码示例

下面是一个可运行的客服 Agent：工具调用 + 条件路由 + 持久化 + 大额退款人工审批。API 均按 2026-08 官方文档核实（langgraph v1.x / langchain v1.x）。

# pip install -U langgraph langchain langchain-anthropic
from typing import Annotated
from typing_extensions import TypedDict

from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import interrupt, Command

# ---------- 1. 工具 ----------
@tool
def query_order(order_id: str) -> str:
    """查询订单状态。"""
    return f"订单 {order_id}：已发货，预计明天送达"

@tool
def refund(order_id: str, amount: float) -> str:
    """发起退款。大额退款会先触发人工审批。"""
    if amount > 500:
        # 在工具内部 interrupt：审批逻辑跟着工具走，任何图复用都生效
        decision = interrupt({
            "action": "refund",
            "order_id": order_id,
            "amount": amount,
        })
        if decision != "approve":
            return f"退款被拒绝（人工审批结果：{decision}）"
    return f"已为订单 {order_id} 退款 {amount} 元"

tools = [query_order, refund]

# ---------- 2. 状态 ----------
class State(MessagesState):
    pass  # 本例只需内置的 messages 字段（add_messages reducer）

# ---------- 3. 节点 ----------
llm = init_chat_model("anthropic:claude-sonnet-4-6").bind_tools(tools)

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

def should_continue(state: State) -> str:
    """条件路由：模型还想调工具就去 tools，否则结束。"""
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

# ---------- 4. 构图 ----------
builder = StateGraph(State)
builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", should_continue)
builder.add_edge("tools", "agent")          # 工具结果回到模型，形成 Agent Loop

graph = builder.compile(checkpointer=InMemorySaver())

# ---------- 5. 运行（含人工审批恢复） ----------
config = {"configurable": {"thread_id": "thread-001"}}

result = graph.invoke(
    {"messages": [("user", "帮我退掉订单 A123，金额 800 元")]},
    config,
)

# 触发大额退款 interrupt：result 里带 __interrupt__ 键
if "__interrupt__" in result:
    print("等待审批:", result["__interrupt__"][0].value)
    # 模拟审批人点击"批准"后恢复执行
    final = graph.invoke(Command(resume="approve"), config)
    print(final["messages"][-1].content)

什么时候不需要自己构图

如果只是"模型 + 工具 + 循环"的标准 ReAct Agent，v1 之后直接用 LangChain 的 create_agent，底层就是 LangGraph，但一行图代码都不用写：

from langchain.agents import create_agent
agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[query_order, refund],
    system_prompt="你是客服助手，大额退款需要谨慎。",
)
agent.invoke({"messages": [{"role": "user", "content": "查询订单 A123"}]})

它还带 middleware 体系（PII 脱敏、对话压缩、HumanInTheLoopMiddleware 等），能覆盖大部分"标准 Agent + 少量定制"的需求。只有当路由逻辑、状态结构、多 Agent 协作超出模板能力时，才值得下沉手写 StateGraph。注意 langgraph.prebuilt.create_react_agent 已废弃，别再抄旧教程。

这个手写图的版本，本质上就是把 Agent Loop 显式化了：每一步的输入输出、状态流转、中断点全部可见可持久化——这正是你放弃黑盒、选择 LangGraph 换来的东西。

四、LangSmith Deployment（原 LangGraph Platform）与 Studio

本地跑通图只是第一步，把长时运行、有状态的 Agent 部署成服务才是真正的工程量所在。LangChain 官方的商业化部署产品经历了 LangGraph Cloud → LangGraph Platform → LangSmith Deployment（2025 年 10 月更名）的演进，核心组件没变：

• LangGraph Server：为 Agent 定制的服务运行时——水平扩展的任务队列、长时运行支持（不是为秒级 HTTP 请求设计的普通 Web 框架）、跨会话持久化、流式/后台运行、并发控制（用户连发多条消息的处理策略）、cron 与 webhook。
• Studio：可视化调试器，能看图结构、逐步执行、在中间状态上人工修改后继续跑，开发期价值极高。
• CLI + Python/JS SDK：本地起服务和部署管理。

本地开发只需要一个 langgraph.json 声明依赖和图的入口：

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

然后 langgraph dev 一条命令起本地服务，自带 Studio 界面（通过 LangSmith 网页端连接本地端口），断点、状态检查、流式输出全都能玩。

部署有四档（官方公告）：

方案	说明	适用
Self-Hosted Lite	免费自托管，限 100 万节点执行量	小团队验证、内部工具
Cloud SaaS	全托管，随 LangSmith 套餐走	大多数团队
BYOC	部署在你的 VPC（目前仅 AWS），他们代管	数据合规要求
Self-Hosted Enterprise	完全自控基础设施	大企业

费用层面（2026 年年中数据）：LangSmith Developer 档免费（1 seat，每月 5k base traces），Plus 档 $39/seat/月（含 10k base traces，超出按 trace 计费，约 $2.5/千条）。Deployment 侧 2026 年初改为按运行次数计量（约 $0.005/run）。这些数字变动频繁，上线前以 langchain.com/pricing 为准。

不上平台也能部署

langgraph 库本身是 MIT 开源的，图编译后就是普通 Python 对象，包进 FastAPI 直接跑没有任何限制。LangSmith Deployment 卖的是"不用自己写任务队列、持久化层和运维脚手架"，不是运行许可。流量不大、无长时任务的话，自托管完全够用。

五、生态位：LangChain / LangGraph / LangSmith 的分工

用一张表把 v1 之后的分工钉死，别再混淆：

	角色	你什么时候碰它
LangChain v1	Agent API 层：create_agent、middleware、init_chat_model 统一模型接口、几百个三方集成	每个项目都会用——至少模型和工具的接入层
LangGraph	Agent 运行时：StateGraph 编排、checkpointer、interrupt、子图	标准 ReAct 模板不够用，需要自定义控制流时
LangSmith	观测与工程平台：tracing、eval、prompt 管理、Deployment	调试线上行为、做回归评估、部署托管（详见可观测性）

历史包袱提示：langchain 包在 v1 做了大瘦身，LLMChain、RetrievalQAChain、旧 retriever、hub 等全部移入 langchain-classic。维护旧代码时按迁移指南改 import 即可，新代码不要再用这些。

六、优缺点：诚实的评价

优势：

• 控制粒度无可替代。状态结构、路由逻辑、中断点全部显式声明，你能回答"Agent 此刻在第几步、状态是什么、为什么走这条边"——这是黑盒式 Agent SDK 给不了的。
• 持久化与容错是业界最成熟的一档。super-step 级 checkpoint、断点恢复、time travel、幂等语义，配上 Postgres checkpointer 就是一套 durable execution 引擎，同类框架里几乎没有对手。
• 生态惯性。模型/工具集成最全，招人最容易，Stack Overflow 和中文社区资料最多，LangSmith 的 tracing 体验目前是标杆。

劣势与社区真实批评：

• 学习曲线陡。State/reducer/super-step/Command/Send/interrupt 的概念密度不低，想写出正确的人机协作流，得先理解"resume 时节点从头重跑"这类反直觉语义。官方文档在 v0.x 时代变动频繁，网上教程新旧混杂是最大的入门噪音（v1 冻结后好转）。
• 简单场景是过度设计。Hacker News 上一直有高热度讨论（如 2025 年 3 月"We chose LangGraph to build our coding agent"一帖）呈现两派：一派认为图的抽象是有用的心智模型，另一派直言"大多数场景不需要任何框架，直接调模型 API 写循环更清楚"。这个批评对线性、无状态、无人工介入的流程完全成立。
• 抽象层的调试税。图行为由框架调度，出问题时要同时理解自己的代码和 LangGraph 的执行模型；langgraph-prebuilt 与 langgraph 核心包版本不匹配导致 import 报错这类问题在社区 issue 里并不少见（如 2026 年 4 月的 issue #7404）。好在有 LangSmith trace 兜底，纯靠 print 调试 LangGraph 是痛苦的。
• 商业绑定感。虽然库本身开源，但最佳体验路径（Studio、Deployment、trace）都导向 LangSmith 付费体系，介意的团队需要提前想清楚。

七、适用场景与替代方案

选 LangGraph 的信号：

1. 流程有分支、循环、并行扇出，不是一条直线；
2. 需要跨会话记忆、崩溃恢复、人工审批挂起——即"有状态 + 长时运行"；
3. 多 Agent 系统且要求 handoff 过程可控可观测；
4. 团队已在 Python/LangChain 生态内。

替代方案速查：

场景	更合适的选项
标准 ReAct Agent，不要编排细节	LangChain create_agent，或 OpenAI Agents SDK（更轻、OpenAI 生态）
写代码/终端类 Agent	Claude Agent SDK（Claude Code 同款 harness）
角色扮演式多 Agent 协作，要低代码表达	CrewAI
研究/对话式多 Agent	AutoGen（AG2 / 已并入 Microsoft Agent Framework 生态）
流程简单、状态自管理	裸写 Agent Loop，一个 while 循环 + SQLite，往往 200 行搞定

一句话结论：LangGraph 的价值与流程复杂度正相关。线性任务用它纯属给自己加税；但只要业务里出现"审批挂起三天后恢复""崩了从断点续跑""五个 Agent 按状态机协作"这类需求，它是目前省工程量最多的选择。动手路线建议：先用 create_agent 起原型（参考从零构建 Agent），撞到编排天花板再下沉 StateGraph，同时把常见陷阱过一遍。

参考资料

• What's new in LangGraph v1（官方发布说明） —— v1 定位、API 冻结承诺与 create_react_agent 废弃说明。
• What's new in LangChain v1 —— create_agent、middleware 体系与 langchain-classic 迁移。
• LangGraph Graph API 概念文档 —— State/Node/Edge/reducer/Command/Send 的权威定义，本文代码语法的核对来源。
• LangGraph Interrupts 文档 —— interrupt()/Command(resume=...) 用法与三大反直觉规则。
• LangGraph Platform 公告（含更名说明） —— 四档部署方案与"2025 年 10 月更名 LangSmith Deployment"的官方表述。
• LangSmith Plans and Pricing —— Developer/Plus/Enterprise 定价的实时官方页面。
• ToolNode API Reference —— 确认 v1.1.0 中 ToolNode/tools_condition 仍为官方 prebuilt 组件。
• Hacker News: We chose LangGraph to build our coding agent（讨论存档） —— 社区对图抽象价值与"不需要框架"之争的真实讨论样本。