agent框架langgraph4j原理源码分析 图 I状态图，推理框架

简介

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

系列内容：

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

> 状态图

>> StateGraph分析

>> 推理框架

> 编译图

> 执行图

>> 检查点

>> aync-generator

>> 执行分析

>>> 中断/恢复

>>> 取消执行

> agent和集成

>> 简单agent

>> 多agent

> 观测

> studio

本文基于langgraph4j v1.8.20

关键词

agent

graph

缩写

spring ai 缩写sa

langgraph4j 缩写 lg/lg4j

参考资料

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.外部能力生态层：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, 推理框架映射成graph，以图的节点承载执行逻辑，边决定下一节点，支持检查点保存执行状态，实现执行的暂停和恢复

状态图

本节分析状态图(StateGraph)，状态图数据结构适用构建图

上图是图结构类图，展示了一个用于构建复杂、有状态 workflow AI 应用的框架结构, 是构建推理框架的“蓝图”。其核心思想是通过定义节点（Nodes）、边（Edges）和状态（State）来编排执行流程。

StateGraphC位，是整个系统的中枢，它负责管理和编排整个执行流程，标准的图结构，有节点和边组成

节点 (Nodes)

• Node: 节点接口/类。
  • 动作工厂: 每个节点都关联ActionFactory，该工厂负责创建异步动作 AsyncNodeActionWithConfig。这个动作是节点执行逻辑。AsyncNodeActionWithConfig是BiFunction ，若设置action类型是NodeActionWithConfig，AsyncNodeAction等function类型，使用AsyncNodeActionWithConfig统一适配

边 (Edges)

• Edge: 图的一条边
  • 目标 (targets): 节点一个或多个出边， EdgeValue
• EdgeValue: 封装了边的信息，二选一
  • 字符串: 节点的id，简单路由，指向一个节点
  • EdgeCondition: 条件
• EdgeCondition: 条件，决定走哪条边。
  • 动作 (acton): 条件的判断逻辑
    • AsyncCommandAction: 返回命令 (Command)。
  • 映射关系 (mappings): 条件和节点的映射关系集，例如，X:_x_， EdgeCondition返回‘X’，边走’_x_’节点

状态（state）和状态维护组件channel放到执行图分析

推理框架

推理框架是智能体的“思维方式”，定义了 Agent 如何思考、规划、决策以及适应环境，是一个结构化的流程，常用的 ReAct、CoT、Reflection、Plan-and-Execute，可以认为,

agent = 推理框架 + 上下文 + 工具

其中上下文，包括系统提示词，工具说明，对话记忆，用户提示词等，可以看到，agent的不可缺少是推理框架，其他可以根据用户任务设置，agent封装了特定框架，在saa，推理框架映射成特定”图”型。

上节分析了图模型，下面分析agent的推理框架graph实现

Reflection适用做好一件事，重心在迭代，它不关心“下一步做什么”，只关心“现在这个够不够好”反复打磨，直到达到要求

ReAct适用做完一件事，重心在交互，每一步都依赖上一步的观察结果，路径是动态生成的，思考，动作，观察，再思考确定下一步，一步步完成事情

P&E适用做成一件事，重心在执行，既定的步骤，确保事情做成

Cot适合逻辑推理场景，重心在推导，复杂问题拆成中间步骤，一步步推出结论

agent builder框架

本节首先介绍下agent构建框架，agent篇分析了lg4j给开发者的开发范式，本节针对该范式问题重新设计

上图 回顾lg4j的agent构建框架,整体架构采用了清晰的分层设计，三层组成：

1. 面向用户agent的交付接口AgentExecutor.builder
2. 可重用的 AI组件集成层Agent.Builder/ReactAgent.Builder
3. 图构建核心层Agent.Builder

lg4j的框架有几个问题：

1 Agent.Builder/ReactAgent.Builder 创建调用模型action和工具调用action，依赖Agent.Builder

2 没有集成springboot，构建依赖很繁琐

3 类命名不太理想

上图新的agentbuilder框架

1. AgentActionBuilder 合并Agent.Builder/ReactAgent.Builder，不依赖Agent.Builder，负责构建model调用和action调用等基础部件，可重用，其他部件通过继承增加
2. ReAct，ReAct推理框架，负责构建ReAct图
3. ReActAutoConfiguration 自动配置，注入springboot自动配置组件，包括lg4j，springai等
4. 用户agent 注入ReAct

下面分析几种推理框架的构图

Relection

Reflection（反思）是一种 AI 自我评估、优化自身输出的思维范式。Reflection 聚焦于内部自我批判和迭代改进——让模型扮演"生成者"和"评审者"双重角色，通过多轮自我优化提升输出质量

Reflection循环一般包含：

• 生成阶段 (Generation)：模型根据指令生成初始输出
• 反思阶段 (Reflection)：模型（或另一个模型）对输出进行批判性评估
• 优化阶段 (Refinement)：回到生成阶段，基于反思结果改进输出
• 迭代控制：设置最大轮次，直到质量达标或达到上限

下图是Reflection构建示例

上图ReflectAgent构建图

上图自动配置部分，

依赖 chatModel，stateSerializer通过springboot机制注入

两个AgentActionBuilder 构建2套调用模型/调用工具action(本实例没有用到工具调用)，工具可以根据需要分组，支持配置不同的model

返回Reflection，注入到用户agent

上图是对应的流程图， generate生成节点，reflection生成节点；边的条件，前面的generateCount，迭代累计超过最大迭代stop；后面的检查生成的质量，使用打分，给出评价，决定是下一轮生成还是stop。

​​​​​​​ReAct

ReAct（Reasoning + Acting）是一个“思考 →行动 →观察 →再思考”的闭环流程。它让大语言模型（LLM）不再是只靠内部知识“空想”，而是能在需要时调用外部工具（Tool）获取信息，再基于这些新信息进行下一步推理，直到最终完成任务。

saa实现了react示例，用ReactAgent实现，带天气查询工具，回答天气相关的问题，如，查询天气并推荐活动

下面以saa graph包的react示例分析

上图ReactAgent生成的图，这是简单的ReAct

1 reasoning 推理节点，按用户请求生成内容

2 action节点，没有设置动作，toolCallAction是CommandAction放到边

3.边执行toolCallAction，返回结果决定走向

下面看一下构建ReAct图

上图 构建ReAct图的代码

上图 ReAct自动配置，AgentActionBuilder创建一套调用模型action和工具调用action

​​​​​​​plan and execute

Plan-and-Execute（规划与执行） 是一种专为解决复杂、多步骤任务而设计的 AI Agent 架构范式，其核心思想是将“思考”与“行动”解耦，先由规划器制定全局路线图，再由执行器按步骤逐一落实，从而避免传统 ReAct 模式在长任务中容易出现的逻辑跑偏、无限循环和上下文爆炸等问题。

下面以示例分析Plan and Execute

上图Plan and Execute图

• planner (规划节点): 流程的第一步，负责根据输入制定执行计划（通常是将大任务拆解为子任务列表）。
• executor (执行节点): 负责执行计划中的具体步骤或子任务。
• check state (状态检查): 条件判断节点，这是一个决策点，用于评估当前任务的执行进度。
• finalizer (终结节点): 任务全部完成或需要输出最终结果时，该节点负责整理并生成最终回复

上图 Plan and Execute图的构建代码，代码从saa拷过来，稍作修改即可执行，saa和lg4j图框架相似度很高，这里也展示另一种构建方式，没有使用agent builder框架，直接手搓，适合action有定制逻辑，通常是model调用消息的修改，当然也可以通过继承AgentActionBuilder和call model action和call tool action实现

其他

多agent也可使用图映射和执行，放到agent篇 II 多agent分析