第 1 章 导论：Agent 范式、框架定位与生态
1.1 从单次 LLM 调用到 Agent 范式
大语言模型的基础调用形态是一次性的请求-响应：输入一段提示词，模型返回一段文本。这种模式适用于翻译、摘要、改写等单轮任务，但在需要与外部环境交互、多步推理、根据反馈调整策略的场景中存在天然局限。ReAct（Reasoning + Acting）范式将"观察（Observe）—思考（Think）—行动（Act）"组织为一个循环：模型先根据当前状态产生思考，再选择并执行一个动作（调用工具、读取数据等），获得观察结果后再次进入思考，直到任务完成。
在工程落地中，直接使用 while True 手写循环存在若干不可控因素：循环边界与终止条件散落在业务代码中，难以做统一的超时与递归深度控制；中间状态没有结构化承载，跨步骤的上下文依赖容易出错；缺少可持久化的快照点，进程崩溃后无法从中断处恢复；人类介入（Human-in-the-Loop, HITL）没有一等公民支持，必须在循环内部插入阻塞等待；并发节点、并行工具调用等需求需要手动写 asyncio 调度。这些问题共同催生了专门的 Agent 编排框架。
1.2 Agent 编排框架的分类
当前主流的 Agent 编排框架可以按抽象方式划分为四类。
DAG（有向无环图）框架将工作流建模为节点与有向边组成的无环图，代表是 LangChain Expression Language（LCEL）、LlamaIndex Query Pipelines 早期版本。其优势是执行路径可预测、易于流式与追踪，劣势是无法表达循环，多轮推理需要在外层再套循环。
状态机框架以显式的状态（State）和节点间的转移为核心，天然支持循环与条件跳转，代表是 LangGraph 与 LlamaIndex Workflows。状态机框架在图层面提供持久化、中断与恢复能力，是工程化 Agent 的主流方向。
对话式框架以多轮对话的 turn 为基本调度单位，将 Agent 视为一个可以持续接收消息的对话参与者，代表是 AutoGen 的早期 ConversableAgent。该模型在多角色聊天场景下直观，但对非对话形态的工作流（如批处理、数据流水线）表达力较弱。
角色驱动框架以 Agent 的角色、目标、分工为抽象单元，关注"谁来做"而非"执行到哪一步"，代表是 CrewAI。该类框架在多智能体协作的叙事层表达力强，但底层控制粒度较粗，对精确状态管理与中断恢复的支持相对有限。
1.3 LangGraph 的定位
LangGraph 被定位为一个低级别（low-level）编排运行时：它不提供高层的 Agent 角色模板，而是提供一套最小但完备的图执行原语——节点（Node）、边（Edge）、状态（State）、通道（Channel）、检查点（Checkpoint）、中断（Interrupt），让使用者以有向图的方式建模任意循环工作流。
其执行模型基于 Google Pregel 论文提出的 BSP（Bulk Synchronous Parallel，整体同步并行）模型，将一次图执行拆分为若干个"超步（Superstep）"：每个超步内选中的节点并发执行，执行完毕后在屏障处同步，将写入合并到状态中再进入下一个超步。基于该模型，LangGraph 提供四项核心能力：
- 状态（State）：通过类型化 Schema 声明全局共享状态，并通过 reducer 规则声明字段的合并语义；
- 循环（Cycles）：边可以回指到已执行过的节点，天然支持 ReAct 循环、反思循环等；
- 持久化（Persistence）：每个超步结束后自动写入 Checkpoint，支持断点续跑、时间旅行调试；
- 中断（Interrupt）：在超步边界挂起执行，等待人类或外部系统输入后恢复，用于审批、补充信息等 HITL 场景。
LangGraph 与 LangChain 的关系需要明确区分。LangChain 是组件库，提供模型封装、提示词模板、工具、Retriever 等可复用积木；LangGraph 是编排运行时，负责把这些（或其他任意）积木组装成可循环、可持久化、可中断的工作流。LangGraph 可以独立使用，节点函数可以直接写原生 Python，不强制依赖 LangChain；但在接入模型与工具时，复用 LangChain 的组件生态可以显著降低样板代码量。
适用场景与不适用场景对比如下：
| 维度 | 适用 | 不适用 |
|---|---|---|
| 流程长度 | 长流程、多步骤、含循环的工作流（如研究助手、代码生成-执行-修复） | 单次问答、简单 RAG、一进一出的模型调用 |
| 人类介入 | 需要审批、确认、补充信息的业务流程 | 完全自动化、无人值守的短链路任务 |
| 协作模式 | 多智能体协作、Supervisor-Worker 分工 | 单一模型调用即可完成的任务 |
| 可靠性要求 | 需要断点续跑、故障恢复、状态可审计的生产流程 | 一次性脚本、临时原型 |
| 延迟要求 | 秒级到分钟级可接受 | 亚秒级极高并发低延迟场景（BSP 屏障同步会引入固定开销） |
1.4 生态全景与版本
LangGraph 生态由以下包与服务构成：
- langgraph：主包，提供 StateGraph、Pregel 运行时、Checkpoint 机制、Command 原语等核心能力；
- langgraph-checkpoint-sqlite / postgres / redis：检查点持久化后端，分别基于 SQLite、PostgreSQL、Redis 存储 Superstep 快照；
- langgraph-prebuilt：预构建的常用组件，包括
create_react_agent、ToolNode、ChatPromptTemplate适配层等； - langgraph-cli：命令行工具，提供
langgraph dev（启动 LangGraph Studio 本地调试服务）、langgraph build等命令； - langgraph-sdk：运行时客户端 SDK，用于从外部进程以 HTTP/WebSocket 方式调用部署好的图；
- LangSmith：可观测性平台，提供 trace、评估、prompt 管理，与 LangGraph 深度集成；
- LangGraph Platform / Cloud：托管部署服务，提供长时运行线程、cron 调度、API 网关等生产能力。
版本线方面，LangGraph 于 2024 年 4 月首次公开发布，2026 年 1 月发布 1.0 稳定版本。本手册基于 LangGraph 1.2.x（2026 年稳定版），Python 版本要求 ≥ 3.9，推荐使用 3.11 或 3.12。
1.5 同类框架对比
| 维度 | LangGraph 1.2.x | AutoGen (MAF) 0.4+ | CrewAI | LlamaIndex Workflows | Semantic Kernel |
|---|---|---|---|---|---|
| 抽象层级 | 低级别运行时 | 多 Agent 消息传递 | 角色/任务驱动 | 事件驱动工作流 | 插件/规划器栈 |
| 控制粒度 | 细（节点/边/Channel） | 中（消息/Agent 句柄） | 粗（Task/Agent） | 中（Step/Event） | 中（Kernel/Function） |
| 循环支持 | 原生一等公民 | 通过对话 turn 实现 | 通过 Task 回指 | 通过事件回环支持 | 通过 Plan 迭代支持 |
| 持久化 | Checkpoint 一等公民（SQLite/Postgres/Redis） | 有限 | 需自行实现 | 社区扩展 | 通过 Memory Store |
| HITL | interrupt/resume 原生 | 通过 Human-in-the-loop Agent | Task 级 callback | 事件中断点 | Kernel 事件钩子 |
| 多智能体模式 | Supervisor/Wallet/Map-Reduce 等可自由构图 | 群聊/选择发言者 | 层级/顺序/并行 | EventBus 式 | Planner/Hand-off |
| 部署形态 | Library + Platform/Cloud 自托管 | Library + Studio | Library | Library | Library + Azure |
| 学习曲线 | 中（需理解 BSP/Channel） | 中 | 低 | 中 | 中 |
| 典型场景 | 生产级长流程 Agent、可审计工作流 | 研究型多 Agent 对话 | 原型/演示级多角色协作 | RAG+工作流结合 | .NET/Azure 企业栈 |
本章小结
LangGraph 将 Agent 执行抽象为基于 BSP/Pregel 模型的有向状态图，以显式 State、循环、持久化、中断为核心能力，定位在"编排运行时"而非"Agent 模板库"。它复用 LangChain 的组件生态但不强依赖 LangChain，适合长流程、需要 HITL、多智能体协作与断点续跑的生产场景，不适用于单次问答与极低延迟链路。
常见错误
- 把 LangGraph 当成 LangChain 的一部分。现象：认为必须深度使用 LangChain 的 Chain/Tool 才能写 LangGraph。原因：两个包由同一团队维护，早期文档容易混淆。修复：节点函数可以是任意 Python Callable，LangChain 仅作为可选组件源。
- 在简单任务上过度引入。现象：单次 RAG 问答也画了一张 5 节点图，代码复杂度高于直接调用链。原因：误将框架视为通用替换。修复：对照 1.3 节的适用场景表，短链路优先用 LCEL 或直接调用模型。
- Python 版本不匹配。现象：安装或导入时出现语法错误、类型错误。原因：使用 3.8 或更低版本。修复：升级到 3.11/3.12，并在虚拟环境中锁定解释器。
生产建议
- 项目初始化时即选定 Checkpoint 后端：开发期使用 SQLite，生产期使用 PostgreSQL，并通过环境变量切换；
- 从第一天起接入 LangSmith 采集 trace，便于后续复盘超步耗时与节点异常；
- 长流程业务在图设计阶段就标注 HITL 节点位置，使用 interrupt 而非在节点内阻塞等待输入；
- 选型阶段对照 1.5 节对比表，若团队以 .NET 为主栈可评估 Semantic Kernel，若主要是快速原型且角色分工明确可短期使用 CrewAI，生产级可控编排优先 LangGraph。