LangGraph4j 架构拆解：Java Agent 编排的图、状态与执行引擎

1. 为什么值得花时间啃 LangGraph4j 的架构

第一次看到 LangGraph4j 这个项目名，很多 Java 后端同学的反应大概是：又一个把 Python 那套东西搬到 JVM 上的移植货。我一开始也这么想，直到真正把它的源码拉下来读了一遍，才发现这个判断有点草率。LangGraph4j 并不是简单地把 LangChain 或 LangGraph 的 API 换个语言重写，它在架构层面做了不少针对 JVM 生态的取舍，尤其是围绕Agent 编排、状态流转和图结构执行这三件事，设计思路和 Python 版本有明显差异。

这篇文章聚焦的是架构层面，不铺开讲每一个 API 怎么调，而是把 LangGraph4j 的整体骨架拆开来看：它由哪些核心模块组成，这些模块之间怎么协作，为什么这么分层，以及这种架构在实际做 Agent 开发时会带来什么影响。如果你正在纠结“现在到底用 Spring AI 还是 LangGraph4j”，或者想自己动手写一个 Agent 框架，那搞清楚 LangGraph4j 的架构设计，比背它的 API 有用得多。

适合读这篇内容的人，我大致分三类：一是 Java 后端想切入 AI Agent 方向，需要找一个能落地的框架来研究；二是已经在用 LangChain4j 或 Spring AI，但发现做多步骤、带分支和循环的 Agent 编排时有点力不从心；三是纯粹对图计算 + 状态机这套架构感兴趣，想看看它在 Agent 场景下是怎么落地的。不管你是哪一类，只要对 Java 生态下的 Agent 框架有实际需求，这篇架构拆解都能给你一些参考。

需要提前说明的是，LangGraph4j 本身还在快速迭代，不同版本之间类名和包结构可能有调整。我下面分析的内容基于我实际读过的几个版本，核心架构思想是稳定的，但具体类名你对照自己项目里的版本去核实。另外，文中涉及的一些设计意图，有一部分是源码里能直接看出来的，有一部分是我结合常见 Agent 框架实践做的合理推断，我会尽量把这两类区分清楚。

2. LangGraph4j 整体架构拆解

2.1 从“图”这个核心抽象说起

LangGraph4j 最核心的抽象就是图（Graph）。整个框架围绕“节点（Node）”和“边（Edge）”来组织 Agent 的执行逻辑。你定义一个图，图里有若干节点，每个节点做一件事，节点之间通过边连接，边决定了执行流程往哪走。这个思路和 TensorFlow 的计算图、Airflow 的 DAG 有相似之处，但 LangGraph4j 的图是带状态的、可循环的，这是它和传统 DAG 编排框架最大的区别。

为什么 Agent 场景需要“可循环的图”？因为 Agent 的典型行为不是一条直线走到底。它可能需要：调用工具、拿到结果、判断结果是否满足条件、不满足就换个工具再试、满足就继续下一步。这个“判断-回退-重试”的过程天然就是一个循环结构。用传统的链式调用（Chain）去写，代码会变成一堆嵌套的 if-else 和 while 循环，可读性和可维护性都很差。用图来表达，循环就是一条从下游节点指回上游节点的边，结构一目了然。

LangGraph4j 的图结构里，有几个关键概念需要先厘清：

• State（状态）：整个图共享的一份数据，所有节点都能读写。它相当于 Agent 的“工作内存”，记录了当前对话历史、工具调用结果、中间变量等。
• Node（节点）：图中的一个执行单元，接收 State，做处理，返回更新后的 State。
• Edge（边）：定义节点之间的跳转关系。普通边是固定跳转，条件边（Conditional Edge）根据 State 的内容动态决定下一个节点是谁。
• CompiledGraph（编译后的图）：图定义好之后需要编译，编译过程会做校验和优化，生成一个可执行的图对象。

这套抽象的好处是，你把 Agent 的“思考流程”显式地画出来了。流程本身成了代码的一部分，而不是藏在各种回调和控制流里。调试的时候，你可以直接看当前执行到哪个节点、State 里有什么，定位问题比翻日志快得多。

2.2 模块分层与依赖关系

把 LangGraph4j 的源码包结构摊开看，大致可以分成这么几层：

这个分层不是官方文档里明写的，是我读源码时按职责归的类。分层的意义在于，每一层只依赖它下面的层，上层的变化不会轻易影响下层。比如你想换一个状态存储后端，只需要动检查点层的实现，图定义和执行逻辑不用改。

依赖关系上，LangGraph4j 对 LangChain4j 有依赖，但耦合度控制得比较克制。它主要用 LangChain4j 的 LLM 接口和消息模型，图执行本身是独立的。这意味着你理论上可以把 LLM 那部分换成别的实现，图引擎照样能跑。这种设计对想深度定制的人来说是好事，但也意味着你不能指望 LangGraph4j 帮你把 LLM 调用的所有细节都封装好，有些胶水代码还是得自己写。

2.3 和 Python 版 LangGraph 的架构差异

很多人会拿 LangGraph4j 和 Python 版 LangGraph 对比。两者核心思想一致，但架构实现上有几个值得注意的差异。

第一，类型系统。Java 是强类型语言，LangGraph4j 在 State 的定义上更依赖泛型和显式类型声明。Python 版可以用字典随便塞，Java 版你得定义一个 State 类或者用 Map 但会丢失类型安全。这个差异导致 Java 版在定义复杂 State 时样板代码更多，但换来的是编译期检查和更好的 IDE 支持。

第二，并发模型。Python 有 GIL，LangGraph 的并行节点执行主要靠异步 IO。Java 这边可以用真正的多线程，LangGraph4j 在执行层对并行节点的处理更接近传统的线程池模型。这对需要高并发调用多个工具的 Agent 场景是有利的，但也引入了线程安全的问题，State 的读写需要额外注意。

第三，持久化机制。Python 版 LangGraph 的 Checkpoint 机制和 LangSmith 等平台结合紧密。LangGraph4j 的检查点层更独立，提供了接口让你自己接数据库或文件系统。这给了更多自由度，但也意味着开箱即用的体验不如 Python 版。

这些差异没有优劣之分，是语言特性和生态决定的。理解这些差异，能帮你在选型时判断 LangGraph4j 是否适合你的场景。

3. 核心模块的源码级解析

3.1 StateGraph：图的定义入口

StateGraph是整个框架的入口类。你通过它来注册节点、添加边、指定状态类型。从源码看，StateGraph内部维护了几个关键数据结构：节点映射表、边列表、条件边列表、以及状态的定义信息。

注册节点的方法大致长这样（伪代码，具体签名以你用的版本为准）：

StateGraph<MyState> graph = new StateGraph<>(MyState::new); graph.addNode("llm_call", nodeAction); graph.addNode("tool_exec", toolAction); graph.addEdge("llm_call", "tool_exec"); graph.addConditionalEdge("tool_exec", conditionFn, Map.of( "continue", "llm_call", "end", StateGraph.END ));

这里有个设计细节值得说：StateGraph在添加节点时并不立即执行任何逻辑，它只是把定义记下来。真正的校验和执行发生在编译阶段。这种“定义与执行分离”的设计是很多图计算框架的常见做法，好处是定义阶段可以反复修改，编译阶段统一做校验，避免边指向不存在的节点这类低级错误。

StateGraph还负责管理状态的合并策略。当多个节点并行执行、或者一个节点返回部分状态更新时，框架需要知道怎么把新状态合并到旧状态里。LangGraph4j 默认的策略是覆盖式合并，但你可以自定义合并函数。这个点在多节点并行写同一个状态字段时特别重要，搞不好会出现数据覆盖的问题。

3.2 CompiledGraph：从定义到可执行

StateGraph编译之后得到CompiledGraph。编译过程做了几件事：校验图的连通性、检查是否有孤立节点、确认条件边的分支覆盖完整、以及生成内部的执行计划。

我读源码时注意到，编译阶段会构建一个邻接表来表示图的拓扑结构。执行时，引擎通过查这个邻接表来决定下一个节点是谁。对于条件边，邻接表里存的是条件函数和分支映射，执行到该节点时调用条件函数，根据返回值查映射表得到下一个节点。

CompiledGraph还暴露了invoke、stream等方法作为执行入口。invoke是同步执行，跑完整个图返回最终状态；stream是流式执行，每经过一个节点就吐出一个事件。流式执行对 Agent 场景很有用，因为你可以实时看到 Agent 每一步在干什么，而不是等它全部跑完才拿到结果。

编译后的图是不可变的。你不能在运行时往CompiledGraph里加节点或改边。这个约束是有意为之的，保证了执行过程的可预测性。如果你需要动态改变流程，得在节点内部通过条件边来实现，而不是改图结构本身。

3.3 执行引擎：图是怎么跑起来的

执行引擎是 LangGraph4j 里最复杂的部分。它的核心是一个循环：从起始节点开始，执行节点逻辑，根据边决定下一个节点，直到到达结束节点或触发中断。

这个循环的实现要考虑几个问题。第一是状态传递：每个节点执行完返回的状态更新，需要合并到全局状态里，再传给下一个节点。第二是条件分支：遇到条件边时，要调用条件函数并解析返回值。第三是并行执行：如果一个节点有多条出边指向不同节点，这些节点是否可以并行执行。第四是中断与恢复：执行到某个节点时如果需要人工介入，怎么暂停、怎么从暂停点恢复。

从源码看，执行引擎用一个while循环驱动，内部维护一个“待执行节点队列”。每轮从队列取节点执行，执行完根据边把后续节点加入队列。条件边在加入队列前会先求值。这个模型比较简单直接，但并行执行的支持需要额外处理，因为多个节点同时写状态会有竞争。

关于并行，LangGraph4j 的处理方式是：如果多个后续节点之间没有数据依赖，引擎可以把它们提交到线程池并行执行，执行完再统一合并状态。但框架本身不会自动分析依赖关系，需要你在定义图的时候通过结构来保证。这一点和某些自动并行的框架不同，控制权更多在开发者手里。

3.4 状态管理与检查点机制

State 的管理看似简单，实则有不少门道。LangGraph4j 的 State 本质上是一个可变的容器，节点通过它读写数据。但为了支持检查点和恢复，State 需要能被序列化和反序列化。

检查点机制的工作方式是：在图的执行过程中，每经过一个节点（或者按配置的间隔），框架会把当前 State 的快照保存下来。如果执行中断，可以从最近的检查点恢复，不用从头再跑。这对长流程的 Agent 特别有价值，比如一个需要调用多个外部服务、跑十几分钟的流程，中途某个服务挂了，没有检查点就得全部重来。

检查点的存储后端是可插拔的。框架定义了检查点存储的接口，你可以用内存、文件、数据库来实现。默认实现通常是内存版，适合开发和测试；生产环境一般要换成持久化存储。这里有个坑：State 里如果放了不可序列化的对象（比如某些 LLM 客户端实例），检查点保存会失败。所以设计 State 时要有意识地把“数据”和“服务”分开，State 里只放数据，服务通过依赖注入的方式传给节点。

4. 架构设计背后的取舍与考量

4.1 为什么用图而不是链

Chain 和 Graph 是 Agent 编排的两种主要范式。Chain 是线性的，A 完了到 B，B 完了到 C。Graph 是网状的，可以有分支、循环、并行。LangGraph4j 选择 Graph，是因为 Agent 的实际行为模式更接近图。

举个具体例子：一个客服 Agent，用户提问后，它要先判断问题类型。如果是查询订单，走订单查询流程；如果是退换货，走退换货流程；如果判断不了，走人工转接。这个“判断-分支”的结构，用 Chain 写就是一堆 if-else，用 Graph 写就是条件边。当分支多起来、分支之间还有交叉和回退时，Graph 的优势会越来越明显。

但 Graph 也不是没有代价。图的定义比链复杂，学习曲线更陡。对于简单的线性流程，用 Graph 反而是杀鸡用牛刀。LangGraph4j 的定位很明确，它瞄准的是复杂 Agent 编排场景，不是简单的 LLM 调用封装。如果你的需求只是“调一次 LLM 拿结果”，那用 LangChain4j 的基础 API 就够了，没必要上 LangGraph4j。

4.2 状态共享带来的便利与风险

所有节点共享一个 State，这个设计让节点之间的通信变得非常简单。节点 A 往 State 里写个字段，节点 B 直接读就行，不需要显式地传参数。这在快速开发时很爽，但也埋了隐患。

最大的风险是状态污染。节点 A 写了一个字段，节点 B 以为它是初始值，实际上已经被 A 改过了。或者多个节点并行写同一个字段，后写的覆盖先写的。这类 bug 在调试时很难定位，因为状态的变化是隐式的。

LangGraph4j 对此的应对是提供状态合并策略和检查点，让你能追溯状态的变化历史。但框架层面没法完全杜绝这个问题，更多要靠开发者的纪律：给 State 字段起清晰的名字、在节点里明确注释读了哪些字段写了哪些字段、并行节点尽量避免写同一字段。我自己的习惯是，State 里的字段按“谁写谁读”来分组，减少交叉。

4.3 编译期校验的价值

前面提到StateGraph编译成CompiledGraph时会做校验。这个设计我觉得是 LangGraph4j 架构里比较聪明的一笔。Agent 的流程定义很容易出错，比如边指向了不存在的节点、条件边的分支没覆盖全、起始节点没指定。这些错误如果在运行时才暴露，可能已经跑了一半流程才崩，排查成本高。

编译期校验把这些错误提前到启动阶段。图编译不通过，应用直接起不来，问题在开发阶段就暴露了。这和 Java 的编译期类型检查是一个思路：早发现，早修复。代价是定义图的时候要多写一点代码来满足校验要求，但长期看是划算的。

校验的严格程度是可以配置的。开发阶段可以开严格模式，把所有潜在问题都报出来；生产环境如果图是动态生成的，可能需要放宽一些校验。这个灵活性是必要的，因为不是所有场景都能在编译期确定图结构。

4.4 与 Spring AI、LangChain4j 的定位差异

热词里有人问“现在到底用 Spring AI 还是 LangGraph4j”，这个问题本身就有点错位，因为两者定位不同。Spring AI 更偏向于提供 LLM 调用的统一抽象和 Spring 生态集成，它的强项是让你在 Spring 项目里方便地调用各种模型、管理配置、做可观测性。LangGraph4j 则专注于 Agent 的流程编排，它假设你已经有了 LLM 调用能力，它帮你解决的是“怎么把多个 LLM 调用和工具调用组织成一个有逻辑的流程”。

实际项目中，两者可以配合使用。用 Spring AI 或 LangChain4j 做底层的 LLM 调用和工具封装，用 LangGraph4j 做上层的流程编排。LangGraph4j 的节点内部可以调用 Spring AI 的客户端，这没有任何冲突。选型时不要把它们当成互斥选项，而是看你的核心痛点在哪：痛在 LLM 接入和配置管理，优先 Spring AI；痛在复杂流程编排，优先 LangGraph4j。

5. 实操：从零搭一个最小可用的图

5.1 环境准备与依赖引入

先确认 JDK 版本。LangGraph4j 对 JDK 版本有要求，我用的版本需要 JDK 17 及以上。如果你还在 JDK 8 或 11，得先升级，这个没有绕过的办法。Maven 或 Gradle 都可以，我用 Maven 演示。

依赖方面，核心是 LangGraph4j 的包，加上 LangChain4j 的 LLM 集成包。具体坐标以你用的版本为准，大致结构是这样：

<dependency> <groupId>org.bsc.langgraph4j</groupId> <artifactId>langgraph4j-core</artifactId> <version>你的版本号</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>你的版本号</version> </dependency>

版本号这里我不写死，因为迭代快，写死了反而误导。你去 Maven Central 搜最新的稳定版就行。注意 LangGraph4j 和 LangChain4j 的版本兼容性，有时候新版的 LangGraph4j 需要配套新版的 LangChain4j，混用旧版可能报 NoSuchMethodError。

5.2 定义 State 和节点

State 的定义方式有两种：用 Map 或者用自定义类。Map 简单但丢类型安全，自定义类啰嗦但好用。我推荐自定义类，尤其是流程复杂的时候。

public class AgentState { private List<Message> messages; private String nextAction; private int retryCount; // getter/setter 省略 }

节点就是一个函数，接收 State 返回 State 更新。LangGraph4j 里节点通常实现为一个函数式接口，你可以用 lambda 写：

Node<AgentState> llmNode = state -> { // 调用 LLM，把结果加到 messages 里 // 返回状态更新 return Map.of("messages", updatedMessages); };

这里有个细节：节点返回的是“状态更新”而不是完整状态。框架会负责把更新合并到全局状态。这个设计减少了节点之间的耦合，节点不需要知道全局状态长什么样，只需要返回自己改动的部分。但前提是你得清楚合并策略，否则可能出现预期外的覆盖。

5.3 组装图并编译执行

把节点和边组装起来：

StateGraph<AgentState> graph = new StateGraph<>(AgentState::new); graph.addNode("agent", llmNode); graph.addNode("tools", toolNode); graph.addEdge(StateGraph.START, "agent"); graph.addConditionalEdge("agent", state -> state.getNextAction().equals("tool") ? "tools" : StateGraph.END, Map.of("tools", "tools", "end", StateGraph.END)); graph.addEdge("tools", "agent"); CompiledGraph<AgentState> compiled = graph.compile(); AgentState result = compiled.invoke(Map.of("messages", initialMessages));

这段代码定义了一个经典的 Agent 循环：agent 节点调用 LLM，根据 LLM 的输出决定是调工具还是结束；如果调工具，工具节点执行后回到 agent 节点继续。这个循环会一直跑，直到 LLM 决定结束。

编译时如果图有问题，比如条件边的分支映射不完整，compile()会抛异常。这是好事，问题在启动时就暴露了。执行时用invoke同步跑，或者用stream拿流式事件。

5.4 加入检查点支持中断恢复

检查点的配置在编译阶段：

CompiledGraph<AgentState> compiled = graph.compile( CompileConfig.builder() .checkpointSaver(new MemorySaver<>()) .build() );

MemorySaver是内存版，重启就没了。生产环境要换成基于数据库的实现。加了检查点之后，如果执行中断，可以用线程 ID 从上次的检查点恢复：

compiled.invoke(input, RunnableConfig.builder() .threadId("conversation-123") .build());

同一个 threadId 的多次调用会共享检查点历史，这对多轮对话场景很有用。用户第二次提问时，Agent 能从上次的状态继续，而不是从零开始。

6. 常见问题与排查实录

6.1 图编译报错怎么定位

编译报错最常见的原因是边指向了不存在的节点。错误信息一般会告诉你哪个边有问题，但有时候信息不够具体。我的排查步骤是：先把所有节点名打印出来，再对照边定义检查。如果节点名是动态生成的，特别容易出这种问题。

另一个常见原因是条件边的分支映射不完整。比如条件函数可能返回三个值，但映射表只配了两个，编译时可能不报错，运行时走到没配的分支就崩了。所以条件边的映射表要覆盖条件函数所有可能的返回值，宁可多配一个默认分支。

6.2 状态更新丢失的排查思路

状态更新丢失通常表现为：节点明明写了某个字段，下游节点读到的却是旧值。排查时先确认合并策略，默认的覆盖式合并下，如果两个节点并行写同一字段，后完成的会覆盖先完成的。如果不是并行问题，检查节点返回的 Map 的 key 是否和 State 字段名一致，大小写、拼写都要对。

还有一种情况是 State 类没有无参构造函数，框架反序列化时创建不了实例。这个错误在检查点恢复时特别容易遇到，因为恢复需要从序列化数据重建 State。给 State 类加个无参构造函数，或者用框架支持的序列化方式。

6.3 并行节点执行结果不一致

并行节点如果都写 State，结果可能不稳定，因为线程调度顺序不确定。解决办法有两个：一是让并行节点写不同的字段，避免冲突；二是用支持合并的字段类型，比如用 List 而不是单个值，合并策略改成追加而不是覆盖。

LangGraph4j 对并行的支持需要显式配置，不是所有图都会自动并行。如果你没配置并行但发现节点执行顺序乱了，检查一下是不是有节点内部起了异步任务但没等它完成就返回了。节点函数应该是同步的，异步逻辑要在节点内部处理完再返回。

6.4 检查点恢复失败的常见原因

检查点恢复失败，十有八九是 State 里有不可序列化的对象。比如你把一个 HTTP 客户端或者数据库连接放进了 State，序列化时就会失败。解决办法是把这类对象从 State 里挪出去，通过依赖注入的方式传给节点。

另一个原因是检查点存储后端的配置问题。内存版重启就丢，这个要知道。数据库版要确认表结构建对了，字段类型匹配。文件版要注意并发写的问题，多个线程同时写同一个文件会损坏数据。

6.5 几个我踩过的坑

第一个坑是节点返回 null。有些节点逻辑上不需要更新状态，我一开始直接返回 null，结果框架报空指针。后来改成返回空 Map，问题解决。节点返回空 Map 表示“没有更新”，返回 null 是非法操作。

第二个坑是条件函数抛异常。条件函数在边求值时执行，如果它抛异常，整个执行会中断，而且错误信息可能不指向条件函数本身。条件函数里要做防御性判断，对 null 和异常情况有兜底返回值。

第三个坑是图太复杂导致调试困难。我一开始把所有逻辑塞进一个大图，节点几十个，出问题根本不知道从哪查。后来拆成多个小图，每个图负责一个子流程，图之间通过状态传递衔接。这样每个图都能单独测试，定位问题快很多。

7. 架构层面的扩展思考

7.1 分布式执行的可行性

LangGraph4j 目前的执行引擎是单机的，图在单个 JVM 里跑。如果要做分布式，需要把节点执行分发到不同机器，状态和检查点也要跨机器共享。这个改造量不小，但架构上是可行的，因为节点之间通过 State 通信，只要 State 能跨机器同步，节点在哪台机器执行对图逻辑是透明的。

实际做分布式时，最大的挑战是状态一致性。多个节点并行执行时，状态的合并需要分布式锁或者乐观锁来保证。检查点存储也要换成分布式的，比如用支持事务的数据库。这些在单机版里都不是问题，分布式下就都冒出来了。

7.2 可观测性怎么补

LangGraph4j 本身的可观测性支持比较基础，主要靠流式事件和检查点。生产环境需要更细的监控：每个节点的执行耗时、LLM 调用的 token 消耗、工具调用的成功率。这些可以在节点内部埋点，或者用 AOP 的方式统一拦截。

流式事件是个好的切入点。stream方法吐出的事件里包含了节点执行的信息，你可以把这些事件转发到监控系统。检查点则提供了状态的历史快照，可以用来做执行回放和问题复现。

7.3 和其他 Agent 框架的架构对比

市面上 Java 生态的 Agent 框架不多，LangGraph4j 算是比较专注的一个。和 Python 生态比，Java 这边的选择少，但 LangGraph4j 的架构设计并不落后。它的图抽象、状态管理、检查点机制，和 Python 版 LangGraph 的核心思想是一致的，差异主要在语言特性和生态集成上。

如果拿它和基于规则的传统工作流引擎比，LangGraph4j 的优势在于对 LLM 的原生支持和对不确定性的容忍。传统工作流引擎假设每一步的结果是确定的，而 Agent 场景下 LLM 的输出是不确定的，需要条件分支和重试机制来应对。LangGraph4j 的图结构天然适合这种场景。

我在实际项目里用 LangGraph4j 搭过一个多工具调用的 Agent，整体体验是：架构清晰，调试比手写控制流方便，但样板代码确实比 Python 版多。如果你的团队是 Java 背景，又需要做复杂 Agent 编排，LangGraph4j 值得投入时间研究。如果只是简单调用，用 LangChain4j 的基础 API 就够了，不用上这么重的框架。后续我还会继续拆它的执行引擎和检查点实现细节，那部分代码量更大，坑也更多，有兴趣的可以持续关注。