SpringAI Alibaba Tool工具调用机制实战-注解注册与函数调用全流程

[一、什么是工具调用（Function Calling / Tool Calling）](#一、什么是工具调用（Function Calling / Tool Calling）)

[二、Spring AI 工具调用三步走](#二、Spring AI 工具调用三步走)

[2.1 第一步：定义工具类](#2.1 第一步：定义工具类)

[2.2 第二步：注册工具到ChatClient](#2.2 第二步：注册工具到ChatClient)

[2.3 第三步：直接调用，AI自动决定是否使用工具](#2.3 第三步：直接调用，AI自动决定是否使用工具)

三、工具注册的几种方式

四、注意事项

一、什么是工具调用（Function Calling / Tool Calling）

工具调用是让 AI 大模型能够"调用"外部函数的能力，使 AI 不再局限于生成文本，而是能执行真实操作
简单说，就像给 AI 配了一套"工具箱"------模型自己判断什么时候用哪个工具，用完再把结果告诉用户
典型场景：
- 用户问"今天北京天气怎么样" → AI 调用天气查询工具 → 返回实时天气
- 用户说"帮我查询订单123的状态" → AI 调用数据库查询工具 → 返回订单信息
- 用户说"帮我发一封邮件给张三" → AI 调用邮件发送工具 → 执行发送

二、Spring AI 工具调用三步走

2.1 第一步：定义工具类

java 复制代码

@Component
public class WeatherTool {

    /**
     * @Tool 注解标记这是一个可以被 AI 调用的工具
     * description 是给 AI 看的工具说明，越清晰 AI 越会正确使用
     */
    @Tool(description = "查询指定城市的实时天气信息，包括温度、天气状况、湿度等")
    public String getWeather(
            @ToolParam(description = "城市名称，如：北京、上海、杭州") String city) {
        // 实际业务中调用天气API
        // 这里用模拟数据演示
        return String.format("{\"city\":\"%s\", \"temperature\":\"25°C\", " +
                "\"weather\":\"晴\", \"humidity\":\"60%%\"}", city);
    }

    @Tool(description = "根据订单ID查询订单状态和详细信息")
    public String queryOrder(
            @ToolParam(description = "订单ID，格式为纯数字") String orderId) {
        // 实际业务中查询数据库
        return String.format("{\"orderId\":\"%s\", \"status\":\"已发货\", " +
                "\"createTime\":\"2026-03-21\"}", orderId);
    }
}

2.2 第二步：注册工具到ChatClient

java 复制代码

@Configuration
public class AiConfig {

    @Autowired
    private WeatherTool weatherTool;

    @Bean
    public ChatClient chatClient(ChatModel chatModel) {
        return ChatClient.builder(chatModel)
                .defaultSystem("你是一位智能助手，可以帮助用户查询天气和订单信息")
                // 注册工具：方式一，注册 Bean（推荐）
                .defaultTools(weatherTool)
                .build();
    }
}

2.3 第三步：直接调用，AI自动决定是否使用工具

java 复制代码

@GetMapping("/chat7")
public String chat7(@RequestParam String message) {
    // AI 会根据用户问题自动判断是否调用工具
    return chatClient.prompt()
            .user(message)
            .call()
            .content();
}

三、工具注册的几种方式

java 复制代码

// 方式一：defaultTools 注册对象（推荐，AI自动判断调用时机）
ChatClient.builder(chatModel)
        .defaultTools(weatherTool)
        .build();

// 方式二：运行时动态指定工具（本次请求有效）
chatClient.prompt()
        .user("查一下北京天气")
        .tools(weatherTool)    // 临时注册工具
        .call()
        .content();

// 方式三：通过 ToolCallback 函数式注册
ToolCallback weatherCallback = MethodToolCallback.builder()
        .toolMethod(WeatherTool.class.getMethod("getWeather", String.class))
        .toolObject(weatherTool)
        .build();
ChatClient.builder(chatModel)
        .defaultTools(weatherCallback)
        .build();

四、注意事项

@ToolParam 的 description 必须清晰准确，这是 AI 判断"什么时候调用、传什么参数"的依据
工具方法的返回值会被序列化为字符串传给模型，建议返回 JSON 格式字符串，信息更结构化
工具调用涉及多次模型请求（查询+分析），会消耗更多 Token，注意成本控制
高危操作（如删除数据、发送消息）建议在工具内部增加二次确认逻辑或权限校验