版本基准：Spring AI Alibaba 1.1.2.x+Spring AI 1.1.2+JDK 17+
官方文档：https://java2ai.com
主仓库：https://github.com/alibaba/spring-ai-alibaba
示例仓库：https://github.com/spring-ai-alibaba/examples
一、JDK 17+ 与 Maven 3.8+
JDK 17+ 与 Maven 3.8+ 的组合，是目前 Java 生态中最稳妥、最主流的生产环境基准线。AI 推荐这个版本，核心原因在于JDK 17 是 LTS（长期支持版），而 Maven 3.8+ 是能稳定支撑 JDK 17 及现代框架（如 Spring Boot 3.x）的最低安全版本。
JDK 17+ 的核心新特性
JDK 17 于 2021 年 9 月正式发布，是继 JDK 8、11 之后的又一个 LTS 版本。它的新特性主要集中在语言表达力和代码安全性上：
- 密封类 (Sealed Classes)：允许你精确控制“哪些类或接口可以继承/实现我”。这对于设计稳定的领域模型非常有用，能避免意外的扩展破坏代码逻辑。
- 模式匹配增强：虽然
switch的模式匹配在 17 中还是预览特性，但它代表了 Java 语言未来的方向，能大幅简化复杂的if-else类型判断代码。 - 强封装 JDK 内部 API：默认禁止通过反射访问
java.*的内部实现，这迫使开发者放弃对内部 API 的依赖，保证了应用在未来升级 JDK 时的稳定性。
Maven 3.8+ 的核心新特性
Maven 3.8 系列（以及 3.8.6、3.8.8 等后续补丁版）主要解决了安全和依赖管理的确定性问题，这是现代 CI/CD 流水线的基石：
- 依赖项验证 (Dependency Verification)：允许你配置校验和，验证从仓库下载的依赖是否被篡改。这在防范供应链攻击时非常关键。
- 移除对不安全 HTTP 仓库的默认支持：强制推动开发者使用 HTTPS，避免依赖在传输过程中被劫持或篡改。
- 凭证加密：支持对存储在
settings.xml中的仓库密码进行加密，避免明文密码泄露。
为什么 AI 会推荐 “JDK 17 + Maven 3.8+”
AI 推荐这个组合，通常是基于生态兼容性和项目稳定性的权衡：
- Spring Boot 3.x 的强制门槛：如果你使用的是 Spring Boot 3.0 或更高版本，官方要求最低 JDK 17，且不再支持 JDK 8 或 11。如果你用旧版 JDK 打开项目，会直接抛出
UnsupportedClassVersionError异常。 - Maven 3.8.6+ 是许多现代项目的硬性要求：很多基于 Spring Boot 3.x 的教程和脚手架工具（如 Spring Initializr）默认推荐 Maven 3.8.6 或 3.8.8 以上。低于这个版本（如 3.6.x），可能会在解析现代依赖或处理 JDK 17 项目时遇到兼容性问题。
- 生产环境的“最大公约数”：JDK 17 已经是当前生产环境的事实标准，几乎所有主流框架（Spring、Quarkus、Micronaut）和工具链都对它提供了最佳的稳定支持。Maven 3.8+ 的改动相对 3.6 是平滑的，它既带来了必要的安全加固，又没有引入像 Maven 4 那样激进的破坏性变更，是风险最低的选择。
如果你正在启动一个全新的 Spring Boot 项目，直接选择JDK 17（Temurin 发行版）+Maven 3.8.8+的组合，通常能避免绝大多数版本兼容性的“坑”。
二、 Spring AI Alibaba核心架构
根据 Spring AI Alibaba 官网的架构说明，这几个框架呈现出清晰的分层关系。从底层到上层，从开发到管理，可以这样理解它们各自的角色：
底层基座：Spring AI
Spring AI 是整个体系的地基，由 Spring 官方团队维护，并非阿里专属。它的核心目标是连接企业数据与 AI 模型，提供最基础的原子抽象。你可以把它理解为“零件库”，提供了模型接入（Model）、工具调用（Tool）、对话记忆（Memory）、向量存储（Vector Store）等基础组件。它不负责复杂的业务编排，只解决“如何让 Java 应用调用大模型”的问题。
核心引擎：Spring AI Alibaba Graph
Graph 是 Spring AI Alibaba 区别于上游 Spring AI 的核心价值，可以理解为Java 版的 LangGraph。它的角色是工作流与多智能体编排的底层运行时基座。它通过 State（状态）、Node（节点）、Edge（边）这三个概念，让开发者能够用声明式的方式定义复杂的流程。它内置了 SequentialAgent、ParallelAgent、RoutingAgent 等预置模式，支持 Human-in-the-loop（人工介入）、流式响应和状态持久化。当你的业务需要“先执行 A，再根据结果判断走 B 还是 C”这类流程时，Graph 就是用来干这个的。
上层封装：Spring AI Alibaba Agent Framework
Agent Framework 是构建在 Graph之上的 Agent 开发框架，它的设计目标是让开发者用更少的代码快速构建智能体。它的核心是ReactAgent，遵循“推理+行动”范式：Agent 会先思考（Reasoning）需要做什么，决定调用哪个工具（Acting），观察结果（Observation），然后迭代直到任务完成。Agent Framework 帮你封装了自动上下文工程、人机交互等高级能力，你不需要从零去拼装这些逻辑。简单说，Graph 是给你搭乐高积木的底板，Agent Framework 是给你提供预装好的乐高套装。
可视化调试：Spring AI Alibaba Studio
Studio 是一个可视化的聊天窗口，用于与你开发的 Agent 进行交互。它的核心作用是调试：当你用 Agent Framework 或 Graph 开发了一个智能体后，可以通过 Studio 的界面直观地看到 Agent 的推理过程和工具执行细节。它不参与应用的运行时，而是开发阶段的辅助工具。
生命周期管理：Spring AI Alibaba Admin
Admin 是一个企业级 Agent 开发与评估平台，定位比 Studio 更重。它覆盖了从Prompt 工程、数据集管理、评估器配置，到实验执行和结果分析的完整工作流。简单说，Studio 用来“聊天调试”，Admin 用来“系统化地管理和优化”你的智能体——比如维护 Prompt 版本、构建评估数据集、跑实验对比不同配置的效果、通过集成的可观测性追踪调用链路
如果把开发一个智能体应用比作造车：Spring AI是螺丝、齿轮、发动机；Graph是底盘和传动系统，负责让各个部件按流程协同工作；Agent Framework是整车组装线，让你快速拼出一辆能跑的车；Studio是试车跑道，用来试驾和观察；Admin是 4S 店的管理系统，负责保养记录、性能评估和版本管理。
三、Chatbot / 单 Agent / 多 Agent / Workflow 四种应用形态
这四种形态可以理解为从“最简单”到“最复杂”的四个台阶，核心区别在于控制权在谁手里：是代码预先定好，还是让大模型自己决定
| 形态 | 控制权归属 | 核心特点 | 典型场景 |
|---|---|---|---|
| Chatbot | 代码 + 简单 LLM | 单轮/多轮对话，无复杂工具调用 | 客服问答、知识库查询 |
| 单 Agent | LLM 主导（ReAct循环） | 自主推理+调用工具，解决单一领域问题 | 数据分析助手、代码生成 |
| Workflow | 代码侧 100% 控制 | 预定义步骤（顺序/并行/路由），确定性高 | 审批流、RAG管道、结构化提取 |
| 多 Agent | LLM 主导 + 编排框架 | 多个专家 Agent 协作或路由，处理复杂多领域任务 | Deep Research、跨领域客服 |
Workflow vs Agent：这是最重要的分界线。Workflow 是“把 LLM 当可靠函数用”，路径由你写死（A→B→C），适合结果必须可控、可验证的场景。Agent 则是“给 LLM 一个目标让它自己找路”，容忍过程不确定，换取解决未知问题的灵活性。
单 Agent vs 多 Agent：当单 Agent 的上下文窗口快撑爆、或者任务需要不同领域的专精能力时，才考虑拆分。奥卡姆剃刀原则：如无必要，勿增实体。多 Agent 的核心价值是上下文隔离和并行执行，但代价是复杂度和 token 消耗都上升。
在 Spring AI Alibaba 里怎么对应
- Chatbot / 单 Agent：直接用 Spring AI 的
ChatClient，搭配Advisor实现记忆。 - Workflow：用Spring AI Alibaba Graph的
StateGraph编排，支持顺序、并行、路由、循环四类 Flow Agent。 - 多 Agent：用Agent Framework的预置模式——
SequentialAgent（顺序）、ParallelAgent（并行）、LlmRoutingAgent（路由）、SupervisorAgent（监督者）。
官方对 Spring AI Alibaba 的定位更侧重Workflow 和 Graph 编排，如果你追求的是“把自主权完全交给模型”的 Agentic 范式，官方推荐考虑 AgentScope。
四、何时用 ChatClient，何时用 ReactAgent，何时下沉 Graph API
这三者的选择，本质上是在代码控制力和模型自主性之间做权衡。可以理解为一条从“轻”到“重”的谱系：ChatClient 是基础对话能力，ReactAgent 是开箱即用的智能体，Graph API 是终极的流程控制权。
何时用 ChatClient
当你需要的只是一次可靠的对话或工具调用，不需要 Agent 自主循环时，用ChatClient就够了。
它的核心优势是简单直接。你发起调用，它返回结果，流程控制权完全在你手里。Spring AI 的ChatClient本身也支持工具调用，如果你只是想让模型在回答前查一下天气或数据库，直接配置工具即可，不必引入 Agent 的复杂度。
判断信号：你的需求是“提问-回答”式的，即使涉及工具，也是“查一次、答一次”的线性流程，不需要模型自己决定“下一步该干什么”。
何时用 ReactAgent
当你需要把一个目标交给模型，让它自己规划并执行多步骤任务时，用ReactAgent。
它实现的是 ReAct（推理+行动）循环：模型思考需要什么，调用工具，观察结果，再思考，直到任务完成。你只需要提供工具集和任务描述，剩下的循环逻辑由框架处理。与ChatClient的关键区别在于过程可见性和可干预性：ReactAgent的stream()会暴露每一步的模型推理和工具调用事件，而ChatClient只给你最终回复。
判断信号：任务需要多个工具的组合调用（比如先查天气、再根据天气查航班、最后生成建议），且步骤间的依赖关系由模型根据中间结果动态决定，而不是你预先写死的。
何时下沉 Graph API
当你有明确的、必须严格遵循的流程，或者需要对执行状态进行精细控制（中断、恢复、回滚）时，直接使用Graph API。
Graph 的核心价值是确定性和控制力。你可以用 StateGraph 显式定义节点和边：什么条件下走哪个分支、哪些节点并行、哪里需要人工审批。官方文档明确指出，Graph API 适用于需要超高可靠性、大量自定义逻辑、需要精确控制延迟的场景。
判断信号：你的业务流程本身就有明确的结构（比如“分类 → 路由 → 处理 → 记录”），你希望代码完全掌控流转，而不是让模型“自由发挥”去决定下一步。或者，你需要人工介入（Human-in-the-loop）、断点续传这类运行时控制能力，这些只有 Graph 层才能提供。
可以按这个顺序判断：如果 ChatClient 够用，就不引入 Agent；如果单个 ReactAgent 能完成任务，就不下沉到 Graph；如果流程必须由你精确编排，或者需要运行时控制，再直接用 Graph。
反过来，一旦你发现自己在 ReactAgent 外面包了一层又一层的判断逻辑来“引导”它走正确的流程，那大概率说明这个场景更适合用 Graph 来显式定义。
五、Spring AI Alibaba 与 AgentScope 的定位差异
官方文档中有一个很清晰的概括：Spring AI Alibaba 以 Graph 为核心，强调工作流编排；AgentScope 以 Agentic 为核心，最大化利用基础大模型的能力。
核心设计哲学：Workflow vs Agentic
这是两者最根本的分界线，决定了框架的“性格”。
Spring AI Alibaba的设计哲学是：把 LLM 当作一个不可靠的“函数”，用可靠的代码结构把它“框”住。控制权 100% 在代码侧，开发者决定何时调用模型、Prompt 是什么、输出怎么解析、失败怎么重试。路径是预先定义的，结果可预测、可测试。
AgentScope的设计哲学则相反：把 LLM 当作“大脑”，给它工具和目标，让它自己找路。控制权在 LLM 侧，系统只给一个目标，模型自主决定下一步做什么。它容忍过程的不确定性，以换取解决复杂、未知问题的能力。
由此衍生的定位差异
| 维度 | Spring AI Alibaba | AgentScope |
|---|---|---|
| 核心抽象 | Graph（状态图）、Workflow 编排 | Agent（尤其是 ReActAgent）、多智能体协作 |
| 擅长场景 | 流程明确的业务：审批流、RAG 管道、结构化提取、高风险业务 | 开放式任务：市场调研、代码生成与修复、需要动态规划的场景 |
| 语言与生态 | Java 原生，深度绑定 Spring 生态 | Python 原生（后推出 Java 版），多语言覆盖 |
| 企业级侧重 | 工作流可靠性、状态持久化、人工介入 | 分布式部署、多租户、安全沙箱、实时介入控制 |
官方问答给出了很直接的建议：想构建以 Agent 为核心的智能应用，选择 AgentScope；想基于现有工作流集成 AI 能力，选择 Spring AI Alibaba。
更具体地说，如果你的业务逻辑是“先分类，再路由到不同处理流程，最后记录结果”这种有明确结构的场景，Spring AI Alibaba 的 Graph 编排更合适。如果你的任务是“帮我研究一下这个领域并写份报告”这种目标开放、路径未知的场景，AgentScope 的自主 Agent 范式更对路。
两者并非完全对立，Spring AI Alibaba 也提供了 Agent Framework 层（ReactAgent），AgentScope 也在增强工程化能力。官方透露未来 Spring AI Alibaba 会在底层集成 AgentScope 的编排能力，走融合路线。
六、完整调用链图
1. ReactAgent 的核心循环（绿色区域）
ReactAgent 运行在Graph Runtime之上，本质是一个由 Model Node 和 Tool Node 构成的图循环。一次完整的call()会经历：记忆检索 → 构建 Prompt → LLM 推理 → 判断返回类型。如果是 Tool Call，执行工具后把结果写回记忆，然后再次进入模型调用，直到模型返回纯文本才跳出循环。
2. 多智能体的两种协作范式（紫色区域）
Spring AI Alibaba 的 Multi-Agent 有两条路径：
- Agent as Tool：主 Agent（控制器）把子 Agent 当作一个“工具”来调用。子 Agent 不直接与用户对话，执行完任务后把结果返回给主 Agent，由主 Agent 决定下一步。适合集中式编排场景。
- Handoff：当前活跃的 Agent 主动把控制权交接给另一个 Agent，新 Agent 直接与用户交互。适合跨领域对话、专家接管场景。
3. 多智能体编排模式（橙色区域）
Agent Framework 预置了四类编排模式：
- SequentialAgent：按顺序执行，上一个输出传给下一个
- ParallelAgent：多个 Agent 并行处理同一输入，结果合并
- LlmRoutingAgent：LLM 单次路由到最合适的子 Agent
- SupervisorAgent：LLM 作为监督者，支持多步骤循环路由——子 Agent 完成后返回监督者，监督者决定继续路由还是 FINISH
4. 记忆与状态（黄色区域）
短期记忆由MemorySaver/RedisSaver管理，以thread_id区分会话。长期记忆通过ModelHook在模型调用前后自动加载和保存。状态快照（Checkpoint）是 Graph Runtime 提供的底层能力，支持断点续传和 Human-in-the-loop。
5. 工具与 MCP（粉色区域）
工具来源有两种：本地@Tool注解的方法，以及通过MCP 协议从外部服务发现的标准工具。ReactAgent 可以在一次对话中同时调度两者。