agent框架langgraph4j原理源码分析(一)-架构

简介

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

系列内容：

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

> 状态图

>> 状态和序列化

>> StatGraph分析

> 编译图

> 执行图

>> 检查点

>> aync-generator

>> 执行分析

> agent

> 观测

> studio

集成springai的分析分布到各相关章节

本文基于langgraph4j v1.8.20

关键词

workflow/agentic

langchain4j/springai

缩写

langgraph4j缩写lg4j

spring ai 缩写 sa

参考资料

Overview - LangGraph4j langgraph4j官网

https://mp.weixin.qq.com/mp/appmsgalbum?action=getalbum&album_id=4540202703779627014 spring ai Alibaba原理源码分析，包括spring ai部分

架构

本节分析lg4j架构，包括场景，逻辑架构，集成架构

场景

本节介绍分析场景

上图场景视图，本文分析的提纲， lg4j的原理源码拆解为四个核心维度：图、状态与存储、 agent 和集成，开发以及两个组件, 观测和流式异步组件(async-generator)

架构是本文，包括场景视图，逻辑视图，集成架构，开发架构描述

下面 lg4j的核心场景分布，我们将逐一解析：

1. " 图" 为核心

lg4j的核心是 Graph （图）, 是一个支持循环（Cycles）的有限状态机

状态图 (StateGraph)：这是构建应用的pipeline，开发者通过定义节点（Nodes）和边（Edges），指定状态（State）如何在节点间传递，实现推理框架
编译图 (CompiledGraph)：状态图经过 compile() 后，变成高效执行的图结构，包含了完整的执行逻辑和生命周期管理
执行图 ：编译后的图被触发时，进入运行阶段，负责驱动状态的流转，流式执行能力 ：
- 并行执行：分支节点并行运行，提升效率
- 中断/ 恢复：执行过程中暂停，常用在请求人工批准，外部介入后恢复执行
- 取消执行：动态终止正在运行的图
- 流式输出 (Streaming)：执行过程可以实时向外部推送数据（如 LLM 的 Token 流），使用异步组件 async-generator 实现，集成springai流式执行返回的flux

2. 状态和检查点：时间与状态的锚点

与普通的函数调用链不同，Agent需要跨越时间和空间。lg4j 通过"检查点和存储"机制实现了图状态的快照，持久和恢复

状态 (State) 和序列化(Serializer)：图在运行过程中产生的所需数据都被视为"状态"。为了让这些状态可被记录和恢复，必须进行序列化（支持 JSON和java对象流），状态和序列化是集成的重点，lg4j适配springai的消息和序列化组件
检查点 (Checkpoint)：这是状态的时间戳。每当图运行到一个关键节点，系统会保存一份"快照"。
存储 (Saver) ：负责将这些快照写入持久化存储（如内存、文件系统或数据库）。通过 Checkpoint 和 Saver 的配合，lg4j实现了时间旅行（Time Travel）功能------你可以回滚到之前的任何一个状态点重新执行。

3. agent 和集成

LangGraph4j专注图，智能体的其他功能，如，工具调用，大模型调用，集成Spring AI来提供

集成 Core：提供了标准的抽象的集成组件，集成的目标框架实现和扩展，提供智能体的基础组件，集成架构中深入介绍
集成 Spring AI：提供与 Spring AI 模型的无缝对接，使得图节点可以直接调用 LLM 能力。

4. 开发

LangGraph4j 提供了可视化开发辅助工具

Studio：一个可视化的agent调试web应用，开发者可以在浏览器中直观地看到图的拓扑结构和实时运行轨迹，与agent交互
生成图片：定义的图逻辑导出为可视化的架构图

逻辑架构

本节分析逻辑架构

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

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

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

这是 lg4j的核心所在，负责定义和驱动状态机的流转。

StateGraph ( 状态图)：这是开发者构建 Agent 的核心抽象。它代表了整个工作流的"蓝图"，开发者在这里定义有哪些节点（Node）以及它们之间的流转规则（Edge）。
CompiledGraph ( 编译图)：当 StateGraph 被构建完成后，经过 compile() 方法转化而来。编译图重整了状态图的数据结构，支持高效的图执行；编译图包含了流执行逻辑、状态机引擎和调度策略的"可运行实例"。

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

这一层支撑着图在运行时的具体行为和数据变化。

Action ( 动作/ 指令)：这是图中节点流转的最小原子单位。无论是执行一个 LLM 调用，还是发送一个消息，都被抽象为具体的 Action（如 Command, AsyncNodeAction, InterruptableAction）。
State ( 状态)：贯穿整个图生命周期的全局数据容器。它包含了 AgentState（Agent 当前状态）、Channel（数据通道，用于节点间通信）和 Reducer（状态归约器，决定状态如何更新）。
Agent：在图的基础上，封装了推理框架，提供了多层次的构建器（如 Agent.Builder，ReactAgentBuilder，ReactAgent.Builder，AgentExecutor.Builder）
Internal ( 内部机制)：包含 edge（边/条件分支）、hook（生命周期钩子）和 node（节点）的具体内部实现。

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

为了让 Agent 能在生产环境中稳定运行，LangGraph4j 提供了强大的基础设施支持。

Checkpoint ( 检查点)：这是 Agent 具备"记忆"和"抗灾"能力的关键。通过 CheckpointSaver 机制，它能在图的执行过程中定期保存 Checkpoint（包含当前状态、执行路径等）。当程序崩溃或需要人工干预时，可以从检查点完美恢复。
Saver ( 持久化器)：为 Checkpoint 提供了丰富的存储后端支持，涵盖了内存级（hazelcast saver）和多种主流数据库（redis saver, mysql saver, postgres saver, oracle saver）。
Async-Generator ( 异步生成器)：支持流式输出（Streaming），确保在长耗时任务中，前端能够实时接收到 Agent 的思考过程或 LLM 的 Token 流。
OpenTelemetry ( 可观测性)：集成了业界标准的可观测性规范。通过 OTELWrapCallTraceHook 等钩子，LangGraph4j 能够自动追踪图的每一次执行、节点的耗时、状态的变化，为性能调优和故障排查提供完整的数据支撑。

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

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

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

5. 开发工具

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

总结:

LangGraph4j 的逻辑架构分成"图的定义，编译和执行"、"状态的管理"、"持久化"和"基础AI 能力"，并通过标准和抽象的接口进行组合。这不仅保证了框架的核心极其稳定，同时也赋予了集成智能体基础组件的极高的灵活性。

集成架构

本节分析集成架构，lg4j专注图框架，智能体基础组件，工具/模型等通过集成来实现，lg4j架构定义了标准和抽象的组件，支持不同的智能体框架集成，目前支持langchain4j和spring ai，本文分析springai集成

上图 lg4j集成架构图，该模块作为一个"胶水层"，适配器将Spring AI 的能力接入到 LangGraph4j

左侧是lg4j的标准组件；中，springai的适配实现

Agent：agent可以看作推理框架的包装，agent的主要作用是集成与图的粘合，同时负责构建图
springai 组件 (Model/Tool/skills) ：
- SpringAIToolService：将 Spring AI 的 Tool 机制封装起来，使其能够被 LangGraph4j 的图逻辑所调用，ExecuteToolsAction依赖其调用springai工具组件
- ReactAgent.ChatService：DefaultChatService 是默认实现，封装了对 Spring AI 中 ChatClient 的调用，ChatModelAction依赖ChatService提供model调用能力
action ：
- ExecuteToolsAction：图节点的action实现，依赖SpringAIToolService，负责工具调用
- ReactAgent.ChatService：DefaultChatService 是默认实现，封装了对 Spring AI 中 ChatClient 的调用，ChatModelAction依赖ChatService提供model调用能力
流式适配 (Generators)： StreamingChatGenerator，将 Spring AI 模型返回的 flux流，适配为 LangGraph4j 的流式执行图（async-generator），从而实现前端的实时显示。
序列化适配：图上显示 Jackson实现，还有java对象流实现，是抽象类，实现类需声明具体的类型即可，springai集成，声明其消息类型，为消息类型设置序列化器。

Spring AI 能力层与生态 (spring ai model / mcp&tool&skills)

这是集成的最终目的。适配层通过标准的接口，调用 Spring AI 框架提供的能力。

- 模型支持 (Model)：Spring AI 统一了各种 LLM 的 API。无论是图中的 OpenAI、阿里千问，deepseek

, 还是其他厂商的模型，lg4j 都无需关心其底层实现，只需通过适配层调用即可。

- 工具与技能 (mcp & tool & skills)： Spring AI 支持的各类工具和生态。LangGraph4j 可以无缝集成这些组件，使 Agent 具备"手"和"脚"。

总结：

lg4j的集成架构展示了一个高度模块化、可扩展的设计，通过适配层 实现了编排与能力的解耦。

在这种架构下：

集成Core 定义标准的抽象的图流转、状态管理和持久化。
集成目标（Spring AI、LangChain4j ）作为可插拔的插件，负责实现特定框架的 API。

开发者 获得了极大的灵活性，可以在同一个图中，轻松混合使用 Spring AI 的 Tool、模型以及自定义的流式生成器，而无需修改核心代码。