agent框架langgraph4j原理源码分析 图 III 执行图1原理分析

简介

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

系列内容：

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

> 状态图

>> StatGraph分析

>> 推理框架

> 编译图

> 执行图

>> 检查点

>> aync-generator

>> 执行分析

> agent和集成

>> 简单agent

>> agent框架，多agent

>> 分布式agent

> 观测

> studio

本文分析图执行，分为原理分析和源码分析

本文基于langgraph4j v1.8.20

关键词

agent

graph

缩写

langgraph4j缩写lg4j

spring ai 缩写 sa

参考资料

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，以图的节点承载执行逻辑，边决定下一节点，支持检查点保存执行状态，实现执行的暂停和恢复

执行图

上篇分析了图编译，编译后图具备高效执行的数据结构，本文分析图执行。

中断

本节介绍lg4j的中断机制，中断图执行等待外部干预，常用于人工验证，同时生成检查点(CheckPoint)，用于恢复执行

中断机制两种实现方式，

1. InterruptableAction 实现该接口的NodeAction，执行识别Action类型，中断，返回提示，等候外部介入，恢复执行
2. interruptsBefore /interrupteAfter 设置interruptsBefore/ interrupteAfter，在CompileConfig设置哪个节点的前/后中断，执行时识别，中断处理

检查点

本节介绍检查点，检查点是图的执行期重要的组件，负责保存执行环境，用作中断后执行恢复，回溯等关键功能，也是图执行容错机制的支撑，agent的短期记忆组件。

上图检查点的类图

CheckPoint 检查点保存着图执行的上下文，用于中断恢复，容错，回放等

id：checkpoint id，

state：全局状态，AgentState

nodeId/nextNodeId 当前执行的nodeId，下一个执行nodeId

检查点整体存储类似文件夹，文件夹id就是threadId(会话id)，通常外部传入，checkpoints按时间倒序list存储

BaseCheckPointSaver 检查点存储接口，有多种实现，redis，memory，mysql等

aync-generator

本节分析aync-gernerator组件，流式异步迭代组件，异步流式遍历图

上图 async-generator核心类图

1. AsyncGenerator( 核心接口/ 容器)
   • 对外暴露的异步迭代器接口 ，继承了 Iterable接口，提供了标准的 hasNext() 和 next() 方法，顾名思义，异步生成器，异步生成元素，概念有点类似flux，数据流处理，但前者是拉式，消费者主动；后者是订阅， flux 推动给消费者
   • AsyncGenerator是接口类，同时也是容器，AsyncGenerator的实现类都在里面，看上去是lg4j的风格
2. Base 与 BaseCancellable ( 抽象基类与可取消能力)
   • AsyncGenerator.Base AsyncGenerator抽象基类，提供基础设施，Executor和关闭清理能力
   • AsyncGenerator.BaseCancellable 继承Base，提供了取消（ Cancellation **）**能力。这对于长耗时的图执行至关重要，允许外部在任意时刻中断图的遍历。
3. WithEmbed/Embed ( 执行上下文/ 栈管理)
   • 包含一个 generatorStack，图遍历通过栈的push/pop实现深度遍历，充当了异步生成器的执行上下文或运行时栈。
   • AsyncGenerator.Embed record类，成员是AsyncGenerator和EmbedCompletionHandler，图遍历遇到子图（Subgraph）时，可以通过 Embed 机制将子图的生成器推入栈中，子图执行完毕后再弹出，EmbedCompletionHandler处理，实现图的深度遍历。
4. WithResult WithResult 相对WithEmbed **，**WithResult只包括结果值的生成器，没有内嵌generator
5. InternalIterator 底层 AsyncGenerator "问一句动一下"的异步拉取模式 ，InternalIterator转换成 Stream "源源不断推送"的内部迭代模式。消费之能优雅地用 stream() 去消费图引擎的异步结果了，其内部使用jdk stream的Spliterators，分割Iterator，类似于微批成流的机制

图执行类图

下面分析参与执行的类图，类的职责和关系，下节分析互动实现的图遍历执行

上图 参与执行的类图，基于async-generator

CompiledGraph ：编译后高效的图遍历邻接表数据结构

• nodes：图的节点（Node）名称和可执行的异步动作的map。通过节点 ID（String）直接索引，避免了遍历时的线性查找。
• edges：存储图的边（Edge）信息，包含了路由逻辑，当前节点执行完后，下一步该去哪个节点

CompiledGraph.AsyncNodeGeneratorWithEmbed ：图遍历流程主控类

这个类是图遍历的总指挥，继承自 AsyncGenerator.WithEmbed，并实现了 AsyncGenerator 接口。它的核心职责是驱动整个图的异步流式遍历，并管理遍历过程中的上下文（Embed）。

1. 核心机制：委托与流式生成

• delegate (委托)：实际节点执行委托给底层的 AsyncNodeGenerator。将具体的"节点执行"细节下放，自己则专注于"流程控制"。
• stream (流式输出)：它实现了 AsyncGenerator 接口，意味着外部调用者可以通过 hasNext() 和 next() 以拉取（Pull）的方式，一步步获取图遍历过程中产生的中间状态或最终结果。

2. 核心职责：管理 Embed (上下文栈)

• 结合上一节的 async-generator 类图，WithEmbed 维护了一个 generatorStack
• 在图遍历中（尤其是深度优先搜索 DFS 或存在循环/分支的图），当进入一个深层节点时，主控类会将当前状态压入栈（Embed）, 下一轮next优先处理
• 子图执行完毕，主控类负责从栈中弹出上一个状态，恢复上下文

图执行类互动

上节分析了执行图的类图，分析类的职责，静态的关系，本节分析类互动实现图的执行

上图 图执行类互动图

客户端（Client ）使用流式自动化驱动迭代器

• Client 调用编译图stream方法， InternalIterator适配jdk的stream框架自动的流式遍历，底层使用jdk的stream的Spliterators组件
• CompiledGraph.AsyncNodeGeneratorWithEmbed 是调度控制中心，利用 generatorStack 维护执行路径的上下文（Embed），通过压栈深入子图/循环，通过弹栈实现回溯
• CompiledGraph.AsyncNodeGenerator 是节点执行引擎，负责节点动作(action)的异步执行和结果包装（Data/Future），也是智能体的逻辑实现的引擎
• 底层依赖 AsyncGenerator 体系，保证了整个过程是流式、异步且可随时中断和取消，遍历的中间信息实时推送给client

**!**图的遍历也支持迭代器手动next遍历

NEXT

图执行2 源码分析