跳转到主要内容

LangChain

16 · LangGraph 基础

StateGraph、节点、条件边、checkpointer——把 create_agent 拆开看

  • LangChain
  • Python

本节速览

这一节的每一块内容,分别是干什么的:

内容是干什么的
StateGraph把执行过程建模成状态图:节点改状态、边定顺序
MessagesState预置的消息列表状态,多轮对话的标准载体
条件边按状态动态决定下一步,循环的来源
手写 agent 循环用第 15 章的工具 + 本章的图,手搓一遍 create_agent 的内核
Checkpointer每步之后存档状态,thread_id 恢复——记忆的真身
interrupt人机协同:跑到一半停下来等人批准再继续

上一章(Function Calling)讲清了模型怎么「要」工具:tool_calls 的往返协议。但你可能已经发现一个问题:那个流程要自己写循环——调模型、执行工具、回传、再调模型,直到 finish_reason != "tool_calls"。到底循环到第几轮,写代码时不知道,只有模型运行时才知道。

链(LCEL)解决不了这个问题:RunnableSequence 是单向流水线,数据从上往下流一遍就结束,没有「回到上一步」的能力。这一章讲 LangGraph——1.x 中 agent、记忆、循环控制的底座,把 create_agent 拆开看它的发动机。

为什么需要图:链跑不了的循环

没有它会怎样——用 while 循环手写工具调用:轮数判断、消息拼装、异常处理、每轮打印调试,四十行样板代码;想在中间插一步「人工确认」,整个循环结构推翻重写。

有了它——节点是函数、边是流向、条件边是分支判断,循环和分支变成声名式的结构,框架负责调度,你只写每个节点「做什么」。

LangGraph 的核心是三个概念:

  • State(状态):一个所有节点共享的字典。最常用的是消息列表 messages——每个节点往里追加消息,下一个节点看到的就是完整的最新状态。
  • Node(节点):一个普通函数,收到 state,返回 state 的增量(只返回要更新的字段,框架负责合并)。
  • Edge(边):固定边写死「A 之后必然 B」;条件边是个函数,按当前 state 返回下一个节点的名字——循环就是「条件边指回之前的节点」实现的。

第一个图:Hello StateGraph

没有它会怎样——没有直观感受:节点返回的字典不是新的完整状态,而是「增量」,这个合并规则不看例子记不住。

有了它——跑一个两节点的小图,亲眼看 state 怎么被逐步改写。

from typing import Annotated, TypedDict   # 参数级注解、字典化状态类型

from langgraph.graph import START, StateGraph
import operator   # 合并函数


class State(TypedDict):
    messages: Annotated[list, operator.add]   # 追加合并:节点返回的列表拼到原列表后面


def greet(state: State):
    return {"messages": ["你好"]}   # 只返回增量,不用带全量


def ask(state: State):
    return {"messages": ["有什么可以帮你?"]}


graph = StateGraph(State)
graph.add_node("greet", greet)
graph.add_node("ask", ask)
graph.add_edge(START, "greet")   # 入口
graph.add_edge("greet", "ask")   # 固定边:greet 之后必然 ask

app = graph.compile()
print(app.invoke({"messages": []})["messages"])
# ['你好', '有什么可以帮你?']

要点:

  • Annotated[list, operator.add] 声明合并策略:节点返回的列表追加到原列表,而不是覆盖。这是消息累积的关键——没有它,后一个节点会覆盖前一个节点的消息。
  • 节点函数只返回增量,框架合并进状态。
  • START 是虚拟入口节点;不连 END 时,没有出边的节点就是终点。

MessagesState:预置的消息状态

没有它会怎样——每个图都自己写 class State(TypedDict): messages: Annotated[list, operator.add],所有项目重复这一行。

有了它——LangGraph 预置了 MessagesState,开箱即用,还支持 add_messages 语义(同 id 的消息更新、不同 id 的追加)。

from langgraph.graph import MessagesState, START, StateGraph


def call_model(state: MessagesState):
    return {"messages": [("human", "再重复一遍")]}   # 演示:直接追加一条


graph = StateGraph(MessagesState)
graph.add_node("call_model", call_model)
graph.add_edge(START, "call_model")

app = graph.compile()
result = app.invoke({"messages": [("human", "你好")]})
print(result["messages"])
# [HumanMessage(content='你好', ...), HumanMessage(content='再重复一遍', ...)]

MessagesState 等价于:

from typing import Annotated, TypedDict   # 参数级注解、字典化状态类型

from langgraph.graph.message import add_messages   # 消息合并策略


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

add_messages 比 operator.add 聪明:普通消息追加,同 id 的消息替换(编辑场景),RemoveMessage 按 id 删除。第 14 章记忆系统的消息裁剪,底层就是这套合并语义。

条件边:循环的关键

没有它会怎样——「模型还想调工具就继续,够了就停」这种运行时才能决定的流向,固定边表达不了;退回 while 循环手写,又回到四十行样板。

有了它——一个函数看状态、返回下一站名字,分支和循环一行声明。

上一章的工具调用流程,用条件边改写「调模型 → 有 tool_calls 就执行工具 → 回到调模型」的循环:

from langgraph.graph import END, MessagesState, START, StateGraph
from langgraph.prebuilt import ToolNode
import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain.tools import tool   # 工具定义装饰器
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)


@tool
def get_exchange_rate(from_currency: str, to_currency: str) -> str:
    """查询两种货币之间的汇率"""
    return "7.24"


model_with_tools = model.bind_tools([get_exchange_rate])


def call_model(state: MessagesState):
    return {"messages": [model_with_tools.invoke(state["messages"])]}


def should_continue(state: MessagesState):
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END   # 模型还要调工具就回工具节点,否则结束


graph = StateGraph(MessagesState)
graph.add_node("call_model", call_model)
graph.add_node("tools", ToolNode([get_exchange_rate]))   # 预置节点:执行 tool_calls 并回传结果
graph.add_edge(START, "call_model")
graph.add_conditional_edges("call_model", should_continue)   # 条件边:运行时决定去向
graph.add_edge("tools", "call_model")                        # 固定边:工具结果回模型 —— 循环成型

app = graph.compile()

result = app.invoke({"messages": [("human", "17 美元是多少人民币?请先查汇率再计算")]})
print(result["messages"][-1].content)

这三行就是循环的全部:

  1. add_conditional_edges("call_model", should_continue) —— 每次模型说完,运行时检查:有 tool_calls 去 tools,没有去 END;
  2. add_edge("tools", "call_model") —— 工具执行完回到模型,下一轮开始;
  3. 节点返回的消息增量自动累积在 state["messages"] —— 模型每轮都能看到完整历史。

对照第 15 章手写的 while 循环:轮数判断变成了条件边函数、消息拼装变成了状态合并、ToolNode 接住了工具执行。这段手写的图,就是 create_agent 的内核——下一章讲的 create_agent(model, tools),内部组装的就是这么一张图(外加 system_prompt、checkpointer 的接线)。

Checkpointer:状态持久化

没有它会怎样——app.invoke 一次性的:进程退出状态消失,同一个用户第二次提问,图从零开始,完全不记得上一句——第 14 章说的「每个 thread 都失忆」。

有了它——每一步之后自动存档,同 thread_id 下次调用从存档恢复,状态全量带回。

第 14 章把 InMemorySaver 当黑盒用,这里揭开它存了什么:

from langgraph.checkpoint.memory import InMemorySaver   # 内存版记忆持久化
from langgraph.graph import MessagesState, START, StateGraph
import os   # 读取环境变量

from dotenv import load_dotenv   # 从 .env 读环境变量
from langchain_openai import ChatOpenAI   # OpenAI 聊天模型

load_dotenv()

model = ChatOpenAI(
    base_url=os.environ["GLM_BASE_URL"],
    api_key=os.environ["GLM_API_KEY"],
    model=os.environ["GLM_MODEL_ID"],
)


def call_model(state: MessagesState):
    return {"messages": [model.invoke(state["messages"])]}


graph = StateGraph(MessagesState)
graph.add_node("call_model", call_model)
graph.add_edge(START, "call_model")

checkpointer = InMemorySaver()
app = graph.compile(checkpointer=checkpointer)   # 编译时挂上

config = {"configurable": {"thread_id": "user-001"}}

app.invoke({"messages": [("human", "我叫小明,记住了")]}, config)
result = app.invoke({"messages": [("human", "我叫什么?")]}, config)
print(result["messages"][-1].content)
# 你叫小明。

# 看一眼存档里到底有什么
state = checkpointer.get(config)
print(len(state["channel_values"]["messages"]), "条消息")   # 4 条:两问两答全在

要点:

  • 存的是每一步之后的完整状态(消息列表 + 各节点私有的中间值),不是摘要;
  • thread_id 是存档的键:同一 id 共享一份记忆,换一个 id 就是全新会话;
  • InMemorySaver 存进程内存(重启即失),生产换 PostgresSaver,接口一致;
  • 第 14 章的 middleware(摘要、裁剪)就是在「存档」和「模型看到多少」之间加加工层——存档永远全量,视图按需加工。

interrupt:人机协同

没有它会怎样——删数据、下单支付这类敏感动作,要么不敢交给 agent,要么在工具函数里弹确认——流程控制权和业务代码搅在一起。

有了它——图跑到指定节点前暂停,状态存档,人批准后 Command 恢复继续,拒绝则走另一条路。

from langgraph.checkpoint.memory import InMemorySaver   # 内存版记忆持久化
from langgraph.graph import MessagesState, START, StateGraph
from langgraph.types import interrupt, Command   # 中断与恢复指令

checkpointer = InMemorySaver()


def delete_with_confirm(state: MessagesState):
    answer = interrupt({"question": "确认删除这条记录吗?", "record_id": "R-1024"})
    return {"messages": [("ai", f"用户批复:{answer},执行结果:已删除")]}


graph = StateGraph(MessagesState)
graph.add_node("delete_with_confirm", delete_with_confirm)
graph.add_edge(START, "delete_with_confirm")

app = graph.compile(checkpointer=checkpointer)   # interrupt 依赖 checkpointer 存档

config = {"configurable": {"thread_id": "op-001"}}

result = app.invoke({"messages": [("human", "帮我删除记录 R-1024")]}, config)
print(result["__interrupt__"][0].value)   # {'question': '确认删除这条记录吗?', 'record_id': 'R-1024'}

# 人工批准后恢复执行
result = app.invoke(Command(resume="同意"), config)
print(result["messages"][-1].content)   # 用户批复:同意,执行结果:已删除

要点:interrupt 把当前状态完整存档后抛出,等同一个 thread_id 的下一次 invoke(Command(resume=...)) 恢复——批准/拒绝的分支写在节点代码里,权限控制归图结构管。

create_agent 对照:封装替你干了什么

没有它会怎样——每个项目都手写「call_model + ToolNode + 条件边 + checkpointer 接线」,重复且容易漏(忘了接回边、忘了挂 checkpointer)。

有了它——create_agent(model, tools) 一行,返回的就是上面手写那张图的超集。

手写图里的零件create_agent 里的对应物
call_model 节点内置模型节点(自动带 system_prompt 注入)
ToolNode([工具])tools 参数
should_continue 条件边内置路由
compile(checkpointer=...)checkpointer=... 参数
自己写循环上限保护recursion_limit(默认 25)

什么时候手写、什么时候用封装:标准 agent 循环用 create_agent,一行顶五十行;流程不是「模型-工具」循环(多阶段流水、人工审批节点、自定义状态字段)时,回 LangGraph 手写图。两者不是二选一——create_agent 返回的图还能作为子图嵌进更大的图里。

常见问题

  • pip install langgraph 装了吗——第 02 章的按用途安装清单里有它;import 报错先查这个。
  • 节点返回后被覆盖而不是追加——state 字段没加 Annotated[list, operator.add](或改用 MessagesState),默认合并策略是覆盖。
  • 条件边的函数返回了不存在的节点名——add_conditional_edges 的路由目标要在图里注册过,返回 END 才是终止。
  • checkpointer 没生效、多轮还是失忆——invoke 时没传 config={"configurable": {"thread_id": ...}};或每次用了不同的 thread_id。
  • 想看图长什么样——app.get_graph().draw_mermaid() 输出 mermaid 文本,贴进任何 mermaid 渲染器出图。

上一节:Function Calling · 下一节:Agent