Spring AI Alibaba 技术架构与源码分析

zhengliebin

603人浏览 · 2026-09-05 10:17:05

zhengliebin · 2026-09-05 10:17:05 发布

Spring AI Alibaba 技术架构与源码分析

一句话概括：Spring AI Alibaba 不是在 Spring AI 上“加几个阿里云适配器”，而是将整个框架的演进方向从“模型调用抽象”推向了“工作流编排平台”——以 Graph 为运行时基座、以 ReactAgent 为高层抽象、以 A2A + Nacos 为分布式协作骨架，让 Java 开发者用 Spring 的方式构建生产级 Agentic 应用。

一、引言

如果你是一个 Java 开发者，在 Spring Boot 项目里用过大模型，你大概经历过这样的场景：

// 用 Spring AI 调用模型——很干净
String response = chatClient.prompt("你好").call().content();

// 但当业务需要多步骤协作时，代码开始变得复杂
// 第一步：调用模型分析
// 第二步：根据分析结果决定调用哪个工具
// 第三步：根据工具结果再调用模型
// 第四步：如果需要人工审批，暂停等待...
// ——这些逻辑散落在 Service 层，难以维护，更无法可视化

几行代码调用模型很轻松，但当你的应用需要多步骤推理、条件分支、工具循环、人工审批、状态持久化时，你发现自己正在用 if-else 和 while 手搓一个工作流引擎。这在 Python 生态里有 LangGraph，在 Java 生态里呢？

Spring AI Alibaba 正是为回答这个问题而生的。

Spring AI Alibaba（以下简称 SAA）由阿里云团队主导开发，于 2024 年 9 月正式开源。它基于 Spring AI 构建，是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践。项目官网明确写道：“Spring AI Alibaba 是构建 Agentic、Workflow 和 Multi-agent 应用的生产就绪框架” 。截至 2026 年 8 月，项目已迭代至 1.1.2.x 系列，在阿里巴巴集团十余条核心业务线生产环境深度使用。

SAA 的特别之处在于：它不是 Spring AI 的“阿里云适配器”，而是一个在 Spring AI 之上重构了 Agent 编程范式的框架——它把“Agent 推理框架映射成 Graph”，用 Graph 作为运行时基座，让 Java 开发者用 Spring 的方式构建生产级 Agentic 应用。

那么，这个“把 Agent 变成 Graph”的 Java 框架到底是如何设计的？为什么说它“不只是 Spring AI 的阿里云版本”？它的 Graph 引擎和 ReactAgent 背后是什么原理？我们从源码出发，一步步拆解。

二、整体架构与设计哲学

2.1 架构总览：三层引擎 + 一个管理平台

SAA 的整体架构可以用“三层引擎 + 一个管理平台”来概括：

┌──────────────────────────────────────────────────────────────────────┐
│                Admin & Studio 层（可视化与运维平台）                 │
│    可视化 Agent 开发 · 可观测性 · 评估 · MCP 管理 · 一键部署         │
├──────────────────────────────────────────────────────────────────────┤
│                 Agent Framework 层（高层抽象）                       │
│    ReactAgent（ReAct 范式）· SequentialAgent · ParallelAgent         │
│    RoutingAgent · LoopAgent · 上下文工程 · HITL · 钩子与拦截器      │
├──────────────────────────────────────────────────────────────────────┤
│                   Graph Core 层（运行时引擎）                        │
│    StateGraph · 节点与边 · 条件路由 · 嵌套图 · 并行执行              │
│    检查点 · 中断与恢复 · 状态持久化（PG/MySQL/Redis/File）          │
├──────────────────────────────────────────────────────────────────────┤
│              Augmented LLM 层（Spring AI 基础抽象）                  │
│    ChatModel · EmbeddingModel · Message · Prompt · Tool · MCP       │
│    Vector Store · RAG · Advisor · 结构化输出                        │
└──────────────────────────────────────────────────────────────────────┘

图：Spring AI Alibaba 的四层架构。最底层是 Spring AI 的基础抽象，Graph Core 提供工作流编排运行时，Agent Framework 提供高层 Agent 抽象，Admin & Studio 提供可视化管理平台。

各层职责：

层级	职责	关键模块
Admin & Studio	可视化 Agent 开发、可观测性、评估、MCP 管理	`spring-ai-alibaba-admin`、`spring-ai-alibaba-studio`
Agent Framework	以 ReactAgent 为核心的高层 Agent 开发框架	`SequentialAgent`、`ParallelAgent`、`RoutingAgent`、`LoopAgent`
Graph Core	底层工作流编排运行时，状态管理与持久化	`StateGraph`、`CompiledGraph`、检查点机制
Augmented LLM	Spring AI 的底层原子抽象	`ChatModel`、`Tool`、`MCP`、`Vector Store`

看到这里，你可能会问：Spring AI Alibaba 和 Spring AI 到底是什么关系？

用一句话说：Spring AI 提供“零件”（模型、工具、消息等底层抽象），Spring AI Alibaba 提供“装配线”（Graph 引擎 + Agent 框架） 。SAA 的定位是在 Spring AI 之上，为 Java 开发者提供一套生产级的 Agent 工作流编排能力。官方文档将其描述为“深度集成 Spring AI 生态，专为多智能体系统和工作流编排设计的项目”。

2.2 设计哲学：Graph 是运行时基座，ReactAgent 是高层抽象

SAA 的设计建立在几个核心判断之上：

判断一：Agent 不是对话，是工作流。 真实的企业级 Agent 需要多步骤推理、条件分支、并行执行、人工审批——这些无法用线性对话表达，必须用图（Graph） 来建模。

判断二：Graph 是运行时基座，Agent 是高层抽象。 SAA 的 ReactAgent 实际上运行在 Graph Runtime 之上。开发者可以使用 Graph 底层 API 直接构建工作流，也可以使用 Agent Framework 获得既定的图形，简化 Agent 的开发。

判断三：企业级能力不是外挂，是内置。 持久化、可观测、人在回路、分布式协调——这些能力从第一天就内置于 Graph Core 中。

判断四：Agent 需要团队协作。 通过 A2A（Agent-to-Agent）+ Nacos 实现分布式 Agent 协调。

官方设计原则：

原则	含义	在框架中的体现
推荐 ReactAgent	用内置的 ReactAgent 快速构建 Agent 应用	`ReactAgent.builder()` 开箱即用
预置多智能体模式	复杂场景使用内置工作流模式	`SequentialAgent`、`ParallelAgent`、`RoutingAgent`、`LoopAgent`
Graph API 兜底	超高定制化场景直接使用 Graph API	更灵活的编排、更直接的状态控制

2.3 包结构与代码规模

SAA 采用 Maven 多模块结构：

spring-ai-alibaba/
├── spring-ai-alibaba-agent-framework/   # 多 Agent 框架（Sequential, Parallel, Routing, Loop）
├── spring-ai-alibaba-graph-core/        # Graph 运行时（持久化、工作流编排、状态管理）
├── spring-ai-alibaba-studio/            # 嵌入式 UI 调试面板
├── spring-ai-alibaba-admin/             # 一站式 Agent 平台（可视化开发、可观测、MCP 管理）
├── spring-ai-alibaba-bom/               # 依赖管理 BOM
├── spring-boot-starters/                # Spring Boot Starters
│   ├── spring-ai-alibaba-starter-a2a-nacos/      # Nacos A2A 通信
│   ├── spring-ai-alibaba-starter-builtin-nodes/  # 内置工作流节点
│   ├── spring-ai-alibaba-starter-config-nacos/   # Nacos 动态配置
│   └── spring-ai-alibaba-starter-graph-observation/ # 可观测性
└── examples/                            # 示例应用

截至 2026 年 8 月，项目已迭代至 1.1.2.x 系列，最新稳定版本为 1.1.2.2。

2.4 技术栈速览

层次	技术选型
语言	Java 17+
框架基础	Spring Boot 3.5.x、Spring AI 1.1.x
云原生集成	阿里云 DashScope、Nacos（服务发现与配置）
可观测性	Spring Cloud Observation（Micrometer/OpenTelemetry）
持久化	PostgreSQL、MySQL、Oracle、MongoDB、Redis、File
许可证	Apache 2.0

三、核心抽象与编程模型

3.1 ReactAgent——ReAct 范式的 Java 实现

好了，现在来回答刚才那个问题：SAA 的 ReactAgent 和普通的 ChatClient 有什么区别？

ChatClient 是一次性的“问答”，ReactAgent 是可迭代的“推理-行动”循环。

// 文件路径：示例代码 —— ReactAgent 使用

ReactAgent agent = ReactAgent.builder()
    .name("weather_agent")
    .model(chatModel)
    .instruction("You are a helpful weather forecast assistant.")
    .build();

agent.call("what is the weather in Hangzhou?");

ReactAgent 遵循 ReAct（Reasoning + Acting）范式，即“推理 → 行动 → 观察 → 再推理”的循环：

┌─────────────────────────────────────────────────────────────────────┐
│                    ReAct 循环                                       │
│                                                                     │
│  ① 用户输入 → Agent 推理（Reasoning）                               │
│         ↓                                                           │
│  ② 决定是否需要调用工具（Acting）                                   │
│         ├── 不需要 → 生成最终答案                                   │
│         └── 需要 → 调用工具 → 获取结果 → 回到 ①                    │
└─────────────────────────────────────────────────────────────────────┘

设计模式解读：ReactAgent 是模板方法模式（Template Method Pattern） 的体现——它定义了 ReAct 循环的固定流程骨架（推理→决策→执行→观察），而具体的模型、工具、钩子则是可插拔的“步骤”。

设计权衡分析：

收益：①ReAct 循环开箱即用，开发者无需手写 while 循环；②内置上下文工程和 HITL 支持；③Agent 运行在 Graph 之上，自动获得状态管理能力。
代价：①ReactAgent 是高层抽象，对于需要完全自定义执行逻辑的场景不够灵活；②框架层面有额外的调度开销。
适用场景：绝大多数需要工具调用和多步推理的 Agent 场景；需要极致自定义的场景可直接使用 Graph API。

3.2 StateGraph——图的三要素：State、Node、Edge

Graph Core 是 SAA 整个框架的“心脏”。它的核心模型只有三个概念：

// 文件路径：spring-ai-alibaba-graph-core（结构示意）

// ① State：共享状态 —— 所有节点共享的数据结构
public class State {
    private Map<String, Object> data;  // 所有节点共享的数据
}

// ② Node：节点 —— 执行具体逻辑
public interface Node {
    Object execute(State state);  // 接收 state，返回更新
}

// ③ Edge：边 —— 决定下一个节点
public interface Edge {
    String route(State state);    // 返回下一个节点 ID
}

Graph 以图的节点承载执行逻辑，边决定下一节点，支持检查点保存执行状态，实现执行的暂停和恢复。

三要素详解：

要素	说明	预置类型
State	全局共享数据，贯穿流程	`Map<String, Object>` + 归约策略
Node	封装具体操作或模型调用	`LlmNode`、`ToolNode`、`KnowledgeRetrievalNode`、`QuestionClassifierNode` 等 15+ 种
Edge	表示节点间的跳转关系	普通边（固定跳转）、条件边（动态路由）

构建流程：

构建（Build）→ 编译（Compile）→ 执行（Execute）

构建：使用 StateGraph 添加节点和边，定义工作流结构
编译：调用 compile() 验证图结构、生成可执行对象 CompiledGraph
执行：CompiledGraph.invoke(input) 按拓扑序调度执行

设计模式解读：StateGraph.compile() 是构建器模式（Builder Pattern） 的经典应用——StateGraph 负责“构建”，compile() 负责“产出可执行产品”。这种分离使得构建阶段可以自由添加/删除节点，编译后图结构固定，可安全并发执行。

设计权衡分析：

收益：①图结构天然支持分支、循环、并行等复杂工作流；②检查点机制让长运行 Agent 可以暂停和恢复；③与 LangGraph 等 Python 框架设计理念对齐，降低了跨语言学习成本。
代价：①图抽象比线性管道更复杂，学习曲线较陡；②对于简单的“问答”场景，图的开销高于直接调用 ChatClient。
适用场景：多步骤、多分支、需要持久化的复杂 Agent 工作流；简单的对话场景直接使用 ChatClient 即可。

3.3 内置多智能体模式——开箱即用的团队协作

SAA 的 Agent Framework 提供了四种内置的多智能体工作流模式：

模式	说明	适用场景
SequentialAgent	按顺序依次执行多个 Agent	有明确依赖链的确定性流程
ParallelAgent	多个 Agent 并行执行	大量相似独立任务的处理
RoutingAgent	根据输入路由到不同 Agent	不同输入需要不同专业处理
LoopAgent	循环执行直到满足条件	需要迭代优化的任务

这些模式让开发者可以用声明式的方式构建多智能体系统，而不需要手写复杂的编排逻辑。多 Agent 协作的核心是上下文工程——决定每个 Agent 看到什么信息。

3.4 上下文工程——让 Agent 更可靠

SAA 将“上下文工程”作为内置的一等公民能力：

策略	说明
人在回路（HITL）	高风险操作前暂停，等待人工审批
上下文压缩	对话历史过长时自动压缩
上下文编辑	动态修改上下文内容
模型与工具调用限制	防止无限循环
工具重试	工具调用失败时自动重试
规划	复杂任务分解为步骤
动态工具选择	根据上下文智能选择可用工具

这些策略通过钩子（Hooks）和拦截器（Interceptors） 实现，允许开发者挂接到 Agent 生命周期的任何步骤。

设计模式解读：Hook/Interceptor 体系是观察者模式（Observer Pattern） 和责任链模式（Chain of Responsibility Pattern） 的结合——各钩子在特定事件点被触发执行，多个钩子可以串联形成处理链。

3.5 A2A + Nacos——分布式 Agent 协调

SAA 的 A2A（Agent-to-Agent） 机制让 Agent 能够相互寻求和通信：

Agent A → Nacos 服务注册 → Agent B 发现 Agent A → 通信协作

A2A 通过 Nacos 作为注册中心实现了分布式 Agent 协调。Agent 可以注册自己的能力，其他 Agent 通过 Nacos 发现并调用这些能力——这让多 Agent 系统可以跨越多个微服务实例部署。

3.6 MCP 支持——Model Context Protocol 的 Java 实现

SAA 提供了 MCP（Model Context Protocol） 支持，包括：

Client 端：调用外部 MCP Server 的工具
Server 端：暴露 Agent 能力为 MCP 服务
MCP Registry：服务注册发现
MCP Gateway：统一入口、路由转发、负载均衡

这种设计让 Agent 可以无缝接入 MCP 生态，与其他 MCP 服务互操作。

四、核心模块源码解析

4.1 Graph Core——graph-core 模块

职责：提供有向图编排运行时，是整个框架的“心脏”。

核心类与接口：

类/接口	职责
`StateGraph`	状态图构建器，定义节点和边
`CompiledGraph`	编译后的可执行图
`Node`	节点接口，定义执行逻辑
`Edge`	边接口，定义路由逻辑
`OverAllState`	全局状态，贯穿流程共享数据

Graph 的核心数据结构：

图结构由节点和边组成
支持条件路由、嵌套图、并行执行和状态管理
编译后生成扁平化图结构和邻接表结构

4.2 Agent Framework——agent-framework 模块

职责：提供以 ReactAgent 为核心的高层 Agent 开发框架。

核心组件：

组件	职责
`ReactAgent`	ReAct 循环的 Agent 实现
`AgentLlmNode`	LLM 调用的节点封装
`AgentToolNode`	工具执行的节点封装
`Hook / Interceptor`	生命周期拦截与增强

ReactAgent 的构建流程：

// 文件路径：spring-ai-alibaba-agent-framework（结构示意）

ReactAgent agent = ReactAgent.builder()
    .name("my-agent")
    .model(chatModel)
    .instruction("系统提示词")
    .tools(toolList)                    // 工具列表
    .hooks(List.of(hook))               // 钩子/拦截器
    .saver(new PostgresSaver())         // 检查点保存器
    .build();

关键设计：ReactAgent 的底层运行在 Graph 之上——builder() 在背后构建了一个标准的 ReAct 循环图（LLM 节点 ↔ 工具节点），然后编译为 CompiledGraph 执行。

4.3 钩子与拦截器——生命周期增强

SAA 的 Hook/Interceptor 机制覆盖 Agent 全生命周期：

// 文件路径：示例代码 —— Hook 实现

public class MyHook implements AgentHook {
    @Override
    public State beforeLlm(State state) {
        // 模型调用前：注入额外上下文
        state.put("context", loadContext());
        return state;
    }
    
    @Override
    public State afterLlm(State state) {
        // 模型调用后：记录 token 用量
        logTokenUsage(state);
        return state;
    }
}

通过 Hook 可以实现日志记录、记忆管理、权限控制、审计追踪等横切关注点。

4.4 Studio 与 Admin——从开发到运维的完整闭环

SAA 提供了两个可视化工具：

Studio：嵌入式 UI 调试面板，用于可视化调试 Agent 执行。

Admin：一站式 Agent 平台，提供：

可视化 Agent 开发
可观测性（指标收集、链路追踪）
评估（数据集构建、线上链路数据复用）
MCP 管理
一键部署

Admin 还集成了 Dify 等开源低代码平台，支持从 DSL 快速迁移到 SAA 项目。

五、核心执行流程与运行时机制

5.1 执行流程——从 Agent.call 到 Graph 执行

当你调用 agent.call("用户问题") 时，底层发生了什么？

┌─────────────────────────────────────────────────────────────────────┐
│ 1. 用户调用 agent.call("用户问题")                                 │
│    ↓                                                               │
│ 2. ReactAgent 将调用委托给底层 CompiledGraph                        │
│    ↓                                                               │
│ 3. Graph 初始化状态 → 进入超步循环                                  │
│    ↓                                                               │
│ 4. 第一超步：执行 LLM 节点（AgentLlmNode）                         │
│    ├── 执行前置 Hooks（beforeLlm）                                 │
│    ├── 调用 ChatModel → 获取响应                                  │
│    └── 执行后置 Hooks（afterLlm）                                  │
│    ↓                                                               │
│ 5. 条件边路由：响应是否包含 tool calls？                            │
│    ├── 否 → 跳到 END，返回最终答案                                 │
│    └── 是 → 执行工具节点（AgentToolNode）                          │
│         ↓                                                          │
│ 6. 工具节点：执行所有工具调用                                       │
│    ├── 执行前置 Hooks（beforeTool）                                │
│    ├── 调用工具方法 → 获取结果                                     │
│    └── 执行后置 Hooks（afterTool）                                 │
│    ↓                                                              │
│ 7. 将工具结果追加到状态 → 回到 LLM 节点（下一超步）                 │
│    ↓                                                              │
│ 8. 检查点保存（如配置了 saver）                                    │
│    ↓                                                              │
│ 9. 循环直到 LLM 不再返回 tool calls                               │
└─────────────────────────────────────────────────────────────────────┘

图：Spring AI Alibaba 的完整执行流程。从 Agent.call 到最终响应，经历 LLM 推理、工具执行、条件路由、检查点保存的完整链路。

关键设计：整个执行过程遵循 “构建 → 编译 → 执行”的三阶段模式。Agent Framework 在构建阶段定义图结构，编译阶段验证并生成可执行图，执行阶段由 Graph Core 按拓扑序调度。

5.2 检查点与持久化——让 Agent 扛得住崩溃

SAA 的 Graph Core 支持多种持久化后端：

存储后端	适用场景
PostgreSQL	生产环境（推荐）
MySQL	生产环境
Oracle	企业级环境
MongoDB	文档数据库环境
Redis	高性能缓存场景
File	开发测试

// 配置 PostgreSQL 检查点
PostgresSaver saver = PostgresSaver.builder()
    .dataSource(dataSource)
    .build();

CompiledGraph graph = stateGraph.compile(
    CompileConfig.builder()
        .saver(saver)
        .build()
);

检查点保存的内容包括：

当前图状态（所有通道的值）
历史消息
下一步要执行的节点
待写入的更新

检查点的核心能力：

故障恢复：任意副本都能从最近的检查点恢复
中断与恢复：支持在任意节点前后暂停执行
时间旅行：回溯到任意检查点重新执行

5.3 运行时关键决策的权衡分析

决策	方案	收益	代价
Agent 运行时	Graph（有向状态图）vs 线性循环	支持分支、并行、状态管理、检查点	图调度有额外开销
状态持久化	多后端检查点（PG/MySQL/Redis 等）	故障恢复、时间旅行调试	每超步都有 I/O 开销
多 Agent 编排	内置模式（Sequential/Parallel/Routing/Loop）	开箱即用，降低开发成本	预置模式可能无法覆盖所有边缘场景
Agent 抽象	ReactAgent（高层）vs Graph API（底层）	快速开发，降低学习成本	灵活性受限

六、工程化实践

理论说完了，接下来咱们聊聊实战——用 Spring AI Alibaba 搭建生产级 Agent 应用时，你最关心的三个问题：怎么快速接入？怎么扩展？有哪些坑？

6.1 快速接入

Maven 依赖：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-agent-framework</artifactId>
    <version>1.1.2.0</version>
</dependency>
<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.2.1</version>
</dependency>

基础使用——ReactAgent：

import com.alibaba.cloud.ai.dashscope.api.DashScopeApi;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;

DashScopeApi dashScopeApi = DashScopeApi.builder()
    .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
    .build();

ChatModel chatModel = DashScopeChatModel.builder()
    .dashScopeApi(dashScopeApi)
    .build();

ReactAgent agent = ReactAgent.builder()
    .name("weather_agent")
    .model(chatModel)
    .instruction("You are a helpful weather forecast assistant.")
    .build();

String result = agent.call("what is the weather in Hangzhou?");

6.2 Graph API——底层工作流编排

对于需要精确控制执行路径的场景，可以直接使用 Graph API：

// 构建工作流
StateGraph graph = new StateGraph("customer_service", stateFactory)
    .addNode("classifier", node_async(feedbackClassifier))
    .addNode("handler", node_async(handlerNode))
    .addEdge(START, "classifier")
    .addConditionalEdges("classifier", edge_async(dispatcher), 
        Map.of("positive", "handler", "negative", END))
    .build();

// 编译并执行
CompiledGraph compiled = graph.compile(CompileConfig.builder().build());
Object result = compiled.invoke(input);

6.3 Studio 与 Admin——可视化开发与运维

Studio 调试：

嵌入式 UI 面板，在开发过程中可视化调试 Agent 执行
提供 Chat UI 界面，用于调试 Agent

Admin 平台：

可视化 Agent 开发
可观测性（指标收集、链路追踪）
评估（数据集构建、线上链路数据复用）
MCP 管理
一键部署

6.4 常见工程陷阱与解决方案

陷阱 1：检查点未配置导致状态丢失

现象：Agent 执行过程中服务重启，所有进度丢失。

原因：没有在 compile() 或 ReactAgent.builder() 中配置 saver。

解决方案：

// ❌ 错误：没有检查点
ReactAgent agent = ReactAgent.builder()
    .model(model)
    .build();

// ✅ 正确：配置检查点
ReactAgent agent = ReactAgent.builder()
    .model(model)
    .saver(new PostgresSaver(dataSource))
    .build();

陷阱 2：工具调用无限循环

现象：Agent 在 LLM 节点和工具节点之间无限循环。

原因：没有配置模型与工具调用限制。

解决方案：在 Agent 配置中设置最大迭代次数或通过上下文工程策略限制工具调用次数。

陷阱 3：分布式部署时 A2A 通信失败

现象：多 Agent 协作时，Agent 无法发现彼此。

原因：A2A 依赖 Nacos 作为注册中心，但 Nacos 未正确配置。

解决方案：

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-a2a-nacos</artifactId>
    <version>${version}</version>
</dependency>

确保 Nacos 服务发现和配置管理正确启用。

七、总结与展望

7.1 关键版本里程碑

版本/事件	时间	核心变化
项目启动	2024 年初	基于 Spring AI 开始构建
正式开源	2024 年 9 月	Spring AI Alibaba 开源
1.0 GA	2025 年	生产就绪的企业级框架
1.1.2.0	2026 年 2 月	Agent Skills 支持、多智能体并行执行增强
1.1.2.1	2026 年	DashScope Starter 迭代
1.1.2.2	2026 年	当前最新稳定版本

7.2 横向对比：Spring AI Alibaba vs Spring AI vs LangChain4j vs AgentScope Java

7.2.1 可比性说明

Spring AI Alibaba、Spring AI、LangChain4j、AgentScope Java 均定位于 Java 生态的 AI Agent 应用开发框架，面向 Java/Spring 技术栈开发者。它们在功能定位上有重叠——都提供模型统一抽象、工具调用和多智能体支持——但各自的核心设计哲学和擅长领域不同。

7.2.2 横向对比表

对比维度	Spring AI Alibaba	Spring AI	LangChain4j	AgentScope Java 2.0
核心定位	企业级 Agent 工作流平台	Spring 官方 AI 抽象	声明式 Java AI 框架	生产级智能体运行时
设计哲学	Graph 为运行时基座	抽象与解耦（JDBC 风格）	声明式服务（接口+代理）	事件流 + 三权分立控制面
核心抽象	StateGraph + ReactAgent	Model + ChatClient + Advisor	AiServices（声明式接口）	Agent + Middleware + Event
工作流引擎	自研 Graph Core	无内置	有限	无（事件驱动）
多智能体模式	Sequential/Parallel/Routing/Loop	有限	有限	有限
分布式 A2A	✅ Nacos 原生集成	❌	❌	有限
Admin/Studio	✅ 可视化平台	❌	❌	Studio 调试面板
JDK 要求	Java 17+	Java 17+	Java 17+	Java 17+
Spring 集成	官方原生 + 阿里云生态	官方原生	官方 Starter	社区集成

7.2.3 差异来源分析

框架	核心判断	架构推论
Spring AI Alibaba	企业 Agent 是工作流问题，不是模型调用问题	用 Graph 作为运行时基座，Agent 运行在 Graph 之上
Spring AI	开发者最熟悉 Spring 的抽象方式	用 Model/ChatClient 提供统一抽象，与 Spring 生态深度绑定
LangChain4j	Java 开发者最习惯“声明接口，框架实现”	AiServices + 动态代理，声明式编程
AgentScope Java	Agent 最难的是控制——自主没有控制是负债	三权分立控制面 + 事件流

7.2.4 结论性建议

场景	推荐选择	核心理由
需要复杂工作流编排、多 Agent 协作、可视化运维	Spring AI Alibaba	Graph 引擎 + Admin 平台 + A2A 分布式协调
已有 Spring Boot 项目，需要基础 AI 能力	Spring AI	官方出品，与 Spring Boot 4.x 同步演进
需要声明式 AI 服务、组件最全	LangChain4j	AiServices + 20+ 模型提供商
需要严格权限控制、沙箱隔离、事件溯源	AgentScope Java	三权分立控制面 + Workspace 沙箱

7.3 设计哲学提炼

Spring AI Alibaba 的设计哲学可以提炼为三个关键词：

Graph 即运行时：Agent 不是对话，是工作流——有状态、有分支、可并行、可暂停、可恢复
Agent 即抽象：在 Graph 之上封装 ReAct 模式，让开发者用更少的代码构建更复杂的 Agent
企业级即默认：可观测、可治理、可持久化、人在回路、A2A 分布式——从第一天就内置

7.4 核心架构亮点

亮点	说明
Graph Core 引擎	有向图编排运行时，支持条件路由、嵌套图、并行执行、状态管理
ReactAgent 高层抽象	ReAct 范式封装，Builder 模式构建，底层运行在 Graph 之上
上下文工程	人在回路、上下文压缩、工具重试、动态工具选择等内置策略
4 种多智能体模式	Sequential/Parallel/Routing/Loop，开箱即用
A2A + Nacos	分布式 Agent 协调，服务注册与发现
MCP 双端支持	Client + Server + Registry + Gateway，完整 MCP 生态
Admin + Studio	可视化开发、调试、运维一站式平台

7.5 对开发者的启示与适用场景

Spring AI Alibaba 的本质不是在 Spring AI 上“加几个阿里云适配器”，而是将整个框架的演进方向从“模型调用抽象”推向了“工作流编排平台”——以 Graph 为运行时基座、以 ReactAgent 为高层抽象、以 A2A + Nacos 为分布式协作骨架，让 Java 开发者用 Spring 的方式构建生产级 Agentic 应用。

适用场景：

需要多步骤、多分支、需要持久化的复杂 Agent 工作流
需要多 Agent 协作和分布式协调的企业级系统
需要人在回路审批的高风险操作
需要可视化开发、可观测、可治理的生产级部署
需要与 Spring Boot 生态深度集成的 Java 项目
已有阿里云技术栈（DashScope、Nacos 等）的企业

不适用场景：

简单的单次 LLM 调用（直接用 ChatClient 即可）
对延迟极度敏感、不能接受图调度开销的场景
非 Spring 生态的 Java 项目（LangChain4j 或 AgentScope Java 更合适）
JDK 8 及以下的老旧系统

本文数据来源：Spring AI Alibaba 官方文档、GitHub 仓库源码、InfoQ 技术文章、CSDN 源码分析系列、Spring AI Alibaba Admin 深度解读（截至 2026 年 8 月）

如您所在的企业正面临数字化难题，或有 AI 落地、系统集成相关需求，欢迎进一步沟通。我们可提供针对贵企业具体场景的定制化方案和现场调研服务。

龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

我用 NVIDIA SkillSpector 纯静态扫了一遍 GitHub 最火的 agent skills：能挖出多少注入？0 个

龙虾开发者社区

周榜换血九成，Agent Skills 星数翻倍

龙虾开发者社区

写给 TypeScript 工程师的 OpenClaw.NET 上手指南：用你熟悉的 TS 思维，跑起一个生产级 AI Agent

读代码层：TS 和 C# 本来就是「远房亲戚」——asyncawait??、接口、泛型、严格空检查，你的心智模型几乎无缝平移。真正要适应的只有两件事：类型是具名而非结构化的（多一句显式声明），以及 NativeAOT 下的「禁反射」约束。写扩展层：你甚至可以不怎么碰 C#——Node.js 插件桥意味着你的 TypeScript 插件就是一等公民，而且能在生产 aot 车道跑。内核给你 .NET

龙虾开发者社区

所有评论(0)

查看更多评论

zhengliebin

@zhengliebin

已为社区贡献3条内容

Spring AI Alibaba 技术架构与源码分析

zhengliebin

Spring AI Alibaba 技术架构与源码分析

一、引言

二、整体架构与设计哲学

2.1 架构总览：三层引擎 + 一个管理平台

2.2 设计哲学：Graph 是运行时基座，ReactAgent 是高层抽象

2.3 包结构与代码规模

2.4 技术栈速览

三、核心抽象与编程模型

3.1 ReactAgent——ReAct 范式的 Java 实现

3.2 StateGraph——图的三要素：State、Node、Edge

3.3 内置多智能体模式——开箱即用的团队协作

3.4 上下文工程——让 Agent 更可靠

3.5 A2A + Nacos——分布式 Agent 协调

3.6 MCP 支持——Model Context Protocol 的 Java 实现

四、核心模块源码解析

4.1 Graph Core——graph-core 模块

4.2 Agent Framework——agent-framework 模块

4.3 钩子与拦截器——生命周期增强

4.4 Studio 与 Admin——从开发到运维的完整闭环

五、核心执行流程与运行时机制

5.1 执行流程——从 Agent.call 到 Graph 执行

5.2 检查点与持久化——让 Agent 扛得住崩溃

5.3 运行时关键决策的权衡分析

六、工程化实践

6.1 快速接入

6.2 Graph API——底层工作流编排

6.3 Studio 与 Admin——可视化开发与运维

6.4 常见工程陷阱与解决方案

陷阱 1：检查点未配置导致状态丢失

陷阱 2：工具调用无限循环

陷阱 3：分布式部署时 A2A 通信失败

七、总结与展望

7.1 关键版本里程碑

7.2 横向对比：Spring AI Alibaba vs Spring AI vs LangChain4j vs AgentScope Java

7.2.1 可比性说明

7.2.2 横向对比表

7.2.3 差异来源分析

7.2.4 结论性建议

7.3 设计哲学提炼

7.4 核心架构亮点

7.5 对开发者的启示与适用场景

所有评论(0)

温馨提示：您尚未绑定手机号

zhengliebin