langgraph4j原理源码分析图 II图编译

简介

langgraph4j是java技术栈ai agent框架，深入掌握其源码与原理，指导agent的开发，重构/改造框架，增加特性，快速定位和修复bug，发布私有版本

系列内容：

> 架构，包括逻辑架构，运行架构，集成架构

> 状态图

>> 状态和序列化

>> StatGraph分析

>> 推理框架

> 编译图

> 执行图

>> 检查点

>> aync-generator

>> 执行分析

>>> 中断/恢复

>>> 取消执行

> agent和集成

>> 简单agent

>> 多agent

> 观测

> studio

本文分析图编译

本文基于langgraph4j v1.8.20

关键词

agent

graph

缩写

spring ai 缩写sa

spring ai alibaba 缩写saa

参考资料

Overview - LangGraph4j langgraph4j官网

mp.weixin.qq.com/mp/appmsgalbum?action=getalbum&album_id=4540202703779627014

spring ai Alibaba原理源码分析，包括spring ai部分

lg4j概览

上图 lg4j的逻辑架构图，逻辑架构展示lg4j功能模块，描述其职责，模块通过精密的协作，共同支撑起复杂 Agent 的构建与运行。

逻辑架构解构为以下四个核心域：图编排、执行与状态、基础设施扩展、集成外部能力生态、开发支持

1. 核心编排层：图的蓝图与引擎

StateGraph ( 状态图)：这是开发者构建 Agent 的核心抽象。它代表了整个工作流的"蓝图"，开发者在这里定义有哪些节点（Node）以及它们之间的流转规则（Edge）。

CompiledGraph ( 编译图)：当 StateGraph 被构建完成后，经过 compile() 方法转化而来。编译图重整了状态图的数据结构，支持高效的图执行；编译图包含了流执行逻辑、状态机引擎和调度策略的"可运行实例"。

2. 执行与状态层：原子动作与数据流转

3. 基础设施扩展层：持久化、异步与可观测

4. agent ，agent 有两部分，core 内agent 包是lg4j 提供; core 外的agent 框架，spring ai alibaba 移植，提供完整的agent 框架，也包括基于core 内agent 重构的agent builder 组件

5. 外部能力生态层：AI 核心能力

这一层是LangGraph4j 与 AI 生态对接。

Spring AI：作为底层的能力供给层，Spring AI 提供了 Agent 所需的原子能力，包括 LLM model（大语言模型）、RAG（检索增强生成）、prompt（提示词工程）、memory（长期记忆）、mcp&tool&skills（工具调用与技能扩展）等。
LangGraph4j也集成了langchain4j

5. 开发工具

Studio ( 可视化开发工具)：lg4j的Studio模块提供了一套完整的可视化调试和开发界面，让开发者能够直观地看到图的执行路径和状态流转，极大地降低了复杂 Agent 的开发门槛。

graph

lg4j是workflow框架，以图的结构，节点，边构建处理流程，节点执行动作实现逻辑，边决定下一个节点。agentic是另一种模式，整个流程大模型自主编排，agentic省心省事，但同时agentic容易失控，纯粹看大模型心情，因此，目前比较好的方案，主体使用flowable，需要的时候使用agentic节点。

在lg4j, agent的推理框架映射成graph，以图的节点承载执行逻辑，边决定下一节点，支持检查点保存执行状态，实现执行的暂停和恢复

编译图

上篇分析了状态图，状态图是图的结构，目的是为了方便构建图；而编译图数据结构，目的是为了高效执行

上图是编译图类图，编译把整个图，包括子图的数据结构转换为扁平化的邻接表结构。并行分支，使用并行节点，节点内处理并行，执行器无需处理并行。

nodes 图的节点集，类型Map<String, AsyncNodeActionWithConfig<State>>

edges 图的边集，类型Map<String, EdgeValue<State>>

结构是变种的邻接表，与正常邻接表不同，编译图有默认起始节点START，节点Id获取EdgeValue计算出后续的连接的节点

EdgeValue: 封装了边的信息，二选一

- 字符串: 节点的id，简单路由，指向一个节点
- EdgeCondition: 条件
EdgeCondition: 条件，决定走哪条边。
- 动作 (acton): 条件的判断逻辑
  - AsyncCommandAction: 返回命令 (Command)。
- 映射关系 (mappings): 条件和节点的映射关系集，例如，X:x， EdgeCondition返回'X'，边走'x'节点

下面分析编译的原理和源码

扁平化邻接表

ProcessedNodesEdgesAndConfig 负责扁平化状态图数据结构，以示例解释代码逻辑

介绍一下连接表，

'A': $'B'$ ,

'B': $'C'$ ,

'C': \[\]

连接点结构，左是head节点，'A','B','C'; 右是数组，代表head节点连接的节点

对应的图

进一步，假设B是子图节点，其子图 D->E, D->F,E->G,F->G

ProcessedNodesEdgesAndConfig 处理过后

|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 'A': $'B-D'$ , 'B-D': $'B-E', 'B-F'$ , 'B-E': $'B-G'$ , 'B-F': $'B-G'$ , 'B-G': $'C'$ , 'C': \[\] | |

图的数据结构扁平化，合并到一个**邻接表结构，**主图与子图节点(B)的连接重定向到子图的节点，子图节点名称修改，格式%s-%s

最后，返回子图的Node写入到nodes，节点id为key，action为value的map

CompiledGraph.CompiledGraph()

nodes是最终的邻接表head节点集

！注意，lg4j子图节点有两种，一种是StateGraph，也就是状态图，另一种CompiledGraph，编译图，只有状态图编译打平，编译图是保留独立的执行，用在多agent的子agent

边和并行处理

ProcessedNodesEdgesAndConfig处理后，返回边(edges)是list，图遍历按节点找边需要遍历list，因此边数据需要转为map，以sourceNodeId为key，List<Edge>类型转为Map<String, EdgeValue>，另外，图有并行分支，编译使用并行节点替代，并行执行action完成在并行节点内完成，不需要执行器介入

下图，边处理分多targes和单个target