简介langgraph4j是java技术栈ai agent框架深入掌握其源码与原理指导agent的开发重构/改造框架增加特性快速定位和修复bug发布私有版本系列内容 架构包括逻辑架构运行架构集成架构 状态图 状态和序列化 StatGraph分析 编译图 执行图 检查点 aync-generator 执行分析 中断/恢复 agent和集成 观测 studio本文分析agent和集成第一部分 I ReAct Agent本文基于langgraph4j v1.8.20关键词workflow/agenticlangchain4j/springai缩写langgraph4j缩写lg4jspring ai 缩写 sa参考资料Overview - LangGraph4j langgraph4j官网mp.weixin.qq.com/mp/appmsgalbum?actiongetalbumalbum_id4540202703779627014spring 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长期记忆、mcptoolskills工具调用与技能扩展等。LangGraph4j也集成了langchain4j5.开发工具Studio (可视化开发工具)lg4j的Studio模块提供了一套完整的可视化调试和开发界面让开发者能够直观地看到图的执行路径和状态流转极大地降低了复杂 Agent 的开发门槛。agent和集成本节分析lg4j的agentagent可以看作推理框架的包装agent的主要作用是集成与图的粘合同时负责图的构建。lg4j的agent分两部分一部分是lg4j的core部分负责”图形”也可以认为是推理框架另一部在集成模块单agent本节分析简单agent首先看看lg4j core部分上图 lg4j侧的Agent.Builder使用状态图的addNodeaddEdge构建图节点边和节点的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多agentsupervisor模式handoffs模式