LangGraph：Agent状态图

为什么需要 LangGraph：链式调用扛不住 Agent 的循环与恢复

LLM 应用早期用「链」或纯 Python 编排：一段接一段调 LLM，分支写在 if/else 里。到了 Agent 场景，三个工程问题浮出水面：其一，「思考 → 调工具 → 看结果 → 再思考」的反馈循环无法用线性链表达，最终写成递归或 while 循环加全局变量；其二，进程崩溃、请求超时后多轮对话状态全部丢失，无法从断点恢复；其三，并行分支、人工审批、多 Agent 协作这类生产需求没有统一抽象，每个团队各写一套。

LangGraph 把这些问题建模成状态图：节点是函数，边定义状态流转，图持有显式状态；运行层面提供检查点（每步落盘）、interrupt（暂停等人工输入）、流式输出与时间旅行调试，并把图编译成可嵌入任意服务的 Runnable。它以低层 API 起步，2024 年起迅速成为 Agent 生产化的主流选项之一。

与 LangChain 高层链式 API 不同，LangGraph 不替你封装 prompt 与模型路由，给的是状态机运行时。节点里可以自由调用任意函数——LangChain 组件、原生 API、数据库都行。这种「可控、可恢复、可观测」的特性，正是生产 Agent 基础设施所需要的。

安装与环境配置：3 步就绪

步骤一·建环境：需要 Python 3.9+（建议 3.11+），先建虚拟环境避免污染系统 Python。

步骤二·安装：pip 安装 langgraph 本体；接入 OpenAI 模型装 langchain-openai；需要自托管部署时再装 langgraph-cli。

步骤三·验证：打印版本号确认安装成功。

说明：langgraph 会自动拉取 langgraph-checkpoint、langgraph-sdk、langchain-core 等核心依赖，不需要手动安装。

python -m venv .venvsource .venv/bin/activate        # Windows: .venv\Scripts\activatepip install --upgrade pippip install langgraph langchain-openaipython -c "import langgraph; print(langgraph.__version__)"

快速上手：10 分钟跑通第一个带循环的状态图

最小流程 4 步：定义 State Schema → 实现节点函数 → 组装图 → compile 后 invoke。下面的例子不需要 API key，演示「循环 + 条件退出」。

1. 定义状态：messages 字段声明 Annotated[list, operator.add]，多个节点写入时自动拼接而非覆盖。

2. 实现节点：node_a / node_b 是普通函数，返回要更新的字段字典。

3. 组装图：add_node 注册节点；add_edge(START, “a“) 固定入口；add_conditional_edges(”a”, route, ……) 让 route 函数根据当前状态决定去 b 还是终止。

4. 执行：app.invoke 返回最终状态字典。

执行路径是 a → b → a → END：node_a 执行后 route 判断消息不足 3 条去 b，b 执行完回 a，再次 route 判定达到 3 条终止。关键在于「条件转移由路由函数读状态决定」，这正是 Agent 思考循环的底层机制。进阶方向：把节点换成 LLM 工具调用（用 prebuilt 的 create_react_agent），或在 compile 时传入 checkpointer 体验断点恢复。

import operatorfrom typing import Annotated, TypedDict from langgraph.graph import END, START, StateGraph  class State(TypedDict):    messages: Annotated[list, operator.add]  # 同 key 多次写入时按顺序拼接  def node_a(state: State) -> dict:    return {"messages": ["A 已执行"]}  def node_b(state: State) -> dict:    return {"messages": ["B 已执行"]}  def route(state: State) -> str:    # 消息累计 3 条就退出循环，否则回到 b    return END if len(state["messages"]) >= 3 else "b"  builder = StateGraph(State)builder.add_node("a", node_a)builder.add_node("b", node_b)builder.add_edge(START, "a")builder.add_conditional_edges("a", route, {"b": "b", END: END})builder.add_edge("b", "a") app = builder.compile()print(app.invoke({"messages": []})["messages"])# 输出：['A 已执行', 'B 已执行', 'A 已执行']

核心能力详解：5 大支柱

支柱一·StateGraph 显式状态：状态是全图共享的 TypedDict（或 pydantic 模型）。节点函数入参为当前状态，返回值按 key 合并进状态：未声明 reducer 的 key 直接覆盖，声明了 Annotated[list, operator.add] 的 key 走追加合并。分支汇聚、多 Agent 协作时，不同路径的产出能自然合并，不需要手工拼接上下文。编译产物是与 LangChain 生态一致的 Runnable，天然支持 invoke / stream / ainvoke。

支柱二·条件边与循环：Agent 的「观察-思考-行动」本质是环。add_conditional_edges 注册路由函数，读状态返回下一节点名，从而实现循环、早停、回退。0.2 起引入 Command，节点可直接返回 Command(goto=……, update=……) 同时决定去向与状态更新。注意图默认 recursion_limit=25，死循环会在超限时抛 GraphRecursionError。

支柱三·检查点持久化：compile() 传入 checkpointer 后，每个节点执行完状态即落盘。自带 MemorySaver（内存）、SqliteSaver（本地文件）、PostgresSaver（生产），社区另有 Redis、MongoDB 等实现。thread_id 是会话隔离键，同一 thread 的多次 invoke 从上次中断处继续——这是多轮记忆与任务恢复的基础；get_state_history 可回放任意历史状态，配合 update_state 做「时间旅行」调试。

支柱四·Human-in-the-loop：interrupt() 是暂停原语。节点里调用 interrupt(payload) 会停下图并把 payload 返回给外部调用方；外部通过 Command(resume=……)（或 LangGraph Platform 的 Assistants API）传回人工输入，图从断点继续。退款审批、人工修正 LLM 输出等流程都靠它实现。

支柱五·流式与多 Agent：stream() 支持 values（每节点后全量状态）、updates（增量）、messages（LLM token 级）、custom（自定义事件）四种模式。多 Agent 上，官方模式包括 Supervisor 主管路由、Handoff 转交、Send API 动态扇出（map-reduce，每个子任务走独立检查点分支）。

生产部署与监控：从上线到运维

部署方式一·LangGraph Platform（托管）：项目根目录放 langgraph.json（声明 graphs 入口、依赖与模型配置），关联 GitHub 仓库后平台自动构建部署，或本地用 langgraph-cli 的 langgraph deploy 推送。平台内置 Postgres 持久化、任务队列、并发控制与 LangSmith 观测，前端通过 Assistants API 按 thread_id 调用，是最省事的生产路径。

部署方式二·自托管 Docker：pip install langgraph-cli 后，用 langgraph build 构建镜像、langgraph dev 启动本地服务（0.1.x 版 CLI 命令为 langgraph up）。生产环境把检查点从内存切换为 Postgres（官方提供 PostgresSaver 文档），长时间运行任务建议接 Redis 队列，避免单实例进程重启丢状态。自托管适合私有化部署或成本敏感团队。

可观测性：LangSmith 自动记录每个节点的输入输出、LLM 调用与耗时，可按 thread_id 检索整条链路；不接入外部服务时，用 graph.get_state(thread_id) 查看当前检查点、get_state_history(thread_id) 查看历史版本。线上应盯三个指标：节点级延迟、GraphRecursionError 出现频率、interrupt 等待时长（反映人工审批瓶颈）。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>未声明 reducer 的字段会被覆盖：多节点写入同一 key 时，无 Annotated[list, operator.add] 等 reducer 的字段采用覆盖语义，后写覆盖先写，数据静默丢失。</li><li>配了 checkpointer 却漏传 thread_id：恢复会话与记忆都依赖 thread_id，漏传会直接抛错或每次当新会话处理，多轮功能全部失效。</li><li>忽略默认 recursion_limit=25：复杂循环图超过 25 步会抛 GraphRecursionError，需在 invoke 时显式调大，否则上线后流量一大必现。</li><li>异步框架里调同步 invoke：FastAPI 等事件循环中调用同步 invoke 会阻塞整个进程，应使用 ainvoke/astream；节点内也不要混用同步与异步工具调用。</li></ul>

版本迭代

LangGraph 从 2024 年初的图执行器起步，主线是「低层运行时 → Agent 生产平台」：0.2 引入 Command 并开放云平台预览，0.3 推出 LangGraph Platform 正式版与多 Agent 模式，0.4/0.5 聚焦长会话稳定性与 CLI 体验。（截至训练数据，可能已有更新版本）

AI 应用场景

常见误区

面试题