Spring AI Alibaba 中的 Tools（工具）到底是个啥？（通俗易懂汇总版）

💡 核心结论：一句话先记住

Tools（工具）就是大模型的“功能外挂”和“乐高积木”！ 大模型本身是个只懂“吟诗作赋”的文科生，而 Tools 给它接上了现实世界的管道——让它有能力去查最新的数据库、调用外部 API（如查天气、发邮件），甚至去操作系统文件。

---

🛑 工具的两大核心用途

页面中提到，Tools 在 AI 应用中主要扮演两个硬核角色：

1. 信息检索（RAG 增强）： 大模型不知道你数据库里的秘密，也不懂今天的新闻。通过工具，它能自己跑去数据库或网页搜索引擎“抄答案”，再回答用户。
2. 执行操作（Function Calling）： 用户说“帮我给张三发个周报邮件”，大模型自己发不了，但它可以通过工具去触发你的邮件系统，真正把活给干了。

---

🛠️ 如何创建工具？（2种主流姿势）

在 Spring AI Alibaba 里，把一个普通的 Java 功能变成大模型能看懂的“工具”，主要有两种写法：

方式一：方法（Method）作为 Tools（最常用 ⭐⭐⭐⭐⭐）

• 大白话： 在你的普通 Java Bean 方法上加一个 @Tool 注解，大模型就能自动识别并调用它。
• 💻 代码展示：

import org.springframework.ai.alibaba.agent.annotation.Tool;
import org.springframework.stereotype.Component;

@Component
public class WeatherTools {

    // ⭐ 核心：加了 @Tool 注解，大模型就知道这是个它可以调用的技能了
    // description 非常重要！大模型就是靠看这段“大白话”来决定什么时候用这个工具的
    @Tool(description = "根据城市名称查询该城市当前最新的天气情况")
    public String getCurrentWeather(String city) {
        // 实际的业务逻辑：可以调高德地图或者天气 API
        if ("杭州".equals(city)) {
            return "晴天，25℃，微风";
        }
        return "未知地区的神秘天气";
    }
}

方式二：函数（Function）作为 Tools（函数式编程玩家 ⭐⭐⭐⭐）

• 大白话： 利用 Java 8 的 Function<Req, Resp> 接口来定义工具，适合需要动态注册或者喜欢函数式风格的开发者。
• 💻 代码展示：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Description;
import java.util.function.Function;

@Configuration
public class MyFunctionToolConfig {

    // 定义输入入参的数据结构（大模型会自动根据这个生成 JSON Schema）
    public record Request(String orderId) {}
    // 定义工具返回的数据结构
    public record Response(String status, String logistics) {}

    @Bean
    @Description("根据订单ID查询该订单的物流状态和进度") // 同样必须用描述告诉 AI 怎么用
    public Function<Request, Response> queryOrderLogistics() {
        return request -> {
            // 查数据库或快递 API
            return new Response("已发货", "顺丰速运：商品已到达杭州集散中心");
        };
    }
}

---

🔍 核心概念与规范（AI 是怎么识别工具的？）

大模型和 Java 之间隔着一条鸿沟，框架在底层做了一系列翻译工作：

1. Tool Definition（工具定义）与 JSON Schema： 大模型只认 JSON。当你写完上面的 Java 代码，Spring AI 会悄悄把你的方法名、入参、@Description 文本，翻译成一套标准的 JSON Schema 规范发给大模型。大模型看懂了，才能决定传什么参数给你。
2. Result Transformation（结果转换）： 你的 Java 方法返回的是个对象（比如上面的 Response），框架会自动把它转成 String 或 JSON 扔回给大模型，大模型读完后，再用人类听得懂的话回答用户。
3. 返回直接（Return Direct）： 页面提到一个高级属性。默认情况下，工具查到的结果要先还给大模型，让大模型“润色”一下再给用户。但如果开启了“返回直接”，工具查到什么就直接吐给前端用户，大模型不再中间插手。

---

🚀 Tool 执行的两种控制模式

当大模型高喊“我要调工具”时，程序的控制权有两种走法：

1. 框架控制的 Tool 执行（自动驾驶 ⭐⭐⭐⭐⭐）

• 大白话： 也是最推荐的玩法。你把工具丢给 ReactAgent，剩下的事情你不用管了。Agent 发现需要调工具，自己去调，调完拿到结果自己继续思考，直到出结果。
• 💻 代码展示：

// 把上面声明的 WeatherTools 直接喂给 Agent，全程自动驾驶
ReactAgent agent = ReactAgent.builder()
        .chatModel(chatModel)
        .tools(List.of(weatherTools)) // 塞进去就完事了
        .build();

2. 用户控制的 Tool 执行（手动挡/半自动 ⭐⭐⭐）

• 大白话： 大模型想调工具时，它不直接调，而是委婉地回复一句：“我想调用查天气的工具，参数是杭州，你帮我调一下”。你的后端代码拿到这个意图后，自己手动去调 Java 方法，再把结果手动塞给大模型。适合对安全和权限要求极高的场景。

---

🎯 终极秒记口诀

大模型是个文科生，遇到算术就发懵；
多亏有了 Tools 帮忙，查流查天全拿手！
方法上面加 @Tool，描述千万要写足；
框架自动转 JSON，大模型干活不含糊！