简介
langgraph4j是java技术栈ai agent框架，深入掌握其源码与原理，指导agent的开发，重构/改造框架，增加特性，快速定位和修复bug，发布私有版本
系列内容：
> 架构，包括逻辑架构，运行架构，集成架构
> 状态图
>> 状态和序列化
>> StatGraph分析
> 编译图
> 执行图
>> 检查点
>> aync-generator
>> 执行分析
>>> 中断/恢复
> agent和集成
> 观测
> studio
本文分析agent和集成，第一部分 I ReAct Agent
本文基于langgraph4j v1.8.20
关键词
workflow/agentic
langchain4j/springai
缩写
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的逻辑架构图，逻辑架构展示lg4j功能模块，描述其职责，模块通过精密的协作，共同支撑起复杂 Agent 的构建与运行。
逻辑架构解构为以下四个核心域：图编排、执行与状态、基础设施扩展、集成外部能力生态、开发支持
1. 核心编排层：图的蓝图与引擎
StateGraph ( 状态图)：这是开发者构建 Agent 的核心抽象。它代表了整个工作流的"蓝图"，开发者在这里定义有哪些节点（Node）以及它们之间的流转规则（Edge）。
CompiledGraph ( 编译图)：当 StateGraph 被构建完成后，经过 compile() 方法转化而来。编译图重整了状态图的数据结构，支持高效的图执行；编译图包含了流执行逻辑、状态机引擎和调度策略的"可运行实例"。
2. 执行与状态层：原子动作与数据流转
3. 基础设施扩展层：持久化、异步与可观测
4. 外部能力生态层：AI 核心能力
这一层是LangGraph4j 与 AI 生态对接。
- Spring AI：作为底层的能力供给层，Spring AI 提供了 Agent 所需的原子能力，包括 LLM model（大语言模型）、RAG（检索增强生成）、prompt（提示词工程）、memory（长期记忆）、mcp&tool&skills（工具调用与技能扩展）等。
- LangGraph4j也集成了langchain4j
5. 开发工具
Studio ( 可视化开发工具)：lg4j的Studio模块提供了一套完整的可视化调试和开发界面，让开发者能够直观地看到图的执行路径和状态流转，极大地降低了复杂 Agent 的开发门槛。
agent和集成
本节分析lg4j的agent，agent可以看作推理框架的包装，agent的主要作用是集成与图的粘合，同时负责图的构建。lg4j的agent分两部分，一部分是lg4j的core部分，负责"图形"，也可以认为是推理框架；另一部在集成模块
简单agent
本节分析简单agent，首先看看lg4j core部分
上图 lg4j侧的Agent.Builder，使用状态图的addNode，addEdge构建图，节点，边和节点的action
注意到，callModelAction和executeToolsAction类型是action接口，不是强类型，不能用类型确定这是调用model的action，这是lg4j集成的问题，为了集成不同框架，代码上的妥协
上图agent的"图形"，agent节点是调用model，也就是ReAct的推理节点; executeToolsAction作为边的Condition，执行结果在EdgeMappings选择走那条边
下面分析agent的集成spring ai集成部分
上图 agent的全貌，是lg4j给开发者的范式
上图展示了 AgentExecutor 的全貌，体现了 lg4j 为开发者提供的一套标准化的 Agent 开发范式。
整体架构采用了清晰的分层设计，三层组成：
面向用户agent 的交付接口AgentExecutor.builder
用户agent使用AgentExecutor构建StateGraph
可重用的 AI 组件集成层Agent.Builder/ReactAgent.Builder
- 这一层深度集成了 Spring AI 的基础能力，具备高度的可重用性。
- 节点动作 (Action) 抽象：封装 AI 基础能力为标准的动作节点，例如 CallModelAction（负责调用大模型）和 ExecuteToolsAction（负责调用工具）。
- 基础服务封装 ：
- 模型调用： ReactAgent.ChatService 接口和其实先 DefaultChatService，底层对接springai的ChatModel
- 工具调用：SpringAIToolService，封装 ToolCallback 接口，支持各类工具、MCP (Model Context Protocol) 以及 Skills
- 钩子机制 (Hooks)：提供 callModelHooks 和 executeToolsHooks，允许开发者在模型调用和工具执行的各个生命周期阶段进行拦截、监控或逻辑处理。
图构建核心层Agent.Builder
底层的 lg4j 图构建器，这一层屏蔽了复杂的底层细节，负责将上层的各种 Action（节点）、Hook 以及状态映射进行组装成向用户交付可编译的 StateGraph
示例：
上图用户agent示例，使用AgentExecutor构建ReAct的状态图
总结：
Agent 的设计范式通过这三层解耦，用户agent，最顶层AgentExecutor交付可执行的StateGraph，中间层复用 Spring AI 提供的标准化 AI 能力，底层 lg4j 核心的 Builder 完成最终的图形装配与生成，复用图结构，即复用推理框架。
NEXT
多agent，supervisor模式，handoffs模式