Spring AI 工具调用（Tool Calling）实战

注解说明：

控制器调用示例：

@GetMapping("/annotate/setAlarm")
public String setAlarm(String userInput) {
    return chatClient.prompt().tools(new LocalDateTimeTool()) // 注册整个类中的 @Tool 方法.
        .user(userInput)
        .call()
        .content();
}

测试请求：

GET /tool/annotate/setAlarm?userInput=请帮我设置 10 分钟后的闹钟 

模型会自动提取时间并格式化为 ISO-8601 字符串传入 setAlarm() 方法。

使用限制

当使用方法作为工具时，以下类型不能用于参数或返回值：

• Optional<T>
• 异步类型（如 CompletableFuture, Future）
• 响应式类型（如 Mono, Flux, Flow）
• 函数式接口（如 Function, Supplier, Consumer）

方法二：使用函数式编程定义工具

Spring AI 还支持以 Function<I, O> 形式定义工具，更适合无状态的服务逻辑。

示例：天气查询服务

import org.springframework.ai.tool.annotation.Description;

public class WeatherService implements Function<WeatherService.WeatherRequest, WeatherService.WeatherResponse> {
    public record WeatherRequest(String location, Unit unit) {}
    public record WeatherResponse(double temp, Unit unit) {}
    public enum Unit { C, F }

    @Override
    public WeatherResponse apply(WeatherRequest request) {
        System.out.println("获取{" + request.location + "}的天气");
        double temperature = Math.random() * 50; // 模拟随机温度
        return new WeatherResponse(temperature, Unit.C);
    }
}

方式 A：手动构建 FunctionToolCallback

适用于灵活注册、动态管理工具场景。

@GetMapping("/method/getWeather")
public String getWeather(String userInput) {
    FunctionToolCallback<WeatherService.WeatherRequest, WeatherService.WeatherResponse> callback = FunctionToolCallback.builder("currentWeather", new WeatherService())
        .description("Get the weather in location")
        .inputType(WeatherService.WeatherRequest.class)
        .build();
    return chatClient.prompt().toolCallbacks(callback).user(userInput).call().content();
}

方式 B：通过 @Bean 注册工具（推荐）

利用 Spring IoC 容器统一管理工具实例，更符合我们的开发习惯。

@Configuration(proxyBeanMethods = false)
public class WeatherTools {
    public static final String CURRENT_WEATHER_TOOL = "currentWeather";

    @Bean(CURRENT_WEATHER_TOOL)
    @Description("Get the weather in location")
    public Function<WeatherRequest, WeatherResponse> currentWeather() {
        return new WeatherService();
    }
}

注意：@Description 注解用于提供工具描述，若不加则默认使用 Bean 名称作为描述。

调用控制器：

@GetMapping("/spring/getWeather")
public String getWeatherBySpring(String userInput) {
    return chatClient.prompt().toolNames(WeatherTools.CURRENT_WEATHER_TOOL) // 仅传入 Bean 名称.
        .user(userInput)
        .call()
        .content();
}

测试请求：

GET /tool/spring/getWeather?userInput=上海今天热吗？ 

模型会正确解析出地点'上海'，调用 currentWeather 工具，并结合返回温度生成人性化回答。

函数工具的类型限制

以下类型不支持作为函数工具的输入或输出：

• 原始类型（primitive types，如 int, double）
• Optional<T>
• 集合类型（如 List, Map, Set, 数组）
• 异步/响应式类型

✅正确做法是使用 Record 或 POJO 封装参数和返回值，如上文的 WeatherRequest 和 WeatherResponse。

总结对比

最佳实践建议

1. 优先使用 @Bean + Function 模式：便于依赖注入、单元测试和统一管理；
2. 务必填写 description：高质量的描述能显著提升模型选择工具的准确性；
3. 合理命名工具和参数：语义清晰有助于模型理解和推理；
4. 避免副作用过重的操作：工具应尽量保持幂等性和安全性；
5. 记录日志便于调试：观察模型是否准确识别了工具调用时机；
6. 考虑错误处理机制：工具执行失败时应有兜底策略。

结语

Spring AI 对工具调用的抽象极大简化了大模型与现实世界的连接。无论是将已有方法快速暴露为工具，还是构建新的函数式服务，Spring AI 都提供了简洁而强大的支持。

本文使用 @Tool 注解创建了时间工具和闹钟功能，利用 Function + @Bean 构建了可复用的天气查询服务，介绍了工具调用背后的多轮交互机制和常见类型限制陷阱。