# https://github.com/langchain-ai/langgraphjs 项目说明书 生成时间：2026-06-18 08:56:18 UTC ## 目录 - [Repository Overview and Monorepo Structure](#page-1) - [Core Graph Engine: StateGraph, Channels, and Pregel](#page-2) - [Client SDK, Streaming Protocol, and Framework Hooks](#page-3) - [Persistence (Checkpoints), Server API, CLI, and Deployment](#page-4) ## Repository Overview and Monorepo Structure ### 相关页面 相关主题：[Core Graph Engine: StateGraph, Channels, and Pregel](#page-2), [Client SDK, Streaming Protocol, and Framework Hooks](#page-3), [Persistence (Checkpoints), Server API, CLI, and Deployment](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md) - [libs/langgraph-core/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/package.json) - [libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json) - [libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json) - [libs/langgraph-cua/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/package.json) - [libs/create-langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/package.json) - [libs/sdk-vue/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md) - [libs/sdk-angular/src/use-stream.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/src/use-stream.ts) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [examples/quickstart/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/examples/quickstart/package.json) - [examples/how-tos/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/examples/how-tos/package.json)
# 仓库概览与 Monorepo 结构 ## 项目定位与目标 `langgraphjs` 是 LangChain 官方维护的 JavaScript/TypeScript 实现，用于构建**有状态、多角色（multi-actor）的大语言模型应用**。仓库自述文件强调，该库为开发者提供基于图（graph）的编排原语，以便在生产环境中可靠地协调 LLM 调用、工具调用与人工介入。资料来源：[README.md:1-30]() 设计上，`langgraphjs` 借鉴了 Google 的 [Pregel](https://research.google/pubs/pub37252/) 与 [Apache Beam](https://beam.apache.org/) 的执行模型，并参考 [NetworkX](https://networkx.org/documentation/latest/) 的图 API 风格。公共 API 允许仅使用核心 LangGraph 库，不强制依赖 LangChain 本身。资料来源：[README.md:60-72]() ## Monorepo 拓扑与工作区结构 仓库根目录采用 **pnpm 工作区 + Turborepo** 的多包管理模式。`libs/` 目录下按职责拆分为多个独立可发布的 npm 包，每个包都自带 `package.json`、`README.md`、`src/` 与 `dist/`，并通过 `peerDependencies` 与 `workspace:*` 协议相互引用。资料来源：[libs/langgraph-core/package.json:1-40]() [libs/langgraph/package.json:1-40]() 下表总结了主要子包及其职责： | 子包目录 | npm 名称 | 关键职责 | | --- | --- | --- | | `libs/langgraph-core` | `@langchain/langgraph` | 核心图执行、状态管理、检查点抽象 | | `libs/langgraph` | `langgraph` | 在 `langgraph-core` 之上提供的运行时入口与兼容层 | | `libs/checkpoint` | `@langchain/langgraph-checkpoint` | 检查点持久化与 Store 接口 | | `libs/create-langgraph` | `create-langgraph` | 项目脚手架 CLI（`npx create-langgraph`） | | `libs/langgraph-cua` | `@langchain/langgraph-cua` | 基于 LangGraph 的 Computer Use Agent 实现 | | `libs/sdk-vue`、`libs/sdk-angular` | `@langchain/vue`、`@langchain/angular` | 框架集成 SDK，提供 `useStream` 等响应式 hook | 资料来源：[libs/langgraph-core/package.json:1-40]() [libs/langgraph/package.json:1-20]() [libs/checkpoint/package.json:1-30]() [libs/create-langgraph/package.json:1-20]() [libs/langgraph-cua/package.json:1-40]() ## 包之间的依赖关系 ```mermaid graph TD A["@langchain/langgraph (libs/langgraph-core)"] --> B["@langchain/langgraph-checkpoint (libs/checkpoint)"] C["langgraph (libs/langgraph)"] --> A D["@langchain/langgraph-cua"] --> C E["create-langgraph CLI"] -.scaffolds.-> C F["@langchain/vue / @langchain/angular SDK"] --> G["@langchain/langgraph-sdk"] G -.remote runs.-> A ``` 核心关系链：`langgraph` 公开包仅依赖 `@langchain/langgraph`，而 `@langchain/langgraph` 又依赖 `@langchain/langgraph-checkpoint`。检查点包定义了 `BaseStore`、`PutOperation` 等基础接口，供不同后端实现遵循。资料来源：[libs/langgraph/package.json:30-44]() [libs/langgraph-core/package.json:30-44]() [libs/checkpoint/src/store/base.ts:1-50]() 框架 SDK（Vue/Angular）通过 `useStream` 等 hook 暴露流式响应、工具调用解析、中断（interrupts）以及运行生命周期状态（如 `isLoading`、`interrupt`），它们与 LangGraph Platform 的远程运行配合使用。资料来源：[libs/sdk-angular/src/use-stream.ts:1-30]() [libs/sdk-vue/README.md:1-20]() ## 示例与脚手架 `examples/` 目录集中放置教程与端到端样例，每个子目录均为独立的 pnpm 包，共享同一份依赖声明模板（`@langchain/openai`、`@langchain/anthropic`、`@langchain/tavily`、`zod` 等）。常见示例包括： - `examples/quickstart` —— 最简入门 - `examples/how-tos` —— 分主题的用法集合 - `examples/rag`、`examples/reflection`、`examples/rewoo`、`examples/plan-and-execute` —— 进阶 Agent 范式 资料来源：[examples/quickstart/package.json:1-20]() [examples/how-tos/package.json:1-20]() 对于新项目，`create-langgraph` CLI 既能下载模板项目，又能通过 `npx create-langgraph config` 扫描现有仓库，自动识别 `createAgent()`、`new StateGraph(...).compile()`、`workflow.compile()` 三类导出模式，并生成 `langgraph.json`。**仅已导出的 agent 会被纳入配置**，未导出者会以警告形式列出。资料来源：[libs/create-langgraph/README.md:1-50]() ## 构建、运行时与版本约束 所有库均声明 `"type": "module"`，主入口同时提供 ESM 与 CJS 两种解析路径（通过 `exports` 字段的 `import` / `require` 子句区分）。`engines.node` 约束为 `>=18`（核心库为 `>=20`），保证 `async_hooks` 等现代 Node API 可用。资料来源：[libs/langgraph-core/package.json:5-44]() [libs/checkpoint/package.json:5-30]() 构建管线使用共享脚本 `pnpm turbo build:internal --filter=`，内部调用 `@langchain/build` 编译；测试使用 `vitest`，并区分 `test`、`test:watch`、`test:int`、`test:browser` 等模式。这种统一抽象让核心库、SDK、CLI 三类产物能在同一仓库内独立演进。资料来源：[libs/langgraph-core/package.json:18-30]() [libs/langgraph-cua/package.json:12-30]() ## 社区关注点与已知差异 仓库的 issue 列表反映出用户在不同运行环境下遇到的痛点：例如 `async_hooks` 在浏览器侧的兼容问题（[#1699](https://github.com/langchain-ai/langgraphjs/issues/1699)）、LangGraph Studio 对类内构建的 graph 的支持差异（[#1722](https://github.com/langchain-ai/langgraphjs/issues/1722)）、以及 `useStream` 通过 Next.js 代理时的状态更新问题（[#1295](https://github.com/langchain-ai/langgraphjs/issues/1295)）。这些上下文也解释了 SDK 包持续维护 `useStream` API 与传输类的原因。资料来源：[libs/sdk-angular/src/use-stream.ts:1-30]() [libs/sdk-vue/README.md:1-20]() ## See Also - LangGraph 核心概念与 API：[`libs/langgraph-core/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md) - 检查点与 Store 接口：[`libs/checkpoint/src/store/base.ts`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - 项目脚手架 CLI：[`libs/create-langgraph/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - Vue SDK 使用指南：[`libs/sdk-vue/README.md`](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md) --- ## Core Graph Engine: StateGraph, Channels, and Pregel ### 相关页面 相关主题：[Repository Overview and Monorepo Structure](#page-1), [Client SDK, Streaming Protocol, and Framework Hooks](#page-3), [Persistence (Checkpoints), Server API, CLI, and Deployment](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md) - [libs/langgraph-core/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md) - [libs/langgraph-core/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/package.json) - [libs/langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md) - [libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json) - [libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) - [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - [libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md) - [libs/langgraph-supervisor/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md) - [libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md)
# Core Graph Engine: StateGraph、Channels 与 Pregel ## 概述与定位 LangGraph.js 的**核心图引擎**是构建有状态、多角色 LLM 应用的运行时基础。该项目在多个 README 中明确指出：LangGraph 受到 [Pregel](https://research.google/pubs/pub37252/) 与 [Apache Beam](https://beam.apache.org/) 的启发，公共接口则借鉴自 [NetworkX](https://networkx.org/documentation/latest/)。资料来源：[README.md](https://github.com/langchain-ai/langgraphjs/blob/main/README.md) 仓库采用 monorepo 结构，将图引擎拆分为两个核心 npm 包： | 包名 | 版本 | 作用 | |------|------|------| | `langgraph` | 1.0.44 | 用户面向的主入口，重新导出 `langgraph-core` | | `@langchain/langgraph-core` | （workspace） | 核心图抽象：`StateGraph`、Channels、Pregel 运行时 | | `@langchain/langgraph-checkpoint` | 1.1.2 | Checkpoint 与持久化抽象（基类） | 资料来源：[libs/langgraph/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/package.json)、[libs/langgraph-core/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/package.json)、[libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json) `langgraph-core` 通过多入口字段暴露子模块，例如 `./zod/schema`，表明核心引擎自带 Zod 集成用于状态模式校验。资料来源：[libs/langgraph-core/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/package.json) ## StateGraph：状态模式的声明式定义 `StateGraph` 是用户构建图时最常使用的入口。`create-langgraph` 的文档描述了三种被自动检测的声明模式： ```typescript // 使用 createAgent export const agent = createAgent({ model, tools }); // 使用 StateGraph export const graph = new StateGraph(annotation).compile(); // 使用 workflow builder export const app = workflow.compile(); ``` 资料来源：[libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) 其关键设计要点为： - **Annotation 驱动的状态**：通过 `StateGraph(annotation)` 传入状态注解，自动派生出 channel 与 reducer 映射。 - **节点函数**：节点接收当前状态并返回部分更新，由核心引擎合并。 - **边与条件路由**：支持固定边与条件函数，从而实现循环、分支与人机协同（human-in-the-loop）。 - **`.compile()`**：将声明式图编译为可执行的 Pregel 运行时实例。 社区中较常见的痛点是 **LangGraph Studio 不会显示在类（class）内部构建的 Chat 标签**（issue #1722，共 26 条评论），该问题正是与 `StateGraph` 实例化与导出方式相关，需要确保编译后的图在模块顶层 `export`。资料来源：[libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) ## Channels：状态的读写抽象 Channel 是核心引擎中**管理单个状态字段**的基本单元，提供了隔离的写入/读取语义与更新合并规则。 - Channel 是 `StateGraph` 在编译阶段根据 annotation 自动生成的底层数据结构，每个被声明的状态字段对应一个 channel 实例。 - 由于 LangGraph 受到 [Pregel](https://research.google/pubs/pub37252/) 与 [Apache Beam](https://beam.apache.org/) 的启发，Channel 的更新语义（`update`/`consume`）与 Beam 的 `PCollection` 思想类似——只有显式标记已消费的值才会被下一轮 superstep 看到。 - Channel 还支持 reducer（如 `messages` 字段默认追加），通过 `messages_reducer` 实现对话历史的累积。 ```mermaid flowchart LR A[State Annotation] --> B[StateGraph 编译] B --> C[Channels 映射] C --> D[Pregel Superstep] D --> E{有下一节点?} E -- 是 --> F[节点函数读取] F --> G[写入 Channel] G --> D E -- 否 --> H[Checkpoint 持久化] ``` ## Pregel 风格的执行模型 核心引擎采用 **Pregel 风格的同步超级步（superstep）模型**： 1. 每个 superstep 中，所有被调度的节点以**当前快照状态**作为输入并发执行。 2. 节点返回的部分更新被写入到对应的 channel，不会立即覆盖全局状态。 3. 当本轮 superstep 中所有节点执行完毕后，引擎统一将 channel 的写入合并到状态中，并依据条件边决定下一轮要激活的节点。 4. 若存在 checkpoint saver，则在每一步 superstep 之后持久化。 资料来源：[libs/checkpoint/src/store/base.ts](https://github.com/langgraph-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts)、[libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json) Pregel 模型直接带来三项关键能力： - **流式输出（Streaming）**：每个 superstep 都可对外发出增量事件，从而支持 token 级、节点级、状态级的多种 stream 模式。 - **人机协同**：执行可暂停在某个 superstep，等待外部输入再恢复，这正是 checkpoint 的核心价值。 - **时间旅行 / 重放**：依赖持久化的 checkpoint 可回放到任意历史 superstep。 社区中 [`useStream` Hook 在代理后无法更新消息](https://github.com/langchain-ai/langgraphjs/issues/1295)（issue #1295）即与 superstep 流事件通过 SSE 协议跨代理透传有关——开发者需要保证代理正确转发 LangGraph 的流式事件格式。 ## Checkpoint 与存储抽象 `@langchain/langgraph-checkpoint` 包提供了 checkpoint saver 的**基础接口**，对外暴露统一的存储/读取 API。资料来源：[libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) 在基础 store 接口中定义了关键操作，例如 `PutOperation`： - `namespace: string[]` —— 层级化路径，作为类文件夹结构组织条目。 - `key: string` —— 命名空间内的唯一标识。 - `value: Record | null` —— JSON 可序列化的载荷；为 `null` 时表示删除。 - 索引控制参数 —— 控制字段是否被索引以支持搜索。 `query` 参数允许按字符串进行最近邻式语义检索，例如 `query: "machine learning papers from 2023"`。资料来源：[libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) Checkpoint 库同时被上层多智能体库使用，例如： - `@langchain/langgraph-swarm`（群聊式多智能体） - `@langchain/langgraph-supervisor`（层级监督者多智能体） - `@langchain/langgraph-cua`（Computer Use Agent） 它们都依赖核心引擎的流式、记忆与人机协同能力。资料来源：[libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md)、[libs/langgraph-supervisor/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-supervisor/README.md)、[libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) ## 常见失败模式与注意事项 | 现象 | 根因 | 参考 | |------|------|------| | Studio 不显示 Chat 标签 | `StateGraph` 实例在 class 内部未 `export` | issue #1722 | | `useStream` 消息不更新 | 代理未透传 SSE 流事件 | issue #1295 | | 浏览器中使用 `AsyncLocalStorage` 报错 | `@langchain/core` 1.0.0-alpha.x 在浏览器环境未注入 `async_hooks` | issue #1699 | | Python 版可可视化 PNG，JS 版不可 | JS 暂未实现图渲染后端 | issue #107 | ## 参见 - [Streaming 与事件流协议](https://langchain-ai.github.io/langgraphjs/how-tos/#streaming) - [Checkpoint 与记忆](https://langchain-ai.github.io/langgraphjs/concepts/memory/) - [人机协同（Human-in-the-loop）](https://langchain-ai.github.io/langgraphjs/concepts/human_in_the_loop/) - [@langchain/langgraph-sdk 客户端](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) - [Pregel 论文](https://research.google/pubs/pub37252/) --- ## Client SDK, Streaming Protocol, and Framework Hooks ### 相关页面 相关主题：[Repository Overview and Monorepo Structure](#page-1), [Core Graph Engine: StateGraph, Channels, and Pregel](#page-2), [Persistence (Checkpoints), Server API, CLI, and Deployment](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) - [libs/sdk-vue/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md) - [libs/sdk-svelte/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/README.md) - [libs/sdk-angular/src/use-stream.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/src/use-stream.ts) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - [libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) - [libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md) - [libs/langgraph-core/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md) - [libs/langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md)
# 客户端 SDK、流式协议与框架 Hook ## 概述与定位 LangGraph.js 的客户端 SDK 与流式协议层为前端框架（React、Vue、Svelte、Angular 等）提供了一套统一的接入方式，让浏览器或 Node.js 端应用能够与运行中的 LangGraph 图（Graph）进行实时、低延迟的双向通信。整个客户端栈由 `@langchain/langgraph-sdk`（核心传输与子客户端）、`@langchain/vue`、`@langchain/svelte` 与 Angular 包中的 `useStream` 共同组成。 根据 [libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) 的描述，SDK 的核心职责是「创建与管理 assistants、threads、runs、cron schedules 与 KV store，并实时流式推送图执行过程」。默认连接地址是 `http://localhost:2024`，对应 `langgraph dev` 本地开发服务器。 | 子客户端 | 职责 | 文档入口 | | --- | --- | --- | | `client.threads` | 创建线程、管理状态、**流式**运行 | `Threads` 与 `Streaming` 文档 | | `client.assistants` | 对 assistants（schemas、graphs、versions）进行 CRUD | `Assistants` 文档 | | `client.runs` | 触发 / 加入 / 取消运行（非流式） | `Runs`（遗留接口）文档 | | `client.crons` | 调度周期性运行 | `Crons` 文档 | | `client.store` | 带命名空间与语义搜索的 KV 存储 | `Store` 文档 | 资料来源：[libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) ## 核心 SDK 与流式协议 ### `ThreadStream` 流式通道 `client.threads.stream(...)` 返回一个 `ThreadStream` 对象，提供多种类型化、惰性（lazy）投影，让前端无需关心底层 SSE / WebSocket 细节即可消费数据。常用字段包括： - `thread.messages` / `thread.toolCalls`：组装后的聊天输出与工具调用； - `thread.values` / `thread.output`：图状态与最终结果； - `thread.interrupts` / `thread.interrupted`：人机协同（human-in-the-loop）中断； - `thread.subgraphs` / `thread.subagents`：嵌套图 / Deep Agent 的子执行轨迹； - `thread.extensions.`：类型化自定义服务器投影； - `thread.audio` / `thread.images` / `thread.video` / `thread.files`：多媒体通道。 资料来源：[libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) ### 快速上手示例 ```ts import { Client } from "@langchain/langgraph-sdk"; const client = new Client({ apiUrl: "http://localhost:2024" }); // 推荐的线程中心化流式入口 const thread = client.threads.stream({ assistantId: "my-agent" }); await thread.run.start({ input: { messages: [{ role: "user", content: "hello" }] }, }); for await (const message of thread.messages) { for await (const token of message.text) { process.stdout.write(token); } } console.log(await thread.output); await thread.close(); ``` 资料来源：[libs/sdk/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk/README.md) > 社区关注点：Issue #504 多次提及希望 LangGraph 兼容 Vercel 的 Data Stream Protocol，以便在已使用 `ai` SDK 的 React 应用中无缝接入。`ThreadStream` 的 `messages` / `toolCalls` 等强类型投影正是为这类场景设计，可经轻量适配层映射到 Vercel 的数据流格式。 ## 框架 Hook 与响应式集成 ### Vue 集成 `@langchain/vue` 通过 `useStream` 将 LangGraph 代理绑定到 Vue 组件，响应式字段以 getter 形式暴露在稳定的 `stream` 句柄上。组件模板中可直接访问 `stream.messages`、`stream.isLoading` 等，配合 `stream.submit(...)` 即可发送消息。 资料来源：[libs/sdk-vue/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md) ### Svelte 5 集成 `@langchain/svelte` 同样基于 Svelte 5 runes，通过 `useStream` 返回响应式句柄，模板与 `$derived` 表达式会自动追踪更新。重要提示：**必须通过 `stream.xxx` 访问字段**，因为解构会冻结值。 ```svelte {#each stream.messages as msg (msg.id)}
{msg.content}
{/each} ``` 资料来源：[libs/sdk-svelte/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-svelte/README.md) ### Angular 集成 Angular 包在 [libs/sdk-angular/src/use-stream.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/src/use-stream.ts) 中导出 `useStream`，利用 Angular Signals 提供响应式能力。关键字段包括： - `toolCalls: Signal[]>`：从 `tools` 通道组装得到的完整 `AssembledToolCall`（含 name、args、id），可用于审批 UI 或无头工具处理器； - `interrupts: Signal[]>`：活动线程上根命名空间未处理的协议中断，初始由 `thread.getState()` 水合，新运行开始或调用 `respond` 时会被乐观清空； - `interrupt: Signal | undefined>`：`interrupts[0]` 的便捷别名； - `isLoading: Signal`：由根命名空间的 `running → 终端` 生命周期事件驱动，可用于禁用提交按钮与展示加载状态。 资料来源：[libs/sdk-angular/src/use-stream.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-angular/src/use-stream.ts) ## 数据流与持久化抽象 ```mermaid flowchart LR UI[前端框架
React/Vue/Svelte/Angular] -->|useStream| Hook[框架 Hook 句柄] Hook -->|HTTP/SSE/WS| SDK[langgraph-sdk Client] SDK -->|ThreadStream| Server[LangGraph API Server] Server -->|事件流| SDK SDK -->|messages/values/interrupts| Hook Hook -->|Signals/getters| UI Server <-->|Checkpoint| Store[(MemorySaver / Postgres)] Server <-->|KV / 语义搜索| KV[Store 子客户端] ``` ### Checkpoint 与 Store 后端通过 `MemorySaver` 等 Checkpoint 机制持久化图状态；`client.store` 则提供带命名空间与可选索引字段的 KV / 语义搜索能力。其基础类型定义见 [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts)： - `SearchOperation.query`：用于语义搜索的查询字符串； - `PutOperation.namespace`：层级化路径，充当文件夹结构； - `PutOperation.key`：在命名空间内的唯一标识； - `PutOperation.value`：JSON 可序列化对象（设为 `null` 即删除）。 资料来源：[libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) ### 生态扩展 - `@langchain/langgraph-swarm`：在 LangGraph 之上构建多智能体群（Swarm），提供 `createSwarm`、`createHandoffTool` 与开箱即用的流式、记忆、人机协同支持。资料来源：[libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md) - `@langchain/langgraph-cua`：基于 LangGraph.js 的 Computer Use Agent 实现，提供屏幕感知与操作能力。资料来源：[libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) - `@langchain/langgraph-core` 与 `@langchain/langgraph`：核心图运行时、检查点与预构建组件。资料来源：[libs/langgraph-core/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md) 与 [libs/langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md) - `create-langgraph`：脚手架 CLI，提供 `create-langgraph config [path]` 子命令，自动扫描项目中的 `createAgent`、`new StateGraph(...).compile()`、`workflow.compile()` 等模式生成 `langgraph.json`。资料来源：[libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) ## 常见失败模式与社区反馈 - **代理路径下的流式更新丢失**（Issue #1295）：当 `useStream` 通过 Next.js API 代理使用时，可能无法填充 `messages` 或 `values`，但 SSE 事件本身已被正确接收。建议在代理层保持 `text/event-stream` 头与分块传输，并避免缓冲整段响应。 - **浏览器中 `async_hooks` 不可用**（Issue #1699）：`@langchain/core` 升级到 `^1.0.0-alpha.x` 后部分 API 在浏览器中受限，需确认 SDK 入口使用支持浏览器的 `web` 子导出路径。 - **类包裹的图在 Studio 中不显示 Chat 标签**（Issue #1722）：若图实例由类封装且未导出，`create-langgraph config` 扫描器会将其列为 warning。在 Studio 中需确保图是模块级 `export` 产物。 - **Data Stream 协议互通**（Issue #504）：若需对接 Vercel AI SDK，可通过 `ThreadStream` 的标准化消息/工具调用投影进行转译，避免直接解析裸 SSE。 ## See Also - 核心运行时与图 API：[libs/langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md) - Checkpoint 与 Store 抽象：[libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - 多智能体群（Swarm）模式：[libs/langgraph-swarm/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-swarm/README.md) - Computer Use Agent 模板：[libs/langgraph-cua/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-cua/README.md) - 项目脚手架与配置扫描：[libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) --- ## Persistence (Checkpoints), Server API, CLI, and Deployment ### 相关页面 相关主题：[Repository Overview and Monorepo Structure](#page-1), [Core Graph Engine: StateGraph, Channels, and Pregel](#page-2), [Client SDK, Streaming Protocol, and Framework Hooks](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [libs/checkpoint/src/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/base.ts) - [libs/checkpoint/src/types.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/types.ts) - [libs/checkpoint/src/store/base.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/src/store/base.ts) - [libs/checkpoint/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint/package.json) - [libs/checkpoint-postgres/src/index.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-postgres/src/index.ts) - [libs/checkpoint-postgres/src/migrations.ts](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-postgres/src/migrations.ts) - [libs/checkpoint-validation/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-validation/README.md) - [libs/checkpoint-validation/package.json](https://github.com/langchain-ai/langgraphjs/blob/main/libs/checkpoint-validation/package.json) - [libs/create-langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/create-langgraph/README.md) - [libs/langgraph/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph/README.md) - [libs/langgraph-core/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/langgraph-core/README.md) - [libs/sdk-vue/README.md](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md)
# Persistence (Checkpoints), Server API, CLI, and Deployment ## 持久化抽象层：BaseCheckpointSaver LangGraph.js 的持久化能力由 `@langchain/langgraph-checkpoint` 包提供（`name`、`version` 字段见 `package.json`）[资料来源：[libs/checkpoint/package.json]()]。该包对外暴露 `BaseCheckpointSaver` 抽象类，作为所有具体检查点保存器（Postgres、SQLite、内存等）必须实现的契约 [资料来源：[libs/checkpoint/src/base.ts]()]。 抽象类内置了一个可被构造函数覆盖的 `serde` 字段，默认使用 `JsonPlusSerializer`，用于对通道写入值进行序列化 [资料来源：[libs/checkpoint/src/base.ts]()]。核心方法包括：`getTuple(config)` 按 `RunnableConfig` 解析线程/命名空间并返回 `CheckpointTuple`（包含 `config`、`checkpoint`、`metadata?`、`parentConfig?`、`pendingWrites?`）；`get(config)` 是其便捷封装；`list(config, options?)` 返回 `AsyncGenerator`，支持 `limit`、`before`、`filter` 三种列表选项；`put(config, checkpoint, metadata, newVersions)` 写入检查点并返回新配置；`putWrites(config, writes, taskId)` 存储与某检查点关联的中间写入；`deleteThread(threadId)` 删除线程级别的全部检查点与写入 [资料来源：[libs/checkpoint/src/base.ts]()]。 ## 检查点元数据与存储模型 每个检查点都带有 `CheckpointMetadata` 元数据，描述其产生方式、步数与父节点关系 [资料来源：[libs/checkpoint/src/types.ts]()]。`source` 字段限定为 `"input" | "loop" | "update" | "fork"` 四种枚举值，分别表示来自 invoke/stream/batch 的输入、内部 pregel 循环、手工状态更新、以及从另一检查点复制而来的分叉 [资料来源：[libs/checkpoint/src/types.ts]()]。`PendingWrite` 与 `CheckpointPendingWrite` 分别定义为 `[Channel, PendingWriteValue]` 与 `[TaskId, ...PendingWrite]` 的元组结构，配合 `putWrites` 实现细粒度的任务级写入 [资料来源：[libs/checkpoint/src/types.ts]()]。 | `source` 取值 | 含义 | 典型 `step` 起点 | | --- | --- | --- | | `"input"` | 来自 invoke/stream/batch 入口 | -1 | | `"loop"` | Pregel 内部循环产生 | 从 0 起递增 | | `"update"` | 手工 `update_state` 产生 | 当前 step | | `"fork"` | 从既有检查点分叉复制 | 父 step | 在长期记忆 Store 子系统中，`PutOperation` 接口定义了 `namespace: string[]`、`key: string`、`value: Record | null` 三个字段——`namespace` 提供层级路径（类似文件夹）用于组织跨会话记忆，当 `value` 为 `null` 时即表示删除该条目 [资料来源：[libs/checkpoint/src/store/base.ts]()]。 ## 数据库实现：Postgres 检查点保存器 `PostgresSaver` 是官方基于 [node-postgres](https://node-postgres.com/) 实现的检查点保存器 [资料来源：[libs/checkpoint-postgres/src/index.ts]()]。其 `PostgresSaverOptions` 仅含 `schema` 字段（默认 `"public"`），可通过 `fromConnString` 静态工厂快速创建 [资料来源：[libs/checkpoint-postgres/src/index.ts]()]。 底层数据库模式由 `getSQLStatements` 与 `getMigrations` 共同维护。`migrations.ts` 显式创建了 `checkpoint_writes` 表（包含 `thread_id`、`checkpoint_ns`、`checkpoint_id`、`task_id`、`idx`、`channel`、`type`、`blob` 列），并对 `checkpoint_blobs.blob` 列放宽了 NOT NULL 约束以支持 null 删除语义 [资料来源：[libs/checkpoint-postgres/src/migrations.ts]()]。这种"每条写入一行、以 `(thread_id, checkpoint_ns, checkpoint_id, task_id, idx)` 为主键"的设计，使 `putWrites` 能按主键高效地增量持久化通道级状态。 ## 检查点验证、CLI 工具与部署 `@langchain/langgraph-checkpoint-validation`（`v1.1.0`，`engines` 限定 Node `^20.0.0 || ^22.0.0 || >=24.0.0`）是官方提供的检查点实现校验工具 [资料来源：[libs/checkpoint-validation/package.json]()] [资料来源：[libs/checkpoint-validation/README.md]()]。它既可作为 CLI 在终端执行，也可作为库接入测试套件；典型流程为：实现自定义检查点 → 编写默认导出 `CheckpointerTestInitializer` 的文件 → 运行工具验证 → 根据失败用例迭代 [资料来源：[libs/checkpoint-validation/README.md]()]。 部署侧则由 `create-langgraph` CLI 提供脚手架与配置生成能力。其 `create-langgraph config [path]` 子命令会扫描项目源码，自动识别 `createAgent()`、`new StateGraph(...).compile()`、`workflow.compile()`、`builder.compile()` 等模式（同时支持 ESM `export` 与 CommonJS `module.exports` / `exports.x`），并仅将**已导出**的代理写入生成的 `langgraph.json`，未导出的会以警告形式提示用户补加 `export` [资料来源：[libs/create-langgraph/README.md]()]。 对顶层框架而言，LangGraph 官方文档将"持久化执行（durable execution）"与"生产级部署"列为核心卖点——前者依赖上述检查点机制在故障后从中断点恢复，后者通过 [LangSmith Deployments](https://docs.langchain.com/langsmith/deployments) 提供托管运行环境 [资料来源：[libs/langgraph/README.md]()] [资料来源：[libs/langgraph-core/README.md]()]。 ## 常见失效模式与社区关注点 社区侧多个高互动议题都集中在持久化与 SDK 的边界场景：#1722 报告 LangGraph Studio 的 Chat 标签在图构建于 class 内部时无法显示；#1699 指出 `@langchain/core` 1.0.0-alpha 在浏览器中与 `async_hooks` 冲突，影响浏览器端 Vue/React SDK 的流式行为 [资料来源：[libs/sdk-vue/README.md]()](https://github.com/langchain-ai/langgraphjs/blob/main/libs/sdk-vue/README.md)。在引入自定义 `BaseCheckpointSaver` 实现或使用浏览器端 SDK 之前，应先通过 `langgraph-checkpoint-validation` 工具做一轮合规性测试，并优先选用官方 `PostgresSaver` 作为生产基线。 ## See Also - [LangGraph API 参考](https://reference.langchain.com/javascript/langchain-langgraph) - [Durable Execution 概念文档](https://docs.langchain.com/oss/javascript/langgraph/durable-execution) - [LangSmith Deployments 部署指南](https://docs.langchain.com/langsmith/deployments) - [create-langgraph CLI 目录](https://github.com/langchain-ai/langgraphjs/tree/main/libs/create-langgraph) - [langgraph-checkpoint-validation 工具](https://github.com/langchain-ai/langgraphjs/tree/main/libs/checkpoint-validation) --- --- ## Doramagic 踩坑日志 项目：langchain-ai/langgraphjs 摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。 ## 1. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `langgraphjs` 与安装入口 `@langchain/langgraph` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 复现命令：`npm install @langchain/langgraph` - 证据：identity.distribution | https://www.npmjs.com/package/@langchain/langgraph | repo=langgraphjs; install=@langchain/langgraph ## 2. 安装坑 · 来源证据：`streamEvents` v3 produces `AIMessage` with empty `tool_calls` when model emits text alongside a tool call, breaking `c… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`streamEvents` v3 produces `AIMessage` with empty `tool_calls` when model emits text alongside a tool call, breaking `createAgent`'s ReAct loop - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2496 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://www.npmjs.com/package/@langchain/langgraph | README/documentation is current enough for a first validation pass. ## 4. 运行坑 · 来源证据：MongoDBSaver missing indexes causes full collection scans - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：MongoDBSaver missing indexes causes full collection scans - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2551 | 来源类型 github_issue 暴露的待验证使用条件。 ## 5. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://www.npmjs.com/package/@langchain/langgraph | no_demo; severity=medium ## 7. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://www.npmjs.com/package/@langchain/langgraph | no_demo; severity=medium ## 8. 安全/权限坑 · 来源证据：Cross-thread checkpoint data contamination when using singleton agent with concurrent invocations - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Cross-thread checkpoint data contamination when using singleton agent with concurrent invocations - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/2040 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 9. 安全/权限坑 · 来源证据：What format data does `AIMessage` has to have to give `contentBlock` with `{type:"reasoning"}` - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：What format data does `AIMessage` has to have to give `contentBlock` with `{type:"reasoning"}` - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/langchain-ai/langgraphjs/issues/1836 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://www.npmjs.com/package/@langchain/langgraph | release_recency=unknown