LangGraph 入门与编排设计

如果把 LLM 应用分成“模型能力”和“系统执行”两部分，那么 LangGraph 主要解决的是后者。

它不是一个“帮你一句话变出完整 Agent”的黑盒框架，而是一个更靠近运行时和执行控制层的框架：你需要自己定义状态、节点、边、分支和暂停恢复机制，然后把一个复杂任务组织成可运行、可中断、可恢复、可观察的图。

本文基于 LangGraph 官方文档，重点回答 8 个问题：

LangGraph 是什么
为什么它被称为 low-level orchestration framework
它适合什么问题
它不适合什么问题
它和 LangChain 的边界是什么
什么是 stateful agent、durable execution、HITL、workflows
一个最小 graph 长什么样
它和本专题现有章节怎么对应

1. LangGraph 是什么

根据官方文档，LangGraph 的定位可以概括成一句话：

它是一个用于构建、管理和部署 long-running、stateful agents 的 low-level orchestration framework 和 runtime。

把这句话拆开看，会更容易理解。

1.1 `graph`

LangGraph 用图来描述执行流程：

node 表示一个执行步骤
edge 表示从一个步骤流向下一个步骤
state 表示在步骤之间流动和累积的数据
START / END 表示起点和终点

所以它的核心思路不是“写一个 while 循环让 Agent 自己跑”，而是：

把系统的执行结构显式画出来。

1.2 `stateful`

官方文档强调 stateful agents，意思不是“只是有聊天历史”，而是：

系统运行中有明确状态
状态可以在节点之间传递
状态可以被持久化
中断后可以从已有状态继续

这也是它和很多“一次调用一个 prompt”的封装最大的区别。

1.3 `long-running`

很多真实任务不是一次模型调用就结束。

比如：

多轮检索和分析
长链路审批
需要人工确认的执行任务
跑到一半会失败、超时或等待外部输入的任务

LangGraph 的设计目标之一，就是让这类任务不是“断了就重来”，而是可以保留进度、继续往下跑。

2. 为什么它是 low-level orchestration framework

官方文档反复强调：LangGraph 很 low-level，并且“focused entirely on agent orchestration”。

这里的 low-level 不是说它底层到很难用，而是说：

它主要提供编排能力，而不是替你决定上层 Agent 应该长什么样。

你通常需要自己决定：

状态结构如何定义
有哪些节点
节点之间怎么连接
哪些条件下分支
哪里需要暂停
什么情况下恢复
是否把某一步做成固定 workflow，还是交给模型动态决策

从工程层看，LangGraph 更接近：

一个“可编程执行图 runtime”
一个“多步状态机 + 持久化 + 中断恢复”的框架

而不是：

一个默认帮你封装好全部 Agent 行为的高层产品

2.1 它解决的是“编排”，不是“提示词抽象”

官方文档明确提到：LangGraph 不负责抽象 prompts 或 architecture。

所以它更关心的是：

步骤怎么跑
状态怎么流
出错后怎么续
人怎么插手
执行路径怎么观察和调试

而不是：

帮你自动生成一套标准 prompt
帮你默认选一个唯一正确的 Agent 结构

2.2 这种 low-level 设计为什么重要

当系统开始变复杂时，你真正难的往往不是“再调用一次模型”，而是这些问题：

现在做到哪一步了
哪一步成功了，哪一步失败了
失败后能不能不要整条链路重跑
某个动作执行前要不要人工审批
一个任务是否应该拆成若干 worker 并行执行
某些步骤是否必须固定，某些步骤是否允许模型自由决策

这些都属于 orchestration 问题。

LangGraph 的价值就在于：

它把复杂 Agent 系统真正难管的“执行控制层”抽出来，变成一个显式工程对象。

3. LangGraph 适合什么问题

如果任务开始出现下面这些特征，LangGraph 往往就值得考虑。

3.1 适合长链路、多步骤、需要状态累积的问题

比如：

调研 -> 检索 -> 交叉验证 -> 生成报告
读取工单 -> 路由 -> 调多个内部系统 -> 汇总处理结果
用户提出目标 -> Planner 拆解任务 -> Worker 执行 -> 汇总交付

这类任务的共同点是：

不是一次调用结束
中间结果很重要
后续步骤依赖前面步骤的状态

3.2 适合“部分固定、部分动态”的系统

这是 LangGraph 特别擅长的点。

现实系统往往不是纯 workflow，也不是纯自由 Agent，而是混合态：

主流程是固定的
某几个节点里允许模型做动态决策
遇到高风险动作时要人工确认
某些步骤可以并行

官方文档也强调它适合构建 a combination of deterministic and agentic workflows。

3.3 适合需要中断、恢复、人工介入的问题

比如：

发邮件前让人审批
删除数据前让人确认
需要等待用户补材料再继续
外部服务失败后稍后恢复

这类场景如果没有持久化和恢复机制，系统会很脆弱。

而 LangGraph 把这类能力做成了一等公民。

3.4 适合想真正掌控执行路径的时候

如果已经发现：

高层 Agent 封装不够透明
默认循环不好调试
很难插入自己的控制逻辑
很难解释“为什么系统走了这条路”

那 LangGraph 的显式图结构就很有帮助。

4. LangGraph 不太适合什么问题

不是所有 LLM 应用都值得一上来就用 LangGraph。

4.1 不适合非常简单的单步应用

如果只是：

单轮问答
简单摘要
单次分类
固定 prompt + 固定工具调用

那直接用更轻的调用层通常更合适。

4.2 不适合“我还没搞清楚任务结构”的早期阶段

LangGraph 的强项是显式建模。

但如果连下面这些都还不清楚：

系统到底有哪些步骤
哪些状态值得保留
哪些地方必须可控
哪些动作需要人工审查

那太早进入 graph 设计，反而会增加建模负担。

4.3 不适合只想“尽快跑一个默认 Agent”的场景

官方文档的判断很明确：

如果是刚开始做 Agent
或者更想要高层抽象

那么优先考虑 LangChain 提供的预构建 Agent 架构会更合适。

LangGraph 更适合需要主动掌控执行系统的场景，不适合把它当成最快起步的现成 Agent 封装。

5. LangGraph 和 LangChain 的边界

这是最容易混淆的部分之一。

两者可以先作如下区分：

LangChain 更偏上层开发框架与预构建 Agent 抽象
LangGraph 更偏底层编排 runtime

5.1 LangChain 偏“上层应用开发层”

根据官方文档，LangChain 提供：

模型集成
工具集成
预构建 Agent 架构
更快的上手路径

如果目标是：

快速做一个可用 Agent
用比较少的代码先验证产品
优先用成熟默认架构

那通常先从 LangChain 出发更顺手。

5.2 LangGraph 偏“执行控制层”

而 LangGraph 负责的是：

durable execution
persistence
streaming
human-in-the-loop
显式 workflow / graph orchestration

官方文档也明确说，LangChain 的 agents 是建立在 LangGraph 之上的，因此才能获得持久化、流式输出、人工介入等能力。

5.3 两者不是对立关系

很多人会误以为二选一，其实不是。

更准确的理解是：

可以只用 LangGraph
也可以在 LangGraph 里使用 LangChain 的模型和工具组件
还可以直接用基于 LangGraph 能力构建的 LangChain agents

所以边界不是“谁替代谁”，而是：

LangChain 解决“更快搭建应用和 Agent”
LangGraph 解决“更强执行控制和编排”

5.4 一个简单选型判断

可以先这样判断：

只想快速做出一个可用 Agent：先看 LangChain
需要混合 deterministic workflow 和 agentic decision：看 LangGraph
需要暂停、恢复、人工审批、长期运行：优先看 LangGraph
已经被默认 Agent 抽象卡住：下沉到 LangGraph

6. 关键能力：stateful agent / durable execution / HITL / workflows

这几个词几乎构成了 LangGraph 的核心理解框架。

6.1 Stateful Agent

在 LangGraph 里，状态不是附属品，而是执行主轴。

官方文档里，graph 会围绕 state 运转：

节点读取状态
节点返回状态更新
runtime 合并状态
后续节点继续基于新状态运行

因此一个 Agent 系统可以显式保留：

对话消息
当前任务进度
已完成步骤
工具结果
决策痕迹
中间产物

从工程角度看，stateful 的价值在于：

系统不是“每一步都重新猜上下文”，而是在操作一个持续演化的执行状态。

6.2 Durable Execution

官方文档对 durable execution 的解释很清楚：

在关键点保存进度
允许流程暂停
之后能从原位置继续
不需要重做已完成步骤

在 LangGraph 里，这通常通过 checkpointer 和 persistence 实现。

官方文档里的几个关键概念是：

checkpoint：每一步执行后的状态快照
thread：某次连续执行的状态轨迹
thread_id：恢复同一条执行线程的关键标识

所以可以把它理解成：

LangGraph 不是只在“跑逻辑”，而是在持续记录“这条逻辑已经跑到哪里”。

6.3 HITL

HITL 就是 Human-in-the-Loop。

在 LangGraph 官方文档里，这通常通过 interrupt 机制实现：

graph 跑到某一步先暂停
把当前等待的信息或待审批动作抛给外部
人做出批准、修改或拒绝
再用相同 thread_id 恢复执行

这类设计放在高风险动作里会更稳一些，比如：

发邮件
删除记录
执行交易
改写线上配置

LangGraph 的价值不只是“能暂停”，而是：

暂停时状态是持久化的，所以人工审批不是临时打断，而是系统级可恢复流程的一部分。

6.4 Workflows

官方文档区分得很明确：

workflows 是预定义代码路径
agents 是动态决定过程和工具使用

这很重要，因为 LangGraph 并不只适合“自由 Agent”。

它同样适合构建：

prompt chaining
parallelization
routing
orchestrator-worker
evaluator-optimizer

LangGraph 处理的不只是 Agent loop，而是把 workflow 和 agent 放进同一个图式执行模型里。

7. 一个最小 graph 风格示意

先看最小结构：

START
  |
  v
llm_node
  |
  v
 END

这表示：

从 START 开始
执行一个节点 llm_node
然后到 END

再看一个非常接近官方文档的最小 Python 风格示意：

from langgraph.graph import StateGraph, MessagesState, START, END


def mock_llm(state: MessagesState):
    return {
        "messages": [
            {"role": "ai", "content": "hello world"}
        ]
    }


graph = StateGraph(MessagesState)
graph.add_node("mock_llm", mock_llm)
graph.add_edge(START, "mock_llm")
graph.add_edge("mock_llm", END)
compiled = graph.compile()

compiled.invoke({
    "messages": [{"role": "user", "content": "hi"}]
})

这个最小例子里已经有 LangGraph 的几个核心要素：

有 state
有 node
有 edge
有 compile
有一次完整的图执行

如果再往前走一步，典型扩展通常就是：

START
  |
  v
planner -----> human_review?
  |                |
  | no             | yes
  v                v
worker --------> resume
  |
  v
 END

这里就开始出现 LangGraph 真正擅长的东西：

分支
人工介入
恢复执行
多节点状态流转

8. 和本专题现有章节怎么对应

如果把本专题已有内容看成一张地图，LangGraph 这一篇就是“框架层与执行编排层”的补充入口。

可以这样对应：

8.1 和 `Workflow vs Agent` 的关系

对应文件：AI/agent-engineering/Workflow-vs-Agent.md

那一篇回答的是：

什么是 workflow
什么是 agent
两者什么时候分别更合适

而这一篇回答的是：

当你需要把 workflow 和 agent 都落成可执行系统时，LangGraph 怎么提供图式编排能力

可以理解为：

Workflow vs Agent 讲概念边界
LangGraph 讲如何承载这两类执行模式

8.2 和 `Agent Memory and State` 的关系

对应文件：AI/agent-engineering/Agent-Memory-and-State.md

那一篇重点在：

state 和 memory 的概念区分
系统里到底该记什么

而 LangGraph 官方能力里，stateful agent、persistence、thread、checkpoint 则是把这些概念落到运行时机制里。

可以理解为：

Agent Memory and State 讲“为什么要有状态”
LangGraph 讲“状态如何成为执行系统的一部分”

8.3 和 `Guardrails and Human-in-the-Loop` 的关系

对应文件：AI/agent-engineering/Guardrails-and-Human-in-the-Loop.md

那一篇更偏：

为什么要让人介入
哪些动作需要 guardrails

而 LangGraph 则提供了更贴近 runtime 的 interrupt + resume + persistence 机制。

可以理解为：

Guardrails / HITL 讲策略和治理
LangGraph 讲实现这些策略的底层执行能力

8.4 和 `AI Agent 技术栈与框架对比` 的关系

对应文件：AI/overview/AI-Agent-Tech-Stack-and-Framework-Comparison.md

那一篇在更高层讨论：

技术栈怎么分层
什么阶段该选什么框架

而这篇文档是在其中把 LangGraph 单独展开：

它到底在哪一层
它解决什么问题
什么时候值得用它

8.5 和后续模板类文档的关系

像这些文档：

AI/agent-engineering/Minimal-Agent-TypeScript-Template.md
AI/agent-engineering/Tool-Using-Agent-TypeScript-Template.md
AI/agent-engineering/Research-Agent-TypeScript-Template.md

更偏“一个 Agent 最后怎么写成代码骨架”。

而 LangGraph 这一篇的作用是：

在你决定写哪种模板之前，先帮你判断是否需要 graph 化编排。

9. 一个实用判断：什么时候该学 LangGraph

如果已经开始遇到下面这些问题，就该认真看 LangGraph 了：

默认 Agent 循环不够透明
任务不是单步，而是多步有状态执行
某些步骤需要人工审批
失败后不能整条链路重跑
需要把 workflow 和 agent 混合在一起
需要更强的调试和运行态可见性

如果还处在这些阶段，反而可以先放一放：

还在学基本 prompt / tool calling
只做简单单轮应用
还没有多步骤状态管理需求
只是想最快做出一个 demo

10. 小结

可以把 LangGraph 先记成一句话：

它不是帮你“自动变出 Agent”的框架，而是帮你“把复杂 Agent / workflow 组织成可持续运行、可中断恢复、可人工介入的执行图”的框架。

所以它真正解决的问题不是“怎么再多调一次模型”，而是：

复杂执行路径怎么表达
状态怎么保存和流动
失败后怎么恢复
人怎么在关键节点接管
workflow 和 agent 怎么放进同一个运行时里

如果系统已经开始进入这些问题域，LangGraph 往往就不是“可选优化项”，而会逐渐变成核心基础设施。

参考资料

以下为本篇主要参考的 LangChain / LangGraph 官方文档：

LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
Workflows and agents: https://docs.langchain.com/oss/python/langgraph/workflows-agents
Persistence: https://docs.langchain.com/oss/python/langgraph/persistence
Interrupts / Human-in-the-loop: https://docs.langchain.com/oss/python/langgraph/human-in-the-loop
LangChain overview: https://docs.langchain.com/oss/python/langchain/overview

1. LangGraph 是什么​

1.1 graph​

1.2 stateful​

1.3 long-running​

2. 为什么它是 low-level orchestration framework​

2.1 它解决的是“编排”，不是“提示词抽象”​

2.2 这种 low-level 设计为什么重要​

3. LangGraph 适合什么问题​

3.1 适合长链路、多步骤、需要状态累积的问题​

3.2 适合“部分固定、部分动态”的系统​

3.3 适合需要中断、恢复、人工介入的问题​

3.4 适合想真正掌控执行路径的时候​

4. LangGraph 不太适合什么问题​

4.1 不适合非常简单的单步应用​

4.2 不适合“我还没搞清楚任务结构”的早期阶段​

4.3 不适合只想“尽快跑一个默认 Agent”的场景​

5. LangGraph 和 LangChain 的边界​

5.1 LangChain 偏“上层应用开发层”​

5.2 LangGraph 偏“执行控制层”​

5.3 两者不是对立关系​

5.4 一个简单选型判断​

6. 关键能力：stateful agent / durable execution / HITL / workflows​

6.1 Stateful Agent​

6.2 Durable Execution​

6.3 HITL​

6.4 Workflows​

7. 一个最小 graph 风格示意​

8. 和本专题现有章节怎么对应​

8.1 和 Workflow vs Agent 的关系​

8.2 和 Agent Memory and State 的关系​

8.3 和 Guardrails and Human-in-the-Loop 的关系​

8.4 和 AI Agent 技术栈与框架对比 的关系​

8.5 和后续模板类文档的关系​

9. 一个实用判断：什么时候该学 LangGraph​

10. 小结​

参考资料​

1. LangGraph 是什么

1.1 `graph`

1.2 `stateful`

1.3 `long-running`

2. 为什么它是 low-level orchestration framework

2.1 它解决的是“编排”，不是“提示词抽象”

2.2 这种 low-level 设计为什么重要

3. LangGraph 适合什么问题

3.1 适合长链路、多步骤、需要状态累积的问题

3.2 适合“部分固定、部分动态”的系统

3.3 适合需要中断、恢复、人工介入的问题

3.4 适合想真正掌控执行路径的时候

4. LangGraph 不太适合什么问题

4.1 不适合非常简单的单步应用

4.2 不适合“我还没搞清楚任务结构”的早期阶段

4.3 不适合只想“尽快跑一个默认 Agent”的场景

5. LangGraph 和 LangChain 的边界

5.1 LangChain 偏“上层应用开发层”

5.2 LangGraph 偏“执行控制层”

5.3 两者不是对立关系

5.4 一个简单选型判断

6. 关键能力：stateful agent / durable execution / HITL / workflows

6.1 Stateful Agent

6.2 Durable Execution

6.3 HITL

6.4 Workflows

7. 一个最小 graph 风格示意

8. 和本专题现有章节怎么对应

8.1 和 `Workflow vs Agent` 的关系

8.2 和 `Agent Memory and State` 的关系

8.3 和 `Guardrails and Human-in-the-Loop` 的关系

8.4 和 `AI Agent 技术栈与框架对比` 的关系

8.5 和后续模板类文档的关系

9. 一个实用判断：什么时候该学 LangGraph

10. 小结

参考资料