如果你用简单的 while 循环构建过 AI Agent——调用模型、执行工具、追加结果、再循环——你一定体会过那种痛苦:循环跑几步就跑偏,一次崩溃就丢光所有进度,而且在 Agent 做出不可逆操作之前,人根本没有干净的介入方式。
LangGraph 是 LangChain 团队的开源项目,正是为了解决这个问题而生。它是一个面向有状态、长时间运行的 Agent 的底层编排框架,如今已是 Agent 生态中最流行的基石之一(GitHub 超过 4 万 star,Klarna、Replit、Elastic 等公司都在生产环境使用)。
问题:朴素的 Agent 循环为什么会崩#
把 Agent 想象成一个要在城里跑 20 个任务的快递员。
- 朴素循环就是一个没有便签本的快递员。每送完一单,全靠脑子记。一走神就忘了还剩哪些件。车坏了(异常、超时、部署),一天的活全白干。
- 你真正想要的是一个带夹板的快递员:每送一单就记下状态,任何人都能接手,主管也能在派送贵重件之前先看一眼夹板。
这正是 LangGraph 的核心思想:Agent 的状态是一等公民。框架负责持久化它、恢复它,并允许你在 Agent 运行时查看甚至修改它。
解决方案:把 Agent 建模为图#
LangGraph 把 Agent 建模为跑在共享状态上的图。我们逐个拆解概念。
1. State — 共享白板#
State 是流经整张图的数据结构(TypedDict 或 Pydantic 模型)。每个节点都能读取它并向它写入更新:
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph.message import add_messages
class State(TypedDict):
# add_messages 是一个「reducer」:新消息是追加,不是覆盖
messages: Annotated[list, add_messages]
query: strpythonAnnotated[list, add_messages] 这一段就是 reducer(归约器):它告诉 LangGraph 当多个节点写同一个字段时如何合并——追加,而不是替换。
2. 节点 — 处理步骤#
节点就是一个函数:接收当前状态,返回一部分更新。关键在于,节点既可以是确定性的 Python 代码(调 API、做校验),也可以是一次 LLM 调用——两者可以混在同一张图里:
from langgraph.graph import StateGraph, START, END
from langchain.chat_models import init_chat_model
llm = init_chat_model("anthropic:claude-sonnet-4-5")
def chatbot(state: State):
return {"messages": [llm.invoke(state["messages"])]}
graph = StateGraph(State)
graph.add_node("chatbot", chatbot)
graph.add_edge(START, "chatbot")
graph.add_edge("chatbot", END)
app = graph.compile()
app.invoke({"messages": [{"role": "user", "content": "hi!"}]})python3. 边 — 控制流#
- 普通边(
add_edge)永远从 A 走到 B。 - 条件边(
add_conditional_edges)根据状态动态路由——「Agent」的灵魂就在这里:由 LLM 决定是调用工具还是收工。
经典的 Agent 形状长这样:
from langgraph.prebuilt import ToolNode, tools_condition
graph.add_conditional_edges("chatbot", tools_condition) # 由 LLM 决定
graph.add_node("tools", ToolNode(my_tools))
graph.add_edge("tools", "chatbot") # 循环回去python4. Checkpointer — 持久化执行#
这是 LangGraph 的超能力。加上 checkpointer,图会在每一步之后保存状态:
from langgraph.checkpoint.memory import InMemorySaver
checkpointer = InMemorySaver() # 生产环境请用数据库版
app = graph.compile(checkpointer=checkpointer)
app.invoke(
{"messages": [{"role": "user", "content": "hi!"}]},
config={"configurable": {"thread_id": "user-123"}},
)pythonthread_id 标识一段对话。如果进程中途崩溃,用同一个 thread ID 重新调用即可从最近的检查点续跑——便签本在车祸中幸存了下来。
5. Interrupt — 人工介入#
有了持久化,停下来等人审批就变得非常简单:
app.invoke(input, config, interrupt_before=["tools"])python图会在 tools 节点之前停下,人工检查(还可以修改)状态后再继续。对于能发邮件、能执行代码、能花钱的 Agent,这是必备机制。
为什么这种设计更胜一筹#
| 能力 | LangGraph 提供的东西 |
|---|---|
| 持久化执行 | 故障后存活,长任务可续跑 |
| 人工介入 | 在危险步骤之前查看 / 修改 Agent 状态 |
| 记忆 | 短期工作记忆 + 跨会话长期记忆 |
| 混合逻辑 | 确定性代码与 LLM 步骤同处一张可审计的图 |
| 可观测性 | LangSmith 追踪每个节点与每次状态转移 |
因为整个 Agent 就是一张图,你可以可视化、重放、逐步调试——这是纠缠不清的 while 循环永远给不了的。
[!TIP] 如果不想手写图,LangChain 在 LangGraph 之上提供了预置 Agent(
create_react_agent),还有更高层的 Deep Agents 包,用于会规划、会用子 Agent 和文件系统的 Agent。可以先从这里起步,需要自定义控制流时再下沉到原生 LangGraph。
什么时候该用它?#
适合: 需要调用工具、需要审批流、要运行几分钟到几小时、或必须扛住重启的多步 Agent——客服机器人、编程 Agent、研究流水线。
杀鸡用牛刀: 一次性问答,或不涉及工具调用的简单 RAG 链。普通一次 LLM 调用或小链条更简单;LangGraph 的价值恰恰在状态、循环和可靠性开始变得重要的时候。
实战示例#
一个真实的客服 Agent 图:
每个方框都是一个易于测试的小函数;checkpointer 保证白天部署也不会毁掉进行中的对话。小部件加上持久化状态,正是这套组合让 Agent 具备了生产可用性。