LangGraph:构建有状态 AI Agent 的编排框架|部署与使用指南
用图结构把大模型、工具与记忆串成可循环、可中断、可持久化的有状态智能体,是 LangChain 生态下构建生产级 Agent 的主流编排层。
| 项目 | 信息 |
|---|---|
| 官方仓库 | langchain-ai/langgraph |
| 官方文档 | docs.langchain.com · LangGraph 概览 |
| API 参考 | reference.langchain.com · langgraph |
| 官网 | langchain.com/langgraph |
| 语言 / 许可 | Python / MIT |
▲ 图 0:LangGraph 官方 Logo(官方标识)
项目简介
LangGraph 是 LangChain 团队推出的有状态 AI Agent 编排框架。如果说 LangChain 负责把模型、提示词、工具等组件串联成一条线性链路,LangGraph 则在此之上提供了一张"状态图":你可以把 Agent 的工作流程拆成一个个节点(调用模型、执行工具、检索资料、人工审核等),再用边定义节点之间的流转方向,包括条件分支、循环回退与并行分支,从而表达"模型决定是否调用工具 → 工具执行结果回传模型 → 继续推理"这类典型的 ReAct 循环。
截至 2026 年 10 月 25 日,其 GitHub 仓库已收获约 4.39 万 star(43,854),fork 7,533,采用 Python 编写、MIT 许可证,最后推送日期为 2026 年 10 月 25 日,社区迭代活跃。它被广泛用于客服机器人、研究助手、代码 Agent、多角色协作流程与工作流自动化等场景,也是 LangChain 官方推荐的生产级 Agent 构建方案。

▲ 图 1:LangGraph 官网产品页预览,页面标语 "Own your intelligence"(官方截图)
需要明确的是:LangGraph 本身是一个纯 Python 编排库,不自带大模型权重,也不提供推理算力。运行一个 Agent 需要自备 LLM 提供商——可以是 OpenAI、Anthropic 等云端 API Key,也可以是通过 Ollama、vLLM 等跑在本机或内网的开源模型。框架负责状态管理、流转控制与持久化,模型能力由你接入的后端决定。
核心能力与特性
- 状态图建模:以
StateGraph定义共享状态与节点、边,把 Agent 流程表达为一张可可视化、可调试的图,支持条件路由与循环。 - 内置消息归并:
add_messages注解自动把新消息追加进状态,多轮对话与工具往返无需手工拼接历史。 - 工具调用循环:
ToolNode与tools_condition开箱即用,模型判断需要工具时自动进入工具节点,结果回传后继续推理。 - 持久化与检查点:内置 Checkpointer 机制(内存、SQLite、PostgreSQL 等后端),按线程保存状态,支持断点续跑、人工介入后恢复。
- 流式输出:支持按节点、按消息、按 token 等多种流式模式,便于把中间过程实时推送到前端界面。
- 人机协作:图中可插入
interrupt节点暂停流程,等待人工审批或补充输入后再继续,适合需要把关的业务流程。 - 生态兼容:与 LangChain 模型封装、工具、记忆组件无缝配合,也可单独使用;官方提供 Studio 可视化调试与 LangSmith 追踪集成。
- 本地模型友好:通过 LangChain 模型适配器接入 Ollama、本地 vLLM 等后端,离线环境同样可以跑通完整 Agent 流程。
硬件与系统要求
LangGraph 框架本身非常轻量,资源占用主要来自你接入的模型后端:
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | x86-64 双核 | 4 核以上 |
| 内存 | 4 GB(仅跑编排逻辑与 API 调用) | 8 GB 以上;本地跑模型另按模型大小估算 |
| GPU | 不需要(云端 API 模式) | 仅在本机跑开源模型时需要,显存按所选模型估算 |
| 操作系统 | Linux、macOS、Windows 10+(Python 3.10+) | 同左 |
| 磁盘 | 500 MB(Python 依赖) | 2 GB 以上;本地模型权重另计 |
完整部署方式
环境准备
LangGraph 是纯 Python 库,建议先准备独立虚拟环境,避免与系统 Python 依赖冲突:
# 确认 Python 版本(3.10 及以上)
python3 --version
# 创建虚拟环境
python3 -m venv .venv
# 激活虚拟环境(Linux / macOS)
source .venv/bin/activate
# Windows PowerShell 激活方式
# .venv\Scripts\Activate.ps1
安装核心包
# 安装 LangGraph 与 LangChain 基础依赖
pip install -U langgraph langchain-core langchain-openai
# 如需接入 Ollama 本地模型,再安装适配器
pip install -U langchain-ollama
# 验证安装成功
python -c "import langgraph; print(langgraph.__version__)"
配置模型后端 API Key
云端模型模式下,把 Key 写入环境变量即可,代码中无需硬编码:
# OpenAI 兼容接口(按所用服务商替换 base_url 与 key)
export OPENAI_API_KEY="sk-你的密钥"
# 若使用其他 OpenAI 兼容服务商,可同时指定接口地址
export OPENAI_BASE_URL="https://你的兼容接口地址/v1"
本地模型后端(可选,以 Ollama 为例)
不想依赖云端 API 时,可以先用 Ollama 在本机拉起开源模型,再让 LangGraph 调用:
# 启动 Ollama 服务并拉取一个中文能力较好的模型
ollama serve
ollama pull qwen2.5:7b
源码安装(进阶)
需要跟进最新提交或二次修改时,可直接克隆官方仓库:
git clone https://github.com/langchain-ai/langgraph.git
cd langgraph
pip install -e .
使用方法
构建一个简单的 ReAct Agent
下面的示例定义了一个"模型节点 + 工具节点"的循环图:模型先判断是否需要调用工具,需要则进入工具节点执行,结果回传模型继续回答;不需要则直接结束。
# 依赖:pip install -U langgraph langchain-core langchain-openai
from typing import Annotated
from typing_extensions import TypedDict
from langchain_core.messages import HumanMessage
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
# 定义共享状态:messages 字段由 add_messages 自动归并新消息
class AgentState(TypedDict):
messages: Annotated[list, add_messages]
# 准备模型与示例工具(一个简单计算器)
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
def calculator(expression: str) -> str:
"""计算传入的数学表达式,例如 128 * 36"""
try:
return str(eval(expression, {"__builtins__": {}}, {}))
except Exception as exc:
return f"计算失败: {exc}"
tools = [calculator]
llm_with_tools = llm.bind_tools(tools)
# 定义节点:调用模型生成下一步动作
def call_model(state: AgentState):
response = llm_with_tools.invoke(state["messages"])
return {"messages": [response]}
# 构图:注册节点、连接起点、配置条件分支与回边
builder = StateGraph(AgentState)
builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges(
"agent",
tools_condition,
{"tools": "tools", END: END},
)
builder.add_edge("tools", "agent")
# 编译图并发起一次调用
graph = builder.compile()
result = graph.invoke(
{"messages": [HumanMessage(content="帮我算一下 128 × 36 等于多少")]}
)
for message in result["messages"]:
message.pretty_print()
接入 Ollama 本地模型
把模型初始化部分替换为本地适配器,其余节点与构图代码保持不变:
# 依赖:pip install -U langchain-ollama,且本机已运行 ollama serve
from langchain_ollama import ChatOllama
llm = ChatOllama(model="qwen2.5:7b", temperature=0)
llm_with_tools = llm.bind_tools(tools)
状态持久化(检查点)
编译时传入 Checkpointer,即可按线程保存对话状态,下次调用同一 thread_id 时自动恢复历史上下文:
from langgraph.checkpoint.memory import MemorySaver
checkpointer = MemorySaver()
graph = builder.compile(checkpointer=checkpointer)
# 第一次对话,绑定线程标识
graph.invoke(
{"messages": [HumanMessage(content="我叫周若琳")]},
config={"configurable": {"thread_id": "user-001"}},
)
# 同线程再次调用,模型可以读到之前的自我介绍
graph.invoke(
{"messages": [HumanMessage(content="我刚才说我叫什么?")]},
config={"configurable": {"thread_id": "user-001"}},
)
流式输出
把 invoke 换成 stream 即可逐节点或逐消息获取中间结果,适合对接聊天界面实时渲染:
for chunk in graph.stream(
{"messages": [HumanMessage(content="用三句话介绍什么是向量数据库")]},
config={"configurable": {"thread_id": "user-002"}},
stream_mode="messages",
):
print(chunk[0].content, end="", flush=True)
官方链接
| 资源 | 链接 |
|---|---|
| GitHub 仓库 | github.com/langchain-ai/langgraph |
| 官网 | www.langchain.com/langgraph |
| 官方文档 | docs.langchain.com · LangGraph |
| API 参考 | reference.langchain.com · langgraph |
常见问题(FAQ)
问:LangGraph 和 LangChain 是什么关系? LangChain 提供模型封装、工具、提示词等基础组件;LangGraph 是在其之上的 Agent 编排层,负责状态管理、节点流转、条件分支、循环与持久化。两者经常配合使用,LangGraph 也可以独立于 LangChain 组件工作。
问:必须使用 OpenAI 等云端 API 吗?能不能用本地模型? 不必须。通过 LangChain 模型适配器可以接入 Ollama、vLLM、LM Studio 等本地后端,代码中只需替换模型初始化对象,节点与图结构保持不变。本地模型的工具调用能力受模型自身函数调用支持程度影响,建议选择支持工具调用的开源模型。
问:部署 LangGraph 需要 GPU 吗? 框架本身是纯 Python 编排逻辑,普通 CPU 机器即可运行。只有当你选择在本机跑开源模型时,才需要相应显存;云端 API 模式下调用方只承担网络与少量内存开销。
问:Agent 的对话记忆是怎么保存的?
编译时传入 Checkpointer(内存、SQLite 或 PostgreSQL 等后端),运行时通过 thread_id 区分不同会话,状态会自动持久化,重启进程后可从检查点恢复。
问:适合用来做什么样的项目? 适合需要多步推理、工具往返、条件分支、人工审批或长时间运行的流程型 Agent,例如客服助手、研究报告生成器、数据分析机器人、代码排障助手与多角色协作工作流。单一轮次的简单问答直接调用模型即可,不必引入图编排。
问:官方文档地址有变化吗? 有。LangChain 已把文档迁移至 docs.langchain.com,API 细节查阅 reference.langchain.com,旧站点链接会逐步跳转。
许可证
LangGraph 仓库采用 MIT 许可证,允许自由使用、复制、修改、合并、发布、分发与商用,只需在源码与副本中保留原始版权声明与许可声明。需要注意:接入的第三方模型、工具组件与其服务条款分别遵循各自协议;云端 API 的调用费用由对应服务商按用量收取。