Loading...

文章背景图

LangGraph:构建有状态 AI Agent 的编排框架|部署与使用指南

2026-10-25
2
- 字
- 分钟
|

LangGraph:构建有状态 AI Agent 的编排框架|部署与使用指南

用图结构把大模型、工具与记忆串成可循环、可中断、可持久化的有状态智能体,是 LangChain 生态下构建生产级 Agent 的主流编排层。

项目 信息
官方仓库 langchain-ai/langgraph
官方文档 docs.langchain.com · LangGraph 概览
API 参考 reference.langchain.com · langgraph
官网 langchain.com/langgraph
语言 / 许可 Python / MIT

LangGraph 官方 Logo

▲ 图 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 构建方案。

LangGraph 官网产品页预览(官方截图)

▲ 图 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 的调用费用由对应服务商按用量收取。

评论交流

文章目录