LangGraph 详解：构建有状态代理的低层编排框架
用大模型做代理（Agent），难的从来不是"调一次模型"，而是让它有状态地连续工作：多步循环、分支路由、失败后从断点恢复、中途让人插手确认。langchain-ai/langgraph（LangGraph）就是为此而生的低层编排框架——把代理工作流建模成图：节点是步骤、边是流转、条件边做动态路由，天然支持循环与多代理协作。约 41.5k Star、MIT 协议，出自 LangChain 团队，Klarna、Replit、Elastic 都在用。本文从核心模型、快速上手、四大能力到生态定位，完整拆解。
1、项目概述
LangGraph 是 LangChain 公司推出的开源编排框架，定位是"构建有状态代理的低层编排基础设施"，用于搭建、管理与部署长时间运行、有状态的代理工作流。仓库约 41.5k Star、7k Fork，MIT 协议。设计灵感来自 Pregel、Apache Beam 与 NetworkX——把数据流图的执行模型引入了代理编排。
基本面：
- 与 LangChain 的分工：LangChain 提供可组合组件与集成，LangGraph 专注有状态、长时运行工作流的低层编排
- 可独立于 LangChain 单独使用，不绑定全家桶
- 生产案例：Klarna、Replit、Elastic 等公司在用
- 同源生态：JS/TS 版 LangGraph.js、LangChain Academy 免费课程
2、核心模型：用图编排代理
LangGraph 的世界观很简单：代理工作流就是一张图——节点干活，边定顺序，共享状态贯穿全程。
三个原语：
- 节点（Nodes）：工作单元——函数、LLM 调用或工具执行
- 边（Edges）：节点间的固定流转；条件边（Conditional Edges）按状态动态路由
- 状态（State）：类型化的共享状态，贯穿全图，节点读写更新
图模型的独特优势：
1. 支持循环（cycles）——代理"思考-行动-观察"反复迭代，线性链做不到
2. 支持分支与子图，多代理（multi-actor）在同一状态上协作
3. 条件边让路由逻辑成为图的一部分，可控可测
4. 与 Agent 对话协议天然契合：一轮工具调用就是图上一圈循环
3、安装与最小示例
一条 pip 装好，二十行代码跑通"定义状态-加节点-连边-编译-调用"全流程。
// 安装
pip install -U langgraphfrom typing import TypedDict
from langgraph.graph import StateGraph, START, END
// 1. 定义类型化状态
class State(TypedDict):
messages: list
// 2. 节点：读状态、返回状态更新
def agent_node(state: State) -> dict:
return {"messages": state["messages"] + ["Hello from the agent!"]}
// 3. 组装图：加节点、连边
builder = StateGraph(State)
builder.add_node("agent", agent_node)
builder.add_edge(START, "agent")
builder.add_edge("agent", END)
// 4. 编译成可执行图并调用
graph = builder.compile()
result = graph.invoke({"messages": []})代码要点：
1. State 用 TypedDict 声明，类型即文档
2. 节点函数返回状态的增量更新，而非全量改写
3. START 与 END 是内置端点，标明图的入口与出口
4. compile 后得到可反复 invoke 的可执行图，也可流式运行
4、四大生产级能力
让 LangGraph 区别于玩具示例的，是四项面向长时运行生产环境的能力。
四大能力：
- 持久化执行（Durable Execution）：跨故障持久保存，长时运行也能从上次中断处精确恢复
- 人机协同（Human-in-the-loop）：通过 interrupt 中断执行，人工检查、修改代理状态后继续
- 双层记忆：短期工作记忆（当前会话状态）+ 长期持久记忆（跨会话）
- 流式输出与可观测：全流程 streaming，配合 LangSmith 追踪调试
能力要点：
1. 持久化意味着代理可以"跑几天"——故障重启不丢进度
2. 高风险动作（发邮件、下单）前挂 interrupt，人确认后再放行
3. 记忆分层让代理既记得当前任务，也记得用户长期偏好
4. LangSmith 追踪每一步的状态变迁，坏掉的节点一眼定位
5、生态：Deep Agents 与部署
框架之外，LangChain 围绕它搭了一整套从开发到部署的工具链。
生态组件：
- Deep Agents：基于 LangGraph 的高层包，代理可规划、派生子代理、使用文件系统
- LangSmith：评测、可观测与调试平台，深度集成
- LangSmith Studio：可视化原型工具，拖拽调试图结构
- LangSmith Deployments：有状态工作流的可扩展生产部署
要点：
1. 开发用开源框架，观测与部署走 LangSmith 商业平台，边界清晰
2. Deep Agents 相当于官方给出的"复杂代理参考实现"，值得读源码
3. 文档在 docs.langchain.com，入门有免费的 LangChain Academy 课程
4. JS/TS 项目用同构的 LangGraph.js
6、定位对比：与 LangChain、Dify 怎么选
同为"搭代理"的工具，三者层次不同，组合多于互斥。
三者对比：
- LangGraph：代码级低层编排，图模型 + 持久化 + 人机协同，控制力最强
- LangChain：组件与集成库，负责"调模型、接工具"这类积木
- Dify：可视化平台，业务人员拖拽搭应用，无需写代码
选型建议：
1. 代理逻辑复杂、需要循环与状态恢复、工程师团队维护 → LangGraph
2. 快速拼装原型、集成各家模型工具 → LangChain 组件 + LangGraph 编排
3. 面向业务团队、可视化交付优先 → Dify 平台
4. 组合玩法：Dify 做轻应用，复杂代理内核用 LangGraph，模型接入统一走 LiteLLM
7、使用建议与注意事项
使用建议：
- 先用最小示例吃透 State / Node / Edge 三原语，再上条件边与循环
- 高风险节点一律挂 interrupt，人工确认再继续
- 长时任务开启持久化，重启即恢复，别让进度白跑
- 配 LangSmith 追踪调试，状态变迁全程可见
注意事项：
- 它是低层框架：图的每个节点都要自己写，没有现成"一键代理"
- 与 LangChain 可独立使用，但深度集成时生态最顺
- 循环图要设终止条件，避免代理无限打转烧 token
- LangSmith 观测与部署是商业服务，评估成本再上
8、总结
LangGraph 是 LangChain 公司开源的低层代理编排框架（41.5k Star、MIT），把代理工作流建模为图：节点干活、边流转、条件边动态路由、类型化状态贯穿全程，天然支持循环与多代理。四大生产级能力——持久化执行、人机协同 interrupt、双层记忆、流式与可观测——让它能承载长时运行的复杂代理；生态上 Deep Agents 提供高层参考实现，LangSmith 补齐观测与部署。
落地建议：要让代理多步循环、断点恢复、中途人工介入的团队，从最小 StateGraph 示例起步，逐步加入条件边与持久化，高风险节点挂 interrupt；简单场景用 LangChain 组件或 Dify 平台更省力，复杂内核用 LangGraph、模型接入走 LiteLLM，是当前构建生产级代理的必要架构选择。
