什么是 LangGraph？

LangGraph 是 LangChain 生态系统中的一个库，由 LangChain Inc. 开发，用于构建、管理和部署长期运行的状态化代理（stateful agents）。它是一个低级别的编排框架，专注于代理的协调和执行，支持持久化执行、流式传输、人机交互等功能。LangGraph 的灵感来源于 Pregel…

作者：lh

2026-02-04T17:12:59.039925

LangGraph 是一个开源的低级别编排框架，由 LangChain Inc. 开发，用于构建、管理和部署长时间运行、有状态的智能体（agents）和工作流。它特别适合处理复杂的、多步骤的 AI 应用程序，尤其是在需要状态持久化、人机协作和循环处理的场景中。LangGraph 受到了 Klarna、Replit、Elastic 等知名公司的信任，并被设计为一个灵活的基础设施层，支持从简单聊天机器人到高级多代理系统的开发。

1. LangGraph 的目的和背景

LangGraph 的核心目的是为长时间运行、有状态的工作流或智能体提供底层支持基础设施。它不像一些高层框架那样抽象提示（prompts）或预定义架构，而是专注于编排（orchestration），允许开发者自定义复杂的 AI 系统。

为什么需要 LangGraph？
在 AI 开发中，许多应用（如聊天机器人、自动化代理）需要处理多轮交互、记忆状态、错误恢复和外部工具集成。传统的无状态模型（如简单的 LLM 调用）无法应对这些需求。LangGraph 通过图结构（graph-based）来建模这些流程，使系统能够“记住”过去的状态、处理循环任务，并支持中断后恢复。这使得它特别适合构建可靠的生产级 AI 代理。
灵感来源：
LangGraph 的设计灵感来源于 Pregel（Google 的图计算框架）和 Apache Beam（数据处理管道框架）。它的公共接口借鉴了 NetworkX（一个 Python 图库）。虽然由 LangChain Inc. 构建，但 LangGraph 可以独立使用，不依赖 LangChain。

2. 与 LangChain 的比较

LangGraph 和 LangChain 经常被一起提及，但它们有不同的焦点：

LangChain：一个更高级的框架，提供集成和可组合组件（如链、工具、检索器），用于简化 LLM 应用程序的开发。它更注重快速原型和组件复用，例如构建 RAG（Retrieval-Augmented Generation）系统或简单链式调用。
LangGraph：更低级，专注于编排长时间运行、有状态的智能体。它可以无缝集成 LangChain 的组件（如模型、工具），但强调图结构来管理复杂流程。简单来说，LangChain 提供“积木”，LangGraph 提供“蓝图”来组装这些积木成一个持久化的系统。

如果您已经在使用 LangChain，LangGraph 可以作为其扩展，用于处理更复杂的场景，如多代理协作或循环决策。

3. 核心优势与特性

LangGraph 的设计围绕可靠性、灵活性和生产就绪性。以下是其关键特性，每个特性我都会详细解释：

持久执行（Persistent Execution）：
LangGraph 支持构建能够抵御故障的智能体。如果系统崩溃或中断，它可以从上次检查点（checkpoint）自动恢复。这通过内置的持久化机制实现，例如使用数据库存储状态。适用于长时间任务，如数据处理管道或实时监控代理。
人机协作（Human-in-the-Loop）：
在执行的任何时间点，您可以检查和修改智能体的状态。例如，在一个决策节点暂停，等待人工输入批准或修正。这增强了系统的可控性，尤其在高风险应用中（如医疗诊断或金融交易）。
全面记忆（Comprehensive Memory）：
支持短期工作记忆（in-session）和跨会话的长期持久记忆。状态可以是简单的字典、自定义类或数据库记录，帮助代理“记住”用户偏好或历史交互。
调试（Debugging）：
与 LangSmith 集成，提供可视化工具追踪执行路径、捕获状态转换，并监控运行时指标（如延迟、错误率）。这使得调试复杂图变得直观。
部署（Deployment）：
提供生产就绪的部署选项，支持可扩展基础设施。可以通过 LangGraph 平台处理高并发、有状态的工作流，而无需手动管理服务器。

其他特性包括支持流式传输（streaming）、可视化原型和团队协作。

4. 核心概念

LangGraph 的核心是图论（graph theory）模型。整个系统被建模为一个有向图（directed graph），其中：

图（Graphs）：
图是整个工作流的蓝图。它定义了从输入到输出的完整路径，支持有状态的执行。LangGraph 提供了 StateGraph 和 Pregel 等类来构建图。
节点（Nodes）：
节点是图中的基本单元，代表一个处理函数或组件。例如，一个节点可以是 LLM 调用、工具执行或数据处理函数。节点接收状态作为输入，更新状态并输出。
示例：一个节点可能调用天气 API 并将结果添加到状态中。
边（Edges）：
边连接节点，定义控制流。默认是无条件边（从一个节点直接到下一个），但支持条件边。
条件边（Conditional Edges）：
根据状态或条件决定下一个节点。例如，如果状态中的“confidence” < 0.8，则路由到“human_review”节点。这允许动态分支，类似于 if-else 逻辑。
循环（Cycles）：
支持循环执行，例如在代理未完成任务时循环调用工具。这对于迭代任务（如调试代码或多轮对话）至关重要。LangGraph 内置循环检测以避免无限循环。
状态（State）：
状态是图执行的核心，通常是一个可更新的字典或 Pydantic 模型。它在节点间传递，包含输入、输出、记忆等。状态可以是线程安全的，支持并发。
持久化（Persistence）：
通过检查点（checkpoints）实现。每个节点执行后，状态被保存到存储（如 SQLite、Redis）。这允许中断恢复和版本控制。
人机协作（Human-in-the-Loop）：
如上所述，在图中插入“breakpoint”节点，等待人工输入。
流式传输（Streaming）：
支持实时输出，例如在长生成任务中逐步流式返回 token 而非一次性输出。
可视化（Visualization）：
通过 LangGraph Studio（一个 IDE-like 工具）可视化图结构、原型和迭代。Studio 允许拖拽节点、实时测试。
部署（Deployment）：
使用 LangGraph Cloud 或自托管，支持 scaling 到数千并发。

5. 构建应用的过程

构建 LangGraph 应用遵循一个清晰的结构化流程。以下是详细步骤：

定义状态（Define State）：
使用 TypedDict 或 Pydantic 模型定义状态 schema。例如：

from typing import TypedDict, Annotated
from langgraph.graph import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]  # 消息列表，支持追加
    weather_data: dict  # 自定义字段from typing import TypedDict, Annotated
from langgraph.graph import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]  # 消息列表，支持追加
    weather_data: dict  # 自定义字段

定义节点（Define Nodes）：
节点是 callable 函数，接收状态并返回更新。
示例：

def get_weather_node(state: State) -> State:
    city = state['messages'][-1]['content'].split()[-1]  # 提取城市
    weather = get_weather(city)  # 调用工具
    return {"weather_data": weather}def get_weather_node(state: State) -> State:
    city = state['messages'][-1]['content'].split()[-1]  # 提取城市
    weather = get_weather(city)  # 调用工具
    return {"weather_data": weather}

定义边（Define Edges）：
使用 graph.add_node() 和 graph.add_edge()。对于条件边：

def router(state: State) -> str:
    if "error" in state: return "error_handler"
    return "next_node"

graph.add_conditional_edges("start", router, {"error_handler": "handle_error", "next_node": "process"})def router(state: State) -> str:
    if "error" in state: return "error_handler"
    return "next_node"

graph.add_conditional_edges("start", router, {"error_handler": "handle_error", "next_node": "process"})

编译图（Compile Graph）：
使用 graph.compile() 生成可执行图。支持添加检查点：

from langgraph.checkpoint.sqlite import SqliteSaver
memory = SqliteSaver.from_conn_string(":memory:")
app = graph.compile(checkpointer=memory)from langgraph.checkpoint.sqlite import SqliteSaver
memory = SqliteSaver.from_conn_string(":memory:")
app = graph.compile(checkpointer=memory)

调用图（Invoke Graph）：
通过 app.invoke(input, config) 运行。支持流式： app.stream(input)。
示例：

input = {"messages": [{"role": "user", "content": "weather in sf"}]}
output = app.invoke(input)input = {"messages": [{"role": "user", "content": "weather in sf"}]}
output = app.invoke(input)

6. 入门示例

网站提供了一个简单示例，使用预构建组件创建 ReAct 代理（Reason + Act）：

安装：

pip install -U langgraph langchain-anthropic  # 或其他模型提供者

代码：

from langgraph.prebuilt import create_react_agent

def get_weather(city: str) -> str:
    return f"It's always sunny in {city}!"

model = "anthropic:claude-3-sonnet-20240229"  # 示例模型
agent = create_react_agent(
    model=model,
    tools=[get_weather],
    prompt="You are a helpful assistant"
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "what is the weather in sf"}]
})
print(result)

这个代理会推理（reason）问题，调用工具（act），并返回结果。扩展时，可以添加更多节点如检索或记忆。

7. 资源和教程

快速入门：https://langgraph.com.cn/agents/agents.1.html - 使用预构建组件快速构建代理。
基础教程：langgraph.com.cn/tutorials/get-started/1-build-basic-chatbot/index.html - 构建具有自定义架构和长期记忆的聊天机器人。包括从零构建图的步骤。
参考文档：langgraph.com.cn/reference/graphs/index.html- 详细 API，包括核心类（如 StateGraph）、方法和检查点。
示例：langgraph.com.cn/tutorials/overview/index.html - 入门引导，如工具调用代理、RAG 代理。
模板：langgraph.com.cn/concepts/template_applications/index.html - 预构建应用，如 ReAct 代理、记忆增强代理、检索代理。
LangChain 学院：academy.langchain.com/courses/intro-to-langgraph - 免费课程，涵盖 LangGraph 基础。

8. 生态系统和扩展

LangSmith：用于评估和可观察性。调试轨迹、评估性能、生产监控。
LangGraph 平台：云服务，支持部署、扩展和团队共享代理。
LangGraph Studio：可视化 IDE，用于原型设计、拖拽构建图、实时测试。
LangGraph.js：JavaScript 版本（github.com/langchain-ai/langgraphjs），文档在 github.langchain.ac.cn/langgraphjs。适合前端或 Node.js 开发者，API 类似 Python 版。

9. 高级主题和注意事项

设计模式：支持分支（branching）、子图（subgraphs）、多代理（multi-agent）协作。例如，构建一个主管代理分派任务给子代理。
性能考虑：对于大规模部署，使用异步节点和分布式检查点。避免过度循环以防性能瓶颈。
局限性：作为低级框架，需要更多手动配置。初学者可从预构建模板开始。