# LangChain & LangGraph 功能调研笔记

> 调研时间：2026-07-06
> 两者关系：同一公司（LangChain Inc.）维护的堆栈上下两层，不是竞品

---

## 两者关系

```
┌──────────────────────────────────────────┐
│           LangChain (v1.0 GA)            │ ← 高层框架：模型抽象、工具、提示词、600+集成
│   create_agent / LCEL / 组件库           │
├──────────────────────────────────────────┤
│           LangGraph (v1.0 GA)            │ ← 底层运行时：有向图执行引擎
│   StateGraph / Checkpointing / HITL      │
├──────────────────────────────────────────┤
│          LangSmith (可观测性)             │
└──────────────────────────────────────────┘
```

2025年10月22日同时达到 v1.0 GA，官方分工：

> **LangChain** = agent framework：abstractions and integrations for models, tools, and agent loops.
> **LangGraph** = orchestration runtime：durable execution, streaming, human-in-the-loop, and persistence.

LangChain v1.0 的 `create_agent` 内部已运行在 LangGraph 引擎上。

---

## LangChain v1.0

### 定位
高层应用框架，提供 agent 所需的**组件抽象**和**集成生态**。

### 精简后的核心模块

| 模块 | 功能 |
|------|------|
| `langchain.agents` | `create_agent`, `AgentState`（取代旧 AgentExecutor） |
| `langchain.chat_models` | `init_chat_model`, `BaseChatModel`（统一模型初始化） |
| `langchain.tools` | `@tool`, `BaseTool` |
| `langchain.messages` | 消息类型、内容块、`trim_messages` |
| `langchain.embeddings` | `init_embeddings`, `Embeddings` |

旧组件（`LLMChain`、`ConversationChain` 等）移入 `langchain-classic`。

### 七大组件类别

| 类别 | 关键组件 |
|------|----------|
| **Models** | Chat models, LLMs, Embeddings — 统一接口跨 provider 切换 |
| **Tools** | 600+ provider 集成：API、数据库、搜索引擎等 |
| **Agents** | `create_agent`, ReAct agents, Tool-calling agents |
| **Memory** | 消息历史、自定义状态 |
| **Retrievers** | 向量检索器、网络检索器 |
| **Document** | 加载器、分割器、转换器 |
| **Vector Stores** | Chroma, Pinecone, FAISS 等集成 |

### v1.0 关键新特性

**1. Middleware 中间件系统** — `create_agent` 的钩子系统：
- `before_model` — 模型调用前注入/修改
- `after_model` — 模型调用后验证/后处理
- `wrap_tool_call` — 拦截工具调用错误

**2. Standard Message Content** — 跨 provider 标准化消息内容格式：
- 推理/思维链、引用、多模态（图片/音视频/文档）
- 工具调用、provider 特有工具（web search, code execution）
- 通过 `.content_blocks` 属性访问，向后兼容

**3. `create_agent`** — 取代旧 AgentExecutor，内部运行在 LangGraph 运行时上

### 成熟度

| 维度 | 状态 |
|------|------|
| 版本 | v1.0 GA（2025-10） |
| 稳定性 | 稳定，agent 层经重构后已稳定 |
| 生产证明 | Replit, Clay, Rippling, Cloudflare, Workday |
| 支持 | LTS-style support track |
| 适用场景 | RAG、信息提取、单 agent 助手、快速原型 |

---

## LangGraph v1.0

### 定位
底层编排运行时，专为**有状态、长时间运行、多步骤**工作流设计。

### 核心抽象链

```
StateGraph → Nodes (纯 Python 函数) → Edges (路由逻辑)
                              ↓
                        Shared State (TypedDict / Pydantic)
                              ↓
                     Checkpointer (每个 super-step 快照)
```

- **StateGraph**: 有状态图，参数化 State 类型
- **Nodes**: 纯函数，`(State) → updates`
- **Edges**: `add_conditional_edges`，支持循环/分支/合并
- **State**: `TypedDict` 或 Pydantic，带 reducer 处理并发更新
- **Reducers**: `add_messages` 等，自动处理追加 vs 覆盖

### 完整功能矩阵

| 功能 | 状态 | 细节 |
|------|------|------|
| **StateGraph** | ✅ 稳定 | 循环图（非 DAG），条件边缘，并行 fan-out |
| **Checkpointing** | ✅ v4.1.1 | SQLite / PostgreSQL / Redis 后端 |
| **Durable Execution** | ✅ 稳定 | 跨失败自动恢复，从精确断点继续 |
| **Human-in-the-loop** | ✅ 一等公民 | `interrupt()` + `Command(resume=...)` |
| **Time-travel 调试** | ✅ 稳定 | 回滚任意 checkpoint，fork 重放 |
| **流式输出** | ✅ 稳定 | Token 级 + State 级 + Event 级 |
| **多 Agent 编排** | ✅ 稳定 | Supervisor / Swarm / 层级 / Subgraph |
| **Comprehensive Memory** | ✅ 稳定 | 短时工作记忆 + 长时持久记忆 |
| **增量状态存储** | 🧪 DeltaChannel beta (v4.1.0+) | 长消息列表只存 delta |
| **跨进程状态同步** | 🧪 RemoteCheckpointer (v4.1.0+) | 分布式多 agent 架构 |
| **自动 checkpoint 清理** | ✅ keep_latest TTL (v4.0.2) | 避免无限制积累历史 |
| **LangGraph Platform** | ✅ 稳定 | Agent Server：持久化、任务队列、版本管理 |
| **LangGraph Studio** | ✅ 稳定 | 可视化 agent 工作流 |

### 成熟度

| 维度 | 状态 |
|------|------|
| 版本 | v1.0 GA（2025-10），checkpointer v4.1.1 (2026-05) |
| 稳定性 | 高，持久化为架构一等公民 |
| 生产证明 | Klarna, Replit, Elastic |
| 支持 | LTS-style support track |
| 适用场景 | 多步骤 agent、多 agent 系统、人工审批、长时间运行任务 |

---

## 功能边界对比

| 维度 | LangChain | LangGraph |
|------|-----------|-----------|
| **层次** | 高层应用框架 | 底层编排运行时 |
| **核心抽象** | `create_agent`, LCEL, 组件库 | `StateGraph`, Nodes, Edges, State |
| **思维模型** | 线性或 DAG 管道 | 节点 + 边缘的循环有向图 |
| **循环/分支** | 受限 | **一等公民**：任意循环、分支、合并 |
| **状态持久化** | 无原生支持 | **一等公民**：Checkpointer |
| **Human-in-loop** | 需手动编排 | **一等公民**：`interrupt()` + `Command` |
| **Time-travel 调试** | 无 | **一等公民**：回滚 fork 重放 |
| **Durable Execution** | 无 | **一等公民**：跨故障自动恢复 |
| **流式** | Token 级 | Token + State + Event 每节点流式 |
| **多 Agent 编排** | 需手动组合 | **原生**：Supervisor/Swarm/Subgraph |
| **模型抽象** | **核心优势** | 复用 LangChain |
| **600+ 集成** | **核心优势** | 可复用 LangChain 集成 |
| **LCEL 线性链** | **有** | 无 |
| **Middleware** | **v1.0 特有** | 无 |
| **学习曲线** | 中等 | 较陡（需图思维） |
| **部署平台** | 无独立平台 | LangGraph Platform + Studio |

---

## 决策路线

```
你的 workflow 需要什么？
│
├─ 线性、始终相同步骤 → LangChain (LCEL / create_agent)
├─ 需要循环/分支/重试 → LangGraph (StateGraph)
├─ 需要持久化/故障恢复 → LangGraph (Checkpointer)
├─ 需要人工审批 → LangGraph (interrupt())
├─ 需要 time-travel 调试 → LangGraph (checkpoint + fork)
├─ 需要多 agent 协作 → LangGraph (Supervisor/Swarm/Subgraph)
└─ 不确定 → 先用 create_agent，遇到瓶颈下钻到 StateGraph
```

---

## 参考来源

- [LangChain Blog: v1.0 Milestone](https://www.langchain.com/blog/langchain-langgraph-1dot0)
- [LangChain Documentation](https://docs.langchain.com/oss/python/langchain/overview)
- [LangGraph Documentation](https://docs.langchain.com/oss/python/langgraph/overview)
- [LangGraph GitHub](https://github.com/langchain-ai/langgraph)
- [Atlan: LangChain vs LangGraph 2026](https://atlan.com/know/ai-agent/ai-agent-memory/langchain-vs-langgraph/)
- [truefoundry: LangChain vs LangGraph](https://www.truefoundry.com/blog/langchain-vs-langgraph)