一、什么是 LangGraph

LangGraph 是由 LangChain Inc 开发的低级（low-level）编排框架，用于构建、管理和部署长时运行、具备状态的智能体（stateful agents）。它既可以作为 Python 包使用（langgraph），也提供对等的 JavaScript/TypeScript 实现 langgraphjs。其设计灵感来自 Pregel 与 Apache Beam，而公共接口的语义则借鉴自 NetworkX。资料来源：README.md

它可以独立使用，也可以与 LangChain 配合使用；并且当需要快速构建具备规划、子智能体和文件系统能力的智能体时，推荐基于 LangGraph 之上的高层包 Deep Agents。资料来源：README.md

1.1 项目定位

二、核心特性

LangGraph 在其官方文档中将自身定位为：*"low-level supporting infrastructure for any long-running, stateful workflow or agent"*。其核心项目括以下三项。资料来源：README.md

• Durable execution（持久化执行）：智能体可在失败后从中断点恢复，长时间运行也能精准续跑。
• Human-in-the-loop（人机协同）：在执行任意阶段暂停，允许用户审阅、修改智能体状态。
• Comprehensive memory（综合记忆）：结合短期线程状态与长期记忆（如 BaseStore）构建上下文。

下面是抽象能力的整体视图：

graph TD
    A[用户输入] --> B[StateGraph]
    B --> C[节点执行]
    C --> D{条件边 / Send}
    D -- 命中 A --> E[节点 A]
    D -- 命中 B --> F[节点 B]
    E --> G[Checkpoint / 持久化]
    F --> G
    G --> H[人机协同 / Interrupt]
    H --> C
    G --> I[流式输出 / 流到客户端]

三、生态组成

LangGraph 仓库是一个多包（monorepo）项目，包含核心包、预构建组件包、CLI 工具包和 SDK 包。各子包职责如下：

3.1 核心包 `langgraph`

核心包提供 StateGraph、START、END、add_messages 等基础原语。下面是 libs/cli/uv-examples/simple 中官方示例的简化展示：资料来源：libs/cli/uv-examples/simple/src/agent/graph.py

from collections.abc import Sequence
from typing import Annotated, TypedDict

from langchain_core.messages import AIMessage, BaseMessage
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]

def call_model(state: State) -> dict:
    message = AIMessage(content="Hello from simple uv agent!")
    return {"messages": [message]}

def should_continue(state: State):
    if len(state["messages"]) > 0:
        return END
    return "call_model"

workflow = StateGraph(State)
workflow.add_node("call_model", call_model)
workflow.add_edge(START, "call_model")
workflow.add_conditional_edges("call_model", should_continue)

graph = workflow.compile()

该模板演示了 StateGraph 的最小闭环：声明状态 → 注册节点 → 添加边与条件边 → compile() 得到可执行图。

JS/TS 端的等价形态由 Annotation.Root + messagesStateReducer 承担：资料来源：libs/cli/js-examples/src/agent/state.ts

import { Annotation, messagesStateReducer } from "@langchain/langgraph";

export const StateAnnotation = Annotation.Root({
  // Reducers 决定如何把节点返回值合并进状态
  messages: Annotation<BaseMessage[]>({
    reducer: messagesStateReducer,
    default: () => [],
  }),
});

3.2 预构建包 `langgraph-prebuilt`

重要：langgraph-prebuilt 是随 langgraph 一起发布的，不要单独安装。资料来源：libs/prebuilt/README.md

预构建包提供以下高层组件，资料来源：libs/prebuilt/README.md：

典型 create_react_agent 使用：

from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent

def search(query: str) -> str:
    """Call to surf the web."""
    if "sf" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."

app = create_react_agent(ChatAnthropic(model="claude-3-7-sonnet-latest"), [search])
app.invoke({"messages": [{"role": "user", "content": "what is the weather in sf"}]})

⚠️ 社区曾报告 create_react_agent 与 BaseStore 组合触发 TypeError: Type is not msgpack serializable: Send（#5891）。在使用持久化层时，注意工具返回对象需可被 msgpack 序列化，必要时包装为普通 dict/str。

3.3 命令行工具 `langgraph-cli`

langgraph-cli 提供项目脚手架、本地热重载开发、Docker 镜像构建等能力。资料来源：libs/cli/README.md

安装方式：

pip install langgraph-cli
# 开发模式（带热重载）
pip install "langgraph-cli[inmem]"

CLI 提供的 JS 模板依赖 @langchain/langgraph，项目结构示意（节选自 package.json）：资料来源：libs/cli/js-examples/package.json

{
  "name": "example-graph",
  "type": "module",
  "dependencies": {
    "@langchain/core": "^1.1.48",
    "@langchain/langgraph": "^1.3.3"
  },
  "scripts": {
    "dev": "langgraph dev",
    "build": "langgraph build"
  }
}

3.4 Python SDK `langgraph-sdk`

Python SDK 用于对接 LangSmith Deployment REST API。资料来源：libs/sdk-py/README.md

from langgraph_sdk import get_client

client = get_client()  # 本地默认 http://localhost:8123

assistants = await client.assistants.search()
agent = assistants[0]
thread = await client.threads.create()

input = {"messages": [{"role": "human", "content": "what's the weather in la"}]}
async for chunk in client.runs.stream(thread["thread_id"], agent["assistant_id"], input=input):
    print(chunk)

SDK 的已知限制（节选）：资料来源：libs/sdk-py/README.md

• WebSocket 传输需要 websockets>=14，且仅异步客户端（AsyncThreadStream）可用；同步客户端（SyncThreadStream）只支持 SSE。
• thread.extensions[name] 每次访问都会建立新订阅，建议复用变量。

3.5 JS SDK 迁移说明

This repository has been moved to langchain-ai/langgraphjs. 资料来源：libs/sdk-js/README.md

历史仓库中的 libs/sdk-js 已被迁移到 langgraphjs 仓库，PyPI/Monorepo 用户应直接引用 langgraphjs。

四、版本与发布节奏

最新发布：langgraph==1.2.4。该版本距 1.2.3 的变更点包括：

• release(langgraph): 1.2.4 (#7991)
• test(sdk-py): add factory-graph integration test exercising the server factory path (#7978)
• fix(langgraph): keep _on_started backward-compatible with overrides predating cause (#7987)

资料来源：社区上下文 Latest Release: langgraph==1.2.4。

五、与周边项目的协同关系

graph LR
    LG[LangGraph]
    LA[LangChain]
    DA[Deep Agents]
    LSD[LangSmith Deployment]
    LS[LangSmith]
    CL[langgraph-cli]
    SDK[langgraph-sdk / langgraphjs SDK]

    LG -->|底层编排| LA
    LG -->|构建于之上| DA
    LG -->|可观测 / 评估| LS
    LG -->|运行时| LSD
    CL -->|本地与 Docker 化| LG
    SDK -->|REST 客户端| LSD

• LangGraph + LangChain：LangChain 提供模型与组件集成，LangGraph 负责把它们编排为状态化工作流。资料来源：README.md
• LangGraph + Deep Agents：Deep Agents 是更高层的封装，依赖 LangGraph 的 StateGraph 与 BaseStore。
• LangGraph + LangSmith / LangSmith Deployment：用于评估、追踪与生产部署；langgraph-sdk 是官方提供的 Python 客户端。资料来源：libs/sdk-py/README.md

六、典型最小智能体骨架

下图展示了一个基于 langgraph 与 langgraph-prebuilt 的最小 ReAct 智能体在生态中的位置：

graph TD
    U[用户] -->|input| SDK[langgraph-sdk / UI]
    SDK --> LG[StateGraph 运行时]
    LG -->|调用| RA[create_react_agent]
    RA --> LLM[ChatAnthropic / 其他模型]
    LLM -->|tool_calls| TN[ToolNode]
    TN -->|ToolMessage| RA
    RA -->|流式输出| LG
    LG -->|Checkpoint| DB[(Postgres / SQLite)]
    LG -->|事件| LS[LangSmith]
    LG -->|结果| SDK

七、社区反馈与高频问题

以下问题在社区中讨论度较高，值得在选型与集成时提前关注：

八、扩展阅读入口

• 官方文档：docs.langchain.com/oss/python/langgraph/overview
• API 参考：reference.langchain.com/python/langgraph
• 快速开始：LangGraph Quickstart
• 高层包 Deep Agents
• 社区论坛：forum.langchain.com

See Also

• LangGraph 状态图（StateGraph）核心 API
• LangGraph 持久化与 Checkpoint 机制
• LangGraph 流式输出与人机协同
• LangGraph CLI 与本地开发流程

本页基于仓库根目录 README.md、libs/langgraph/README.md、libs/prebuilt/README.md、libs/cli/README.md、libs/sdk-py/README.md、libs/sdk-js/README.md 及 libs/cli 下的示例代码整理。如仓库结构或命令参数发生变化，请以官方文档为准。

概述

LangGraph 是一个用于构建有状态、长时运行智能体（stateful agents）的低层编排框架。其整体架构由两层组成:

• StateGraph：面向用户的声明式图定义 API，负责描述"图是什么样"——节点、边、状态 schema、入口和出口。
• Pregel：底层的BSP（Bulk Synchronous Parallel）执行引擎，负责将 StateGraph 编译为可运行的图，并在每一步（superstep）中调度节点、读写状态、推进计算。

这种"声明与执行分离"的设计让用户只需关注业务逻辑（即节点函数和状态形状），而无需手动管理并发、消息路由或持久化等横切关注点。LangGraph 在 README 中明确指出其灵感来自 Google 的 Pregel 与 Apache Beam，公共 API 风格借鉴自 NetworkX。资料来源：README.md

下图展示了 StateGraph 与 Pregel 在整个系统中的位置:

graph TD
    User[用户代码<br/>定义 State / Nodes / Edges] --> SG[StateGraph<br/>声明式图]
    SG -->|compile| P[Pregel<br/>可执行图]
    P --> Algo[Pregel 算法<br/>_algo.py]
    P --> Ch[Channels<br/>LastValue / Binop / Topic / EphemeralValue]
    P --> RT[Runtime<br/>configurable / context / store]
    Algo -->|tick / superstep| Tasks[Task 调度<br/>节点函数调用]
    Tasks --> Ch
    Ch -->|checkpoint| Persist[(Checkpoint / Store)]

概述

LangGraph 作为一个面向有状态代理（stateful agents）的低层编排框架，其核心能力之一是持久化执行（durable execution）：当代理在长时间运行中遭遇故障时，可自动从中断处恢复执行，并保留完整的中间状态。这一能力在项目自述中被明确列为 LangGraph 的关键价值之一（libs/langgraph/README.md）。

持久化能力在 LangGraph 中由两个相互独立又彼此协作的子系统共同支撑：

资料来源：libs/checkpoint/langgraph/checkpoint/base/__init__.py、libs/checkpoint/langgraph/store/base/__init__.py

检查点架构

核心抽象

LangGraph 的检查点子系统将"线程（thread）"作为状态隔离的基本单位。每次图执行（run）都在某个线程上推进，并在每个 super-step 完成后生成一个不可变的检查点对象。这样的设计直接源自 LangGraph 所借鉴的 Pregel 同步模型（libs/langgraph/README.md）。

graph TD
    A[START] --> B[Node A]
    B --> C[Node B]
    C --> D[Node C]
    D -->|条件路由| E[Node D1]
    D -->|条件路由| F[Node D2]
    E --> G[END]
    F --> G
    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#e1f5ff

图示说明：每次节点执行后（即每个 super-step），LangGraph 都会产生一个 Checkpoint 对象，其中包含：

• Channel values：所有通道（channel）在该 super-step 结束时的最终值
• Channel versions：每个通道对应的版本号，用于追踪状态来源
• Pending writes：尚未被刷写至通道的暂存写入
• Next versions：下一 super-step 计划写入的版本

资料来源：libs/checkpoint/langgraph/checkpoint/base/__init__.py

写入与读取生命周期

sequenceDiagram
    participant App as 用户应用
    participant Graph as StateGraph
    participant Saver as Checkpoint Saver
    participant Backend as 持久化后端

    App->>Graph: invoke/stream(config)
    Graph->>Saver: get_next_version(thread_id)
    Saver-->>Graph: 返回 channel version
    Graph->>Graph: 执行节点逻辑
    Graph->>Saver: put_writes(thread, task_id, writes)
    Saver->>Backend: 序列化 + 落盘
    Saver->>Backend: put / aput (checkpoint tuple)
    Graph-->>App: 逐步返回 chunk / 状态
    App->>Saver: get_tuple(config) (恢复/时间旅行)
    Saver->>Backend: 读取并反序列化
    Saver-->>App: 返回 Checkpoint 元组

写入流程的关键方法包括 put/aput（写入完整的检查点元组）以及 put_writes/aput_writes（写入尚未物化的中间写操作）。读取侧提供 get_tuple/aget_tuple 与 list/alist 用于线程内重放与历史浏览。

资料来源：libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py、libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py

符合性测试

libs/checkpoint-conformance 包提供统一的 validate 接口，用于验证第三方 Checkpoint 实现的接口一致性。这允许社区维护的存储后端在与 LangGraph 核心代码解耦的前提下，保持与官方一致的读写语义。

资料来源：libs/checkpoint-conformance/langgraph/checkpoint/conformance/validate.py

序列化机制

Serializer 接口

LangGraph 在检查点与存储之上抽象了 Serializer 协议，所有数据在被保存到任意后端之前都需经其处理。libs/checkpoint/langgraph/checkpoint/serde 中提供了多种实现：

资料来源：libs/checkpoint/langgraph/checkpoint/serde/__init__.py、libs/checkpoint/langgraph/checkpoint/serde/_msgpack.py、libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py、libs/checkpoint/langgraph/checkpoint/serde/encrypted.py

已知序列化陷阱

社区议题 #5891 报告了在 create_react_agent 配合使用 BaseStore 的工具时，会抛出 TypeError: Type is not msgpack serializable: Send。其根因是 Send（用于在边条件中触发动态 fan-out 的对象）默认不会被内置 msgpack 序列化器识别。规避思路通常是：

1. 在 Send 经由 Command 提交时，确保其对象是 langgraph.types.Send 的实例化结果；
2. 在工具节点返回的 ToolMessage 中避免直接回传 Send；
3. 必要时通过自定义 Serializer 注册针对 Send 的 fallback 编码函数。

资料来源：社区 Issue #5891

跨进程存储后端

内置后端

LangGraph 仓库中通过 libs/checkpoint-postgres 与 libs/checkpoint-sqlite 两个子项目分别提供生产级与轻量级实现：

SQLite 后端在初始集成测试与本地运行中通常是首选；进入多副本或长时间运行的生产环境时，推荐切换到 Postgres 后端并通过连接池（pool）控制并发。两种后端均实现了与 LangGraph 核心一致的 get/put/list 抽象。

资料来源：libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py、libs/checkpoint-postgres/langgraph/store/postgres/base.py、libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py、libs/checkpoint-sqlite/langgraph/store/sqlite/base.py

Postgres 后端的连接与故障

社区议题 #3716 反映了在多个版本中 langgraph-checkpoint-postgres 偶发 psycopg.OperationalError: sending query and params failed: SSL error: bad length。从错误形态看，根因通常与 SSL 握手时的 bytes sent 与 bytes received 长度字段异常有关，常见触发场景包括：

• 客户端通过代理（nginx、ALB、pgBouncer）在 TLS 终结后重新建立上游连接；
• 长生命周期连接在网络抖动后未正确重连；
• 与 pgvector 扩展并用时，大对象写入触发 large object 子协议。

缓解建议通常指向：在客户端驱动侧开启 tcp_keepalives_idle、调整 statement_timeout、升级 psycopg 至 ≥ 3.1，并视情况切换到 PgBouncer 的 transaction 模式而非 session 模式。

资料来源：社区 Issue #3716

长期存储与 BaseStore

Store 的语义差异

与"线程内短期记忆"的检查点不同，BaseStore 是一种跨线程、命名空间化的键值存储，常被用于以下场景：

• 跨多次会话记忆用户偏好；
• 在多智能体协作中共享中间事实；
• 缓存昂贵的外部调用结果。

数据组织方式如下：

graph LR
    NS["命名空间 (tuple of str)"] --> K1["key1"]
    NS --> K2["key2"]
    K1 --> V1["value (可 JSON/msgpack 序列化)"]
    K2 --> V2["value"]

BaseStore 接口通过 put / get / delete / search 等方法提供语义级 CRUD 与向量检索能力；get 与 search 在缺失时返回 None 或空列表，从不抛错，便于在节点内部安全使用。

资料来源：libs/checkpoint/langgraph/store/base/__init__.py

节点内访问方式

在 StateGraph 中，节点函数通常通过 Runtime（运行时上下文）拿到 Store 引用，而非全局变量。这样的好处是测试时可注入 mock 实现，且与配置（config.configurable）显式解耦。社区议题 #5023 提议的 config.configurable → context API 演进，正是希望让用户更直观地区分"运行时常量（context）"与"线程状态（state）"。

资料来源：社区 Issue #5023

错误处理与常见失败模式

状态更新错误

社区议题 #740 反复出现的 langgraph.errors.InvalidUpdateError: Must write to at least one of ['input', 'plan', 'past_steps', 'response'] 表明：在使用 TypedDict 定义状态时，节点函数必须至少返回声明的键之一，否则 LangGraph 会拒绝此次更新。常见根因包括：

资料来源：社区 Issue #740

v1 路线图中的相关变化

社区议题 #4973 收集了用户对 v1 路线图的反馈，多条意见聚焦于：

• 简化 context / configurable 的语义；
• 让 Checkpoint 与 Store 的命名空间、生命周期更显式；
• 统一 Send 的序列化行为。

这些方向直接关联到本页描述的持久化与跨进程存储子系统。资料来源：社区 Issue #4973

配置选项速查

下表汇总了在不同后端上启用持久化与跨进程存储时最常用的配置参数（与各自 README 与 docstring 保持一致；具体取值以代码为准）：

资料来源：libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py、libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py、libs/checkpoint/langgraph/store/base/__init__.py

端到端使用模式

下面示例将 *单线程检查点*、*跨线程 Store*、*序列化* 三个子系统串联起来。注意：示例基于 libs/cli/uv-examples/simple/src/agent/graph.py 与预置 README 中的最小骨架。

from typing import Annotated, Sequence, TypedDict

from langchain_core.messages import AIMessage, BaseMessage
from langgraph.checkpoint.postgres import PostgresSaver
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
from langgraph.graph import END, START, StateGraph, add_messages
from langgraph.store.base import BaseStore

class State(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]

def call_model(state: State, *, store: BaseStore) -> dict:
    # 从跨线程存储中读取长期偏好
    prefs = store.get(("user", "preferences"), "tone")
    tone = (prefs.value if prefs else "neutral")
    text = f"[{tone}] hello from persistent agent!"
    return {"messages": [AIMessage(content=text)]}

# 选择持久化后端：Postgres 适合跨进程
with PostgresSaver.from_conn_string("postgresql://user:pwd@host/db") as checkpointer:
    checkpointer.setup()  # 首次运行需建表
    workflow = StateGraph(State)
    workflow.add_node("call_model", call_model)
    workflow.add_edge(START, "call_model")
    workflow.add_edge("call_model", END)

    graph = workflow.compile(
        checkpointer=checkpointer,
        # store=...  # 通过 compile kwarg 注入长期存储
    )

    config = {"configurable": {"thread_id": "demo-1"}}
    result = graph.invoke({"messages": []}, config=config)

要点：

1. Checkpointer 与 Store 是正交的两套接口，可在 compile() 时按需组合。
2. 线程 ID 是 configurable 下的标准字段，用于隔离不同会话。
3. 首次运行需要调用 setup()，其内部会执行幂等的 DDL。
4. 节点函数可通过运行时上下文访问 store 等依赖，避免在节点内引用全局对象。

资料来源：libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py、libs/checkpoint/langgraph/store/base/__init__.py、libs/cli/uv-examples/simple/src/agent/graph.py

部署与运维视角

在通过 langgraph up（Docker）或 langgraph dev（本地）启动的 API 服务中，检查点与存储配置由服务启动器读取并注入到图工厂。这意味着：

• 同一份图定义可被多个进程/容器复用，但后端连接指向同一个 Postgres 库即可实现跨进程共享；
• 零代码改造即可将本地 SQLite 升级到 Postgres：仅修改 langgraph.json 中 checkpointer 配置项即可；
• LangSmith Deployment 在多副本部署下，强烈建议开启共享 Postgres + 独立 Store schema 的组合，以避免长事务影响检查点读写。

资料来源：libs/cli/README.md、libs/sdk-py/README.md、libs/langgraph/README.md

调试与可观测性

• 线程级时间旅行：graph.get_state(config) / graph.update_state(config, values) 允许在任意历史 super-step 上分支出新的执行路径。
• 历史回放：graph.get_state_history(config) 返回该线程下所有 CheckpointTuple，包含元数据中的 step、source（loop / input / update / fork）、parent_config 等。
• 跨线程检索：store.search(("namespace",), query=..., limit=...) 适合在调试时快速验证命名空间划分是否正确。

资料来源：libs/checkpoint/langgraph/checkpoint/base/__init__.py、libs/checkpoint/langgraph/store/base/__init__.py

最佳实践摘要

1. 优先使用 Postgres 作为生产环境的检查点与存储后端；本地调试可短暂使用 SQLite。
2. 统一 Serializer：在同一应用内避免混用多种 serializer，便于排查 Send 之类的边角问题。
3. 隔离命名空间：在 Store 中以业务维度划分 namespace，例如 ("org", org_id, "user", user_id)。
4. 谨慎设计状态 schema：节点函数必须能返回 schema 中声明的键，否则会触发 InvalidUpdateError。
5. 监控连接健康：在网络抖动或代理环境中显式开启 TCP keepalive，并关注 Postgres 驱动版本。
6. 遵循符合性测试：开发自有的 Checkpointer / Store 时，运行 libs/checkpoint-conformance 提供的 validate 函数以保证与核心兼容。

See Also

• libs/langgraph/README.md — 项目总览与持久化执行的价值定位
• libs/prebuilt/README.md — create_react_agent / ToolNode 等高层 API
• libs/sdk-py/README.md — 跨进程访问 LangSmith Deployment 的 Python SDK
• libs/cli/README.md — langgraph dev / langgraph up 等部署命令
• 社区议题：#4973（v1 路线图）、#5023（context API）、#5891（Send 序列化）、#740（InvalidUpdateError）、#3716（Postgres SSL）

概述

LangGraph 仓库不仅仅包含底层的 StateGraph 编排框架，还提供了一组围绕“代理开发与部署”的辅助库：langgraph-prebuilt（预置代理与工具节点）、langgraph-cli（命令行工具）和 langgraph-sdk（Python 客户端 SDK）。三者面向不同层次的开发者，组合起来构成了从原型到生产部署的完整工作流。

资料来源：libs/prebuilt/README.md、libs/cli/README.md、libs/sdk-py/README.md

三者关系

graph TD
    A[开发者] --> B[langgraph-cli]
    B --> C[脚手架与本地开发]
    B --> D[Docker 部署]
    E[langgraph-prebuilt] --> F[create_react_agent / ToolNode]
    E --> G[ValidationNode / Agent Inbox]
    H[langgraph-sdk] --> I[Assistants / Threads / Runs API]
    I --> J[LangSmith Deployment REST API]
    F --> K[StateGraph 运行时]
    G --> K
    K --> L[(Checkpoint / Store)]

预置代理（langgraph-prebuilt）

langgraph-prebuilt 是与 langgraph 核心包一同分发的高层 API 库。注意仓库中明确指出：此库应随 langgraph 一起安装，不应单独安装。

[!IMPORTANT]

This library is meant to be bundled with langgraph, don't install it directly

资料来源：libs/prebuilt/README.md

create_react_agent

create_react_agent 是工具调用型 ReAct 代理的高层实现，它把聊天模型、工具列表以及提示词组合成一个可调用的 StateGraph 应用。

from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent

def search(query: str):
    """Call to surf the web."""
    if "sf" in query.lower() or "san francisco" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."

tools = [search]
model = ChatAnthropic(model="claude-3-7-sonnet-latest")

app = create_react_agent(model, tools)
app.invoke({"messages": [{"role": "user", "content": "what is the weather in sf"}]})

资料来源：libs/prebuilt/README.md、libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py

#### 关键参数

ToolNode

ToolNode 是把模型发出的 tool_calls 实际分发到对应 Python 函数的节点。在 ReAct 流程里，它被插入到模型节点与循环条件之间。

graph TD
    A[START] --> B[agent 节点<br/>ChatModel]
    B --> C{有 tool_calls?}
    C -- 是 --> D[ToolNode]
    D --> B
    C -- 否 --> E[END]

资料来源：libs/prebuilt/README.md、libs/prebuilt/langgraph/prebuilt/tool_node.py

ValidationNode

ValidationNode 根据 Pydantic 模式对工具调用进行校验，校验失败时可以抛错或返回结构化错误。它常被用于在 ToolNode 之前对模型输出做一次“闸门”：

from pydantic import BaseModel, field_validator
from langgraph.prebuilt import ValidationNode
from langchain_core.messages import AIMessage

class SelectNumber(BaseModel):
    a: int

    @field_validator("a")
    def a_must_be_meaningful(cls, v):
        if v != 37:
            raise ValueError("Only 37 is allowed")
        return v

validation_node = ValidationNode([SelectNumber])
validation_node.invoke({
    "messages": [AIMessage("", tool_calls=[{"name": "SelectNumber", "args": {"a": 42}, "id": "1"}])]
})

资料来源：libs/prebuilt/README.md、libs/prebuilt/langgraph/prebuilt/tool_validator.py

Agent Inbox（人类中断协议）

Agent Inbox 是 LangChain 团队推出的统一人机协作 UI 协议。langgraph.prebuilt.interrupt 模块导出了与该协议协同工作所需的 HumanInterrupt / HumanResponse 模式。

from langgraph.types import interrupt
from langgraph.prebuilt.interrupt import HumanInterrupt, HumanResponse

def my_graph_function():
    tool_call = state["messages"][-1].tool_calls[0]
    request: HumanInterrupt = {
        "action_request": {
            "action": tool_call['name'],
            "args": tool_call['args']
        },
        "config": {
            "allow_ignore": True
        }
    }
    response = interrupt(request)

资料来源：libs/prebuilt/README.md、libs/prebuilt/langgraph/prebuilt/interrupt.py

社区关注点

• 序列化问题：Issue #5891 报告了 create_react_agent 与使用 BaseStore 的工具组合时会触发 TypeError: Type is not msgpack serializable: Send。这通常源于内部 Send 对象未在 checkpoint 序列化路径中被正确处理。
• 上下文 API 改造：Issue #5023 提议将 config.configurable 改造为更直观的 context API，简化不可变上下文的传递；该讨论直接影响预置代理的调用形式。
• 状态写入校验：Issue #740 引发大量 InvalidUpdateError: Must write to at least one of [...] 报错。该错误来自 langgraph.errors.InvalidUpdateError，发生在节点返回的字典未覆盖状态 schema 中任何一个键时。

LangGraph CLI

langgraph-cli 是官方命令行工具，目标是“创建 → 本地开发 → Docker 化 → 远程部署”全流程。

安装

pip install langgraph-cli
# 含内存后端的开发模式（支持热重载）
pip install "langgraph-cli[inmem]"

资料来源：libs/cli/README.md

核心子命令

资料来源：libs/cli/README.md、libs/cli/langgraph_cli/cli.py

配置（langgraph.json）

CLI 通过 langgraph.json（默认路径，可通过 -c 覆盖）声明图入口、依赖与环境变量。配置文件解析逻辑见 libs/cli/langgraph_cli/config.py，Docker 镜像生成逻辑见 libs/cli/langgraph_cli/docker.py，远程部署逻辑见 libs/cli/langgraph_cli/deploy.py。

资料来源：libs/cli/langgraph_cli/config.py、libs/cli/langgraph_cli/docker.py、libs/cli/langgraph_cli/deploy.py

项目结构样例

#### 简单单包项目

# libs/cli/uv-examples/simple/src/agent/graph.py
from collections.abc import Sequence
from typing import Annotated, TypedDict
from langchain_core.messages import AIMessage, BaseMessage
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]

def call_model(state: State) -> dict:
    return {"messages": [AIMessage(content="Hello from simple uv agent!")]}

def should_continue(state: State):
    if len(state["messages"]) > 0:
        return END
    return "call_model"

workflow = StateGraph(State)
workflow.add_node("call_model", call_model)
workflow.add_edge(START, "call_model")
workflow.add_conditional_edges("call_model", should_continue)

graph = workflow.compile()

资料来源：libs/cli/uv-examples/simple/src/agent/graph.py

#### 单仓多包（Monorepo）

python-monorepo-example 与 uv-examples/monorepo 演示了共享 State、共享工具模块的多应用结构：

• 状态定义集中在 apps/agent/src/agent/state.py，便于在多个图之间复用。资料来源：libs/cli/python-monorepo-example/apps/agent/src/agent/state.py
• 图节点可以引用 shared 与 common 包中的辅助函数。资料来源：libs/cli/python-monorepo-example/apps/agent/src/agent/graph.py、libs/cli/uv-examples/monorepo/apps/agent/src/agent/graph.py

#### JavaScript/TypeScript 模板

js-examples 是一个 TypeScript 模板，package.json 声明依赖 @langchain/core 与 @langchain/langgraph，并通过 langgraph template lock 自动生成 config_schemas 段：

{
  "dependencies": {
    "@langchain/core": "^1.1.48",
    "@langchain/langgraph": "^1.3.3"
  }
}

资料来源：libs/cli/js-examples/package.json、libs/cli/js-examples/src/agent/state.ts、libs/cli/js-examples/README.md

本地开发与 Studio 协同

CLI 启动的开发服务器会默认打开 LangGraph Studio（在 langgraph dev 中可使用 --no-browser 关闭）。模板说明建议把项目根目录下的 .env 拷贝为 .env.example，再在 Studio 中迭代。资料来源：libs/cli/js-examples/README.md

Python SDK（langgraph-sdk）

langgraph-sdk 是与 LangSmith Deployment REST API 交互的 Python 客户端。它同时提供同步和异步两种风格，但 WebSocket 流式传输仅在异步客户端可用。

已知限制

• WebSocket 传输需要 websockets>=14，且仅在异步客户端（AsyncThreadStream）中可用。同步客户端（SyncThreadStream）只使用 SSE。
• thread.extensions[name] 每次按名称访问都会开启一个新订阅；建议把投影赋给变量复用，而不是在多次迭代里反复索引。
• 同步流式传输驱动生命周期监听器——同步流路径上的行为差异需注意。

资料来源：libs/sdk-py/README.md

快速上手

pip install -U langgraph-sdk

from langgraph_sdk import get_client

# 本地 dev 服务器默认指向 http://localhost:8123
client = get_client()

# 列出所有 assistants（每个在 config 中注册的图都会自动创建一个）
assistants = await client.assistants.search()
agent = assistants[0]

# 创建新线程
thread = await client.threads.create()

# 启动流式运行
input = {"messages": [{"role": "human", "content": "what's the weather in la"}]}
async for chunk in client.runs.stream(thread['thread_id'], agent['assistant_id'], input=input):
    print(chunk)

资料来源：libs/sdk-py/README.md、libs/sdk-py/langgraph_sdk/client.py

主要 API 命名空间

graph TD
    Client[langgraph-sdk 客户端] --> A[Assistants API]
    Client --> B[Threads API]
    Client --> C[Runs API]
    A --> R[LangSmith Deployment REST API]
    B --> R
    C --> R
    R --> P[langgraph runtime]
    P --> S[(Checkpointer / Store)]

资料来源：libs/sdk-py/langgraph_sdk/client.py、libs/sdk-py/langgraph_sdk/_async/runs.py、libs/sdk-py/langgraph_sdk/_async/threads.py

与 Checkpointer 协同

langgraph-sdk 本身不直接管理 checkpoint 存储；checkpoint 由服务端（langgraph dev / langgraph up 启动的进程）通过 langgraph-checkpoint-sqlite、langgraph-checkpoint-postgres 等后端持久化。客户端通过 threads 命名空间查询、恢复历史状态。

资料来源：libs/checkpoint-sqlite/README.md

#### 社区已知问题

• Postgres SSL 错误：Issue #3716 报告 langgraph-checkpoint-postgres 跨多版本出现 psycopg.OperationalError: sending query and params failed: SSL error: bad length。当通过 SDK 触发长期运行并触发 Postgres 后端写入时需特别留意。
• Checkpoint 快照：SqliteSaver / AsyncSqliteSaver 提供了标准的 put、get、list API，建议参考以下结构化快照设计后端 schema。资料来源：libs/checkpoint-sqlite/README.md

常见失败模式与排查

与核心 LangGraph 的关系

资料来源：libs/langgraph/README.md、libs/prebuilt/README.md、libs/cli/README.md、libs/sdk-py/README.md

版本与发布

仓库当前最新发布的 Python 包为 langgraph==1.2.4。自 1.2.3 起的变化包括：

资料来源：仓库 Release Notes 1.2.4（基于 community context 中提供的最新发布摘要）

参见

• LangGraph 核心文档 — 包含 StateGraph、持久化、人机协作等概念指南
• LangGraph API Reference — 全部公共类与方法
• LangGraph CLI README — 命令行子命令完整说明
• langgraph-sdk README — Python SDK 快速上手
• langgraph-prebuilt README — create_react_agent 等高层 API
• langgraph-checkpoint-sqlite README — 内置 SQLite checkpoint 后端
• 相关 Issue：#5023 context API 提案、#4973 v1 路线图、#5891 Send 序列化、#740 InvalidUpdateError、#3716 Postgres SSL

Pitfall Log / 踩坑日志

项目：langchain-ai/langgraph

摘要：发现 10 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：LangGraph API 0.7.60: Redis TLS cluster PubSub fails with port 0 (go-redis v9.18.0 regression)。

1. 安全/权限坑 · 来源证据：LangGraph API 0.7.60: Redis TLS cluster PubSub fails with port 0 (go-redis v9.18.0 regression)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LangGraph API 0.7.60: Redis TLS cluster PubSub fails with port 0 (go-redis v9.18.0 regression)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraph/issues/6987 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：ToolNode accepts ToolMessage results bound to sibling tool_call_id values

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ToolNode accepts ToolMessage results bound to sibling tool_call_id values
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraph/issues/7989 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:676672661 | https://github.com/langchain-ai/langgraph | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:676672661 | https://github.com/langchain-ai/langgraph | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:676672661 | https://github.com/langchain-ai/langgraph | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:676672661 | https://github.com/langchain-ai/langgraph | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：Feature request: OWASP ASI06 memory poisoning defense for LangGraph agent state/checkpointer

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature request: OWASP ASI06 memory poisoning defense for LangGraph agent state/checkpointer
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraph/issues/7798 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：Run Cancellation Causes Loss of Streamed State Not Yet Persisted as a Checkpoint

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Run Cancellation Causes Loss of Streamed State Not Yet Persisted as a Checkpoint
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/langchain-ai/langgraph/issues/5672 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:676672661 | https://github.com/langchain-ai/langgraph | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:676672661 | https://github.com/langchain-ai/langgraph | release_recency=unknown