Spring AI Alibaba（五）外部工具集成

一、引言

Spring AI Alibaba 提供了丰富的 外部工具集成能力 ，涵盖高德地图、百度翻译、天气查询、快递追踪等 40+ 插件 。这些工具通过 spring-ai-alibaba-starter-tool-calling-* 系列包实现，开发者可快速对接第三方服务，构建功能完备的智能体应用。本文以高德地图天气服务为例，详解工具集成流程及底层实现原理。

---

二、快速集成高德地图天气服务

1. 引入依赖包

在 pom.xml 中添加高德地图工具包：

<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-tool-calling-amap</artifactId>
</dependency>

说明 ：

• 该依赖包含高德天气服务的自动配置类、属性类及工具实现类。
• 建议通过 spring-ai-alibaba-bom 统一管理版本，避免兼容性问题 。

---

2. 申请 API Key 并配置

1. 获取 API Key ：
   登录 高德开放平台，在“我的应用”中创建项目并获取天气服务 API Key 。
2. 配置参数 ：

spring.ai.alibaba.toolcalling.amap.enabled=true
spring.ai.alibaba.toolcalling.amap.api-key=your_api_key

关键点 ：

• enabled 控制工具是否启用，避免未配置时启动失败。
• API Key 需妥善保管，建议通过密钥管理服务加密存储。

---

3. 工具实现类与注解绑定

（1）服务实现类 WeatherSearchService

该类实现 Function<WeatherRequest, WeatherResponse> 接口，并通过 @Description 注解绑定工具名称与描述 ：

@Description(value = "gaoDeGetAddressWeather", description = "获取指定地址的天气信息")
public class WeatherSearchService implements Function<WeatherRequest, WeatherResponse> {
    private final AmapProperties amapProperties;
    private final WebClient webClient;

    public WeatherSearchService(AmapProperties amapProperties, WebClient webClient) {
        this.amapProperties = amapProperties;
        this.webClient = webClient;
    }

    @Override
    public WeatherResponse apply(WeatherRequest request) {
        String city = request.getAddress();
        String url = "https://restapi.amap.com/v3/weather/weatherInfo?city={city}&key={apiKey}";
        return webClient.get()
        .uri(url, city, amapProperties.getApiKey())
        .retrieve()
        .bodyToMono(WeatherResponse.class)
        .block();
    }
}

核心逻辑 ：

• 调用高德天气 API（/v3/weather/weatherInfo），传入城市编码（city）和 API Key 。
• 使用 WebClient 发起 HTTP 请求并解析响应数据。

（2）属性类 AmapProperties

加载配置文件中的参数：

@ConfigurationProperties("spring.ai.alibaba.toolcalling.amap")
public class AmapProperties {
    private boolean enabled;
    private String apiKey;
    // Getter/Setter
}

（3）自动配置类 AmapAutoConfiguration

注册 WeatherSearchService 为 Bean：

@Configuration
public class AmapAutoConfiguration {
    @Bean
    public WeatherSearchService weatherSearchService(AmapProperties properties, WebClient webClient) {
        return new WeatherSearchService(properties, webClient);
    }
}

---

4. 工具调用流程

（1）声明工具名称并触发调用

在 Controller 中通过 toolNames("gaoDeGetAddressWeather") 指定工具名称：

@GetMapping("/tool")
public String tool(String input) {
    return chatClient.prompt()
        .toolNames("gaoDeGetAddressWeather") // 工具名称匹配 @Description.value
        .user(input)
        .call()
        .content();
}

（2）底层匹配机制

• 名称绑定 ：Spring AI Alibaba 在启动时扫描所有带有 @Description 注解的 Bean，建立工具名称到 Function 实现类的映射表。
• 参数传递 ：用户输入的内容（如地址）会被解析为 WeatherRequest 对象，并传递给 apply() 方法

---

5. 高德天气 API 的调用细节

（1）API 接口与参数

• 接口地址 ：https://restapi.amap.com/v3/weather/weatherInfo
• 必填参数 ：

• • city：城市编码（adcode），如北京为 110101。
  • key：高德开放平台申请的 API Key 。

• 返回格式 ：JSON，包含实时天气、温度、湿度等信息。

（2）请求示例

GET https://restapi.amap.com/v3/weather/weatherInfo?city=110101&key=your_api_key

响应示例 ：

{
  "lives": [
    {
      "province": "北京",
      "city": "北京",
      "weather": "晴",
      "temperature": "25",
      "winddirection": "西风",
      "windpower": "≤3",
      "humidity": "60"
    }
  ]
}

---

三、工具集成源码解析

1. 核心组件结构

以 spring-ai-alibaba-starter-tool-calling-amap 为例，其核心类包括：

AmapAutoConfiguration	自动配置类，注册WeatherSearchServiceBean，并通过@Description注解声明工具描述。
AmapProperties	属性类，加载spring.ai.alibaba.toolcalling.amap.*配置项。
WeatherSearchService	实现Function接口，封装高德天气 API 调用逻辑，包含以下功能：
-apply()方法	调用WebClientTool发起 HTTP 请求，获取天气数据。
- 参数类定义	声明请求参数（如城市名），并通过@Description注解描述参数用途。

---

2. 自定义工具开发指南

开发者可仿照上述结构实现自定义工具：

1. 定义 Function 实现类 ：

public class MyCustomTool implements Function<Request, Response> {
    @Override
    public Response apply(Request request) {
        // 实现业务逻辑
    }
}

1. 注册为 Bean ：

@Bean
public MyCustomTool myCustomTool() {
    return new MyCustomTool();
}

1. 调用工具 ：

chatClient.prompt().toolNames("myCustomTool").user("...").call();

---

四、总结

Spring AI Alibaba 通过模块化设计实现了灵活的外部工具集成能力。开发者只需遵循依赖引入、配置声明、工具调用三步流程，即可快速对接高德地图、天气服务等 40+ 插件。通过源码分析还可发现，其底层基于 Function 接口和自动配置机制，为自定义工具开发提供了清晰的扩展路径。未来可进一步探索多工具协同调用、异步执行等高级特性，构建更智能的企业级 AI 应用 。