Spring AI 智能体 —— 工具回调

大家好，上一期我们用 Spring AI 搭建了一个“小爱同学”智能体，实现了最基本的对话能力。但那个智能体只会“说”，还不会“做”。本期我们就给它装上 “手脚”，让它能调用工具干活儿——这就是工具回调（Tool Calling）。

一、小白话简介

先想一个场景：你问智能体，“今天深圳天气怎么样？”

普通的大模型只能根据训练数据瞎猜，或者老老实实告诉你“我不能查询实时信息”。

而一个接了工具的智能体，会自动调用天气查询工具，拿到真实数据后再整理成自然语言回答：“深圳今天多云，26~32℃”

这个“自动识别意图 → 选择工具 → 执行调用 → 理解返回结果 → 生成最终回答”的过程，就是工具回调。

简单类比：

大模型 = 脑子 🧠
工具 = 手脚 🦾
工具回调 = 脑子指挥手脚去干活，并把干完的活儿说给你听。

在 Spring AI 里，你只需要用 @Tool 注解声明一个普通 Java 方法，框架就会自动把它包装成智能体可以调用的工具，非常简单。

二、基础铺垫

1️⃣ 工具的本质是什么？

对智能体来说，工具就是一段可以被大模型调用的结构化函数。每次工具调用通常包含：

工具名称：比如 getWeather
工具描述：告诉模型什么时候用，比如“根据城市名查询实时天气”
参数定义：比如城市名、日期等
执行逻辑：你的 Java 方法体

大模型本身并不执行这些逻辑，而是生成一个“我想调用这个工具”的指令，由框架替你执行，然后把结果送回模型做下一轮推理。

2️⃣ Spring AI 的工具回调机制

Spring AI 的工具回调基于 ReAct 模式（推理-行动循环），流程如下：

用户提问
→ 模型思考（我要不要用工具？用哪个？）
→ 模型输出“函数调用请求”
→ 框架执行对应 Java 方法
→ 将执行结果返回给模型
→ 模型结合结果生成最终回答

整个过程智能体可能循环多次（比如先查城市编码，再查天气），就像人处理复杂任务一样。

3️⃣ @Tool 注解的使用

在 Spring AI Alibaba 中，你只需要：

public class WeatherTools {    @Tool(description = "根据城市名获取实时天气")    public String getWeather(String city) {        // 实际去调天气 API，这里模拟一下        return city + "：多云，26~32℃";    }}

在构造智能体时把工具对象传进去即可。

框架会自动解析注解，把方法元信息告诉大模型。

三、应用实践：为“小爱同学”装上天气查询工具

下面我们一步步实现一个能查天气的智能体。

步骤一：环境准备

与上一期一样，准备 Spring Boot 3 + JDK 17或以上的项目，pom.xml 核心依赖不变：

<!-- Spring AI Alibaba Agent框架 --><dependency>    <groupId>com.alibaba.cloud.ai</groupId>    <artifactId>spring-ai-alibaba-agent-framework</artifactId>    <version>1.1.2.0</version></dependency><!-- DashScope模型支持 --><dependency>    <groupId>com.alibaba.cloud.ai</groupId>    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>    <version>1.1.2.0</version></dependency>

spring-ai-alibaba-agent-framework 已经内置了对工具回调的支持，不需要额外依赖。

步骤二：编写工具类

创建一个模拟天气查询的工具，真实场景中可接入高德、和风天气等 API。

import com.alibaba.cloud.ai.graph.agent.annotation.Tool;import org.springframework.ai.tool.annotation.ToolParam;import org.springframework.stereotype.Component;@Componentpublic class WeatherTools {    @Tool(description = "查询指定城市的实时天气，返回天气状况、温度范围等信息")    public String getWeather(@ToolParam(description = "城市名称，如'深圳'、'北京'、'上海'") String city) {        // 模拟返回不同城市的天气        return switch (city) {            case "深圳" -> "深圳：多云，26~32℃，微风";            case "北京" -> "北京：晴，18~28℃，北风3级";            case "上海" -> "上海：小雨，22~26℃，东南风2级";            default -> city + "：天气数据暂未覆盖";        };    }}

重点：@Tool 的 description 非常重要，模型正是通过它来判断什么时候该用这个工具。一定要准确、简洁。

步骤三：创建带工具的 ReAct 智能体

在主程序里，把工具对象传给 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;import org.springframework.ai.chat.model.ChatModel;public class ToolCallingAgent {    public static void main(String[] args) throws Exception {        // 1. 创建模型（替换成你自己的 Key）        DashScopeApi dashScopeApi = DashScopeApi.builder()                .apiKey("sk-你的API-KEY")                .build();        ChatModel chatModel = DashScopeChatModel.builder()                .dashScopeApi(dashScopeApi)                .build();        // 2. 实例化工具        ToolCallback[] weatherTools = MethodToolCallbackProvider.builder()                  .toolObjects(new WeatherTools())                  .build()                  .getToolCallbacks();        // 3. 创建 ReAct 智能体，注入工具        ReactAgent agent = ReactAgent.builder()                .name("小爱同学")                .model(chatModel)                .instruction("你叫小爱同学，是一个能查询天气的智能助手。用户问天气时务必调用工具获取实时数据。")                .tools(weatherTools)   // 注册工具                .build();        // 4. 测试问天气        var response1 = agent.call("今天深圳天气怎么样？");        System.out.println("回答1：" + response1.getText());        var response2 = agent.call("北京呢？");        System.out.println("回答2：" + response2.getText());        var response3 = agent.call("天津呢？");        System.out.println("回答3：" + response3.getText());    }}

阿里云百炼的 DashScope API，Key 获取链接：
https://bailian.console.aliyun.com/cn-beijing?tab=api#/api

步骤四：运行与结果

运行 main 方法，观察控制台输出：

这说明智能体正确识别了意图，自主调用了工具，并基于结果生成了最终回答。至此，“手脚”已成功安装！

🎉 总结

本期我们给“小爱同学”添加了天气查询工具，实现了：

@Tool 注解定义工具：一个普通方法瞬间变成智能体的能力
在 ReAct 智能体中注册工具：模型自动根据描述判断何时调用
模拟真实业务：让智能体从“只会说”进化为“能做会说”

这就是工具回调的核心玩法。

掌握了它，你就可以轻松为智能体接入数据库查询、发邮件、操作文件系统、调用企业接口等各种能力，真正成为你的“行动派”私人助理。

下期预告：智能体的“记忆”机制。我们将给智能体装上海马体，让它记住对话上下文、用户偏好，甚至跨会话保持状态。敬请期待！✨

快动手试试，有问题欢迎在评论区交流。

欢迎关注

我知道你 “在看”