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)
这三行就是循环的全部:
add_conditional_edges("call_model", should_continue)—— 每次模型说完,运行时检查:有tool_calls去tools,没有去END;add_edge("tools", "call_model")—— 工具执行完回到模型,下一轮开始;- 节点返回的消息增量自动累积在
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