Spring AI Alibaba on 吾爱主机

Java AI Agent 四框架对比：Spring AI Alibaba、AgentScope Java、LangChain4j 与 Google ADK Java

Thu, 23 Jul 2026 00:00:00 +0800

Java AI Agent 生态已经不再只有“给大模型套一个 HTTP 客户端”。Spring AI Alibaba、AgentScope Java、LangChain4j、Google ADK Java 都能连接模型和工具，但它们解决的问题并不相同：有的强调 Spring 工作流，有的把权限、沙箱和分布式恢复放在核心位置，有的是通用 JVM AI 工具箱，有的则围绕代码优先的多 Agent 编排设计。

本文不按 GitHub Star 简单排名，而是从 编程模型、执行控制、状态恢复、安全、协议、可观测性和生态锁定 等方面比较四个框架，并给出面向真实项目的选型路径。

版本快照：Spring AI Alibaba 稳定线 1.1.2.2，AgentScope Java 2.0.0 GA，LangChain4j 1.18.0，Google ADK Java 1.7.0。版本状态截至 2026-07-23。Google ADK Java 官方仍标记 Preview / Pre-GA；LangChain4j 核心库与其高层 Agentic 模块的成熟度也不能混为一谈。

一、先给结论

如果你的核心问题是	优先考虑
Spring Boot 项目要做 Graph、Supervisor、国内模型和多 Agent	Spring AI Alibaba
Agent 要安全执行 Shell/文件工具，并支持审批、沙箱和跨实例恢复	AgentScope Java
先统一模型、RAG、Tool Calling、MCP，再逐步加入 Agent	LangChain4j
需要代码优先的 Sequential/Parallel/Loop 多 Agent，并深度使用 Gemini/Google Cloud	Google ADK Java
只是一个模型调用 2～3 个只读工具	先用 LangChain4j AI Services 或 Spring AI，未必需要多 Agent

没有“全维度最强”的框架。正确问题不是“哪个框架功能最多”，而是：你的不确定性主要来自模型决策、工作流状态、工具副作用，还是部署运行时？

二、四种不同的设计中心

1. Spring AI Alibaba：Spring + Agent Workflow

Spring AI Alibaba 在 Spring AI 的模型、工具、消息等抽象上，增加 ReactAgent、Graph Runtime、SequentialAgent、ParallelAgent、RoutingAgent、Supervisor 等高层能力。

它的设计中心是 用 Java 和 Spring 管理可组合的 Agent 工作流。适合将 Agent 作为现有 Spring 企业应用的一部分，而不是另起一套运行平台。

典型结构：

Spring Boot
 -> Supervisor / Routing / Graph
 -> ReactAgent A -> Spring Bean Tools
 -> ReactAgent B -> MCP / Service
 -> Saver / Observability / Nacos

2. AgentScope Java：生产运行时与 Harness

AgentScope Java 2.0 不只关心模型如何选择工具，还把生产运行问题提升为一等能力：强类型事件、工具权限、人工审批、Workspace、Sandbox、Middleware、分布式 session 和 memory、跨副本恢复。

它的设计中心是 让长时间运行、会执行真实操作的 Agent 安全稳定地活下去。

HarnessAgent
 -> Workspace / Skills / Memory
 -> Permission Decision
 -> Local / Docker / Kubernetes Sandbox
 -> Distributed Backend + Session Recovery

3. LangChain4j：Java 原生 AI 应用工具箱

LangChain4j 首先是通用 Java LLM 应用库。AI Services 允许开发者用 Java 接口定义模型服务，周围组合 Memory、RAG、@Tool 和 MCP；它同时兼容 Spring Boot、Quarkus、Helidon、Micronaut。

它的设计中心是 用符合 Java 习惯的接口、POJO 和注解连接不同模型与 AI 能力。这使它适合作为长期底座，但不要因为核心库成熟，就默认高层 langchain4j-agentic 模块也达到相同稳定程度；官方仍将该模块标为实验性能力。

4. Google ADK Java：Code-first Agent Development Kit

Google ADK Java 从一开始就围绕 Agent 构建，提供 LlmAgent、Sequential/Parallel/Loop 工作流、Session/State、工具和开发 UI，并支持 A2A。

它的设计中心是 用代码显式定义 Agent、工具和编排，并贯通开发、调试与 Google Cloud 部署。优势是 Agent-first 和 Google 生态，代价是项目仍处于 Preview / Pre-GA 阶段。

三、核心能力横向比较

维度	Spring AI Alibaba	AgentScope Java 2.0	LangChain4j	Google ADK Java
主要定位	Agent 工作流与多智能体	生产级 Agent Harness	JVM AI 应用工具箱	Code-first Agent SDK
主要语言	Java	Java	Java	Java
基础要求	JDK 17、Spring Boot	JDK 17+	依模块而定	Java + Maven/Gradle
单 Agent	`ReactAgent`	`ReActAgent` / `HarnessAgent`	AI Services + Tools；Agentic 模块	`LlmAgent`
工作流	Graph、顺序、并行、路由、循环	Harness、Subagent、事件驱动	高层 Agentic 模块仍需谨慎	Sequential、Parallel、Loop
状态恢复	Saver / Graph checkpoint	分布式 session、memory、跨副本恢复	Chat Memory 为主，复杂恢复自行设计	Session / State / Artifact
HITL	Graph 中断等方式组织	原生权限：允许/审批/拒绝	通常由应用层实现	可通过流程/工具层实现
Sandbox	有独立 Sandbox 生态	本地、Docker、K8s、云 Sandbox	非核心能力	非核心能力
MCP	支持	支持	支持	工具生态可扩展，MCP 与 A2A 应分工看待
A2A	支持，并可结合 Nacos	支持	需看具体集成	官方重点能力
国内模型	很强	DashScope、DeepSeek 等扩展	提供多厂商集成	Gemini 最自然，其他模型需验证
Spring 集成	原生核心	可集成，但不是唯一运行方式	成熟	不是核心设计中心
当前主要风险	版本线迭代快	2.0 GA 较新，工程复杂度高	Agentic 高层 API 实验性	Preview / Pre-GA、平台偏向

这张表不能代替 PoC。尤其是“支持”两个字，可能只代表存在适配器，并不代表拥有相同的错误语义、流式事件、结构化输出和生产经验。

四、编程模型：接口、图、Harness 与 Agent 树

Spring AI Alibaba：把 Agent 当成图中的节点

开发者可以先构建专业 ReactAgent，再将它们包装成 Supervisor 的工具，或放进 Graph 里增加条件边、重试和 checkpoint。它适合“业务流程大体确定，但部分节点需要 LLM 决策”的系统。

优势：

确定性工作流与 Agent 节点可以混合；
Spring Bean、配置、监控和业务服务复用自然；
对复杂流程的控制力强于单纯 ReAct 循环。

代价：Graph、Agent Framework、Spring AI 与 Alibaba 版本线需要一起管理，升级时应做依赖树和回归测试。

AgentScope Java：把 Agent 当成长期运行的受控进程

HarnessAgent 组合 Workspace、Memory、Skills、Subagent、权限和沙箱。这里的关键不只是“下一步调哪个函数”，还包括：调用是否需要用户批准、工具在哪个隔离环境运行、崩溃后从哪里恢复、事件如何实时推给前端。

优势：生产问题覆盖最完整。

代价：如果业务只需简单问答和只读工具，Harness 的概念和部署组件可能过重。

LangChain4j：把 AI 能力当成 Java Service

典型写法是定义接口：

interface Assistant {
 String chat(@MemoryId String userId, @UserMessage String message);
}

再通过 AiServices.builder(...) 绑定模型、Memory Provider 和工具对象。这种方式对传统 Java 团队非常自然，单元测试和依赖注入也容易组织。

优势：模型、RAG、工具与框架集成广，渐进式采用成本低。

代价：复杂多 Agent 的暂停、恢复、HITL 和图执行不应仅靠 Chat Memory 拼装；高层 Agentic 模块仍需要固定版本和充分验证。

Google ADK Java：把 Agent 组合成代码结构

开发者定义多个 LlmAgent，再通过 Sequential、Parallel 或 Loop Agent 显式组合。Session 保存对话和状态，Dev UI 用于本地调试。

优势：多 Agent 编排概念清晰，A2A 与 Google Cloud 路线完整。

代价：官方 README 仍声明 Preview / Pre-GA，且部分评测能力仍在演进。关键生产系统应先做版本冻结、回归集和退出预案。

五、状态与恢复：最容易比较错的维度

“支持 Memory”不等于“支持崩溃恢复”。至少要区分：

对话记忆：模型下一轮能看到什么；
工作流 checkpoint：程序执行到哪个节点；
业务事实：邮件是否真的发送、订单是否真的创建；
Artifact：文件、报告、图片等大对象；
分布式路由状态：哪个副本继续哪个 session。

需求	更适合的起点
多轮问答记住用户上下文	LangChain4j Chat Memory
Graph 节点暂停后继续	Spring AI Alibaba Saver / checkpoint
跨副本恢复长任务和子 Agent	AgentScope Java Distributed Backend
Agent Session、State 与 Artifact 一体组织	Google ADK Java

无论框架多强，都不能替业务工具完成 exactly-once。崩溃可能发生在“下游已经写成功，但 Agent 还没保存结果”的窗口。邮件、支付、工单等工具必须使用幂等键和唯一约束。

六、安全：不要把 Prompt 当权限系统

四个框架都可以在 Prompt 中写“删除前请确认”，但这不是安全边界。

AgentScope Java 的差异最明显：权限系统原生表达 允许、要求用户审批、拒绝，并能把工具放入沙箱。若业务是运维、代码执行或文件操作，它通常更贴近需求。

其他框架也能实现安全控制，但需要在应用层构建：

Agent 只能调用 prepare_operation
 -> 服务端创建 WAITING_APPROVAL 记录
 -> 人类在可信 UI 审批
 -> 后端用 approvalId 执行
 -> 工具返回真实 operationId

所有框架都应遵守：

身份和租户信息来自服务端上下文，不让模型填写；
写工具与读工具分离；
工具参数使用结构化类型和白名单；
高风险工具默认拒绝或必须审批；
沙箱之外还要有操作系统、网络和云 IAM 限制；
日志脱敏，Prompt 与工具结果不能泄露凭据。

七、MCP 与 A2A 不是竞争关系

MCP 主要解决 Agent/模型如何发现并调用工具、资源和提示模板；
A2A 主要解决相互独立的 Agent 如何描述能力、通信和协作。

例如，采购 Agent 可以通过 MCP 调 ERP 查询工具，同时通过 A2A 把合同审查任务交给远程法务 Agent。不要因为框架同时写着 MCP 和 A2A，就把二者当成同一层协议。

选型时应验证的不只是协议名称，还包括：认证、超时、流式、取消、错误码、版本协商、审计和跨租户隔离。

八、用同一个 PoC 做公平测试

建议不要分别跑四个官方 Hello World，而是实现同一个“采购审批 Agent”：

读取采购申请
 -> 并行查询预算与供应商风险
 -> 生成建议
 -> 金额超过阈值则等待人工批准
 -> 创建订单
 -> 模拟进程崩溃并恢复

统一测量：

指标	观察方法
实现复杂度	业务代码量、配置量、概念数量
工具正确率	固定 100 条用例，统计选错/漏调/参数错
副作用安全	重试和恢复后是否重复创建订单
恢复能力	在每个节点前后故障注入
可观测性	能否关联模型、工具、session、审批和错误
成本	模型调用次数、token、延迟
可测试性	不调用真实模型时能否测试控制流
生态约束	替换模型、存储、云环境的改动范围

真正的选型结论通常不是“框架 A 功能比 B 多”，而是“框架 A 让我们的关键失败模式更容易被测试和控制”。

九、按团队和场景选型

场景 1：现有 Spring Boot 企业系统

优先评估 Spring AI Alibaba。它能直接复用 Spring Service、配置、Actuator 和依赖注入，也更容易把确定性 Graph 与 Agent 节点结合。

若当前阶段只做模型、RAG 和少量工具，也可以从 LangChain4j 或 Spring AI 底层能力开始，不必一开始引入多 Agent。

场景 2：运维 Agent、代码 Agent、长任务 Agent

优先评估 AgentScope Java。权限决策、Workspace、Sandbox、事件系统和跨副本恢复与该类风险高度匹配。

不过，选它不等于自动安全：Docker/Kubernetes 隔离、网络出口、凭据代理、资源配额和人工审批后端仍需自行配置。

场景 3：希望模型和应用框架保持中立

优先评估 LangChain4j。它的提供商和向量库集成广，也能运行在 Spring Boot、Quarkus、Micronaut 等环境中。

复杂 Agentic 编排要单独做成熟度评估；必要时可把 LangChain4j 作为模型/工具层，配合其他工作流引擎。

场景 4：Gemini、Google Search、Vertex AI 和 A2A

优先评估 Google ADK Java。其代码优先的 Agent 树、Dev UI 和 Google 生态协同清晰。

但 Preview / Pre-GA 是实际风险，不应藏在脚注里。上线前要锁版本、保留回滚路径，并验证非 Google 模型或未来迁移的成本。

场景 5：框架混用

混用可以成立，但只在边界明确时：

Spring AI Alibaba Graph 负责确定性业务流程；
AgentScope Harness 负责需要沙箱的远程专业 Agent；
LangChain4j 提供某些模型或 RAG 能力；
A2A 连接独立 Agent 服务。

不要在同一进程同时引入四套消息、Memory、Tool 和 tracing 抽象。每多一层适配，都要明确谁负责重试、取消、状态和错误翻译。

十、决策清单

在确定框架前，逐项回答：

我们需要的是聊天记忆，还是工作流崩溃恢复？
工具是否有副作用，是否必须人工审批？
是否会执行 Shell、代码或文件操作，需要哪一级沙箱？
工作流是确定性图，还是高度自治的 ReAct？
是否需要多实例、跨副本恢复和后台长任务？
MCP、A2A 分别解决哪个边界？
是否必须使用 Spring、Google Cloud 或国内模型生态？
当前所用模块是 GA、稳定版、experimental，还是 Pre-GA？
能否在不调用真实模型的情况下测试控制流？
工具是否具备幂等、鉴权、审计和超时？

总结

四个项目代表四条不同路线：

Spring AI Alibaba：用 Spring 和 Graph 构建可控的 Agent 工作流；
AgentScope Java：为安全、长任务和分布式恢复提供生产 Harness；
LangChain4j：用 Java 原生接口组织模型、RAG、工具与 MCP；
Google ADK Java：用代码优先方式组合多 Agent，并连接 Google/A2A 生态。

对于多数团队，最稳妥的方法是先选一个有真实副作用、需要审批和恢复的业务任务，用同一组测试用例做 PoC。Agent 框架的价值，不在于让 Demo 调用更多工具，而在于当模型选错、工具超时、进程崩溃或用户拒绝审批时，系统仍然可解释、可恢复、不会重复造成损失。

参考资料

Spring AI Alibaba 实战：用 Supervisor 构建可持久化的 Java 多智能体助手

Thu, 23 Jul 2026 00:00:00 +0800

很多 Java Agent 示例只演示“模型调用一个工具”，但真实业务通常横跨多个边界：日历 Agent 理解时间并检查冲突，邮件 Agent 负责收件人和正文，协调者还要决定调用顺序、传递结果，并在失败后恢复。

本文基于 Spring AI Alibaba 官方稳定依赖线 1.1.2.2，实现一个 Supervisor + 专业子 Agent 的个人助理。重点不是某个模型的聊天接口，而是四个可复用的工程问题：如何划分 Agent 边界、怎样把子 Agent 暴露成工具、如何保存执行状态，以及如何控制有副作用的操作。

本文代码结构依据官方 examples/multiagent-patterns/supervisor 示例整理。Spring AI Alibaba 同时存在面向 Spring AI 2.0 / Spring Boot 4 的 2.0.0-M1.1 里程碑版本；生产项目不要把 milestone 与本文稳定线混用。

一、为什么需要 Supervisor

多 Agent 并不等于“把四个聊天机器人放进一个群”。一个可控系统至少要区分三层：

层次	职责	本文对应实现
决策层	拆解请求、选择能力、安排调用顺序	`personal_assistant` Supervisor
专业层	在受限领域内推理和调用工具	`schedule_event`、`manage_email`
执行层	访问日历、邮件、数据库等真实系统	Java `@Tool` 方法

用户说“下周二开评审会，并给设计组发提醒”时，Supervisor 先调用日历 Agent；拿到时间和创建结果后，再把必要信息交给邮件 Agent。专业 Agent 看不到无关工具，工具层也不承担自然语言规划。

这种设计的价值是 缩小每次模型决策的工具集合。如果把查日历、建会议、发邮件、查工单、改数据库等几十个工具全部交给一个 Agent，模型更容易选错工具，权限也难以分层。

二、环境与依赖

官方稳定示例使用 JDK 17、Spring Boot 3.5.7、Spring AI 1.1.2 和 Spring AI Alibaba 1.1.2.2：

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>3.5.7</version>
</parent>

<properties>
 <java.version>17</java.version>
 <spring-ai.version>1.1.2</spring-ai.version>
 <spring-ai-alibaba.version>1.1.2.2</spring-ai-alibaba.version>
</properties>

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-bom</artifactId>
 <version>${spring-ai.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-bom</artifactId>
 <version>${spring-ai-alibaba.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

<dependencies>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-agent-framework</artifactId>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter</artifactId>
 </dependency>
</dependencies>

配置密钥时不要写进仓库：

spring:
 ai:
 dashscope:
 api-key: ${AI_DASHSCOPE_API_KEY}

运行前设置环境变量：

export AI_DASHSCOPE_API_KEY="你的密钥"

如果换成其他 Spring AI ChatModel，Agent 编排代码本身可以保持不变，但工具调用、结构化输出和并行调用能力仍取决于具体模型。

三、先写最窄的业务工具

工具的参数和描述会进入模型上下文。名称模糊、参数万能化，会直接降低调用准确率。下面用内存实现代替真实日历系统：

@Component
public class CalendarTools {

 @Tool(description = "检查指定 ISO-8601 起止时间内是否有空闲时段")
 public String getAvailableTimeSlots(
 @ToolParam(description = "开始时间，例如 2026-07-28T14:00:00+08:00") String start,
 @ToolParam(description = "结束时间，例如 2026-07-28T15:00:00+08:00") String end) {
 return "AVAILABLE: " + start + " ~ " + end;
 }

 @Tool(description = "创建日历事件；调用前必须已经确认时间可用")
 public String createCalendarEvent(
 @ToolParam(description = "事件标题") String title,
 @ToolParam(description = "ISO-8601 开始时间") String start,
 @ToolParam(description = "ISO-8601 结束时间") String end) {
 String id = UUID.randomUUID().toString();
 return "CREATED eventId=" + id + ", title=" + title;
 }
}

邮件工具同样保持窄接口：

@Component
public class EmailTools {

 @Tool(description = "发送邮件。仅接受已经确认的收件人、主题和正文")
 public String sendEmail(String recipient, String subject, String body) {
 return "SENT to=" + recipient + ", subject=" + subject;
 }
}

演示可以直接返回字符串，生产环境必须补上：

幂等键：重试不能创建两场相同会议或发送两封邮件；
身份鉴权：工具从服务端上下文读取租户和用户，不能信任模型传入身份；
参数校验：邮箱白名单、时间范围、正文长度均由 Java 代码强制检查；
审计日志：记录调用者、工具名、参数摘要、结果和 trace ID；
超时与熔断：模型重试不应无限放大下游故障。

四、构建两个专业 ReactAgent

ReactAgent 负责“思考—选择工具—观察结果—继续”的循环。每个专业 Agent 只注册本领域工具：

@Configuration
public class AgentConfiguration {

 @Bean
 MemorySaver memorySaver() {
 return new MemorySaver();
 }

 @Bean
 ReactAgent calendarAgent(ChatModel model, CalendarTools tools) {
 return ReactAgent.builder()
 .name("schedule_event")
 .description("检查空闲时间并创建日历事件，输入为自然语言日程请求")
 .systemPrompt("""
 你是日历助理。先把时间转换为带时区的 ISO-8601 格式，
 再检查空闲时段；只有可用时才创建事件。
 最终回答必须包含事件 ID 和确认后的起止时间。
 """)
 .model(model)
 .methodTools(tools)
 .inputType(String.class)
 .build();
 }

 @Bean
 ReactAgent emailAgent(ChatModel model, EmailTools tools) {
 return ReactAgent.builder()
 .name("manage_email")
 .description("根据明确的收件人和上下文撰写并发送邮件")
 .systemPrompt("""
 你是邮件助理。不得猜测收件地址；缺少地址就要求补充。
 发送前检查主题、正文和会议时间是否一致。
 最终回答给出发送状态，不输出敏感凭据。
 """)
 .model(model)
 .methodTools(tools)
 .inputType(String.class)
 .build();
 }
}

这里的 name 和 description 不是装饰字段。Supervisor 会根据它们决定是否调用子 Agent，因此描述要写清楚 何时调用、输入是什么、能产生什么结果。

五、把子 Agent 变成 Supervisor 的工具

Spring AI Alibaba 提供 AgentTool.getFunctionToolCallback(...)，可以把整个专业 Agent 包装成上层 Agent 可调用的工具：

@Bean
ReactAgent supervisorAgent(
 ChatModel model,
 ReactAgent calendarAgent,
 ReactAgent emailAgent,
 MemorySaver memorySaver) {

 return ReactAgent.builder()
 .name("personal_assistant")
 .systemPrompt("""
 你是任务协调者，可以安排日历和发送邮件。
 先拆解请求，再按依赖顺序调用专业工具。
 邮件依赖会议结果时，必须先完成日历操作。
 不要声称执行了未返回成功结果的操作。
 """)
 .model(model)
 .saver(memorySaver)
 .tools(
 AgentTool.getFunctionToolCallback(calendarAgent),
 AgentTool.getFunctionToolCallback(emailAgent))
 .build();
}

调用入口非常直接：

@Component
public class DemoRunner implements ApplicationRunner {
 private final ReactAgent supervisorAgent;

 public DemoRunner(ReactAgent supervisorAgent) {
 this.supervisorAgent = supervisorAgent;
 }

 @Override
 public void run(ApplicationArguments args) throws Exception {
 String request = "下周二 14:00 安排一小时设计评审，"
 + "然后给 design@example.com 发一封提醒邮件";

 AssistantMessage result = supervisorAgent.call(new UserMessage(request));
 System.out.println(result.getText());
 }
}

一次典型执行链是：

User
 -> Supervisor
 -> schedule_event
 -> get_available_time_slots
 -> create_calendar_event
 -> manage_email
 -> send_email
 -> 汇总最终结果

子 Agent 是工具，但它内部仍然可以执行多轮 ReAct。这样既保留自治能力，又把自治限制在专业边界内。

六、状态持久化不等于聊天记忆

示例中的 MemorySaver 适合本地开发和单进程验证。它保存的是图执行所需的 checkpoint，使 Agent 能围绕同一线程继续运行；它不是生产级共享数据库，也不能替代业务幂等。

工程上要区分三类状态：

状态	示例	推荐存储
会话上下文	用户偏好、已确认的时间	Chat Memory / 会话库
Agent checkpoint	当前节点、工具结果、待恢复位置	持久化 Saver
业务事实	已创建会议、邮件发送记录	业务数据库，带唯一约束

即便 checkpoint 恢复成功，若工具在崩溃前已经写入业务系统、但结果还没写回 checkpoint，恢复后仍可能重复调用。因此可靠流程要让工具接受 operationId，并在业务库建立唯一约束。

七、给副作用加一道人工确认

会议和邮件都属于有副作用操作。最稳妥的方式不是只在 Prompt 中写“请先确认”，而是在工具层建立状态机：

DRAFT -> WAITING_APPROVAL -> EXECUTING -> SUCCEEDED / FAILED

Agent 第一次调用只生成草稿并返回 approvalId；API 层收到用户确认后，才调用真正的发送方法。这样即使模型忽略提示，也没有直接执行权限。

还可以进一步拆成两个工具：

prepare_email(...)：任何 Agent 都能调用，只生成草稿；
send_approved_email(approvalId)：不接受正文，只执行服务端已经批准且未过期的草稿。

这比让模型把 approved=true 当参数传进来安全得多。

八、常见问题与排查

1. 子 Agent 从不被调用

检查 name、description 是否明确，并确认模型支持 Tool Calling。描述不要只写“邮件助手”，而要说明输入和使用时机。

2. 依赖冲突或类找不到

不要混用 Spring AI 1.1.x、Spring AI Alibaba 1.1.x 与 2.0 milestone。使用 BOM 统一版本，并执行：

mvn dependency:tree

重点检查 spring-ai-* 是否出现多条不兼容版本线。

3. 时间被理解错

“明天下午”必须结合用户时区和当前日期解析。生产系统应把当前时间、时区作为可信上下文注入，并在工具层拒绝无时区或已经过期的时间。

4. 重启后任务消失

MemorySaver 只在进程内。多实例部署需要共享持久化 Saver，同时工具仍要做幂等；二者缺一不可。

5. 最终回答说成功，业务却没有记录

只信工具返回的结构化结果，不信模型自行生成的成功话术。建议工具返回包含 status、operationId、errorCode 的对象，并在最终输出前增加确定性校验节点。

九、什么时候不用多 Agent

如果任务只有一个模型、三个简单只读工具和一次调用，单个 ReactAgent 往往更便宜、更快，也更容易测试。只有出现以下情况，多 Agent 才真正有价值：

不同领域需要不同 Prompt、工具权限或模型；
任务能拆成可独立测试的专业能力；
子任务需要并行、路由或多阶段交接；
某些 Agent 必须运行在隔离环境或独立服务中；
团队希望分别维护日历、邮件、工单等能力。

不要用 Agent 替代确定性代码。固定审批顺序、金额阈值和权限检查应该写进 Java 与工作流，而不是交给 LLM 临场决定。

总结

Spring AI Alibaba 的 Supervisor 模式可以概括为：上层 Agent 负责选择和协调，下层 Agent 负责专业推理，Java 工具负责可信执行，Saver 负责恢复上下文。

真正决定系统能否进入生产的并不是 Agent 数量，而是边界是否清楚：

每个专业 Agent 只看到必要工具；
有副作用操作经过服务端审批和幂等保护；
checkpoint、会话记忆与业务事实分开保存；
版本通过 BOM 锁定，不混用稳定线和 milestone；
最终成功状态由真实工具结果而不是模型话术决定。

在这个基础上，再引入 ParallelAgent、RoutingAgent、Graph 条件边、A2A 或 Nacos，复杂度才是可控增长，而不是把一个不可预测的大 Agent 拆成一群不可预测的小 Agent。