blog.dopana

返回

如果你用简单的 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: str
python

Annotated[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!"}]})
python

3. 边 — 控制流#

  • 普通边(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")                       # 循环回去
python
|要调用工具?||不调用|STARTchatbot LLMToolNodeEND

4. 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"}},
)
python

thread_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 图:

订单或账单简单问题有没有已批准START意图分类拉取客户数据起草回复有高风险操作?interrupt: 人工审核发送回复END

每个方框都是一个易于测试的小函数;checkpointer 保证白天部署也不会毁掉进行中的对话。小部件加上持久化状态,正是这套组合让 Agent 具备了生产可用性。

参考资料#