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

前言为什么你需要这本教程在 AI 大模型时代调用一个 LLM大语言模型Large Language Model已经非常容易。但真正的挑战在于如何构建一个能自主决策、多步推理、调用外部工具、与人类协作的智能 AgentLangGraph 就是为这个问题而生的。它由 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 框架。它的核心价值在于有状态Stateful与简单的「请求-响应」模式不同LangGraph 的 Agent 可以记住之前的对话上下文、中间推理步骤、工具调用结果多步骤Multi-stepAgent 不是一次性输出答案而是像人类一样经过多步推理、调用工具、验证结果最终得出结论可控流程Controllable Flow你可以精确控制 Agent 的执行路径——什么时候调用 LLM、什么时候调用工具、什么时候暂停等待人类输入一个直观的例子用户问「我下周去东京帮我规划一下行程」。一个 LangGraph Agent 的处理流程是用户输入 → 分析需求提取目的地、时间、预算→ 查询天气 → 查询机票 → 查询酒店 → 综合生成行程 → 展示给用户确认 → 根据反馈修改 → 最终输出每一步都是一个独立的Task任务数据在它们之间流转LangGraph 负责协调整个过程。1.2.3 LangGraph vs LangChain vs 直接调用 LLM很多初学者会混淆这三者的关系。下面用一个表格清晰地说明维度直接调用 LLMLangChainLangGraph本质单次请求-响应工具链和抽象层有状态工作流编排引擎能做什么一问一答链式调用、工具调用、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 APIGraph API控制流写法标准 Pythonif/for/while显式定义节点和边学习曲线低Python 程序员零门槛中需要理解图的概念可见性运行时可观测编译时可视化图结构检查点粒度每个 entrypoint 执行后每个超步superstep后适合场景快速原型、简单到中等复杂度需要精确控制、可视化、时间旅行状态声明无需显式声明必须声明 State 和 Reducer本教程选择 Functional API 的原因使用标准 Python 语法学习成本最低代码更简洁可读性更好适合大多数实际场景是 LangGraph 团队主推的发展方向当需要更细粒度的检查点或时间旅行等高级功能时可以轻松切换到 Graph API两者共享同一运行时可以混合使用。1.2.5 LangGraph 工作原理Mermaid 图下面这张图展示了 LangGraph 的核心工作原理图中每个元素的含义Entrypoint入口用户请求的入口类似工厂的「接单台」。它负责接收输入、启动工作流、返回最终结果Task任务工作流中的独立执行单元每个 Task 完成一个具体的工作如调用 LLM、查询数据库、调用 API条件判断使用 Python 原生的if/else控制流程走向决定下一步执行哪个 TaskCheckpoint检查点自动保存工作流执行状态就像游戏存档。如果流程中断或需要多轮对话可以从检查点恢复工具调用循环Task 调用 LLM → LLM 决定需要工具 → Task 执行工具 → 结果返回给 LLM → LLM 决定是否需要更多工具如此循环直到 LLM 认为任务完成1.2.6 关键术语速查表术语英文含义类比图Graph描述工作流整体结构的「蓝图」工厂流水线设计图节点Node执行具体工作的单元Graph API 概念流水线上的一个工位任务Task执行具体工作的单元Functional API 概念task装饰流水线上的一个工位边Edge定义节点之间的连接关系工位之间的传送带状态State在工作流中传递和累积的数据订单信息表入口Entrypoint工作流的起始点entrypoint装饰流水线的接单台检查点Checkpoint工作流执行状态的快照游戏存档工具ToolLLM 可以调用的外部函数工人手中的工具人在环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 # Gemini1.3.3 配置 API Key在终端中设置环境变量以 OpenAI 为例# macOS / Linux export OPENAI_API_KEYyour-api-key-here # Windows (CMD) set OPENAI_API_KEYyour-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEYyour-api-key-here建议将 API Key 写入~/.bashrc或~/.zshrc文件中避免每次都要重新设置echo export OPENAI_API_KEYyour-api-key-here ~/.bashrc source ~/.bashrc如果你使用的是其他模型提供商如 DeepSeek、Claude、Gemini本教程中所有代码都可以轻松替换只需修改模型初始化部分。我们将在第 2 章详细说明。1.4 API 速查API类型说明导入路径entrypoint()装饰器将函数标记为工作流的入口点from langgraph.func import entrypointtask装饰器将函数标记为工作流中的独立任务单元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.103.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.111.6 最佳实践总结先理解概念再写代码在动手之前花时间理解 Graph、State、Task、Entrypoint 这些核心概念。它们是你后续学习的基础就像学数学前先理解「加减乘除」一样。Functional API 优先对于大多数场景Functional API 是更好的选择——代码更简洁、学习曲线更低、调试更方便。只有在需要时间旅行Time Travel或更细粒度的检查点控制时才考虑 Graph API。LangGraph LangChain 配合使用不要试图用纯 LangGraph 替代 LangChain。LangChain 提供的模型抽象、工具定义、提示模板等基础设施与 LangGraph 的工作流编排能力是互补的。保持 Python 环境干净使用venv或conda创建独立的虚拟环境避免依赖冲突。LangGraph 的依赖链较长隔离环境可以省去很多麻烦。从简单开始逐步迭代不要试图一次性构建复杂的 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 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】