2. LangGraph基础入门

LangGraph 是 LangChain 生态系统中面向有状态、可编排、可复用的智能体应用的底层编排框架。如果说 LangChain 提供了“模型、工具、记忆、检索”等积木，那么 LangGraph 就是把这些积木按图结构组织起来的“施工图纸与调度系统”。它借鉴了图计算与状态机的思想，将一次智能体运行建模为一张有向图：图中的节点（Node）执行具体逻辑，边（Edge）决定流转方向，而贯穿整个图的状态（State）则负责在节点之间传递数据。本章将围绕 LangGraph 的定位、核心抽象、与 LangChain 的关系以及安装配置展开，帮助读者建立清晰的认知框架。

上图展示了 LangGraph 在 LangChain 生态中的位置及其三大核心抽象。下面我们逐一深入解析。

2.1 LangGraph 的定位：从“链式调用”到“图式编排”

在 LangChain 早期版本中，应用通常被组织为线性链（Chain），例如“提示词 → 模型 → 输出解析器”。这种模式对于简单任务足够，但面对多步骤、需要条件分支、循环、人工介入或动态工具选择的智能体场景时，链式结构显得僵化。LangGraph 的定位正是解决这一问题：它提供了一种低层、灵活、可细粒度控制的编排方式，允许开发者将应用建模为一张图，图中的每个节点可以是一个函数、一个 LangChain Runnable、甚至一个子图。

2.1.1 核心原理：图、状态与执行循环

LangGraph 的执行模型基于三个关键机制：

• 图（Graph）：由节点和有向边构成，节点是执行单元，边定义执行顺序。
• 状态（State）：一个在节点间传递的数据结构，所有节点共享同一状态对象，但只能通过返回“更新”来修改状态。
• 超级步（Super-step）：每次图被调用时，从 START 节点开始，沿着边执行，直到到达 END 节点。每个节点执行后返回的状态更新会被合并到全局状态中。

这种设计使得 LangGraph 天然支持循环（如 Agent 反复调用工具直到得到最终答案）和分支（如根据意图路由到不同处理流程）。

2.1.2 判断方法：何时选择 LangGraph？

以下场景适合使用 LangGraph：

1. 需要多步骤、非确定性流程，例如 ReAct Agent、Plan-and-Execute 模式。
2. 需要人工介入（Human-in-the-loop），例如审批、纠错。
3. 需要状态持久化，例如对话历史、任务恢复。
4. 需要细粒度控制，例如自定义循环终止条件、动态路由。

如果应用只是简单的“输入 → 模型 → 输出”，使用 LangChain 的 LCEL（LangChain Expression Language）即可，无需引入 LangGraph。

2.1.3 案例拆解：一个简单的 ReAct Agent 结构

假设我们要构建一个能调用搜索工具的 Agent。用 LangGraph 建模，图结构如下：

执行流程：START → agent → router → （若 continue）→ tools → agent → … → （若 end）→ END。这个循环结构是 LangGraph 最典型的应用模式。

2.1.4 常见误区与总结

2.2 核心概念详解：State、Node、Edge

这三个概念是 LangGraph 的基石。理解它们，就掌握了 LangGraph 的 80%。

2.2.1 State（状态）

State 是一个 TypedDict 或 Pydantic 模型，定义了图执行过程中需要维护的数据结构。每个节点接收当前 State 作为参数，并返回一个字典，其中包含要更新的字段。

from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, END

class AgentState(TypedDict):
    messages: Annotated[list, operator.add]  # 使用 Reducer 合并
    next_step: str
    user_id: str

关键点：

• Reducer：当多个节点同时更新同一字段时，Reducer 决定如何合并。例如 operator.add 用于列表拼接，operator.set 用于覆盖。
• Checkpoint：LangGraph 可以持久化 State 到存储后端（如 SQLite、Postgres），支持断点续跑。

2.2.2 Node（节点）

节点是图的基本执行单元，可以是任意 Python 函数。函数签名固定为 (state) -> dict，即接收当前状态，返回状态更新。

def agent_node(state: AgentState):
    # 调用 LLM 或执行逻辑
    response = llm.invoke(state["messages"])
    return {"messages": [response], "next_step": "tools"}

节点可以：

• 调用 LangChain 的 Runnable（如 model.bind_tools()）。
• 调用外部 API、数据库、工具。
• 包含条件判断、循环等任意 Python 逻辑。

2.2.3 Edge（边）

边定义了节点之间的连接关系。LangGraph 提供两种边：

• 普通边（Normal Edge）：无条件流转，如 graph.add_edge("agent", "tools")。
• 条件边（Conditional Edge）：根据状态或外部条件动态选择下一个节点，如 graph.add_conditional_edges("router", route_function, {"continue": "agent", "end": END})。

此外，还有两个特殊节点：START（图入口）和 END（图出口）。

2.2.4 案例拆解：构建一个带条件分支的图

假设我们要构建一个“意图识别 → 处理”的流程：

from langgraph.graph import StateGraph, START, END

def classify(state):
    # 假设根据输入分类
    if "天气" in state["input"]:
        return {"intent": "weather"}
    else:
        return {"intent": "chat"}

def weather_handler(state):
    return {"response": "今天晴天，25度"}

def chat_handler(state):
    return {"response": "你好，我是助手"}

# 构建图
builder = StateGraph(AgentState)
builder.add_node("classify", classify)
builder.add_node("weather", weather_handler)
builder.add_node("chat", chat_handler)

builder.add_edge(START, "classify")
builder.add_conditional_edges("classify", lambda s: s["intent"], {"weather": "weather", "chat": "chat"})
builder.add_edge("weather", END)
builder.add_edge("chat", END)

graph = builder.compile()

这个例子展示了条件边如何根据 State 中的字段动态路由。

2.2.5 常见误区与总结

2.3 与 LangChain 的关系：互补而非替代

LangChain 和 LangGraph 的关系可以类比为“库”与“框架”：LangChain 提供了丰富的组件（模型封装、提示词模板、输出解析器、文档加载器、向量存储等），而 LangGraph 则提供了将这些组件组合成复杂应用的“骨架”。

在实际项目中，两者经常混合使用：用 LangChain 的组件作为 Node 内部实现，用 LangGraph 控制整体流程。

2.4 安装与配置

LangGraph 的安装非常简单，但需要注意版本兼容性。

2.4.1 安装步骤

# 基础安装
pip install langgraph

# 如果需要持久化（Checkpoint）
pip install langgraph-checkpoint

# 如果需要 CLI 工具（用于调试和部署）
pip install langgraph-cli

# 建议同时安装 LangChain 核心
pip install langchain-core langchain-

2.4.2 验证安装

import langgraph
print(langgraph.__version__)  # 例如 0.2.x

from langgraph.graph import StateGraph
print("LangGraph 导入成功")

2.4.3 配置建议

• Python 版本：要求 3.9+，推荐 3.11+。
• 虚拟环境：建议使用 venv 或 conda 隔离项目依赖。
• 环境变量：如果使用 模型，设置 _。

2.4.4 案例：最小可运行示例

from langgraph.graph import StateGraph, START, END
from typing import TypedDict

class State(TypedDict):
    value: int

def increment(state):
    return {"value": state["value"] + 1}

# 构建图
builder = StateGraph(State)
builder.add_node("inc", increment)
builder.add_edge(START, "inc")
builder.add_edge("inc", END)
graph = builder.compile()

# 执行
result = graph.invoke({"value": 1})
print(result)  # {'value': 2}

这个示例展示了 LangGraph 的最小闭环：定义状态、添加节点、连接边、编译并执行。

2.4.5 常见问题与复盘