【AI Agent】langgraph 深度技术分析报告

langgraph — Deep Technical Due Diligence & Architecture Audit

Repository: https://github.com/langchain-ai/langgraph Project: LangGraph 审计对象： Python/JS Agent orchestration framework 当前源码基线： main，源码中 langgraph package 当前为 1.2.10；仓库最新 GitHub release 页面显示 1.2.9（页面抓取时间差异说明 release/tag 与 main 存在短暂不同步）。(GitHub) 审计结论： ADOPT WITH CONDITIONS 分析日期： 2026-09-02 核心判断：LangGraph 不是 LangChain 的“Agent 模块”，而是一套独立的、以 State + Graph + Pregel-style execution + Checkpoint 为核心的 Agent Runtime。

1. Executive Summary

如果上一份 LangChain 报告的核心结论是：

LangChain = AI Component / Integration Abstraction

那么 LangGraph 的核心结论是：

LangGraph = Stateful Agent Runtime / Durable Orchestration Engine

两者的架构位置不同。

Enterprise AI System
│
┌──────────────────┴──────────────────┐
│ │
Component Layer Runtime Layer
│ │
LangChain Core LangGraph
│ │
┌───────┼────────┐ ┌───────────┼───────────┐
▼ ▼ ▼ ▼ ▼ ▼
Model Tool Retriever State Graph Runtime
│ │ │
▼ ▼ ▼
Checkpoint Pregel Interrupt
│
▼
Memory

因此：

LangChain 解决“AI 组件怎么统一”。

LangGraph 解决“Agent 怎么可靠地运行”。

这是理解 LangGraph 的第一原则。

官方仓库把 LangGraph 定位为：

low-level orchestration framework for building stateful agents

并明确强调 long-running、stateful agents。(GitHub)

2. CTO Verdict

最终决策

ADOPT WITH CONDITIONS

但与 LangChain 的使用方式不同。

推荐程度

3. Project Classification

LangGraph 最准确的分类不是：

Agent Framework

而是：

Stateful Agent Runtime
+
Graph Orchestration Engine
+
Durable Execution Infrastructure

进一步说：

它正在成为 Agent 世界中的“workflow/runtime layer”。

4. Repository Profile

LangGraph 当前是一个 Python + JavaScript/TypeScript monorepo。

官方 AGENTS.md 明确列出了：

libs/
├── checkpoint
├── checkpoint-postgres
├── checkpoint-sqlite
├── cli
├── langgraph
├── prebuilt
├── sdk-js
└── sdk-py

其中：

• checkpoint：checkpoint interface
• checkpoint-postgres：Postgres persistence
• checkpoint-sqlite：SQLite persistence
• langgraph：core stateful multi-actor framework
• prebuilt：high-level Agent / Tool APIs
• sdk-py：Python Agent Server SDK
• sdk-js：JavaScript/TypeScript SDK

官方还给出了明确 dependency map。(GitHub)

5. Repository Architecture Map

真实结构可以抽象为：

langgraph/
│
├── libs/
│ │
│ ├── langgraph/
│ │ └── langgraph/
│ │ ├── graph/
│ │ ├── pregel/
│ │ ├── channels/
│ │ ├── managed/
│ │ ├── checkpoint/
│ │ ├── _internal/
│ │ ├── types.py
│ │ ├── errors.py
│ │ └── …
│ │
│ ├── prebuilt/
│ │ └── langgraph/prebuilt/
│ │ ├── chat_agent_executor.py
│ │ ├── tool_node.py
│ │ ├── tool_validator.py
│ │ └── …
│ │
│ ├── checkpoint/
│ │ └── langgraph/checkpoint/
│ │ ├── base/
│ │ ├── memory/
│ │ └── serde/
│ │
│ ├── checkpoint-postgres/
│ │
│ ├── checkpoint-sqlite/
│ │
│ ├── checkpoint-conformance/
│ │
│ ├── sdk-py/
│ │
│ ├── sdk-js/
│ │
│ └── cli/
│
├── .github/
├── AGENTS.md
└── …

这已经不是一个普通 Python framework，而是一个：

Runtime + Persistence + SDK + CLI + Integration monorepo。

6. Dependency Architecture

官方 dependency map 非常值得研究：

#mermaid-svg-JwdtK5e6muXkay2M{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-JwdtK5e6muXkay2M .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-JwdtK5e6muXkay2M .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-JwdtK5e6muXkay2M .error-icon{fill:#552222;}#mermaid-svg-JwdtK5e6muXkay2M .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-JwdtK5e6muXkay2M .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-JwdtK5e6muXkay2M .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-JwdtK5e6muXkay2M .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-JwdtK5e6muXkay2M .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-JwdtK5e6muXkay2M .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-JwdtK5e6muXkay2M .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-JwdtK5e6muXkay2M .marker{fill:#333333;stroke:#333333;}#mermaid-svg-JwdtK5e6muXkay2M .marker.cross{stroke:#333333;}#mermaid-svg-JwdtK5e6muXkay2M svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-JwdtK5e6muXkay2M p{margin:0;}#mermaid-svg-JwdtK5e6muXkay2M .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-JwdtK5e6muXkay2M .cluster-label text{fill:#333;}#mermaid-svg-JwdtK5e6muXkay2M .cluster-label span{color:#333;}#mermaid-svg-JwdtK5e6muXkay2M .cluster-label span p{background-color:transparent;}#mermaid-svg-JwdtK5e6muXkay2M .label text,#mermaid-svg-JwdtK5e6muXkay2M span{fill:#333;color:#333;}#mermaid-svg-JwdtK5e6muXkay2M .node rect,#mermaid-svg-JwdtK5e6muXkay2M .node circle,#mermaid-svg-JwdtK5e6muXkay2M .node ellipse,#mermaid-svg-JwdtK5e6muXkay2M .node polygon,#mermaid-svg-JwdtK5e6muXkay2M .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-JwdtK5e6muXkay2M .rough-node .label text,#mermaid-svg-JwdtK5e6muXkay2M .node .label text,#mermaid-svg-JwdtK5e6muXkay2M .image-shape .label,#mermaid-svg-JwdtK5e6muXkay2M .icon-shape .label{text-anchor:middle;}#mermaid-svg-JwdtK5e6muXkay2M .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-JwdtK5e6muXkay2M .rough-node .label,#mermaid-svg-JwdtK5e6muXkay2M .node .label,#mermaid-svg-JwdtK5e6muXkay2M .image-shape .label,#mermaid-svg-JwdtK5e6muXkay2M .icon-shape .label{text-align:center;}#mermaid-svg-JwdtK5e6muXkay2M .node.clickable{cursor:pointer;}#mermaid-svg-JwdtK5e6muXkay2M .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-JwdtK5e6muXkay2M .arrowheadPath{fill:#333333;}#mermaid-svg-JwdtK5e6muXkay2M .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-JwdtK5e6muXkay2M .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-JwdtK5e6muXkay2M .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-JwdtK5e6muXkay2M .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-JwdtK5e6muXkay2M .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-JwdtK5e6muXkay2M .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-JwdtK5e6muXkay2M .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-JwdtK5e6muXkay2M .cluster text{fill:#333;}#mermaid-svg-JwdtK5e6muXkay2M .cluster span{color:#333;}#mermaid-svg-JwdtK5e6muXkay2M div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-JwdtK5e6muXkay2M .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-JwdtK5e6muXkay2M rect.text{fill:none;stroke-width:0;}#mermaid-svg-JwdtK5e6muXkay2M .icon-shape,#mermaid-svg-JwdtK5e6muXkay2M .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-JwdtK5e6muXkay2M .icon-shape p,#mermaid-svg-JwdtK5e6muXkay2M .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-JwdtK5e6muXkay2M .icon-shape .label rect,#mermaid-svg-JwdtK5e6muXkay2M .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-JwdtK5e6muXkay2M .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-JwdtK5e6muXkay2M .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-JwdtK5e6muXkay2M :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

langgraph-checkpoint

checkpoint-postgres

checkpoint-sqlite

langgraph-prebuilt

langgraph

sdk-py

cli

sdk-js

(GitHub)

这个结构体现出一个非常重要的设计：

Persistence 被从 Runtime 中抽成独立 protocol/package。

7. Package Dependency

langgraph 当前 pyproject.toml 的核心依赖：

langchain-core >=1.4.7,<2
langgraph-checkpoint >=4.1.0,<5
langgraph-sdk >=0.4.2,<0.5
langgraph-prebuilt >=1.1.0,<1.2
pydantic >=2.7.4
xxhash

并要求 Python >= 3.10。(GitHub)

这里非常值得注意：

LangGraph
│
├── langchain-core
├── checkpoint
├── prebuilt
└── sdk

说明 LangGraph 并不依赖整个 LangChain。

8. Most Important Architectural Principle

LangGraph README 明确指出：

LangGraph can be used without LangChain. (GitHub)

这非常重要。

说明：

LangChain
≠
LangGraph prerequisite

更准确：

AI Application
│
┌────────┴────────┐
▼ ▼
LangChain Core LangGraph
│ │
Components Runtime

这其实说明 LangChain 团队已经把：

Component abstraction

和：

Agent orchestration

进行了架构分离。

9. Core Architecture

LangGraph 的核心不是：

Agent

而是：

State
+
Graph
+
Channels
+
Pregel Execution
+
Checkpoint

这是本次审计最重要的结论。

10. StateGraph

核心源码：

libs/langgraph/langgraph/graph/state.py

源码中明确导入：

Pregel
ChannelRead
PregelNode
ChannelWrite
BranchSpec
StateNode
ManagedValue

说明：

StateGraph 不是简单的 Python DAG。

而是：

Graph Definition
↓
State Schema
↓
Channels
↓
Pregel Runtime

(GitHub)

11. State 是第一等公民

LangGraph 的 State 不是：

dict

那么简单。

它具有：

State
├── Schema
├── Channels
├── Reducers
├── Versions
├── Metadata
└── Persistence

例如官方 quickstart 使用：

class MessagesState(TypedDict):
messages: Annotated[list[AnyMessage], operator.add]
llm_calls: int

这里的：

operator.add

就是 State reducer。

即：

old_state
+
node_update
↓
reducer
↓
new_state

(GitHub)

12. State Update Model

可以抽象为：

Node A
│
│ update
▼
Channel
│
│ reducer
▼
State
│
▼
Checkpoint

这与传统 Agent：

state["messages"].append(...)

有本质区别。

13. Channel Architecture

LangGraph 当前源码中存在：

BaseChannel
BinaryOperatorAggregate
DeltaChannel
EphemeralValue
LastValue
LastValueAfterFinish
NamedBarrierValue

(GitHub)

这实际上构成：

State Dataflow Engine

14. DeltaChannel

这是当前 LangGraph 一个非常值得注意的架构升级。

传统：

Checkpoint
=
Full State Snapshot

长期运行会导致：

State ↑
Checkpoint Size ↑
Storage ↑
Latency ↑

所以现在引入：

DeltaChannel

只存：

incremental delta

而不是每次保存整个累积 state。

官方文档明确说明，DeltaChannel 可以显著减少 append-heavy channel 的 checkpoint size，但目前仍处于 beta。(GitHub)

15. Pregel Architecture

LangGraph 官方明确说明受到：

Pregel 和 Apache Beam

启发。(GitHub)

这不是营销词。

源码真实存在：

langgraph/pregel/

以及：

_pregel/
_loop.py
_read.py
_write.py

等核心执行代码。

(GitHub)

16. What Is Pregel Doing Here?

核心思想：

Graph
↓
Superstep
↓
Execute active nodes
↓
Write updates
↓
Checkpoint
↓
Schedule next nodes
↓
Next superstep

即：

Superstep N
│
┌──────┼──────┐
▼ ▼ ▼
A B C
│ │ │
└──────┼──────┘
▼
State
│
Checkpoint
│
▼
Superstep N+1

17. This Is Not a DAG Engine

普通 DAG：

A → B → C → D

LangGraph：

A
↓
B ─────┐
↓ │
C │
└──→ D ┘

允许：

• cycles
• conditional routing
• parallel execution
• dynamic sends
• interrupts
• resume
• subgraphs

因此更准确：

Stateful cyclic graph runtime

18. Send

源码：

libs/langgraph/langgraph/types.py

Send 支持：

动态向节点发送不同 state。

官方代码明确给出的典型用途：

map-reduce。

(GitHub)

例如：

Input
├── Task A
├── Task B
├── Task C
└── Task D
│
▼
Reduce

这使 LangGraph 不只是：

Agent loop。

它也具备：

Dynamic parallel workflow engine

的特征。

19. Command

Command 是另一个非常重要的原语。

源码支持：

update
resume
goto
graph

(GitHub)

因此：

Node
│
├── update state
├── goto another node
├── send
└── resume interrupted workflow

可以统一表达。

这是一个非常强的 orchestration primitive。

20. Interrupt

LangGraph 的 Human-in-the-loop 不是：

if human:
input()

而是 runtime-level interrupt。

源码明确：

interrupt()

会暂停执行，并由：

Command

恢复。

而且：

使用 interrupt 必须启用 checkpointer。(GitHub)

因此：

Agent
↓
Node
↓
interrupt()
↓
Checkpoint
↓
Human
↓
Command(resume=…)
↓
Resume

21. Critical Detail: Resume Semantics

源码明确说明：

resume 后，node 会从 node 开头重新执行。

(GitHub)

这意味着开发者必须注意：

Node
├── API Call
├── Payment
├── Database Write
└── interrupt()

如果：

interrupt()

发生在副作用之后，那么 resume 时：

副作用可能重新执行。

因此：

Enterprise Requirement

必须保证：

Side Effect
+
Interrupt

之间具有：

• Idempotency
• Transaction boundary
• Outbox
• Deduplication

否则容易造成：

Double charge
Duplicate order
Duplicate email
Duplicate external mutation

这是 LangGraph 架构中非常重要但经常被忽视的一点。

22. Agent Runtime Classification

最终分类：

23. Runtime Path Reconstruction

一个典型 LangGraph request：

User
↓
Agent API
↓
Graph.invoke / stream
↓
Pregel Runtime
↓
State
↓
Schedule Tasks
↓
Execute Node
↓
Write Channel
↓
Checkpoint
↓
Schedule Next Superstep
↓
Execute Node
↓
…
↓
END

如果存在 Agent：

Model Node
↓
Tool Calls?
├── No → END
└── Yes
↓
Tool Node
↓
State Update
↓
Checkpoint
↓
Model Node

24. System Architecture

#mermaid-svg-QGPwvl8Q0jByyHJC{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-QGPwvl8Q0jByyHJC .error-icon{fill:#552222;}#mermaid-svg-QGPwvl8Q0jByyHJC .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-QGPwvl8Q0jByyHJC .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-QGPwvl8Q0jByyHJC .marker{fill:#333333;stroke:#333333;}#mermaid-svg-QGPwvl8Q0jByyHJC .marker.cross{stroke:#333333;}#mermaid-svg-QGPwvl8Q0jByyHJC svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-QGPwvl8Q0jByyHJC p{margin:0;}#mermaid-svg-QGPwvl8Q0jByyHJC .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC .cluster-label text{fill:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC .cluster-label span{color:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC .cluster-label span p{background-color:transparent;}#mermaid-svg-QGPwvl8Q0jByyHJC .label text,#mermaid-svg-QGPwvl8Q0jByyHJC span{fill:#333;color:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC .node rect,#mermaid-svg-QGPwvl8Q0jByyHJC .node circle,#mermaid-svg-QGPwvl8Q0jByyHJC .node ellipse,#mermaid-svg-QGPwvl8Q0jByyHJC .node polygon,#mermaid-svg-QGPwvl8Q0jByyHJC .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-QGPwvl8Q0jByyHJC .rough-node .label text,#mermaid-svg-QGPwvl8Q0jByyHJC .node .label text,#mermaid-svg-QGPwvl8Q0jByyHJC .image-shape .label,#mermaid-svg-QGPwvl8Q0jByyHJC .icon-shape .label{text-anchor:middle;}#mermaid-svg-QGPwvl8Q0jByyHJC .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-QGPwvl8Q0jByyHJC .rough-node .label,#mermaid-svg-QGPwvl8Q0jByyHJC .node .label,#mermaid-svg-QGPwvl8Q0jByyHJC .image-shape .label,#mermaid-svg-QGPwvl8Q0jByyHJC .icon-shape .label{text-align:center;}#mermaid-svg-QGPwvl8Q0jByyHJC .node.clickable{cursor:pointer;}#mermaid-svg-QGPwvl8Q0jByyHJC .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-QGPwvl8Q0jByyHJC .arrowheadPath{fill:#333333;}#mermaid-svg-QGPwvl8Q0jByyHJC .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-QGPwvl8Q0jByyHJC .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-QGPwvl8Q0jByyHJC .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-QGPwvl8Q0jByyHJC .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-QGPwvl8Q0jByyHJC .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-QGPwvl8Q0jByyHJC .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-QGPwvl8Q0jByyHJC .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-QGPwvl8Q0jByyHJC .cluster text{fill:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC .cluster span{color:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-QGPwvl8Q0jByyHJC .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-QGPwvl8Q0jByyHJC rect.text{fill:none;stroke-width:0;}#mermaid-svg-QGPwvl8Q0jByyHJC .icon-shape,#mermaid-svg-QGPwvl8Q0jByyHJC .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-QGPwvl8Q0jByyHJC .icon-shape p,#mermaid-svg-QGPwvl8Q0jByyHJC .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-QGPwvl8Q0jByyHJC .icon-shape .label rect,#mermaid-svg-QGPwvl8Q0jByyHJC .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-QGPwvl8Q0jByyHJC .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-QGPwvl8Q0jByyHJC .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-QGPwvl8Q0jByyHJC :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

User / Application

API / SDK

Compiled Graph

Pregel Runtime

State Channels

Graph Nodes

LLM / Model

Tools

Retrieval

Human / External Event

Task Scheduler

Checkpointer

SQLite

Postgres

Custom Saver

Thread State

Long-term Store

Cross-thread Memory

25. Runtime Sequence

Checkpointer

Tool

LLM

Node

Pregel Runtime

Graph

User

Checkpointer

Tool

LLM

Node

Pregel Runtime

Graph

User

#mermaid-svg-CUnpRpxEycoVLyAn{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CUnpRpxEycoVLyAn .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CUnpRpxEycoVLyAn .error-icon{fill:#552222;}#mermaid-svg-CUnpRpxEycoVLyAn .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CUnpRpxEycoVLyAn .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CUnpRpxEycoVLyAn .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CUnpRpxEycoVLyAn .marker.cross{stroke:#333333;}#mermaid-svg-CUnpRpxEycoVLyAn svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CUnpRpxEycoVLyAn p{margin:0;}#mermaid-svg-CUnpRpxEycoVLyAn .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CUnpRpxEycoVLyAn text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-CUnpRpxEycoVLyAn .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-CUnpRpxEycoVLyAn .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-CUnpRpxEycoVLyAn .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-CUnpRpxEycoVLyAn .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-CUnpRpxEycoVLyAn #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-CUnpRpxEycoVLyAn .sequenceNumber{fill:white;}#mermaid-svg-CUnpRpxEycoVLyAn #sequencenumber{fill:#333;}#mermaid-svg-CUnpRpxEycoVLyAn #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-CUnpRpxEycoVLyAn .messageText{fill:#333;stroke:none;}#mermaid-svg-CUnpRpxEycoVLyAn .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CUnpRpxEycoVLyAn .labelText,#mermaid-svg-CUnpRpxEycoVLyAn .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-CUnpRpxEycoVLyAn .loopText,#mermaid-svg-CUnpRpxEycoVLyAn .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-CUnpRpxEycoVLyAn .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-CUnpRpxEycoVLyAn .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-CUnpRpxEycoVLyAn .noteText,#mermaid-svg-CUnpRpxEycoVLyAn .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-CUnpRpxEycoVLyAn .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CUnpRpxEycoVLyAn .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CUnpRpxEycoVLyAn .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CUnpRpxEycoVLyAn .actorPopupMenu{position:absolute;}#mermaid-svg-CUnpRpxEycoVLyAn .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-CUnpRpxEycoVLyAn .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CUnpRpxEycoVLyAn .actor-man circle,#mermaid-svg-CUnpRpxEycoVLyAn line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-CUnpRpxEycoVLyAn :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

invoke(input, config)

execute

load checkpoint

schedule node

model call

tool call

execute tool

tool result

state update

persist checkpoint

schedule next node

next model call

final answer

persist final state

result

response

26. Component Dependency Graph

#mermaid-svg-5LZdJDiJSTs1BIK9{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-5LZdJDiJSTs1BIK9 .error-icon{fill:#552222;}#mermaid-svg-5LZdJDiJSTs1BIK9 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-5LZdJDiJSTs1BIK9 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .marker.cross{stroke:#333333;}#mermaid-svg-5LZdJDiJSTs1BIK9 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-5LZdJDiJSTs1BIK9 p{margin:0;}#mermaid-svg-5LZdJDiJSTs1BIK9 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .cluster-label text{fill:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .cluster-label span{color:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .cluster-label span p{background-color:transparent;}#mermaid-svg-5LZdJDiJSTs1BIK9 .label text,#mermaid-svg-5LZdJDiJSTs1BIK9 span{fill:#333;color:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .node rect,#mermaid-svg-5LZdJDiJSTs1BIK9 .node circle,#mermaid-svg-5LZdJDiJSTs1BIK9 .node ellipse,#mermaid-svg-5LZdJDiJSTs1BIK9 .node polygon,#mermaid-svg-5LZdJDiJSTs1BIK9 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .rough-node .label text,#mermaid-svg-5LZdJDiJSTs1BIK9 .node .label text,#mermaid-svg-5LZdJDiJSTs1BIK9 .image-shape .label,#mermaid-svg-5LZdJDiJSTs1BIK9 .icon-shape .label{text-anchor:middle;}#mermaid-svg-5LZdJDiJSTs1BIK9 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .rough-node .label,#mermaid-svg-5LZdJDiJSTs1BIK9 .node .label,#mermaid-svg-5LZdJDiJSTs1BIK9 .image-shape .label,#mermaid-svg-5LZdJDiJSTs1BIK9 .icon-shape .label{text-align:center;}#mermaid-svg-5LZdJDiJSTs1BIK9 .node.clickable{cursor:pointer;}#mermaid-svg-5LZdJDiJSTs1BIK9 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .arrowheadPath{fill:#333333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-5LZdJDiJSTs1BIK9 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-5LZdJDiJSTs1BIK9 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-5LZdJDiJSTs1BIK9 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-5LZdJDiJSTs1BIK9 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .cluster text{fill:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 .cluster span{color:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-5LZdJDiJSTs1BIK9 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-5LZdJDiJSTs1BIK9 rect.text{fill:none;stroke-width:0;}#mermaid-svg-5LZdJDiJSTs1BIK9 .icon-shape,#mermaid-svg-5LZdJDiJSTs1BIK9 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-5LZdJDiJSTs1BIK9 .icon-shape p,#mermaid-svg-5LZdJDiJSTs1BIK9 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-5LZdJDiJSTs1BIK9 .icon-shape .label rect,#mermaid-svg-5LZdJDiJSTs1BIK9 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-5LZdJDiJSTs1BIK9 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-5LZdJDiJSTs1BIK9 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-5LZdJDiJSTs1BIK9 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

StateGraph

State Schema

Pregel

Channels

Task Scheduling

Checkpoint

BaseCheckpointSaver

SQLite Saver

Postgres Saver

Custom Saver

langgraph-prebuilt

ToolNode

LangChain Tool

SDK

Agent Server

27. Data Flow

#mermaid-svg-asfqeDyGuPaJysi1{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-asfqeDyGuPaJysi1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-asfqeDyGuPaJysi1 .error-icon{fill:#552222;}#mermaid-svg-asfqeDyGuPaJysi1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-asfqeDyGuPaJysi1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-asfqeDyGuPaJysi1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-asfqeDyGuPaJysi1 .marker.cross{stroke:#333333;}#mermaid-svg-asfqeDyGuPaJysi1 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-asfqeDyGuPaJysi1 p{margin:0;}#mermaid-svg-asfqeDyGuPaJysi1 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-asfqeDyGuPaJysi1 .cluster-label text{fill:#333;}#mermaid-svg-asfqeDyGuPaJysi1 .cluster-label span{color:#333;}#mermaid-svg-asfqeDyGuPaJysi1 .cluster-label span p{background-color:transparent;}#mermaid-svg-asfqeDyGuPaJysi1 .label text,#mermaid-svg-asfqeDyGuPaJysi1 span{fill:#333;color:#333;}#mermaid-svg-asfqeDyGuPaJysi1 .node rect,#mermaid-svg-asfqeDyGuPaJysi1 .node circle,#mermaid-svg-asfqeDyGuPaJysi1 .node ellipse,#mermaid-svg-asfqeDyGuPaJysi1 .node polygon,#mermaid-svg-asfqeDyGuPaJysi1 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-asfqeDyGuPaJysi1 .rough-node .label text,#mermaid-svg-asfqeDyGuPaJysi1 .node .label text,#mermaid-svg-asfqeDyGuPaJysi1 .image-shape .label,#mermaid-svg-asfqeDyGuPaJysi1 .icon-shape .label{text-anchor:middle;}#mermaid-svg-asfqeDyGuPaJysi1 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-asfqeDyGuPaJysi1 .rough-node .label,#mermaid-svg-asfqeDyGuPaJysi1 .node .label,#mermaid-svg-asfqeDyGuPaJysi1 .image-shape .label,#mermaid-svg-asfqeDyGuPaJysi1 .icon-shape .label{text-align:center;}#mermaid-svg-asfqeDyGuPaJysi1 .node.clickable{cursor:pointer;}#mermaid-svg-asfqeDyGuPaJysi1 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-asfqeDyGuPaJysi1 .arrowheadPath{fill:#333333;}#mermaid-svg-asfqeDyGuPaJysi1 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-asfqeDyGuPaJysi1 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-asfqeDyGuPaJysi1 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-asfqeDyGuPaJysi1 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-asfqeDyGuPaJysi1 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-asfqeDyGuPaJysi1 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-asfqeDyGuPaJysi1 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-asfqeDyGuPaJysi1 .cluster text{fill:#333;}#mermaid-svg-asfqeDyGuPaJysi1 .cluster span{color:#333;}#mermaid-svg-asfqeDyGuPaJysi1 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-asfqeDyGuPaJysi1 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-asfqeDyGuPaJysi1 rect.text{fill:none;stroke-width:0;}#mermaid-svg-asfqeDyGuPaJysi1 .icon-shape,#mermaid-svg-asfqeDyGuPaJysi1 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-asfqeDyGuPaJysi1 .icon-shape p,#mermaid-svg-asfqeDyGuPaJysi1 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-asfqeDyGuPaJysi1 .icon-shape .label rect,#mermaid-svg-asfqeDyGuPaJysi1 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-asfqeDyGuPaJysi1 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-asfqeDyGuPaJysi1 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-asfqeDyGuPaJysi1 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

Input

State

Channel

Node

Update

Reducer

Checkpoint

Persistence

Resume

28. Checkpoint Architecture

这是 LangGraph 的第二大核心。

官方 langgraph-checkpoint 明确：

checkpointer 在每个 superstep 保存 graph state。

它支持：

• durable execution
• human-in-the-loop
• memory
• fault tolerance
• time travel

(GitHub)

29. Checkpoint Model

Thread
│
├── Checkpoint 0
│
├── Checkpoint 1
│
├── Checkpoint 2
│
├── Checkpoint 3
│
└── Checkpoint N

其中：

thread_id

是核心隔离键。

官方明确要求使用 checkpointer 时提供 thread_id。(GitHub)

30. Thread

Thread 的意义不是简单：

conversation_id

而是：

一条 Agent execution history / state lineage。

可以：

Thread
├── Run A
│ ├── Checkpoint 1
│ ├── Checkpoint 2
│
└── Run B
├── Checkpoint 3
└── Checkpoint 4

31. Time Travel

由于 checkpoint 是历史状态：

Current
│
├── CP1
├── CP2
├── CP3 ← fork
│
└── CP4

可以从：

CP3

重新运行。

这意味着 LangGraph 天生具备：

Execution history / replay / branching

能力。

这是传统 Agent loop 很难优雅实现的。

32. Pending Writes

这是一个非常优秀的可靠性设计。

如果：

Superstep
├── Node A ✓
├── Node B ✓
└── Node C ✗

LangGraph 会保存已经成功的 pending writes。

恢复时：

A → 不重复执行
B → 不重复执行
C → 重试

官方 checkpoint README 明确说明这一机制。(GitHub)

33. Fault Tolerance

因此 LangGraph 的可靠性模型不是：

Retry entire Agent

而更接近：

Checkpoint
↓
Partial Failure
↓
Recover
↓
Replay only necessary work

这是非常重要的区别。

34. Durability Modes

当前源码支持：

sync
async
exit

含义：

sync
→ persist before next step

async
→ persist while next step runs

exit
→ persist when graph exits

(GitHub)

这实际上提供了：

Durability
↕
Performance

之间的明确 trade-off。

35. Persistence Architecture

LangGraph 把 checkpoint interface 独立出来：

BaseCheckpointSaver

核心 API 包括：

put
put_writes
get_tuple
list
delete_thread
…

(GitHub)

而且还有：

checkpoint-conformance

用于检查实现是否满足能力契约。

(GitHub)

Judgement

这是非常值得企业学习的：

Persistence Contract + Conformance Test

36. Memory Architecture

LangGraph 当前把 Memory 拆成两个层次。

Short-term

Checkpointer
↓
Thread State

Long-term

Store
↓
Cross-thread Memory

官方 persistence 文档明确区分了两者。(GitHub)

37. Memory Model

Agent Memory
│
┌────────────┴────────────┐
▼ ▼
Short-term Long-term
│ │
Checkpointer Store
│ │
Thread Cross-thread
│ │
Current State User Preferences
Facts
Knowledge

这个设计比：

Memory = chat history

成熟很多。

38. Prebuilt Layer

langgraph-prebuilt 提供：

create_react_agent
ToolNode
ValidationNode
InjectedState
InjectedStore
ToolRuntime

(GitHub)

这是：

High-level Agent Layer

而不是核心 Runtime。

39. Important Architectural Boundary

LangGraph
│
┌────────────┴────────────┐
▼ ▼
Core Runtime Prebuilt
│ │
StateGraph create_react_agent
Pregel ToolNode
Channels ValidationNode
Checkpoint

所以：

create_react_agent() 不是 LangGraph 本身。

它只是：

LangGraph Runtime 上的一个 prebuilt agent implementation。

40. create_react_agent Migration

当前源码明确标记：

create_react_agent deprecated，已迁移到 langchain.agents.create_agent。(GitHub)

这是非常重要的架构信号。

说明：

LangGraph
↓
Runtime

LangChain
↓
Default Agent API

正在进一步分层。

41. LangGraph vs LangChain

42. LangGraph 真正的竞争壁垒

不是：

Graph visualization

而是：

State
+
Superstep
+
Checkpoint
+
Resume
+
Replay
+
Interrupt
+
Dynamic scheduling

组合起来形成：

Durable Agent Execution Model

43. This Is the Real Innovation

True Innovation

1. Durable graph execution

★★★★★

2. State + reducer + channel model

★★★★★

3. Checkpoint per superstep

★★★★★

4. Interrupt / Resume

★★★★★

5. Partial failure recovery

★★★★★

44. Engineering Innovation

Checkpointer interface

★★★★★

Checkpoint conformance tests

★★★★★

Separate packages

★★★★★

SDK / CLI

★★★★☆

Python + JS ecosystem

★★★★☆

45. Integration Innovation

LangGraph 可以把：

LLM
Tool
Human
API
Database
RAG
Subgraph

统一纳入：

Stateful Graph

这非常适合复杂 Agent。

46. Repackaging Analysis

如果有人说：

“LangGraph 只是把 Agent 写成 graph。”

这是严重低估。

真正技术含量在：

Graph
↓
State
↓
Channels
↓
Pregel
↓
Checkpoint
↓
Replay
↓
Interrupt
↓
Durable execution

所以：

LangGraph 不是普通 workflow wrapper。

47. Architecture Strengths

S1 — State-first design

Agent 的状态成为 runtime primitive。

★★★★★

S2 — Durable execution

Checkpoint + resume + pending writes。

★★★★★

S3 — Interrupt / HITL

不是 UI feature，而是 runtime primitive。

★★★★★

S4 — Dynamic parallelism

Send 使 map-reduce / fan-out / fan-in 成为 graph primitive。

★★★★★

S5 — Persistence abstraction

Runtime
↓
BaseCheckpointSaver
↓
Storage implementation

非常适合 Enterprise Adapter。

48. Architecture Weaknesses

W1 — Complexity

Severity: High

LangGraph 的核心模型：

Graph
State
Reducer
Channel
Superstep
Checkpoint
Thread
Command
Send
Interrupt
Pregel

对于初学者非常重。

49. W2 — State Explosion

长期运行 Agent：

State ↑
↓
Checkpoint ↑
↓
Storage ↑
↓
Replay Cost ↑

官方文档也明确提醒长期对话会导致 checkpoint 累积、增加 latency 和 storage cost。(GitHub)

因此：

Memory retention policy 是企业必须自行设计的。

50. W3 — Side Effect Semantics

最危险的地方之一：

Node
↓
External Side Effect
↓
Interrupt / Failure
↓
Resume
↓
Node Re-execution

如果没有：

Idempotency Key

可能产生重复副作用。

51. W4 — Checkpoint Security

这是当前最严重的现实风险。

GitHub Security Advisories 当前列出了：

• unsafe msgpack deserialization
• unsafe JSON deserialization
• SQL injection in SQLite checkpointer
• BaseCache deserialization RCE
• unsafe URL path construction
• namespace prefix matching issue

等。(GitHub)

52. Checkpoint Security

当前官方 checkpoint README 已经明确警告：

默认 serializer 允许 checkpoint data 中的 Python type。

并建议新应用使用：

LANGGRAPH_STRICT_MSGPACK=true

或者明确配置：

allowed_msgpack_modules

限制反序列化类型。(GitHub)

这是非常重要的安全边界。

53. CVE-2026-28277

GitHub Advisory Database 对该问题描述为：

LangGraph checkpoint loading 的 unsafe msgpack deserialization。

受影响：

langgraph <= 1.0.9

修复：

1.0.10

该漏洞需要攻击者首先能够修改 checkpoint storage 中的数据，因此属于：

post-exploitation / defense-in-depth

但一旦达到这个前置条件，可能把 checkpoint store write access 转化成 runtime code execution。(GitHub)

54. JSON Deserialization

另一个官方 advisory：

GHSA-fjqc-hq36-qh5p

受影响：

langgraph-checkpoint < 4.1.1

修复：

4.1.1

问题同样涉及 checkpoint JSON reconstruction。(GitHub)

55. SQL Injection

GitHub Security 页面还列出：

SQL injection via metadata filter key in SQLite checkpointer list method

严重度：

High

(GitHub)

这进一步说明：

Checkpoint / Store 是 LangGraph 最需要重点安全审计的区域。

56. 官方 Threat Model 的重要结论

LangGraph 仓库甚至已经维护：

.github/THREAT_MODEL.md

其中明确把：

checkpoint storage boundary

识别为最高风险区域之一。

该 threat model 还指出历史 advisories 中有较高比例涉及 CWE-502 deserialization。(GitHub)

这不是外部猜测。

而是：

项目维护者自己的安全模型。

57. Security Architecture Recommendation

企业不能简单：

LangGraph
↓
Postgres

应该：

Agent Runtime
│
▼
Checkpoint Gateway
│
┌─────┼─────┐
▼ ▼ ▼
Auth ACL Integrity
│
▼
Encrypted Storage

并且：

Untrusted checkpoint
↓
Reject

58. Prompt Injection

LangGraph 本身主要负责：

execution

并不是：

LLM safety

因此：

User
↓
LLM
↓
Tool

仍然需要：

Policy Middleware
↓
Authorization
↓
Tool Gateway

59. Tool Security

推荐：

LLM
↓
Tool Call
↓
Schema Validation
↓
Policy Engine
↓
RBAC / ABAC
↓
Network Policy
↓
Sandbox
↓
External System

不要：

LLM
↓
arbitrary Python function

60. Reliability Audit

61. Agent Loop Reliability

LangGraph 的 loop：

Node
↓
State
↓
Conditional Edge
↓
Node

如果条件永远不满足：

A → B → A → B → …

所以必须配置：

recursion_limit

以及：

budget
timeout
termination condition

企业不能把：

Graph correctness

等同于：

Agent termination guarantee。

62. Performance

不提供伪造 benchmark。

真正的性能模型：

Latency
=
Node Execution
+
LLM Calls
+
Tool Calls
+
Checkpoint
+
Scheduling
+
Serialization
+
Network

特别是：

Checkpoint every superstep

意味着：

Durability 会产生真实的 I/O overhead。

官方 durability modes 已明确暴露了：

sync
async
exit

这种性能/持久性 trade-off。(GitHub)

63. Storage Cost

长期 Agent：

1000 steps
×
state size
×
threads

可能迅速产生：

checkpoint storage explosion

因此企业必须：

Retention
+
Compaction
+
Pruning
+
DeltaChannel
+
Archival

64. Project Evolution

当前仓库已经进入：

1.x

阶段。

源码 pyproject.toml 当前版本为：

1.2.10

(GitHub)

GitHub release 页面显示 1.2.9 为最新 release 页面版本，而 1.2.10 已经有 GitHub Actions release run，说明发布流水线正在快速推进。(GitHub)

65. Evolution Direction

最近 release 中已经出现：

durable error-handler resume
set_node_defaults
DeltaChannel
checkpoint history
stream transformer

等能力。(GitHub)

这说明 LangGraph 正在从：

Graph Framework

继续向：

Durable Agent Runtime

发展。

66. Competitive Landscape

最相关竞品：

67. LangGraph vs Temporal

这是非常重要的比较。

Temporal

Business Workflow
+
Durable Execution
+
Distributed Transactions

LangGraph

AI Agent Workflow
+
State
+
LLM
+
Tools
+
Human-in-loop

因此：

LangGraph 不是 Temporal 的完整替代品。

更合理：

Temporal
│
▼
Enterprise Durable Workflow
│
▼
LangGraph
│
▼
AI Agent Runtime

68. LangGraph vs OpenAI Agents SDK

OpenAI Agents SDK：

Agent
Tool
Handoff
Guardrail
Tracing

更轻量。

LangGraph：

Graph
State
Checkpoint
Interrupt
Replay
Persistence
Dynamic scheduling

更强。

如果目标是：

simple agent

OpenAI SDK 更轻。

如果：

long-running stateful workflow

LangGraph 更强。

69. LangGraph vs AutoGen

AutoGen：

Multi-agent conversation / collaboration

LangGraph：

Explicit stateful execution graph

如果你希望：

Agent A ↔ Agent B ↔ Agent C

AutoGen 思路自然。

如果你希望：

State
↓
Planner
↓
Research
↓
Review
↓
Human
↓
Execute
↓
Audit

LangGraph 更适合。

70. LangGraph vs CrewAI

CrewAI：

Role
Task
Crew

LangGraph：

State
Node
Edge
Command
Checkpoint

因此：

CrewAI 是 application-level multi-agent abstraction。

LangGraph 是 runtime-level orchestration abstraction。

71. LangGraph vs Temporal

这是最有价值的架构问题：

LangGraph 是否应该自己实现 durable execution？

我的判断：

Yes

对于 Agent runtime：

LLM
Tool
Human
State

必须深度理解。

Temporal 很难直接理解：

LLM tool call
interrupt
state reducer
agent message

所以 LangGraph 的 Agent-specific runtime 是合理的。

但是：

Enterprise business workflow 仍然可能需要 Temporal。

72. Recommended Enterprise Architecture

如果做大型 Enterprise Agent：

#mermaid-svg-MeJ58YlcavJR9dcb{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-MeJ58YlcavJR9dcb .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-MeJ58YlcavJR9dcb .error-icon{fill:#552222;}#mermaid-svg-MeJ58YlcavJR9dcb .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-MeJ58YlcavJR9dcb .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-MeJ58YlcavJR9dcb .marker{fill:#333333;stroke:#333333;}#mermaid-svg-MeJ58YlcavJR9dcb .marker.cross{stroke:#333333;}#mermaid-svg-MeJ58YlcavJR9dcb svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-MeJ58YlcavJR9dcb p{margin:0;}#mermaid-svg-MeJ58YlcavJR9dcb .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-MeJ58YlcavJR9dcb .cluster-label text{fill:#333;}#mermaid-svg-MeJ58YlcavJR9dcb .cluster-label span{color:#333;}#mermaid-svg-MeJ58YlcavJR9dcb .cluster-label span p{background-color:transparent;}#mermaid-svg-MeJ58YlcavJR9dcb .label text,#mermaid-svg-MeJ58YlcavJR9dcb span{fill:#333;color:#333;}#mermaid-svg-MeJ58YlcavJR9dcb .node rect,#mermaid-svg-MeJ58YlcavJR9dcb .node circle,#mermaid-svg-MeJ58YlcavJR9dcb .node ellipse,#mermaid-svg-MeJ58YlcavJR9dcb .node polygon,#mermaid-svg-MeJ58YlcavJR9dcb .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-MeJ58YlcavJR9dcb .rough-node .label text,#mermaid-svg-MeJ58YlcavJR9dcb .node .label text,#mermaid-svg-MeJ58YlcavJR9dcb .image-shape .label,#mermaid-svg-MeJ58YlcavJR9dcb .icon-shape .label{text-anchor:middle;}#mermaid-svg-MeJ58YlcavJR9dcb .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-MeJ58YlcavJR9dcb .rough-node .label,#mermaid-svg-MeJ58YlcavJR9dcb .node .label,#mermaid-svg-MeJ58YlcavJR9dcb .image-shape .label,#mermaid-svg-MeJ58YlcavJR9dcb .icon-shape .label{text-align:center;}#mermaid-svg-MeJ58YlcavJR9dcb .node.clickable{cursor:pointer;}#mermaid-svg-MeJ58YlcavJR9dcb .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-MeJ58YlcavJR9dcb .arrowheadPath{fill:#333333;}#mermaid-svg-MeJ58YlcavJR9dcb .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-MeJ58YlcavJR9dcb .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-MeJ58YlcavJR9dcb .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-MeJ58YlcavJR9dcb .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-MeJ58YlcavJR9dcb .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-MeJ58YlcavJR9dcb .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-MeJ58YlcavJR9dcb .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-MeJ58YlcavJR9dcb .cluster text{fill:#333;}#mermaid-svg-MeJ58YlcavJR9dcb .cluster span{color:#333;}#mermaid-svg-MeJ58YlcavJR9dcb div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-MeJ58YlcavJR9dcb .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-MeJ58YlcavJR9dcb rect.text{fill:none;stroke-width:0;}#mermaid-svg-MeJ58YlcavJR9dcb .icon-shape,#mermaid-svg-MeJ58YlcavJR9dcb .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-MeJ58YlcavJR9dcb .icon-shape p,#mermaid-svg-MeJ58YlcavJR9dcb .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-MeJ58YlcavJR9dcb .icon-shape .label rect,#mermaid-svg-MeJ58YlcavJR9dcb .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-MeJ58YlcavJR9dcb .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-MeJ58YlcavJR9dcb .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-MeJ58YlcavJR9dcb :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

API Gateway

Domain Service

Enterprise Workflow

Temporal / Durable Workflow

LangGraph Agent Runtime

Model Gateway

Tool Gateway

RAG Service

LangGraph Checkpointer

Postgres

Memory Store

Agent Evaluation

Observability

Policy Engine

Permission-aware Retrieval

这个架构比：

Everything = LangGraph

更加企业化。

73. KEEP

如果二次开发：

StateGraph
Pregel runtime
Channels
Send
Command
Interrupt
Checkpoint protocol
Persistence abstraction
Conformance testing

这些都值得保留。

74. REFACTOR

需要在企业层封装：

Agent lifecycle
Tool authorization
Memory policy
Retry policy
Budget policy
Tenant isolation
Audit
Evaluation

75. REPLACE

生产环境慎用默认：

InMemorySaver

官方 persistence 文档明确说明：

MemorySaver / InMemorySaver 不会跨进程重启持久化。(GitHub)

Production 应使用：

PostgresSaver

或：

Enterprise Checkpointer

76. REMOVE

如果项目只是：

User
↓
LLM
↓
Answer

不要引入 LangGraph。

甚至：

LLM
↓
Tool
↓
Answer

如果没有：

• state
• cycles
• persistence
• interrupt
• complex orchestration

也未必需要。

77. ADD

Enterprise 必须增加：

Policy Engine
Tool Gateway
Model Gateway
Evaluation
Cost Governance
Audit
Tenant Isolation
Checkpoint Encryption
Checkpoint Integrity
Retention
Idempotency

78. Target Architecture

我建议企业基于 LangGraph 建立：

Enterprise Agent Runtime

而不是：

LangGraph Fork

架构：

#mermaid-svg-ECX4pP7NKi8rIBdZ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ECX4pP7NKi8rIBdZ .error-icon{fill:#552222;}#mermaid-svg-ECX4pP7NKi8rIBdZ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ECX4pP7NKi8rIBdZ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .marker.cross{stroke:#333333;}#mermaid-svg-ECX4pP7NKi8rIBdZ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ECX4pP7NKi8rIBdZ p{margin:0;}#mermaid-svg-ECX4pP7NKi8rIBdZ .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .cluster-label text{fill:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .cluster-label span{color:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .cluster-label span p{background-color:transparent;}#mermaid-svg-ECX4pP7NKi8rIBdZ .label text,#mermaid-svg-ECX4pP7NKi8rIBdZ span{fill:#333;color:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .node rect,#mermaid-svg-ECX4pP7NKi8rIBdZ .node circle,#mermaid-svg-ECX4pP7NKi8rIBdZ .node ellipse,#mermaid-svg-ECX4pP7NKi8rIBdZ .node polygon,#mermaid-svg-ECX4pP7NKi8rIBdZ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .rough-node .label text,#mermaid-svg-ECX4pP7NKi8rIBdZ .node .label text,#mermaid-svg-ECX4pP7NKi8rIBdZ .image-shape .label,#mermaid-svg-ECX4pP7NKi8rIBdZ .icon-shape .label{text-anchor:middle;}#mermaid-svg-ECX4pP7NKi8rIBdZ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .rough-node .label,#mermaid-svg-ECX4pP7NKi8rIBdZ .node .label,#mermaid-svg-ECX4pP7NKi8rIBdZ .image-shape .label,#mermaid-svg-ECX4pP7NKi8rIBdZ .icon-shape .label{text-align:center;}#mermaid-svg-ECX4pP7NKi8rIBdZ .node.clickable{cursor:pointer;}#mermaid-svg-ECX4pP7NKi8rIBdZ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .arrowheadPath{fill:#333333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ECX4pP7NKi8rIBdZ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ECX4pP7NKi8rIBdZ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ECX4pP7NKi8rIBdZ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ECX4pP7NKi8rIBdZ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .cluster text{fill:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ .cluster span{color:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ECX4pP7NKi8rIBdZ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ECX4pP7NKi8rIBdZ rect.text{fill:none;stroke-width:0;}#mermaid-svg-ECX4pP7NKi8rIBdZ .icon-shape,#mermaid-svg-ECX4pP7NKi8rIBdZ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ECX4pP7NKi8rIBdZ .icon-shape p,#mermaid-svg-ECX4pP7NKi8rIBdZ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ECX4pP7NKi8rIBdZ .icon-shape .label rect,#mermaid-svg-ECX4pP7NKi8rIBdZ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ECX4pP7NKi8rIBdZ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ECX4pP7NKi8rIBdZ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ECX4pP7NKi8rIBdZ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

Client

Agent Gateway

Auth / RBAC

Policy Engine

Enterprise Agent Runtime

LangGraph

State

Graph

Checkpoint Adapter

Model Gateway

Tool Gateway

RAG Gateway

Tool Authorization

Retrieval ACL

Evaluation

Tracing

Cost Control

Postgres / Durable Store

79. V1 — MVP

StateGraph
+
Basic Agent
+
ToolNode
+
Postgres Checkpointer
+
API
+
Streaming

核心目标：

完成 Stateful Agent 闭环。

80. V2 — Production

增加：

Retry
Timeout
Checkpoint Recovery
Interrupt
HITL
Observability
Evaluation
Idempotency
Security
Retention

81. V3 — Enterprise

增加：

Multi-tenancy
RBAC
ABAC
Policy Engine
Agent Governance
Model Gateway
Tool Gateway
Audit
Cost Governance
Evaluation Platform
MCP Gateway
Workflow Federation

82. Coding Agent Repository

建议：

src/
├── domain/
│
├── agent/
│ ├── contracts.py
│ ├── runtime.py
│ ├── state.py
│ └── graph.py
│
├── orchestration/
│ ├── scheduler.py
│ ├── policies.py
│ └── lifecycle.py
│
├── checkpoint/
│ ├── adapter.py
│ ├── serializer.py
│ └── retention.py
│
├── tools/
│ ├── registry.py
│ ├── policy.py
│ └── gateway.py
│
├── models/
│ └── gateway.py
│
├── retrieval/
│
├── memory/
│
├── security/
│
├── evaluation/
│
├── observability/
│
└── api/

83. Coding Agent Tasks

AG-001 — Agent Runtime Contract

task_id: AG–001
title: Create AgentRuntime abstraction
goal: Hide LangGraph implementation behind application–owned contract
dependencies: []
files_to_create:
– src/agent/contracts.py
– src/agent/runtime.py
tests:
– tests/unit/agent/test_runtime.py
acceptance_criteria:
– Domain layer does not import LangGraph
– Runtime supports invoke and stream
definition_of_done:
– Unit tests pass
– Type checking passes
risk: Medium

STATE-001 — State Contract

task_id: STATE–001
title: Define versioned AgentState
goal: Establish stable application–owned state schema
dependencies:
– AG–001
files_to_create:
– src/agent/state.py
tests:
– tests/unit/agent/test_state.py
acceptance_criteria:
– State reducers explicitly defined
– State version is persisted
definition_of_done:
– Serialization regression tests pass
risk: High

CP-001 — Checkpoint Gateway

task_id: CP–001
title: Implement checkpoint gateway
goal: Isolate LangGraph checkpoint implementation
dependencies:
– STATE–001
files_to_create:
– src/checkpoint/adapter.py
– src/checkpoint/serializer.py
– src/checkpoint/retention.py
tests:
– tests/integration/checkpoint/
acceptance_criteria:
– Checkpoint data is tenant–isolated
– Serializer rejects unapproved types
– Retention policy exists
definition_of_done:
– Security tests pass
risk: Critical

84. Critical Coding Agent Rule

如果让 Coding Agent 修改 LangGraph 类系统：

必须首先读取：

AGENTS.md

再读取：

libs/langgraph/pyproject.toml
libs/checkpoint/
libs/prebuilt/

官方要求修改 library 后运行：

make format
make lint
make test

并提供 TEST=… make test 的 targeted test 方式。(GitHub)

这非常适合直接写进：

AGENTS.md

85. Testing Architecture

LangGraph 当前测试体系包含：

Unit
Integration
Checkpoint tests
Conformance tests
Prebuilt agent tests
Provider integration

例如 prebuilt 有专门测试 create_react_agent、state、store injection 等行为。(GitHub)

86. Checkpoint Conformance

这是 LangGraph 一个非常值得学习的工程设计：

BaseCheckpointSaver
│
▼
Conformance Suite
│
┌──────┼──────┐
▼ ▼ ▼
SQLite Postgres Custom

Capability 检查甚至区分：

PUT
PUT_WRITES
GET_TUPLE
LIST
DELETE_THREAD
DELETE_FOR_RUNS
COPY_THREAD
PRUNE
DELTA_CHANNEL_HISTORY

(GitHub)

Judgement

★★★★★

这是一个真正适合 Enterprise Infrastructure 学习的模式。

87. Reliability Definition

LangGraph 的可靠性优势：

Checkpoint
+
Pending Writes
+
Resume
+
Interrupt
+
Replay

可以形成：

Failure-aware Agent Runtime

而普通 Agent Framework 通常只有：

try:
agent.run()
except:
retry()

两者完全不是一个级别。

88. But Durable ≠ Transactional

这是必须强调的。

LangGraph 可以：

resume execution

但不自动保证：

database transaction
payment transaction
external API transaction

因此：

Durable Execution
≠
Distributed Transaction

这是企业设计时非常关键的边界。

89. Observability

LangGraph 本身可以产生：

State
Task
Checkpoint
Stream
Debug

源码类型定义甚至包含：

CheckpointStreamPart
TasksStreamPart
DebugStreamPart
MessagesStreamPart
UpdatesStreamPart
ValuesStreamPart

(GitHub)

因此它天然比简单 Agent loop 更适合：

Execution Trace。

90. Production Debugging

一次复杂 Agent：

Run
├── Step 1
├── Step 2
├── Step 3
├── Interrupt
├── Resume
├── Step 4
└── Step 5

可以通过 checkpoint + task state 还原。

这是 LangGraph 的巨大优势。

91. Unverified Claims

92. Evidence Ledger

93. Technical Risk Register

94. Executive Score

Overall Score: 9.4 / 10

95. Why 9.4?

不是因为 LangGraph “很热门”。

而是因为它真正解决了一个普通 Agent Framework 没有解决好的问题：

How do you run
a stateful,
long-running,
interruptible,
recoverable,
multi-step
AI agent?

LangGraph 的答案是：

State
+
Graph
+
Pregel
+
Checkpoint
+
Interrupt
+
Resume
+
Replay

这个组合是有技术含量的。

96. Most Valuable Things to Reuse

1. StateGraph

★★★★★

2. Pregel execution model

★★★★★

3. Checkpoint abstraction

★★★★★

4. Interrupt / Resume

★★★★★

5. Conformance testing

★★★★★

97. Most Important Things to Refactor

98. Biggest Technical Opportunities

99. Biggest Technical Risks

100. One-Page Decision Matrix

101. Final Technical Verdict

Project Type

Stateful Agent Runtime / Agent Orchestration Framework / Durable Execution Engine

Technical Maturity

Production Ready

但必须理解：

LangGraph Runtime
≠
Complete Enterprise Agent Platform

Worth Learning?

Yes — 强烈推荐

尤其值得学习：

State
Graph
Reducer
Channel
Pregel
Checkpoint
Interrupt
Command
Send
Durable Execution
Conformance Testing

Worth Forking?

Conditional Yes

如果目标是：

研究 Agent Runtime。

值得 Fork。

如果目标是：

建自己的 Enterprise Agent Runtime。

不建议直接 Fork。

应该：

LangGraph
↓
Study
↓
Adapter / Extension
↓
Enterprise Runtime

Worth Production?

Yes, with Conditions

必须：

Upgrade patched versions
+
Strict checkpoint serialization
+
Secure storage
+
Idempotent tools
+
Tenant isolation
+
Runtime budget
+
Observability

Worth Enterprise Adoption?

Requires Enterprise Hardening

尤其是：

Checkpoint
Security
Authorization
Tool Gateway
State Retention
Audit
Cost
Idempotency

102. CTO Decision Gate

ADOPT WITH CONDITIONS

Decision

将 LangGraph 定位为：

Enterprise Agent Execution Runtime

而不是：

Enterprise Workflow Platform 的全部。

Why

它真正优秀的地方是：

Stateful
+
Durable
+
Graph-based
+
Interruptible
+
Recoverable

Required Conditions

1. Enterprise Checkpoint Gateway
2. Strict Serialization
3. Tool Authorization Gateway
4. Model Gateway
5. Tenant Isolation
6. Idempotency Framework
7. State Retention
8. Evaluation Platform
9. Observability
10. Security Hardening

103. 与你前面 LangChain 审计的最终对照

这是最值得记住的一张图：

Enterprise Agent Platform
│
┌────────────────┴────────────────┐
│ │
Component Layer Runtime Layer
│ │
LangChain Core LangGraph
│ │
┌───────┼─────────┐ ┌──────────┼──────────┐
▼ ▼ ▼ ▼ ▼ ▼
Model Tool Retriever State Graph Checkpoint
│ │ │ │ │ │
└───────┴─────────┘ └──────────┼──────────┘
▼
Durable Agent

因此：

LangChain 是“AI Components Layer”。

LangGraph 是“Agent Runtime Layer”。

而如果你要做你一直在研究的：

Agent Engineering Harness

那么 LangGraph 更值得研究的其实不是它的 create_react_agent()，而是下面这条架构链：

Agent Engineering Harness
│
▼
Execution Contract
│
▼
Agent State
│
▼
Execution Graph
│
▼
Runtime Scheduler
│
┌──────────┼──────────┐
▼ ▼ ▼
Tool Model Human
│ │ │
└──────────┼──────────┘
▼
Checkpoint
│
▼
Recovery
│
▼
Replay
│
▼
Observability

这实际上已经非常接近一个真正的 Agent Engineering Runtime / Harness。

104. 最终结论

LangGraph 比 LangChain 更值得做“源码级学习”。

LangChain 最值得学的是：

Abstraction

LangGraph 最值得学的是：

Runtime

而 LangGraph 真正值得你吸收进自己 Agent Engineering Harness 的核心不是：

StateGraph API

而是：

“Agent 必须被当成一个可暂停、可恢复、可检查、可重放、可观测、可治理的长期运行程序，而不是一次 LLM 函数调用。”

这正是 LangGraph 相比大量 Agent = while loop + tool calling 项目最重要的架构跃迁。

最终 CTO Decision：ADOPT WITH CONDITIONS。

LangGraph GitHub Repository

LangGraph AGENTS.md

LangGraph Security Advisories