LangGraph 从入门到精通：Functional API 完全指南

前言：为什么你需要这本教程

在 AI 大模型时代，调用一个 LLM（大语言模型，Large Language Model）已经非常容易。但真正的挑战在于：如何构建一个能自主决策、多步推理、调用外部工具、与人类协作的智能 Agent？

LangGraph 就是为这个问题而生的。它由 LangChain 团队开发，是一个专门用于构建有状态、多角色 AI Agent 应用的框架。本教程将带你从零开始，通过构建一个完整的「智能旅行规划助手」项目，全面掌握 LangGraph Functional API 的每一个知识点。

本教程特色：

• 项目驱动

  ：以一个「智能旅行规划助手」为主线，从 v0.1 迭代到 v0.9，每章加入新能力

• API 速查

  ：每章末尾提供该章涉及的 API 速查表，方便随时查阅

• 避坑指南

  ：每章总结新手最常见的错误和解决方案

• 生动类比

  ：每个核心概念都有通俗易懂的类比，帮助你建立直觉理解

• Mermaid 图表

  ：关键流程配有 Mermaid 图，直观展示架构和数据流

学完本教程你将能够：

• 独立使用 LangGraph Functional API 构建生产级 Agent 应用
• 理解 State、Task、Entrypoint、Checkpointing 等核心概念
• 实现工具调用、人在环（Human-in-the-loop）、多 Agent 协作等高级功能
• 将 Agent 部署到生产环境并做好监控和优化

---

第 1 章：概念与架构 — 理解 LangGraph 是什么

1.1 本章目标

学完本章后，你将能够：

• 清楚地解释 LangGraph 是什么，它解决了什么问题
• 理解 Graph（图）、Node（节点）、Edge（边）、State（状态）、Entrypoint（入口）、Task（任务）六大核心概念
• 区分 LangGraph、LangChain 和直接调用 LLM 三者的定位和关系
• 理解 Functional API 和 Graph API 两种编程范式的区别，知道何时选用哪种
• 画出 LangGraph 的工作原理图

1.2 核心概念

1.2.1 一个生动的类比：智能工厂流水线

想象你经营一家智能工厂。客户下单后，订单会经过一系列加工步骤：接单 → 配料 → 加工 → 质检 → 打包 → 发货。每个步骤都是一个工位，由一个工人负责。工位之间通过传送带连接。订单信息（客户地址、产品规格、数量等）贯穿整个流程，每个工位都可以查看和修改它。

LangGraph 做的事情，本质上就是帮你搭建这样的「智能工厂流水线」：

工厂概念	LangGraph 概念	说明
工位	Node（节点） / Task（任务）	执行具体工作的单元，比如调用 LLM、查询数据库、调用 API
传送带	Edge（边）	定义工作流的方向，决定下一步做什么
订单信息	State（状态）	在整个流程中传递和累积的数据
流水线入口	Entrypoint（入口）	用户请求进入流水线的起点
整个工厂流水线	Graph（图）	由节点、边、状态组成的完整工作流

1.2.2 LangGraph 到底是什么

LangGraph 是一个用于构建有状态、多步骤 AI Agent 应用的 Python 框架。它的核心价值在于：

1. 有状态（Stateful）

   ：与简单的「请求-响应」模式不同，LangGraph 的 Agent 可以记住之前的对话上下文、中间推理步骤、工具调用结果

2. 多步骤（Multi-step）

   ：Agent 不是一次性输出答案，而是像人类一样，经过多步推理、调用工具、验证结果，最终得出结论

3. 可控流程（Controllable Flow）

   ：你可以精确控制 Agent 的执行路径——什么时候调用 LLM、什么时候调用工具、什么时候暂停等待人类输入

一个直观的例子：用户问「我下周去东京，帮我规划一下行程」。一个 LangGraph Agent 的处理流程是：

用户输入 → 分析需求（提取目的地、时间、预算）→ 查询天气 → 查询机票 → 查询酒店 → 综合生成行程 → 展示给用户确认 → 根据反馈修改 → 最终输出

每一步都是一个独立的 Task（任务），数据在它们之间流转，LangGraph 负责协调整个过程。

1.2.3 LangGraph vs LangChain vs 直接调用 LLM

很多初学者会混淆这三者的关系。下面用一个表格清晰地说明：

维度	直接调用 LLM	LangChain	LangGraph
本质	单次请求-响应	工具链和抽象层	有状态工作流编排引擎
能做什么	一问一答	链式调用、工具调用、RAG	多步推理、条件分支、并行、人在环、多 Agent 协作
状态管理	无状态（每次独立）	有限的链式状态	完整的状态持久化（Checkpointing）
控制流	无	线性链	图结构（条件分支、循环、并行）
典型场景	简单问答	文档问答、数据提取	自主 Agent、客服系统、工作流自动化
复杂度	低	中	高

关键理解：LangGraph 并不是 LangChain 的替代品，两者是合作关系：

• LangChain

  提供了与 LLM 交互的便捷工具（模型调用、提示模板、工具定义等）

• LangGraph

  提供了编排这些工具的「指挥系统」，让 Agent 能自主决策和行动

你可以把 LangChain 理解为一个工具箱（扳手、螺丝刀、电钻），把 LangGraph 理解为一条自动化流水线——流水线用工具箱里的工具来完成复杂任务。

1.2.4 Functional API vs Graph API：两种编程范式

LangGraph v1.0 引入了 Functional API（函数式 API），与传统的 Graph API（图 API） 形成两种编程范式：

Graph API（传统方式）：显式定义节点和边

from langgraph.graph import StateGraph, START, END
# 需要显式定义 State、节点、边
builder = StateGraph(MyState)
builder.add_node("step1", step1_fn)
builder.add_node("step2", step2_fn)
builder.add_edge(START, "step1")
builder.add_conditional_edges("step1", router_fn, {"a": "step2", "b": END})
graph = builder.compile()

Functional API（新方式·本教程主力）：使用标准 Python 控制流

from langgraph.func import entrypoint, task
@task
def step1(data): ...
@task
def step2(data): ...
@entrypoint()
def workflow(input_data):
result1 = step1(input_data).result()
if result1 == "a":
result2 = step2(result1).result()
return result2
return result1

对比总结：

维度	Functional API	Graph API
控制流写法	标准 Python（if/for/while）	显式定义节点和边
学习曲线	低（Python 程序员零门槛）	中（需要理解图的概念）
可见性	运行时可观测	编译时可视化图结构
检查点粒度	每个 entrypoint 执行后	每个超步（superstep）后
适合场景	快速原型、简单到中等复杂度	需要精确控制、可视化、时间旅行
状态声明	无需显式声明	必须声明 State 和 Reducer

本教程选择 Functional API 的原因：

1. 使用标准 Python 语法，学习成本最低
2. 代码更简洁，可读性更好
3. 适合大多数实际场景
4. 是 LangGraph 团队主推的发展方向

当需要更细粒度的检查点或时间旅行等高级功能时，可以轻松切换到 Graph API，两者共享同一运行时，可以混合使用。

1.2.5 LangGraph 工作原理（Mermaid 图）

下面这张图展示了 LangGraph 的核心工作原理：

图中每个元素的含义：

• Entrypoint（入口）

  ：用户请求的入口，类似工厂的「接单台」。它负责接收输入、启动工作流、返回最终结果

• Task（任务）

  ：工作流中的独立执行单元，每个 Task 完成一个具体的工作（如调用 LLM、查询数据库、调用 API）

• 条件判断

  ：使用 Python 原生的 if/else 控制流程走向，决定下一步执行哪个 Task

• Checkpoint（检查点）

  ：自动保存工作流执行状态，就像游戏存档。如果流程中断或需要多轮对话，可以从检查点恢复

• 工具调用循环

  ：Task 调用 LLM → LLM 决定需要工具 → Task 执行工具 → 结果返回给 LLM → LLM 决定是否需要更多工具，如此循环直到 LLM 认为任务完成

1.2.6 关键术语速查表

术语	英文	含义	类比
图	Graph	描述工作流整体结构的「蓝图」	工厂流水线设计图
节点	Node	执行具体工作的单元（Graph API 概念）	流水线上的一个工位
任务	Task	执行具体工作的单元（Functional API 概念，@task 装饰）	流水线上的一个工位
边	Edge	定义节点之间的连接关系	工位之间的传送带
状态	State	在工作流中传递和累积的数据	订单信息表
入口	Entrypoint	工作流的起始点（@entrypoint 装饰）	流水线的接单台
检查点	Checkpoint	工作流执行状态的快照	游戏存档
工具	Tool	LLM 可以调用的外部函数	工人手中的工具
人在环	Human-in-the-loop	在关键节点暂停等待人类决策	质检员签字确认
子图	Subgraph	嵌套在父图中的独立子工作流	工厂中的独立生产线
流式	Streaming	实时返回执行过程中的中间结果	实时监控大屏

1.3 实战：旅行规划助手 v0.0 — 环境准备

在本章我们不会写代码，而是先把「旅行规划助手」这个项目想清楚，并准备好开发环境。

1.3.1 项目全景图

我们的「旅行规划助手」将从一个极简的「问答机器人」开始，逐步迭代为一个功能完整的多 Agent 系统：

v0.1: 简单问答 —— 用户问「我想去东京玩3天」，LLM 回复一个行程建议
v0.2: 结构化输入 —— 增加目的地、天数、预算等结构化字段
v0.3: 多步骤推理 —— 分析需求 → 生成行程 → 格式化输出
v0.4: 工具调用 —— 接入模拟的机票、酒店、天气 API
v0.5: 对话记忆 —— 支持多轮对话和上下文记忆
v0.6: 用户确认 —— 生成行程后暂停让用户审阅和修改
v0.7: 并行查询 —— 同时查询机票、酒店、天气，提升响应速度
v0.8: 多 Agent 协作 —— 规划师、预订员、客服三个 Agent 协同工作
v0.9: 生产部署 —— 添加错误处理、监控、流式响应

1.3.2 安装环境

在开始之前，请确保你的 Python 版本 >= 3.10：

# 检查 Python 版本
python --version  # 应该显示 Python 3.10 或更高
# 安装核心依赖
pip install langgraph langchain langchain-openai --break-system-packages
# 可选：安装其他模型提供商（根据你使用的模型选择）
# pip install langchain-anthropic  # Claude
# pip install langchain-google-genai  # Gemini

1.3.3 配置 API Key

在终端中设置环境变量（以 OpenAI 为例）：

# macOS / Linux
export OPENAI_API_KEY="your-api-key-here"
# Windows (CMD)
set OPENAI_API_KEY=your-api-key-here
# Windows (PowerShell)
$env:OPENAI_API_KEY="your-api-key-here"

建议将 API Key 写入 ~/.bashrc 或 ~/.zshrc 文件中，避免每次都要重新设置：

echo 'export OPENAI_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

如果你使用的是其他模型提供商（如 DeepSeek、Claude、Gemini），本教程中所有代码都可以轻松替换，只需修改模型初始化部分。我们将在第 2 章详细说明。

1.4 API 速查

API	类型	说明	导入路径
@entrypoint()	装饰器	将函数标记为工作流的入口点	from langgraph.func import entrypoint
@task	装饰器	将函数标记为工作流中的独立任务单元	from langgraph.func import task
.invoke(input)	方法	同步执行工作流，传入输入，返回结果	调用 entrypoint 编译后的实例
.ainvoke(input)	方法	异步执行工作流	调用 entrypoint 编译后的实例
.stream(input)	方法	同步流式执行，逐步返回中间结果	调用 entrypoint 编译后的实例
.astream(input)	方法	异步流式执行	调用 entrypoint 编译后的实例

1.5 常见错误与避坑指南

错误 1：混淆 LangGraph 和 LangChain

症状：新手经常问「LangGraph 是 LangChain 的升级版吗？」「我学了 LangGraph 还需要学 LangChain 吗？」

原因：两者名字相似，且 LangGraph 由 LangChain 团队开发，容易被混淆。

解决方案：记住这个关系——LangChain 提供「零件」（模型调用、工具、提示模板），LangGraph 提供「组装方案」（工作流编排、状态管理、持久化）。在实际项目中，两者通常一起使用：用 LangChain 定义模型和工具，用 LangGraph 编排工作流。

错误 2：以为 Functional API 功能不如 Graph API

症状：认为 Functional API 只是「简化版」，复杂场景必须用 Graph API。

原因：Functional API 写法更简洁，给人「功能简单」的错觉。

解决方案：Functional API 和 Graph API 共享同一运行时（Pregel —— Google 论文中提出的图计算框架，LangGraph 用它作为底层调度引擎），功能上完全等价。Functional API 只是用 Python 原生控制流代替了显式的图定义。你可以在 Functional API 中实现任何 Graph API 能做的事情——条件分支、循环、并行、子图、人在环等。唯一的区别是检查点粒度：Functional API 按 entrypoint 执行生成检查点，Graph API 按每个超步（superstep，即图中每个节点的单次执行）生成。

错误 3：忽视 Python 版本要求

症状：在 Python 3.9 环境下安装 LangGraph 失败或出现奇怪的错误。

原因：LangGraph v1.0+ 要求 Python 3.10+（3.9 已于 2025 年 10 月 EOL）。

解决方案：升级到 Python 3.10 或更高版本。可以使用 pyenv 管理多个 Python 版本：

# 安装 pyenv
curl https://pyenv.run | bash
# 安装 Python 3.11
pyenv install 3.11
# 在项目目录中设置
pyenv local 3.11

1.6 最佳实践总结

1. 先理解概念，再写代码：在动手之前，花时间理解 Graph、State、Task、Entrypoint 这些核心概念。它们是你后续学习的基础，就像学数学前先理解「加减乘除」一样。
2. Functional API 优先：对于大多数场景，Functional API 是更好的选择——代码更简洁、学习曲线更低、调试更方便。只有在需要时间旅行（Time Travel）或更细粒度的检查点控制时，才考虑 Graph API。
3. LangGraph + LangChain 配合使用：不要试图用纯 LangGraph 替代 LangChain。LangChain 提供的模型抽象、工具定义、提示模板等基础设施，与 LangGraph 的工作流编排能力是互补的。
4. 保持 Python 环境干净：使用 venv 或 conda 创建独立的虚拟环境，避免依赖冲突。LangGraph 的依赖链较长，隔离环境可以省去很多麻烦。
5. 从简单开始，逐步迭代：不要试图一次性构建复杂的 Agent。从最简单的「Hello World」开始（第 2 章），每章加入一个新能力，逐步构建。这正是我们本教程的设计思路。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传优快云，朋友们如果需要可以微信扫描下方优快云官方认证二维码免费领取【保证100%免费】