图片

让Java开发者像写Spring Boot一样开发AI应用——第五课

写在前面

前四天，我们学会了创建单Agent、理解ReAct循环、构建多Agent协作，还对比了ReAct和Plan-and-Execute两种架构模式。

但你有没有想过一个问题：这些Agent在底层到底是怎么“跑”起来的？

SequentialAgent为什么能把A的输出自动传给B？ParallelAgent为什么能让多个Agent同时执行？RoutingAgent为什么能根据输入动态选择最合适的Agent？

答案就是今天的主题——Graph（工作流图）。

Graph是Spring AI Alibaba Agent Framework的底层运行时基座。你前四天学的所有Agent模式，在底层都会被编排为Graph来执行。

今天，我们就从“写代码”进化到“画流程”。

一、为什么需要Graph？——传统代码的困境

先看一个场景：构建一个“商品评价处理系统”。

需求很简单：接收用户评价 → 判断是好评还是差评 → 好评直接记录 → 差评进一步分类 → 输出处理结果。

如果用传统Java代码实现：

<span leaf=""><span>public</span>&nbsp;<span>String</span>&nbsp;<span>processReview</span>(<span><span>String</span></span><span>&nbsp;review</span>) {</span>

这段代码有什么问题？

| 问题

|

说明
硬编码流程

流程逻辑写在代码里，修改流程需要改代码、重新编译、重新部署

| | 状态管理混乱 |

每个步骤的中间结果需要手动定义变量传递

| | 难以可视化 |

代码无法直观展示流程全貌

| | 难以扩展 |

增加新分支或新步骤需要修改核心逻辑

| | 难以调试 |

流程执行轨迹不清晰，出了问题难以定位

|

💡 提示：传统代码就像用文字描述一张地图——信息都在，但你看不到全貌。Graph就像把地图画出来——路线、岔路口、终点一目了然。

Graph如何解决这些问题？

① 声明式定义，而非命令式编码

你不需要写if-else来控制流程走向，而是声明“节点A之后可以去节点B或节点C，由条件决定”。

② 状态自动管理

所有节点共享一个OverAllState（全局状态），数据在节点间自动传递。你不需要手动定义变量、传递参数。

③ 可视化与可观测

图结构天然适合可视化——可以导出为PlantUML或Mermaid格式的流程图。每个节点的执行情况都可以被追踪。

二、Graph三大核心概念：State、Node、Edge

Spring AI Alibaba Graph有三个核心概念：

| 概念

|

类比

|

说明
State（状态）

流水线上的“手推车”

|

在Node与Edge之间传递的数据结构，是一个Map<String, Object>

| | Node（节点） |

流水线上的“加工车间”

|

执行逻辑单元，接受State作为输入，返回对State的更新

| | Edge（边） |

流水线上的“传送带+路标”

|

定义Node间的控制流，可以是固定连接，也可以是条件分支

|

💡 一句话总结：Node完成工作，Edge告诉下一步该做什么。

State（状态）——数据的“共享大盘”

State是整个Graph的“数据中枢”。每个Node从State读取输入数据，执行逻辑后，将输出数据写回State。下一个Node再从State读取所需的数据。

State在实现上就是一个Map<String, Object>。你可以往里面放任何类型的数据——字符串、数字、列表、甚至复杂的Java对象。

KeyStrategy（键更新策略）——State的精髓

当多个Node向State的同一个Key写入数据时，应该如何处理？这就涉及到KeyStrategy。

| 策略

|

行为

|

适用场景
ReplaceStrategy（覆盖）

新值直接覆盖旧值

|

大多数场景（如：最终分类结果）

| | AppendStrategy（追加） |

新值追加到旧值后面

|

需要保留历史记录的场景

| | 自定义策略 |

开发者自己定义合并逻辑

|

特殊业务需求

|

Node（节点）——执行的“加工车间”

Graph中的每个Node是一个执行逻辑单元。Node可以是任何东西——调用LLM、执行SQL、调用REST API、甚至只是打印一行日志。Graph不关心Node内部做什么，只关心它输入什么、输出什么。

如何定义Node？

自定义Node需要实现NodeAction或NodeActionWithConfig接口：

<span leaf=""><span>// 方式一：NodeAction - 只接收State</span></span>

Edge（边）——流程的“传送带+路标”

Edge定义Node间的控制流，有两种类型：

① 固定边：从节点A一定走到节点B

<span leaf="">Node&nbsp;<span>A</span>&nbsp;────→ Node&nbsp;<span>B</span></span>

② 条件边：根据State中的某个值，决定去哪个节点

<span leaf="">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;┌─ 好评 → Node&nbsp;<span>B</span>（记录）</span>

三、StateGraph vs CompiledGraph：从“蓝图”到“可运行的程序”

在Spring AI Alibaba Graph中，有两个核心类需要区分：

| 维度

|

StateGraph

|

CompiledGraph
职责

图的定义与构建

|

图的执行与运行

| | 阶段 |

设计时（Design-time）

|

运行时（Runtime）

| | 可变性 |

可变（可添加节点/边）

|

不可变（编译后固定）

| | 执行能力 |

无执行方法

|

提供stream()/invoke()

| | 检查点 |

不支持

|

支持检查点保存/恢复

|

💡 提示：StateGraph是建筑图纸，CompiledGraph是建好的房子。你可以在图纸上随意修改设计，但一旦建好就不能改了——不过你可以住进去（执行）。

构建Graph的标准流程：

<span leaf=""><span>Step</span>&nbsp;<span>1</span>：创建StateGraph，定义State策略</span>

⚠️ 重要：在使用Graph之前，必须先编译它。编译不是可选的，而是必须的步骤。编译过程会进行图结构的基本检查（如没有孤立节点等）。

四、Graph vs Agent Framework：两种API怎么选？

Spring AI Alibaba同时提供了两种API：

| | Agentic API（Agent Framework）

|

Graph API
抽象层次

高层声明式API

|

底层原子化API

| | 使用方式 |

使用预置的Agent模式

|

独立定义每个Node和Edge

| | 控制粒度 |

粗粒度

| 细粒度，完全控制 | | 学习成本 | 低 |

中高

| | 灵活性 |

中等

| 极高 |

选型建议：

<span leaf="">开始：我需要构建一个AI应用</span>

核心原则：Spring AI Alibaba推荐开发者优先使用Agent Framework，但直接使用Graph API也是完全可行的。

五、Graph的运行时特性

除了流程编排，Graph引擎还原生支持以下核心能力：

① Streaming（流式输出）

流式响应对于Agent交互非常关键。框架可以将每个Node节点的运行情况、LLM Token实时发送到用户端。

② Human In The Loop（人机协同）

允许对Agent运行过程中的工具调用进行评估、修改、批准。让用户具备为Agent验证有效性、纠正错误、增加上下文的能力。

③ Memory & Context（记忆与上下文）

框架可以处理Agent应用运行期的短期记忆（一个会话周期内的数据）与长期记忆（跨多个会话时了解历史用户偏好与信息）。

④ Persistence（持久化）

Graph具有内置的持久化层，通过检查点（Checkpointers）实现。当使用检查点编译图时，检查点会在每个超级步骤保存图状态的检查点。

六、实战：商品评价分类系统

系统设计

需求：构建一个“商品评价分类系统”工作流。

流程设计：

<span leaf="">用户提交评价 → 情感分析节点 →&nbsp;<span>[条件判断]</span></span>

核心代码实现

Step 1：定义State策略

<span leaf=""><span>@Configuration</span></span>

Step 2：实现各节点

<span leaf=""><span>// 情感分析节点 - 调用LLM</span></span>

Step 3：构建Graph

<span leaf=""><span>@Configuration</span></span>

Step 4：REST Controller触发执行

<span leaf=""><span>@RestController</span></span>

七、Graph高级特性预览

① 并行节点执行

当前节点不依赖上游节点的结果时，可以并行处理。典型场景：同时调用多个LLM做不同分析（如情感分析 + 关键词提取 + 摘要生成），然后合并结果。

② 嵌套子图（Subgraph）

Graph支持在一个节点中嵌入另一个完整的Graph，使得工作流可以模块化复用。

③ 流程图可视化导出

Graph支持导出为PlantUML和Mermaid格式，方便文档化和团队协作。

八、课后挑战

任务：设计一个“智能客服”工作流，包含至少4个节点

要求：

  • 画出工作流的流程图

  • 明确每个节点的职责、输入、输出

  • 至少包含一个条件分支

  • 说明State中需要定义哪些Key

示例参考：

<span leaf="">用户消息 → 意图识别节点 →&nbsp;<span>[条件判断：意图类型]</span></span>

验收标准：

  • 流程图清晰展示至少4个节点及其连接关系

  • 每个节点有明确的职责描述

  • 至少有一个条件分支

  • 列出了State中需要定义的所有Key及对应的更新策略

九、本日核心收获

📌 本文要点回顾：Graph是Spring AI Alibaba Agent Framework的底层运行时基座。通过State（数据）、Node（执行）、Edge（流转）三大核心概念，你可以用“画流程”的方式替代“写代码”的方式构建AI工作流。StateGraph是蓝图，CompiledGraph是可运行的程序——先定义，再编译，最后执行。

有任何问题，欢迎在评论区留言交流！

作者：Java老兵搞AI，专注Java生态下的AI应用开发

如果觉得有用，点个「在看」支持一下吧