AI Agent on 吾爱主机

AgentScope Java 2.0 实战：构建带权限审批与可恢复执行的生产级 Agent

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

能调用 Shell、修改文件和派发子任务的 Agent，比普通聊天机器人更有价值，也更危险。Prompt 中一句“执行危险操作前请确认”不是安全边界：模型可能误判上下文、被工具输出诱导，或者在重试中重复执行副作用。

AgentScope Java 2.0 把这类生产问题放进框架核心：每次工具调用都经过权限系统，结果是 ALLOW、DENY 或 ASK；ASK 会暂停 Agent，等待用户确认后再恢复。同时，Harness、Workspace、Sandbox 和分布式状态后端用来承载长时间任务。

本文基于 AgentScope Java 2.0.0 GA 和 JDK 17，先搭建一个 HarnessAgent，再实现“读操作自动放行、写操作必须审批、生产资源不可绕过”的权限策略，最后说明 session 恢复与沙箱的边界。

一、ReActAgent 与 HarnessAgent 的分工

AgentScope Java 2.0 提供两层抽象：

抽象	适合场景	核心关注点
`ReActAgent`	轻量聊天、受限 Tool Calling	推理—行动循环、模型、工具
`HarnessAgent`	长任务、文件/代码 Agent、企业部署	Workspace、Memory、Skills、Subagent、Sandbox、恢复

如果只需调用一个天气 API，ReActAgent 已经足够。若 Agent 要在目录里读写文件、执行命令、跨会话继续任务，应该从 Harness 开始，因为这些能力需要共享一致的运行上下文。

官方 2.0 的设计还强调 Agent 本身无状态：运行状态通过 (userId, sessionId) 和后端管理。这比把可变消息列表放进单例 Agent 更适合多实例部署。

二、依赖和模型配置

AgentScope Java 2.0 要求 JDK 17+。Harness 与模型提供商从 2.0 起拆分为独立模块：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <agentscope.version>2.0.0</agentscope.version>
</properties>

<dependencies>
 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-harness</artifactId>
 <version>${agentscope.version}</version>
 </dependency>

 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-extensions-model-dashscope</artifactId>
 <version>${agentscope.version}</version>
 </dependency>
</dependencies>

其他官方可选模型模块包括 OpenAI、Anthropic、Gemini 和 Ollama。使用 DashScope 时，把密钥放进环境变量而不是源码：

export DASHSCOPE_API_KEY="你的密钥"

然后创建最小 HarnessAgent：

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import java.nio.file.Paths;

public class OpsAgentApp {
 public static void main(String[] args) {
 HarnessAgent agent = HarnessAgent.builder()
 .name("ops_assistant")
 .sysPrompt("""
 你是运维分析助手。先读后写，输出每一步依据；
 未获得权限系统批准时，不得声称已经修改任何资源。
 """)
 .model("dashscope:qwen-plus")
 .workspace(Paths.get(".agentscope/workspace"))
 .build();

 RuntimeContext ctx = RuntimeContext.builder()
 .userId("alice")
 .sessionId("incident-20260724-001")
 .build();

 var result = agent.call(
 new UserMessage("检查工作区里的故障日志并给出处理建议"), ctx)
 .block();
 if (result != null) {
 System.out.println(result.getTextContent());
 }
 }
}

模型字符串由 ModelRegistry 解析。workspace 不是随便给 Agent 一个宿主机根目录，而应该是专门分配、权限收敛的工作目录。

三、权限系统如何做决策

权限系统位于 io.agentscope.core.permission，拦截每次工具调用。它综合三类信息：

Rules：针对工具和调用模式的显式 ALLOW、ASK、DENY；
Mode：未命中规则时的默认策略；
Built-in Checks：工具根据真实入参执行的不可绕过检查。

决策顺序中，DENY 规则和危险路径检查优先。即使启用 BYPASS，这类保护仍然生效。

官方提供五种常用模式：

模式	未命中规则时的行为	适用情况
`DEFAULT`	要求显式规则或用户确认	推荐默认值
`ACCEPT_EDITS`	放行工作目录内安全文件操作	用户在场的开发任务
`EXPLORE`	只读，拒绝写与命令	代码探索、规划
`BYPASS`	通常放行，但不可绕过的检查仍有效	完全可信且隔离的 Sandbox
`DONT_ASK`	将 ASK 变为 DENY	无人值守任务

DONT_ASK 尤其重要：定时任务没有用户在线，不能让 Agent 永久等待审批，也不应默认放行。

四、配置 ALLOW、ASK 与 DENY 规则

下面的策略允许安全读取，删除操作必须询问，删表始终拒绝：

import io.agentscope.core.permission.PermissionBehavior;
import io.agentscope.core.permission.PermissionContextState;
import io.agentscope.core.permission.PermissionMode;
import io.agentscope.core.permission.PermissionRule;

PermissionContextState permissions = PermissionContextState.builder()
 .mode(PermissionMode.DEFAULT)
 .addAllowRule(
 "safe_read",
 new PermissionRule(
 "safe_read", null,
 PermissionBehavior.ALLOW, "projectSettings"))
 .addAskRule(
 "dangerous_delete",
 new PermissionRule(
 "dangerous_delete", null,
 PermissionBehavior.ASK, "projectSettings"))
 .addDenyRule(
 "drop_table",
 new PermissionRule(
 "drop_table", null,
 PermissionBehavior.DENY, "projectSettings"))
 .build();

可以把权限上下文交给底层 ReActAgent：

ReActAgent agent = ReActAgent.builder()
 .name("controlled_agent")
 .sysPrompt("先检查，再操作")
 .model(model)
 .permissionContext(permissions)
 .build();

若使用 Harness，应在构建 Harness 的 delegate/permission 配置位置应用同一上下文；具体 Builder 入口以 2.0.0 文档和当前模块为准，不要从 RC 版博客复制包名。

规则来源 projectSettings、userSettings、session 或 suggested 应进入审计日志。由用户在一次 ASK 中接受的 suggested rule，可能影响后续相同调用，UI 必须明确告诉用户这是“一次允许”还是“以后允许”。

五、自定义不可绕过的工具检查

静态规则不一定能识别业务语义。比如同一个 restart_service 工具，测试环境可以自动执行，生产环境必须审批。自定义 Tool 可覆盖 checkPermissions：

import io.agentscope.core.permission.PermissionDecision;
import io.agentscope.core.tool.ToolBase;
import io.agentscope.core.tool.ToolExecutionContext;
import java.util.Map;
import reactor.core.publisher.Mono;

public final class RestartServiceTool extends ToolBase {

 public RestartServiceTool() {
 super(ToolBase.builder()
 .name("restart_service")
 .description("重启指定环境中的服务")
 .readOnly(false));
 }

 @Override
 public Mono<PermissionDecision> checkPermissions(
 Map<String, Object> input,
 ToolExecutionContext context) {

 String environment = String.valueOf(input.get("environment"));
 if (environment.startsWith("prod")) {
 return Mono.just(PermissionDecision.ask(
 "目标是生产环境，需要人工批准：" + environment));
 }

 return Mono.just(PermissionDecision.passthrough(
 "非生产环境，继续按 rules/mode 判断"));
 }
}

PASSTHROUGH 不是 ALLOW，它表示把决定权交回规则和模式。对明确禁止的目标可直接返回 deny(...)。

框架还内置危险路径保护，例如 .ssh/、.git/、.aws/、.kube/、.env 和凭据文件。命中危险路径时会强制 ASK；自定义 Tool 也可以增加危险文件和目录。

六、ASK 后怎样暂停与恢复

权限结果为 ASK 时，Agent 不执行工具，而是以 GenerateReason.PERMISSION_ASKING 暂停。返回消息中包含状态为 ASKING 的 ToolUseBlock，调用方应：

把工具名和脱敏后的参数展示给用户；
让用户选择拒绝、仅本次允许或接受建议规则；
构造 ConfirmResult；
使用相同 (userId, sessionId) 恢复 Agent。

核心确认对象如下：

ConfirmResult confirm = new ConfirmResult(
 true, // confirmed
 toolCall, // 本次待确认调用
 toolCall.getSuggestedRules() // 仅在用户明确接受时传入
);

生产 UI 不应只放一个模糊的“确认”按钮。至少显示：

工具名称与风险级别；
目标环境、资源 ID、路径；
是否产生副作用；
建议规则会影响一次还是后续调用；
session、用户和过期时间。

确认结果必须由服务端绑定当前用户和待审批记录，不能接受客户端随意提交另一个 toolCall。

七、流式事件让执行过程可观察

Harness 可以输出统一事件流：

agent.streamEvents(
 new UserMessage("分析日志；如果需要修改配置先请求批准"), ctx)
 .doOnNext(event -> {
 switch (event.getType()) {
 case TEXT_BLOCK_DELTA ->
 System.out.print(((TextBlockDeltaEvent) event).getDelta());
 case TOOL_CALL_START ->
 System.out.println("[tool] "
 + ((ToolCallStartEvent) event).getToolCallName());
 default -> { }
 }
 })
 .blockLast();

事件流可驱动 Web UI、飞书/钉钉 Channel 或审计平台。注意不要把所有原始参数直接写日志；命令、Prompt 和工具结果可能包含 Token、路径或客户数据。

八、Workspace、Sandbox 和权限各管一层

三者不能互相替代：

Workspace 组织文件、Memory、Skills 和子 Agent 工作上下文；
Permission 决定某次工具调用是否允许、拒绝或询问；
Sandbox 限制已经获准的代码实际能访问哪些系统资源。

即使权限系统批准 rm temp.txt，Sandbox 仍应阻止进程读取宿主机 SSH 密钥。反过来，Docker 隔离也不能代替业务审批：容器里的工具可能仍持有生产 API 凭据。

可按风险逐级部署：

开发：专用本地目录 + DEFAULT
测试：Docker Sandbox + ACCEPT_EDITS
生产交互：Kubernetes Sandbox + DEFAULT + HITL
生产无人值守：最小工具集 + DONT_ASK + 服务端白名单

每个 Sandbox 还应配置 CPU、内存、进程数、超时、只读根文件系统和网络出口策略。

九、可恢复执行的正确边界

AgentScope Java 2.0 支持 Redis、MySQL、PostgreSQL、OSS/COS 等分布式 session 和 memory 后端，并面向跨副本 session 恢复。但“恢复 Agent 状态”仍不等于“业务操作恰好一次”。

经典故障窗口：

工具成功重启服务
 -> 进程在保存工具结果前崩溃
 -> 恢复后模型再次请求重启

解决方案在工具层：

record OperationRequest(String operationId, String service, String environment) {}

operationId 由可信服务端生成；
业务库对它建立唯一约束；
重复请求返回第一次结果，而不是再次执行；
checkpoint 记录 operationId 与状态；
外部系统也尽可能使用幂等键。

userId + sessionId 用于隔离会话，operationId 用于隔离副作用，二者不要混为一谈。

十、生产部署清单

默认使用 DEFAULT 或 EXPLORE，不把 BYPASS 当省事开关；
无人值守任务使用 DONT_ASK，未明确允许的调用直接拒绝；
生产、凭据和危险路径在 Tool 内做不可绕过检查；
ASK 绑定用户、session、调用参数摘要和过期时间；
Suggested Rule 的持久化范围对用户透明；
Sandbox 有资源限制、网络出口策略和短期凭据；
所有写工具都有幂等键与审计记录；
使用共享状态后端，并测试滚动发布和跨副本恢复；
对每种工具做 ALLOW、ASK、DENY 和恢复故障测试；
日志和事件流经过脱敏。

十一、常见问题

Agent 一直要求确认

检查规则的 toolName 和 ruleContent 是否真的匹配调用；若默认 DEFAULT 且没有 ALLOW 规则，询问是预期行为。不要直接切到 BYPASS，先补齐最小权限规则。

定时任务卡在 ASK

无人值守场景改用 DONT_ASK，并显式允许安全工具。ASK 会转成 DENY，从而让任务失败得可观察，而不是永久等待不存在的用户。

工作区恢复后找不到文件

本地 Workspace 不适合多副本。使用共享存储或远程文件系统，并保证所有副本使用一致的路径映射、租户隔离和版本策略。

已有 Sandbox，为什么还要权限系统

Sandbox 限制“能破坏多大范围”，权限系统限制“此刻是否应该执行”。前者是隔离，后者是意图授权，必须叠加。

总结

AgentScope Java 2.0 的核心价值不是又实现了一次 ReAct，而是把 Agent 当成一个需要治理的长期运行系统：

权限系统在每次工具调用前作出 ALLOW、ASK 或 DENY；
Tool 的 Built-in Check 能根据真实参数建立不可绕过的业务安全线；
HITL 用同一 session 暂停和恢复，而不是只在 Prompt 里“请求确认”；
Workspace 管上下文，Sandbox 管隔离，分布式后端管恢复；
幂等和业务事实仍由工具与数据库负责。

如果你的 Agent 会改文件、执行命令或触碰生产资源，先设计权限、审批、隔离和恢复，再讨论模型是否更聪明。生产 Agent 最重要的能力，不是永远做对，而是做错时被阻止、失败后可恢复、重试时不重复造成损失。

参考资料

Google ADK Java 实战：用 Code-first 方式编排多 Agent 工作流

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

Google Agent Development Kit（ADK）Java 是一个代码优先的 Agent 工具包：Agent 的角色、工具和编排直接写在 Java 中，可以进入版本控制、单元测试和部署流程。它不是只能调用 Gemini 的聊天 SDK，而是提供 LlmAgent、Sequential/Parallel/Loop Agent、Session/State、Dev UI 和 A2A 集成。

本文基于 Google ADK Java 1.7.0，实现一个“研究—审查—成稿”的顺序多 Agent 工作流，并说明工具、Session State、Dev UI 以及 A2A 与 MCP 的分工。

截至 2026-07-23，官方 README 仍将 ADK Java 标记为 Preview / Pre-GA，并说明相关能力按 “as is” 提供、支持可能有限。它适合学习、PoC 和可控试点；关键生产系统上线前必须锁版本、做回归测试并准备替代路径。

一、ADK 的 Code-first 是什么

代码优先不只是“不写 YAML”，而是把 Agent 系统的重要结构放进类型化代码：

BaseAgent
├── LlmAgent 模型驱动，能调用工具或委派
├── SequentialAgent 按顺序执行子 Agent
├── ParallelAgent 并行执行独立子 Agent
└── LoopAgent 在条件下重复执行

LLM 适合处理语义判断和非结构化内容；Sequential/Parallel/Loop 则提供确定性控制。一个可靠系统往往混用二者，而不是让一个大模型临场规划全部步骤。

本文流程是：

用户主题
 -> researcher：形成事实清单，写入 research_notes
 -> reviewer：检查证据与风险，写入 review_notes
 -> writer：读取前两步结果，形成文章提纲

三个专业 Agent 可以使用不同 Prompt，输出通过 Session State 传递。

二、依赖、凭据与版本状态

Maven 依赖：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <adk.version>1.7.0</adk.version>
</properties>

<dependencies>
 <dependency>
 <groupId>com.google.adk</groupId>
 <artifactId>google-adk</artifactId>
 <version>${adk.version}</version>
 </dependency>

 <dependency>
 <groupId>com.google.adk</groupId>
 <artifactId>google-adk-dev</artifactId>
 <version>${adk.version}</version>
 </dependency>
</dependencies>

google-adk-dev 用于本地开发 UI，不建议不加区分地打进生产镜像。

使用 Google AI Studio / Gemini API 时，凭据名称和认证方式应以当前 ADK 官方文档为准，常见本地配置是：

export GOOGLE_API_KEY="你的密钥"

如果使用 Vertex AI，还需要 Google Cloud Project、区域和 ADC 等配置。不要把服务账号 JSON 放进源码或容器镜像。

三、先实现一个可验证的 FunctionTool

ADK 可以把静态 Java 方法包装成工具。下面的工具只返回受控的本地资料，便于无外部搜索依赖地验证调用链：

import com.google.adk.tools.Annotations.Schema;
import java.util.Map;

public final class ResearchTools {

 public static Map<String, String> lookupFrameworkFact(
 @Schema(
 name = "framework",
 description = "框架名称，例如 Spring AI Alibaba 或 AgentScope Java")
 String framework) {

 return switch (framework.toLowerCase()) {
 case "spring ai alibaba" -> Map.of(
 "status", "success",
 "fact", "面向 Java 的 Agent、Workflow 与 Multi-Agent 框架");
 case "agentscope java" -> Map.of(
 "status", "success",
 "fact", "面向分布式、生产级、长时间运行 Agent 的 Java 框架");
 default -> Map.of(
 "status", "not_found",
 "fact", "本地资料中没有该框架");
 };
 }
}

包装为 FunctionTool：

import com.google.adk.tools.FunctionTool;

var factTool = FunctionTool.create(
 ResearchTools.class,
 "lookupFrameworkFact");

工具参数用 @Schema 写清名称和描述，返回值使用结构化 Map 或 POJO。模型可以决定是否调用，但 Java 方法必须独立完成参数校验、鉴权、超时和幂等。

四、定义三个专业 LlmAgent

1. Researcher

import com.google.adk.agents.LlmAgent;

LlmAgent researcher = LlmAgent.builder()
 .name("researcher")
 .description("查找并整理主题相关事实")
 .model("gemini-2.0-flash")
 .instruction("""
 根据用户主题整理事实清单。
 可调用 lookupFrameworkFact；找不到的内容明确标为待核验，禁止编造。
 输出简洁 Markdown 要点。
 """)
 .tools(factTool)
 .outputKey("research_notes")
 .build();

outputKey 会把 Agent 最终输出写入 Session State，供后续 Agent 使用。

2. Reviewer

LlmAgent reviewer = LlmAgent.builder()
 .name("reviewer")
 .description("审查研究事实、缺口与风险")
 .model("gemini-2.0-flash")
 .instruction("""
 阅读 session state 中的 research_notes。
 分成：已确认、证据不足、可能过时三类；
 不得把推测升级成事实，给出下一步核验建议。
 """)
 .outputKey("review_notes")
 .build();

3. Writer

LlmAgent writer = LlmAgent.builder()
 .name("writer")
 .description("把研究和审查结果组织成文章提纲")
 .model("gemini-2.0-flash")
 .instruction("""
 使用 research_notes 和 review_notes 生成中文技术文章提纲。
 对证据不足的结论保留警示；不输出版本发布稿，强调可复用原理与实践。
 """)
 .outputKey("article_outline")
 .build();

Prompt 应告诉 Agent 从 State 读取哪些键、输出写到哪里。否则三个 Agent 虽然按顺序运行，却不一定有效协作。

五、用 SequentialAgent 显式编排

import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.SequentialAgent;
import java.util.List;

public final class ArticleWorkflow {

 public static final BaseAgent ROOT_AGENT = SequentialAgent.builder()
 .name("article_workflow")
 .description("研究、审查并生成文章提纲")
 .subAgents(List.of(researcher, reviewer, writer))
 .build();
}

顺序编排的价值是依赖关系明确：Reviewer 不会在 Researcher 之前运行，Writer 也不会绕过审查。它比让一个“主管 Agent”自行决定顺序更容易测试。

何时用其他类型：

ParallelAgent：两个子任务互不依赖，例如同时查官方文档和运行基准；
LoopAgent：审查不通过就重写，但必须设置退出条件和最大轮数；
LlmAgent + subAgents：让模型按语义把任务委派给专业 Agent。

不要把有先后依赖的任务硬塞进 Parallel，也不要创建没有最大次数的 Loop。

六、启动 Dev UI

ADK Java 自带开发 UI，可用于交互、查看事件和调试 Agent。最简单入口：

import com.google.adk.web.AdkWebServer;

public class Main {
 public static void main(String[] args) {
 AdkWebServer.start(ArticleWorkflow.ROOT_AGENT);
 }
}

启动后在本地页面输入：

比较 Java Agent 框架在工具权限和恢复方面的差异

开发 UI 适合：

看模型是否调用了工具；
检查专业 Agent 的执行顺序；
观察 State 中输出键；
保存用于演示和人工回归的会话。

它不是生产认证网关。上线时仍需自己的 API 层、身份系统、限流、审计和 Secret 管理。

七、Session、State 与 Artifact

ADK 中要区分：

概念	用途
Session	某用户/某次连续交互的容器
State	小型结构化状态，如研究摘要、审核结论
Event	用户、模型、工具与 Agent 运行过程
Artifact	文件、报告、图片等较大对象

outputKey 写入的是 State，不应把大文件或整份日志塞进去。大对象应使用 Artifact 服务，并在 State 中只保存引用和摘要。

生产环境还要决定 Session Service 的持久化实现。进程内 Session 适合 Demo；多实例部署需要共享后端，并测试并发更新、过期、迁移和恢复。

即使 Session 能恢复，工具副作用仍要幂等。流程崩溃可能发生在外部 API 已成功、结果尚未写回 Event/State 的窗口。

八、确定性 Workflow 与 LLM 路由怎样选择

优先确定性编排的情况：

合规审批顺序固定；
后一步依赖前一步产物；
需要精确控制成本和最大循环；
每个阶段都要测试和审计。

适合 LLM 路由的情况：

用户意图类别多，规则难以穷举；
多个专业 Agent 能力边界清楚；
选错路由的损失低，且可以回退；
工具和 Agent 都没有越权能力。

常用组合是：顶层确定性 Workflow 控制阶段，某个阶段内部用 LlmAgent 选择工具或子 Agent。

九、A2A 与 MCP 的分工

ADK 官方重点支持 A2A，用于远程 Agent 之间的能力发现和通信。MCP 则主要面向工具、资源和 Prompt 的互操作。

文章 Agent
 --A2A--> 独立部署的法务审查 Agent
 --MCP--> 搜索、数据库、文件等工具服务器

二者不是替代关系：

协议	对端	典型能力
A2A	另一个自治 Agent	委派任务、跟踪远程任务、交换结果
MCP	工具/资源服务器	调函数、读资源、获取 Prompt

跨进程后要验证认证、超时、取消、流式、重试和版本协商。协议兼容不代表安全策略自动兼容。

十、Preview 阶段怎样控制风险

官方 1.7.0 已发布到 Maven Central，但 README 仍标记 Preview / Pre-GA，且部分评测能力仍在演进。工程上应：

锁定 1.7.0，不使用动态版本；
用自己的 AgentWorkflow 接口包住 ADK 类型；
保存固定输入、工具调用和状态输出作为回归集；
将模型与工具封装在可替换适配层；
不把 Dev UI 暴露到公网生产环境；
对每次升级验证 Session schema、事件格式和工具调用；
为迁移到其他工作流引擎保留业务层边界。

“1.x”不自动等于 GA，官方发布阶段声明比版本号更重要。

十一、常见问题

后续 Agent 读不到前一步输出

确认前一步设置 outputKey，后续 Prompt 使用同一个 State 键；还要确认 Workflow 使用同一 Session，而不是为每步创建新会话。

模型不调用 FunctionTool

检查方法是否为可反射调用的静态方法、名称是否传给 FunctionTool.create、参数 Schema 是否明确，以及具体模型是否支持工具调用。

ParallelAgent 结果互相覆盖

每个并行 Agent 使用唯一 outputKey，汇总 Agent 再读取多个键。不要让并行分支写同一个 State 字段。

LoopAgent 不停运行

增加确定性退出条件和最大迭代数，同时记录每轮结果。不要只靠 Prompt 中“完成后停止”。

本地成功，上云后丢 Session

本地 Dev UI 常使用进程内服务。生产要配置共享 Session/Artifact 后端，并验证多副本路由、过期和并发更新。

十二、生产清单

明确标记 ADK Java 为 Preview / Pre-GA，并锁定精确版本；
工作流顺序由代码控制，LLM 只处理需要语义判断的节点；
每个 State Key 有唯一写入者或明确合并规则；
Artifact 与 State 分开保存；
工具有鉴权、幂等、超时和结构化错误；
Loop 有最大次数，Parallel 分支避免写冲突；
Dev UI 只用于受控开发环境；
A2A 和 MCP 分别设计认证与审计；
升级前运行固定 Agent/Tool/State 回归集；
多实例环境使用共享 Session 服务。

总结

Google ADK Java 最有价值的地方，是让 Java 开发者在同一套代码中组合两类控制：

LlmAgent 处理语义、工具选择和非结构化内容；
Sequential、Parallel、Loop 等 Workflow Agent 提供确定性控制；
outputKey、Session State 和 Artifact 负责阶段间传递；
Dev UI 降低本地调试成本；
A2A 连接独立 Agent，MCP 连接工具和资源。

在 Preview 阶段，建议从边界明确的内部工作流开始，而不是立刻替换关键核心系统。Code-first 的真正收益不只是代码看起来清晰，而是工作流能进入代码审查、测试、版本管理和故障演练。

参考资料

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。