阿Q技术站

深浅色

LangGraph 手册 ​

基于 LangGraph 1.2.x 的工程手册：状态图、持久化、HITL、多智能体与三个实战项目。

写在前面 ​

LangGraph 是 LangChain 生态中的低层有状态工作流编排框架（Stateful Workflow Orchestration Framework）。其核心能力聚焦于四项：循环（Loop）、状态（State）、持久化（Persistence）与中断（Interrupt）。与高层 Agent 封装不同，LangGraph 将图结构（Graph）、节点（Node）、边（Edge）与通道（Channel）作为一等公民暴露给开发者，允许以显式方式构建包含条件分支、并行扇出、子图嵌套与人工介入（Human-in-the-Loop，HITL）的长运行 LLM 应用。

本手册面向具备 Python 基础、准备将大语言模型（Large Language Model，LLM）应用投入生产的工程师。读者无需预先掌握 LangChain 全部组件，但应对 ChatModel、Tool、Prompt 等基础抽象有初步了解。

手册按以下逻辑编排：第一至第十章覆盖基础概念与核心抽象，包括状态图构建、节点与边、通道与 reducer；第十一至第二十章展开进阶能力，覆盖流式输出、持久化检查点、HITL 中断、子图、错误处理与并行调度；第二十一至第二十五章面向工程化，包括国产模型适配、多智能体模式、MCP（Model Context Protocol，模型上下文协议）集成与可观测性；第二十六至第三十章提供实战案例；第三十一章至第三十三章与附录构成参考部分。

本手册基于 LangGraph 1.2.x（2026 年稳定版）编写，兼容 Python ≥ 3.9。API 行为以该版本为准，早期 0.2.x 版本的差异已在第 31 章迁移指南中列出。

代码约定如下：所有示例代码采用 OpenAI 风格接口（ChatOpenAI）作为默认模型调用方式，国产模型（如通义千问、文心、DeepSeek 等）的适配方式参见第二十一章；示例中"# ..."表示省略与当前讲解无关的重复代码或样板配置，不影响核心逻辑理解；import 语句在首次出现后默认省略，除非引入新的模块。

阅读建议：建议按章节顺序阅读，每章示例代码应至少独立运行一次，以验证本地环境与依赖版本；进阶能力章节可在基础部分掌握后按项目需求选择性精读，无需一次读完所有章节。遇到 API 行为与手册描述不一致时，以对应版本的官方 Release Notes 为准。

目录 ​

基础 ​

能力 ​

进阶 ​

工程 ​

实战 ​

附录 ​