Spring AI Alibaba 教程
开始前确认两件事：JDK 17+ 和 Spring Boot 3.x。
在你的 Spring Boot 项目 pom.xml 中，至少加入这一个依赖，就能接通通义千问（DashScope）：
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
<version>1.1.2.0</version>
</dependency>
版本号建议直接用 1.1.2.x 系列。从 1.1.2.0 起，Spring AI Alibaba 已经从单纯的“模型接入工具”升级为完整的智能体开发框架，Graph、多智能体等能力都包含在内。如果你的项目需要更底层的 Agent 构建能力，再加 spring-ai-alibaba-agent-framework 依赖。
配置 API Key，不要硬编码，推荐用环境变量 DASHSCOPE_API_KEY。在 application.yml 中：
spring:
ai:
dashscope:
api-key: ${DASHSCOPE_API_KEY}
到这里，地基就打好了。
🌱 第一级：让 AI 开口说话（ChatClient）
这是最简单的一步，目的只有一个：用 Java 代码调通一次大模型，拿到一句回复。
Spring AI Alibaba 提供了 ChatClient，用起来和 RestTemplate 很像。创建一个 Service：
@Service
public class SimpleChatService {
private final ChatClient chatClient;
public SimpleChatService(ChatModel chatModel) {
this.chatClient = ChatClient.builder(chatModel).build();
}
public String chat(String message) {
return chatClient.prompt()
.user(message)
.call()
.content();
}
}
写一个测试或 Controller 调用它，传入“你好，介绍一下你自己”，你应该能收到模型返回的一段文字。
这一步的意义：你验证了依赖、API Key、模型连接全部通畅。后面的所有能力，都是在这个 ChatClient 上层层叠加的。
⚡ 第二级：让 AI 调用你的 Java 函数（Tool Calling）
这是 Spring AI Alibaba 最核心、也最贴合你之前需求的能力：把普通 Java 方法变成 AI 可以“请求调用”的工具。
📝 写一个带 @Tool 的方法
不需要任何复杂的配置，在一个普通类里写方法，加 @Tool 注解：
@Component
public class OrderTools {
@Tool(description = "查询订单状态。当用户询问订单进度、物流信息时调用。需要提供订单号。")
public String queryOrder(
@ToolParam(description = "订单号，格式如 CS20260809001") String orderId) {
// 这里是你原有的业务逻辑
return "订单 " + orderId + " 当前状态：已发货，预计 3 天后送达";
}
}
@Tool 的 description 至关重要。模型就是靠这段话来判断“什么时候该调这个工具”，所以要写清楚使用场景，而不是只写“查询订单”。
🔗 把工具交给 ChatClient
@Service
public class ToolChatService {
private final ChatClient chatClient;
private final OrderTools orderTools;
public ToolChatService(ChatModel chatModel, OrderTools orderTools) {
this.chatClient = ChatClient.builder(chatModel).build();
this.orderTools = orderTools;
}
public String chat(String message) {
return chatClient.prompt()
.user(message)
.tools(orderTools) // 关键：把工具实例注册进来
.call()
.content();
}
}
当你问 “帮我查一下订单 CS20260809001 的状态”，背后发生的事是：
ChatClient 把用户消息和 OrderTools 中所有 @Tool 的描述信息一起发给模型。
模型判断需要调用 queryOrder，并提议参数 orderId = "CS20260809001"。
Spring AI Alibaba 在本地执行你的 queryOrder 方法（模型本身没有能力直接访问你的代码或数据库）。
方法返回的结果被回传给模型，模型用它组织成最终的自然语言回复。
安全边界不变：模型只有“提议调用”的权利，真正的执行权永远在你的 Java 代码手里。你只注册“查询订单”工具，AI 就不可能做出“删除订单”的操作。
🧠 第三级：用 ReactAgent 构建一个“会思考”的智能体
Tool Calling 解决的是“单次调用”。如果你想要一个能多步推理、反复调用工具直到完成任务的 Agent，就用 ReactAgent。
🧩 ReactAgent 是什么
ReactAgent 基于 ReAct 模式：推理（Reasoning）→ 行动（Acting）→ 观察（Observing） 循环，直到任务完成。你只需要把模型、工具和系统提示词交给它，它自己决定下一步做什么。
💻 最小可运行的 ReactAgent
// 1. 构建 ChatModel（也可以用 starter 自动配置的 ChatModel）
DashScopeApi dashScopeApi = DashScopeApi.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.build();
ChatModel chatModel = DashScopeChatModel.builder()
.dashScopeApi(dashScopeApi)
.build();
// 2. 定义工具
ToolCallback weatherTool = FunctionToolCallback.builder("get_weather", new WeatherTool())
.description("获取指定城市的天气")
.inputType(String.class)
.build();
// 3. 构建 ReactAgent
ReactAgent agent = ReactAgent.builder()
.name("weather_agent")
.model(chatModel)
.tools(weatherTool)
.systemPrompt("你是一个有帮助的助手。需要天气信息时调用工具。")
.saver(new MemorySaver()) // 保存对话记忆
.build();
// 4. 调用
AssistantMessage response = agent.call("上海今天天气怎么样？");
System.out.println(response.getText());
工具的实现就是一个普通的 BiFunction：
class WeatherTool implements BiFunction<String, ToolContext, String> {
@Override
public String apply(String city, ToolContext context) {
return city + "今天晴，25°C";
}
}
和二级的区别：在二级里，你手动调一次 ChatClient，模型可能调用一次工具就结束。在三级里，ReactAgent 自己维护“推理-行动”循环，如果一次工具调用不够，它会自己决定继续调用，直到它能给出最终答案。
🕸️ 第四级：用 Graph 编排多步骤工作流
ReactAgent 适合“自主决策”的场景，但有些业务流程是确定性的、有固定步骤的，比如“先分类客户反馈 → 再根据类别走不同处理分支”。这时候用 Graph 工作流更合适。
🧩 Graph 的基本概念
Graph 把流程拆成节点（Node），节点之间用边（Edge） 连接，还可以加条件边实现分支。一个最小的 Graph 大概长这样：
// 伪代码示意：定义两个节点，串联起来
StateGraph graph = new StateGraph();
graph.addNode("classify", classifyNode); // 节点1：分类
graph.addNode("handle", handleNode); // 节点2：处理
graph.addEdge("classify", "handle"); // 串联
graph.setEntryPoint("classify");
graph.setFinishPoint("handle");
CompiledGraph compiled = graph.compile();
compiled.invoke(初始状态);
官方示例中有一个很直观的场景：客户评价处理系统，先用一个节点把评价分成“投诉/咨询/表扬”，再根据分类结果走不同的后续节点。当你的业务流程本身就有明确的步骤和分支时，用 Graph 比让 ReactAgent 自由发挥更可控。
🤝 第五级：多智能体协作（Supervisor 模式）
当任务复杂到“一个 Agent 搞不定”，就需要多个专业 Agent 分工。Spring AI Alibaba 1.1.2.0 内置了 Supervisor 等多智能体模式。
Supervisor 模式的核心是一个“主管”Agent，它接收用户请求后，路由给最合适的子 Agent，并把子 Agent 的结果汇总后返回给用户。比如：
主管 Agent：判断用户的问题属于“查天气”还是“查订单”。
天气 Agent：只负责调用天气工具。
订单 Agent：只负责调用订单工具。
每个子 Agent 只需要关心自己的专业领域和工具，主管负责调度。1.1.2.0 还支持并行路由：主管可以同时把请求发给多个子 Agent，然后汇总结果。
从“单工具调用”到“多智能体协作”，复杂度是跳跃式上升的。不要一上来就写多智能体，先把二级（Tool Calling）和三级（ReactAgent）跑稳，确认你的工具描述准确、Agent 行为符合预期，再考虑引入 Graph 和多智能体。