LangGraph.js 评测：用图结构编排有状态 Agent 的 TypeScript 框架
Framework to build resilient language agents as graphs.
秒懂
- 它是什么？
- LangGraph.js 是 LangChain 团队推出的低层编排框架，用于构建可恢复、可中断、带长期记忆的 Agent。本文基于仓库与文档，分析其图执行模型、状态持久化机制、适用场景与局限。
- 适合谁用？
- LangGraph.js 适合需要长时间运行、可恢复、带人工审批或跨会话记忆的 Agent 场景，尤其是已经使用 LangChain 生态的 TypeScript 团队。它不适合简单的一次性 LLM 调用，也不适合对 Python 生态有强依赖的项目，因为 Python 版 LangGraph 与 JS 版在 API 和生态上并不完全对齐。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 1 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
一个把 Agent 拆成状态机的框架
LangGraph.js 解决的问题很具体：当你需要构建的不是单次提示词调用，而是多步骤、可能运行数小时、中途会失败或需要人工介入的 Agent 时，普通的函数调用链不够用。它把 Agent 的执行建模成一张图，节点是计算步骤，边是转移条件，整张图共享一个可检查点的状态对象。这种设计借鉴了 Google 的 Pregel 和 Apache Beam，README 里明确写了这一点。它面向的是需要精细控制执行流程的开发者，而不是只想快速调用一次模型的用户。如果你只是写一个简单的问答机器人，这个框架是过度的。
状态、检查点与恢复：核心机制拆解
LangGraph.js 的核心抽象是 StateGraph。你定义一个状态类型，然后添加节点和边，每个节点接收状态并返回状态的更新。框架负责按图的结构调度节点。关键机制是检查点（checkpoint），它把每一步之后的状态持久化，这样当进程崩溃或任务被中断时，可以从最后一个检查点恢复，而不是从头开始。文档称之为 durable execution，即持久执行。另一个机制是中断（interrupt），它允许在某个节点暂停执行，等待人工输入，然后从暂停处继续。这两个机制共同支撑了长时运行 Agent 的可靠性。你需要理解的是，状态必须可序列化，因为要写入检查点。如果你在状态里放了不可序列化的对象，比如数据库连接或函数，框架就无法正常工作，这是文档没有明说但实际必然存在的约束。
安装与第一个图：真实命令与代码形态
安装只需要两条命令，来自 README：npm install @langchain/langgraph @langchain/core。注意它依赖 @langchain/core，这是基础包，提供消息、模型接口等类型。实际写一个图的步骤大致是：先定义状态接口，然后创建 StateGraph 实例，用 addNode 注册节点函数，用 addEdge 或 addConditionalEdges 连接节点，最后用 compile 方法编译。编译时你可以传入一个 checkpointer 实例，比如内存版或持久化版。README 没有给出完整代码示例，但文档站 docs.langchain.com 上有详细 API 参考。一个典型的节点函数接收 state 参数，返回部分状态更新。条件边让你根据当前状态决定下一步走哪个分支，这实现了 Agent 的循环和退出逻辑。编译后的图对象有 invoke 方法，传入初始状态即可启动执行。如果你需要流式输出，框架也支持，文档中有专门的 Streaming Cookbook 仓库。
人机协同与记忆：两个被强调的卖点
README 把 human-in-the-loop 和 memory 列为两大特性。人机协同通过 interrupt 机制实现。在执行到某个节点时，你可以让图暂停，把当前状态暴露给人工审核者，审核者可以修改状态再让图继续。这对于需要审批的金融交易或内容生成场景很关键。记忆分为短期和长期。短期记忆就是检查点中的状态，它在单次运行内保留上下文。长期记忆则跨会话存在，让 Agent 记住用户偏好或历史事实。实现上，长期记忆通常需要外部存储，LangGraph 提供了相关抽象，但具体用法要看文档。需要留意的是，这些特性都假设你使用 LangChain 的模型接口和消息格式，如果你用的是裸 OpenAI SDK 或其他框架，集成成本会上升。
调试与部署：LangSmith 的双刃剑
LangGraph.js 的调试体验高度依赖 LangSmith，这是 LangChain 的商业可观测性平台。README 说 LangSmith 能可视化执行路径、捕获状态转换、提供运行时指标。对于复杂的图，这种可视化几乎必不可少，因为节点之间的跳转逻辑很难靠日志推断。但这也意味着，如果你不想使用 LangSmith，或者你的数据合规要求不允许把执行轨迹发送到外部服务，你就失去了官方推荐的主要调试手段。部署方面，README 提到 LangSmith Deployments 可以部署 Agent，但那是商业服务。自托管的话，你需要自己处理检查点的持久化存储，比如数据库或 Redis，框架本身不提供服务器。这是一个实际的运维负担，文档没有回避，但也没有给出开箱即用的方案。
适用边界：什么时候它是错误的工具
LangGraph.js 的图模型带来了灵活性，也带来了复杂度。如果你的 Agent 只有两三个步骤，且步骤之间是简单的顺序关系，用图来表达反而绕远路。此时直接写 async 函数调用更清晰。另一个不适用的场景是状态结构经常变化的情况。因为状态类型是 TypeScript 接口，检查点持久化依赖于状态的稳定结构，频繁修改状态字段会导致旧检查点无法恢复或需要迁移逻辑。还有，如果你需要极低的延迟，每次节点执行都做检查点写入会增加开销。README 没有给出性能数据，但你可以推断，持久化 I/O 不可能免费。最后，如果你不需要中断和恢复，那么 LangGraph 的核心价值就失去了一半，你只是在为一个普通的状态机引入依赖。
替代方案：LangChain 链与 Deep Agents
最直接的替代是 LangChain 本身的链式调用（LCEL），它适合构建线性的、无需持久化的流程。LangGraph 与 LangChain 的关系是互补而非替代，LangChain 提供组件，LangGraph 提供编排。另一个替代是 README 中提到的 Deep Agents，它是构建在 LangGraph 之上的高层包，特点是 Agent 可以规划、使用子 Agent 和文件系统。如果你需要这些能力，直接用 Deep Agents 比从零写 LangGraph 图更快。但 Deep Agents 也意味着你接受了它预设的 Agent 架构，失去了 LangGraph 的低层控制能力。还有一个隐性的替代是 Python 版 LangGraph，它在社区中更成熟，资源更多。如果你不局限于 TypeScript，Python 版可能是更稳妥的选择，但需要放弃 JS 单语言栈的便利。
维护与许可：MIT 背后的现实
LangGraph.js 采用 MIT 许可证，这对商用友好，没有 copyleft 义务。但 MIT 只覆盖框架本身，不覆盖你调用的模型 API 或 LangSmith 服务。维护方面，仓库最后推送时间是 2026 年 9 月，说明项目仍在活跃开发。版本号显示 1.0.36 的候选版本，这意味着 API 已经相对稳定，但 rc 版本的存在也提示你，在正式升级前要阅读 changelog。LangChain 生态的更新节奏很快，LangGraph.js 的 API 可能随主版本变化，你需要在升级时检查破坏性变更。另一个维护成本是学习曲线：图、检查点、中断、条件边，这些概念需要时间掌握，而文档虽然齐全，但分散在 docs.langchain.com 和 API 参考中，新手容易迷失。
编辑结论
LangGraph.js 适合需要长时间运行、可恢复、带人工审批或跨会话记忆的 Agent 场景，尤其是已经使用 LangChain 生态的 TypeScript 团队。它不适合简单的一次性 LLM 调用，也不适合对 Python 生态有强依赖的项目，因为 Python 版 LangGraph 与 JS 版在 API 和生态上并不完全对齐。采用前应先验证三件事：一是确认你的状态结构适合用图节点和边来表达，二是明确是否需要内置的检查点持久化，三是评估 LangSmith 是否在你的部署环境中可用，因为调试体验高度依赖它。若不需要持久化和中断能力，直接使用 LangChain 的链式调用或 Deep Agents 这类高层封装会更省力。
社区笔记