Spring AI 工具调用（Tool Calling）详解

一个关键的安全概念

Spring AI 官方文档特别强调：

Even though we typically refer to tool calling as a model capability, it is actually up to the client application to provide the tool calling logic. The model can only request a tool call and provide the input arguments, whereas the application is responsible for executing the tool call. The model never gets access to any of the APIs provided as tools.

翻译：虽然我们说"模型调用工具"，但实际上模型并没有直接访问任何 API 的权限。模型只能"请求"调用工具并提供参数，而真正执行工具的是你的应用程序。

这就像：你的朋友（模型）说"帮我查一下北京天气"，但实际上是你（应用程序）去查的，然后把结果告诉他。模型本身永远不会直接接触你的 API、数据库或任何外部系统——这是一个重要的安全保障。

3. Tool Calling 的工作原理

完整的 6 步流程

┌─────────┐ ┌──────────┐ ┌──────────┐
│ 你的    │ │ Spring   │ │ AI 模型  │
│ 应用    │ │ AI       │ │ (DeepSeek│
│ 程序    │ │ 框架     │ │ /GPT)    │
└────┬────┘ └────┬─────┘ └────┬─────┘
     │           │            │
     │ ① 发送请求 + 工具定义 │
     │ "今天几号？"          │
     │ 工具：getCurrentDateTime() │
     │─────────────────────────────>│ 发送给模型
     │──────────────────────────────>│
     │           │            │
     │ ② 模型决定调用工具 │
     │ "我需要调用 │
     │ getCurrentDateTime()" │
     │<──────────────────────────────│
     │           │            │
     │ ③ 框架执行工具 │
     │ 调用 getCurrentDateTime() │
     │<─────────────────────────────│
     │           │            │
     │ ④ 返回工具结果 │
     │ "2025-02-17T15:30:00" │
     │─────────────────────────────>│
     │           │            │
     │ ⑤ 把结果发给模型 │
     │──────────────────────────────>│
     │           │            │
     │ ⑥ 模型生成最终回答 │
     │ "今天是 2025 年 2 月 17 日" │
     │<──────────────────────────────│
     │           │            │
     │ 返回最终答案 │
     │<─────────────────────────────│
     │           │            │

用文字总结这 6 步

重点：整个过程中，步骤 ③ 和 ④ 是你需要写的代码（定义工具方法），其余步骤 Spring AI 框架自动帮你完成。

4. 快速入门：第一个工具

4.1 信息获取型工具——获取当前时间

AI 模型不知道"现在是几点"，但我们可以写一个工具告诉它：

import java.time.LocalDateTime;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {
    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }
}

代码解读：

• @Tool 注解：告诉 Spring AI'这个方法是一个工具'
• description：告诉 AI 模型"这个工具是干什么的"——这个描述非常重要，模型根据它来判断什么时候该调用这个工具
• 方法体：实际的工具逻辑——返回当前时间

然后在调用时把工具传给模型：

ChatModel chatModel = ...;
String response = ChatClient.create(chatModel)
    .prompt("What day is tomorrow?")
    .tools(new DateTimeTools()) // ← 把工具传给模型
    .call()
    .content();
System.out.println(response); // 输出：Tomorrow is 2025-02-18.

如果不提供工具，同样的问题模型会回答：

I am an AI and do not have access to real-time information. Please provide the current date so I can accurately determine what day tomorrow will be.

4.2 执行动作型工具——设置闹钟

除了获取信息，工具还可以执行操作：

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

class DateTimeTools {
    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }

    @Tool(description = "Set a user alarm for the given time, provided in ISO-8601 format")
    void setAlarm(@ToolParam(description = "Time in ISO-8601 format") String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }
}

调用：

String response = ChatClient.create(chatModel)
    .prompt("Can you set an alarm 10 minutes from now?")
    .tools(new DateTimeTools())
    .call()
    .content();

这个请求会触发模型连续调用两个工具：

1. 先调用 getCurrentDateTime() → 知道现在是几点
2. 再调用 setAlarm("2025-02-17T15:40:00") → 设置 10 分钟后的闹钟

模型自己规划了工具调用顺序——它知道要先获取当前时间，才能计算 10 分钟后是几点。

5. 定义工具的三种方式

Spring AI 提供了三种方式来定义工具，适用于不同场景：

5.1 声明式：@Tool 注解（最常用，推荐）

在方法上加 @Tool 注解，最简单直观：

class DateTimeTools {
    @Tool(description = "Get the current date and time in the user's timezone")
    String getCurrentDateTime() {
        return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
    }
}

@Tool 注解的属性：

关于方法的要求：

• 可以是 public、protected、package-private 或 private
• 可以是静态方法或实例方法
• 参数类型支持：基本类型、POJO、枚举、List、数组、Map 等
• 返回类型支持：大部分类型，包括 void
• 不支持：Optional、CompletableFuture、Mono、Flux 等异步/响应式类型

5.2 编程式：MethodToolCallback（灵活，适合第三方类）

当你无法修改工具类的源码（比如第三方库），或者需要更精细地控制工具定义时，可以使用编程式：

// 工具类（注意：没有 @Tool 注解）
class WeatherTools {
    String getCurrentWeatherByCityName(String cityName) {
        // 查询天气的逻辑
        return "晴天，25°C";
    }
}

// 手动构建 ToolCallback
Method method = ReflectionUtils.findMethod(WeatherTools.class, "getCurrentWeatherByCityName", String.class);
ToolCallback toolCallback = MethodToolCallback.builder()
    .toolDefinition(ToolDefinitions.builder(method).description("根据给定的城市名称，获取城市当前的天气").build())
    .toolMethod(method)
    .toolObject(new WeatherTools())
    .build();

MethodToolCallback.Builder 的关键属性：

5.3 动态式：@Bean + Function（Spring Bean 方式）

把工具定义为 Spring Bean，Spring AI 在运行时自动解析：

// 定义 Function Bean
@Configuration(proxyBeanMethods = false)
class WeatherToolConfig {
    @Bean
    @Description("Get the weather in location")
    Function<WeatherRequest, WeatherResponse> currentWeather() {
        return request -> new WeatherResponse(30.0, Unit.C);
    }
}

// 入参和出参必须是 POJO
public record WeatherRequest(@ToolParam(description = "The name of a city or a country") String location, Unit unit) {}
public record WeatherResponse(double temp, Unit unit) {}
public enum Unit { C, F }

使用时通过工具名称（Bean 名称）来引用：

ChatClient.create(chatModel)
    .prompt("What's the weather like in Copenhagen?")
    .toolNames("currentWeather") // ← 传工具名称，而不是工具对象
    .call()
    .content();

注意事项：

• Bean 名称就是工具名称
• @Description 注解提供工具描述
• 入参和出参必须是 public 的 POJO，不支持基本类型和集合类型
• 这种方式类型安全性较弱（运行时解析）

三种方式对比

6. 工具规范（Tool Specification）

在前面的章节中，我们学习了如何通过 @Tool、MethodToolCallback、@Bean 三种方式来定义工具。这一节深入讲解 Spring AI 工具系统的底层设计——即这些工具在框架内部是如何被描述、组织和转换的。

官方文档的说法：In Spring AI, tools are modeled via the ToolCallback interface.

翻译：在 Spring AI 中，工具通过 ToolCallback 接口进行建模。

6.1 ToolCallback——工具的核心接口

所有工具最终都是一个 ToolCallback。不管你用 @Tool 注解还是手动构建 MethodToolCallback，最终都会变成一个实现了 ToolCallback 接口的对象。

public interface ToolCallback {
    /** 工具定义——告诉模型这个工具叫什么、干什么、参数是什么格式 */
    ToolDefinition getToolDefinition();

    /** 工具元数据——额外配置信息（如 returnDirect） */
    ToolMetadata getToolMetadata();

    /** 执行工具（无上下文） */
    String call(String toolInput);

    /** 执行工具（带上下文） */
    String call(String toolInput, ToolContext toolContext);
}

通俗理解：ToolCallback 就是一个"工具包装盒"，它包含两部分信息：

1. 工具说明书（ToolDefinition）——名字、描述、参数格式，给模型看的
2. 工具本体（call 方法）——实际执行逻辑，给应用程序调用的

Spring AI 提供了两个内置实现：

6.2 ToolDefinition——工具的"说明书"

ToolDefinition 是工具的定义信息，它决定了模型看到的工具长什么样。

public interface ToolDefinition {
    /** 工具名称——在同一次请求中必须唯一 */
    String name();

    /** 工具描述——模型根据这个描述来判断什么时候该用这个工具 */
    String description();

    /** 参数的 JSON Schema——告诉模型参数的格式、类型、约束 */
    String inputSchema();
}

自动生成 vs 手动构建

自动生成：当你使用 @Tool 注解时，Spring AI 会自动从方法签名中提取这三项信息：

@Tool(description = "获取当前时间") // → description
String getCurrentDateTime() { // → name = "getCurrentDateTime"
    ...
} // → inputSchema = {} (无参数)

手动构建：你也可以用 ToolDefinition.Builder 手动指定：

ToolDefinition toolDefinition = ToolDefinition.builder()
    .name("currentWeather")
    .description("Get the weather in location")
    .inputSchema("""
        { "type": "object", "properties": { 
            "location": { "type": "string" }, 
            "unit": { "type": "string", "enum": ["C", "F"] } 
        }, "required": ["location", "unit"] }
        """)
    .build();

从方法自动生成 ToolDefinition

// 方式一：完全自动（使用方法名和 @Tool 注解的信息）
Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolDefinition toolDefinition = ToolDefinitions.from(method);

// 方式二：部分自定义（覆盖名称和描述，但参数 Schema 仍然自动生成）
ToolDefinition toolDefinition = ToolDefinitions.builder(method)
    .name("currentDateTime")
    .description("Get the current date and time in the user's timezone")
    .inputSchema(JsonSchemaGenerator.generateForMethodInput(method))
    .build();

6.3 JSON Schema——模型理解参数的关键

当你给模型提供一个工具时，模型需要知道参数长什么样才能正确调用。Spring AI 通过 JsonSchemaGenerator 类自动为工具参数生成 JSON Schema。

什么是 JSON Schema？

JSON Schema 就是一份"数据格式说明"。比如下面这个工具方法：

@Tool(description = "设置闹钟")
void setAlarm(@ToolParam(description = "ISO-8601 格式的时间") String time) {
    ...
}

Spring AI 会自动生成这样的 JSON Schema：

{
  "type": "object",
  "properties": {
    "time": {
      "type": "string",
      "description": "ISO-8601 格式的时间"
    }
  },
  "required": ["time"]
}

模型看到这个 Schema 后就知道：调用 setAlarm 需要传一个 time 参数，类型是字符串，格式应该是 ISO-8601。

JSON Schema 的生成规则

描述参数的四种注解

你可以用以下注解来为参数添加描述（优先级从高到低）：

标记可选参数的四种注解

默认所有参数都是必填（required），用以下注解可标记为可选（优先级从高到低）：

这些注解支持递归——如果你的参数是一个嵌套的 POJO，内层字段也可以用这些注解来描述。

6.4 Result Conversion——工具结果的转换

工具执行完毕后，结果需要转换成字符串才能发回给模型。Spring AI 通过 ToolCallResultConverter 接口来处理这个转换。

@FunctionalInterface
public interface ToolCallResultConverter {
    /** 将工具返回的对象转换为字符串 */
    String convert(@Nullable Object result, @Nullable Type returnType);
}

默认行为

默认使用 DefaultToolCallResultConverter，它会把结果序列化为 JSON 字符串（通过 Jackson）。

// 你的工具方法返回一个对象
@Tool(description = "查询客户信息")
Customer getCustomerInfo(Long id) {
    return new Customer(42L, "张三", "[email protected]");
}

// 默认转换结果（JSON 字符串）：
// {"id": 42, "name": "张三", "email": "[email protected]"}
// 这个 JSON 字符串会被发回给模型

自定义结果转换器

如果默认的 JSON 转换不满足需求（比如你想返回 XML 格式、或者只返回部分字段），可以自定义：

// 自定义转换器
public class SimpleCustomerConverter implements ToolCallResultConverter {
    @Override
    public String convert(Object result, Type returnType) {
        if (result instanceof Customer c) {
            return "客户姓名：" + c.getName() + "，邮箱：" + c.getEmail();
        }
        return result.toString();
    }
}

// 在 @Tool 注解中指定
@Tool(description = "查询客户信息", resultConverter = SimpleCustomerConverter.class)
Customer getCustomerInfo(Long id) {
    return customerRepository.findById(id);
}

什么时候需要自定义？

6.5 工具规范的整体结构图

ToolCallback（工具的完整表示）
┌──────────────────────────────┐
│                              │
├───────────────┤ getToolDefinition() │
│               │ → 工具的"说明书"    │
│               │                    │
├────────────┤ getToolMetadata() │
│               │ → 额外配置（returnDirect 等） │
│               │                    │
│               │                    │
│               │ call(input)         │
│               │ call(input, context)│
│               │ → 实际执行工具      │
│               └──────────────────────────────┘
│                              │
│                              │ ToolMetadata
│                              │ ┌──────────────────┐
│                              │ └───────────→│ returnDirect │ 是否直接返回结果给用户
│                              │ └──────────────────┘
│                              │
│                              │ ToolDefinition（给模型看的）
│                              │ ┌──────────────────┐
│                              │ └──────────────→│ name() │ 工具名称
│                              │                 │ description() │ 工具描述
│                              │                 │ inputSchema() │ 参数的 JSON Schema
│                              │ └──────────────────┘
│                              │ JsonSchemaGenerator 自动从方法签名生成
│                              │ 工具执行后 ──→ ToolCallResultConverter ──→ 字符串结果 ──→ 发回模型

7. 使用工具的两种 API

定义好工具后，你可以通过 ChatClient 或 ChatModel 来使用它们。

7.1 通过 ChatClient（推荐，更高层抽象）

声明式工具（@Tool）

// 单次请求中使用
ChatClient.create(chatModel)
    .prompt("What day is tomorrow?")
    .tools(new DateTimeTools()) // ← 传工具类实例
    .call()
    .content();

编程式工具（MethodToolCallback）

ToolCallback toolCallback = ...; // 前面构建的
ChatClient.create(chatModel)
    .prompt("What day is tomorrow?")
    .toolCallbacks(toolCallback) // ← 传 ToolCallback 对象
    .call()
    .content();

动态式工具（@Bean）

ChatClient.create(chatModel)
    .prompt("What's the weather like in Copenhagen?")
    .toolNames("currentWeather") // ← 传工具名称（Bean 名称）
    .call()
    .content();

设置默认工具

如果每次请求都需要同一组工具，可以设置为默认：

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(new DateTimeTools()) // 声明式默认工具
    // .defaultToolCallbacks(toolCallback) // 编程式默认工具
    // .defaultToolNames("currentWeather") // 动态式默认工具
    .build();

// 之后每次请求自动带上工具，不用再手动传
chatClient.prompt("What day is tomorrow?").call().content();

注意：如果同时设置了默认工具和请求级工具，请求级工具会完全覆盖默认工具（不是合并）。

7.2 通过 ChatModel（更底层）

// 声明式
ToolCallback[] dateTimeTools = ToolCallbacks.from(new DateTimeTools());
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(dateTimeTools)
    .build();
Prompt prompt = new Prompt("What day is tomorrow?", chatOptions);
chatModel.call(prompt);

// 动态式
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolNames("currentWeather")
    .build();
Prompt prompt = new Prompt("What's the weather?", chatOptions);
chatModel.call(prompt);

ChatClient vs ChatModel 使用工具时的区别

8. @ToolParam——告诉模型参数怎么填

当工具方法有参数时，你需要告诉模型每个参数的含义。@ToolParam 注解就是干这个的。

基本用法

class DateTimeTools {
    @Tool(description = "Set a user alarm for the given time")
    void setAlarm(@ToolParam(description = "Time in ISO-8601 format") String time) {
        LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
        System.out.println("Alarm set for " + alarmTime);
    }
}

@ToolParam 的属性：

可选参数

默认情况下，所有参数都是必填的。如果某个参数是可选的：

class CustomerTools {
    @Tool(description = "Update customer information")
    void updateCustomerInfo(Long id, String name, @ToolParam(required = false) String email // ← 可选参数
    ) {
        System.out.println("Updated info for customer with id: " + id);
    }
}

你也可以用 @Nullable 标注来表示可选：

void updateCustomerInfo(Long id, String name, @Nullable String email) {
    ...
}

参数描述的替代注解

除了 @ToolParam，还可以使用：

为什么参数描述很重要？

模型在决定如何调用工具时，完全依赖你提供的工具描述和参数描述。如果描述不清楚，模型可能：

• 不该调用工具时却调用了
• 该调用工具时没调用
• 传了错误格式的参数

建议：工具描述和参数描述要写得尽量详细和准确。不要写"时间"，要写"Time in ISO-8601 format, e.g. 2025-02-17T15:30:00"。

9. ToolContext——给工具传递额外上下文

什么场景需要？

有时候，工具需要一些模型不知道的信息——比如当前登录用户的 ID、租户标识等。这些信息不应该让模型来提供（模型也提供不了），而是由你的应用程序传递。

用法

工具方法中声明 ToolContext 参数：

class CustomerTools {
    @Tool(description = "Retrieve customer information")
    Customer getCustomerInfo(Long id, ToolContext toolContext) {
        // 从 ToolContext 中获取租户 ID（这个信息是应用程序传的，不是模型传的）
        String tenantId = toolContext.getContext().get("tenantId");
        return customerRepository.findById(id, tenantId);
    }
}

调用时通过 .toolContext() 传入上下文数据：

// 通过 ChatClient
String response = ChatClient.create(chatModel)
    .prompt("Tell me more about the customer with ID 42")
    .tools(new CustomerTools())
    .toolContext(Map.of("tenantId", "acme")) // ← 传入上下文
    .call()
    .content();

// 通过 ChatModel
ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(ToolCallbacks.from(new CustomerTools()))
    .toolContext(Map.of("tenantId", "acme")) // ← 传入上下文
    .build();
Prompt prompt = new Prompt("Tell me about customer 42", chatOptions);
chatModel.call(prompt);

重要注意事项

⚠️ 如果你的工具方法声明了 ToolContext 参数，调用时就必须通过 .toolContext() 提供上下文数据，否则会报错：

java.lang.IllegalArgumentException: ToolContext is required by the method as an argument

这正是你之前遇到的那个错误！如果你的工具方法不需要额外上下文，就不要声明 ToolContext 参数。

10. returnDirect——工具结果直接返回给用户

默认行为

默认情况下，工具的执行结果会先发回给模型，让模型基于结果生成最终回答：

用户 → 模型 → 调用工具 → 工具结果 → 回传给模型 → 模型生成回答 → 用户

什么时候需要 returnDirect？

有些场景你不需要模型再"加工"工具结果，想直接把结果返回给用户：

• RAG 场景：工具检索到的文档直接返回，不需要模型再处理
• 终止推理循环：工具执行后就结束对话，不需要模型继续思考

用法

class CustomerTools {
    @Tool(description = "Retrieve customer information", returnDirect = true) // ← 直接返回
    Customer getCustomerInfo(Long id) {
        return customerRepository.findById(id);
    }
}

设置 returnDirect = true 后，工具结果跳过模型，直接返回给调用方。

11. 工具执行的两种模式

11.1 框架控制模式（默认）

这是默认行为——Spring AI 框架自动处理一切：

① 你发请求 + 工具定义
② 模型返回工具调用请求
③ 框架自动执行工具 ← 自动的
④ 框架把结果发回模型 ← 自动的
⑤ 模型生成最终回答

你只需要写工具方法，其他的 Spring AI 全部帮你搞定。大多数场景用这个就够了。

11.2 用户控制模式

如果你需要在工具执行的过程中插入自定义逻辑（比如审批、日志、人工确认），可以关闭框架自动执行：

ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(new CustomerTools())
    .internalToolExecutionEnabled(false) // ← 关闭自动执行
    .build();
Prompt prompt = new Prompt("Tell me about customer 42", chatOptions);
ChatResponse chatResponse = chatModel.call(prompt);

// 手动控制工具执行循环
ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();
while (chatResponse.hasToolCalls()) {
    // 你可以在这里加日志、审批、过滤等自定义逻辑
    System.out.println("模型请求调用工具，正在执行...");
    ToolExecutionResult toolExecutionResult = toolCallingManager.executeToolCalls(prompt, chatResponse);
    prompt = new Prompt(toolExecutionResult.conversationHistory(), chatOptions);
    chatResponse = chatModel.call(prompt);
}
System.out.println(chatResponse.getResult().getOutput().getText());

12. 异常处理

工具执行失败怎么办？

当工具方法抛出异常时，Spring AI 通过 ToolExecutionExceptionProcessor 来处理。默认行为：

• RuntimeException：将错误信息发送回模型，让模型基于错误信息继续对话
• 检查异常和 Error（如 IOException、OutOfMemoryError）：直接抛出，由调用方处理

配置异常处理行为

通过配置文件：

# application.yml
spring:
  ai:
    tools:
      throw-exception-on-error: true # true: 所有异常都抛出; false(默认): RuntimeException 发回模型

或者自定义 Bean：

@Bean
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
    return new DefaultToolExecutionExceptionProcessor(true); // true = 始终抛出异常
}

什么时候选哪种？

13. 工具解析（Tool Resolution）

前面我们学的都是手动传工具——通过 .tools(new XxxTools()) 或 .toolCallbacks(callback) 把工具传给 ChatClient。但 Spring AI 还支持另一种方式：通过工具名称动态解析。

13.1 什么是工具解析？

工具解析就是：你只告诉 Spring AI 工具的名字，框架会自动根据名字找到对应的 ToolCallback。

// 不传工具对象，只传工具名称
chatClient.prompt("今天天气如何？")
    .toolNames("currentWeather") // ← 只传名称
    .call()
    .content();

Spring AI 会在运行时通过 ToolCallbackResolver 接口来解析这个名称，找到对应的工具。

13.2 ToolCallbackResolver 接口

public interface ToolCallbackResolver {
    /** 根据工具名称解析出对应的 ToolCallback */
    @Nullable
    ToolCallback resolve(String toolName);
}

13.3 默认的解析策略

Spring AI 默认使用 DelegatingToolCallbackResolver，它委托给两个子解析器：

DelegatingToolCallbackResolver
├── SpringBeanToolCallbackResolver
│   → 从 Spring 容器中查找 Function/Supplier/Consumer/BiFunction 类型的 Bean
│   → 对应 @Bean + Function 动态式工具
└── StaticToolCallbackResolver
    → 从静态的 ToolCallback 列表中查找
    → 自动收集应用上下文中所有 ToolCallback 类型的 Bean

13.4 使用场景

13.5 自定义工具解析器

如果默认的解析策略不满足需求，你可以自定义：

@Bean
ToolCallbackResolver toolCallbackResolver(List<FunctionCallback> toolCallbacks) {
    StaticToolCallbackResolver staticResolver = new StaticToolCallbackResolver(toolCallbacks);
    return new DelegatingToolCallbackResolver(List.of(staticResolver));
}

总结：工具解析是 toolNames() 方式的底层支撑。大多数场景下你不需要关心它——直接 .tools(new XxxTools()) 手动传就够了。当你使用 @Bean 动态式工具或需要运行时动态注册工具时，才会用到工具解析机制。

14. 实战案例：天气查询工具

以你的项目代码为例，完整演示从工具定义到调用的全过程。

场景

用户问"北京今天天气怎么样？"，我们提供一个天气查询工具让模型调用。

方式一：声明式（@Tool）

定义工具：

public class WeatherTools {
    @Tool(description = "根据给定的城市名称，获取城市当前的天气")
    String getCurrentWeatherByCityName(@ToolParam(description = "城市名称，例如：北京、上海、广州") String cityName) {
        switch (cityName) {
            case "北京": return "北京今天天气：晴空万里";
            case "上海": return "上海今天天气：电闪雷鸣";
            case "广州": return "广州今天天气：细雨蒙蒙";
            default: return "没有该城市的天气信息";
        }
    }
}

在 ChatClient 中使用：

@RequestMapping("/chat")
@RestController
public class ChatController {
    private ChatClient chatClient;

    public ChatController(DashScopeChatModel chatModel) {
        this.chatClient = ChatClient.builder(chatModel).build();
    }

    @RequestMapping("/call")
    public String call(String message) {
        return chatClient.prompt()
            .user(message)
            .tools(new WeatherTools()) // ← 声明式，传工具类实例
            .call()
            .content();
    }
}

方式二：编程式（MethodToolCallback）

当 WeatherTools 类上没有 @Tool 注解时，用编程式构建：

@RequestMapping("/call2")
public String call2(String message) {
    // 1. 通过反射获取方法
    Method method = ReflectionUtils.findMethod(WeatherTools.class, "getCurrentWeatherByCityName", String.class);

    // 2. 手动构建 ToolCallback
    ToolCallback toolCallback = MethodToolCallback.builder()
        .toolDefinition(ToolDefinitions.builder(method).description("根据给定的城市名称，获取城市当前的天气").build())
        .toolMethod(method)
        .toolObject(new WeatherTools())
        .build();

    // 3. 传给 ChatClient
    return chatClient.prompt()
        .user(message)
        .toolCallbacks(toolCallback) // ← 编程式，传 ToolCallback 对象
        .call()
        .content();
}

方式三：通过 ChatModel + ToolCallingChatOptions

@RequestMapping("/callByTool")
public String callByTool(String message) {
    // 1. 从工具类生成 ToolCallback 数组
    ToolCallback[] weatherTools = ToolCallbacks.from(new WeatherTools());

    // 2. 构建 ChatOptions
    ChatOptions chatOptions = ToolCallingChatOptions.builder()
        .toolCallbacks(weatherTools)
        .build();

    // 3. 构建 Prompt 并调用
    Prompt prompt = new Prompt(message, chatOptions);
    return chatModel.call(prompt).getResult().getOutput().getText();
}

15. 常见问题与排坑

问题一：ToolContext is required by the method as an argument

报错信息：

java.lang.IllegalArgumentException: ToolContext is required by the method as an argument

原因：工具方法声明了 ToolContext 参数，但调用时没有通过 .toolContext() 提供上下文数据。

解决方案：

// 方案 A：如果不需要 ToolContext，从方法参数中移除它
@Tool(description = "Get current time")
String getCurrentDateTime() {
    // ← 没有 ToolContext 参数
    return LocalDateTime.now().toString();
}

// 方案 B：如果需要 ToolContext，调用时提供它
chatClient.prompt()
    .user(message)
    .tools(new MyTools())
    .toolContext(Map.of("key", "value")) // ← 提供 ToolContext
    .call()
    .content();

问题二：模型不调用工具

可能原因：

1. 工具描述不够清楚 — 模型不知道什么时候该用这个工具
2. 用户的问题和工具描述不匹配 — 模型判断不需要这个工具
3. 模型不支持工具调用 — 有些小模型不支持 function calling

解决方案：

• 优化 @Tool(description = "...") 的描述，写得更具体
• 确认你使用的模型支持工具调用（如 DeepSeek、GPT-4、通义千问等）

问题三：同名工具冲突

规则：同一次请求中，工具名称必须唯一。如果你传了两个同名的工具，会报错。

// ❌ 错误：两个类中都有 getCurrentDateTime 方法
chatClient.prompt()
    .tools(new DateTimeTools(), new AnotherDateTimeTools())
    // 可能同名冲突
    .call()
    .content();

解决方案：通过 @Tool(name = "customName") 给工具取不同的名字。

问题四：默认工具 vs 请求级工具

重要规则：如果同时设置了默认工具和请求级工具，请求级工具会完全覆盖默认工具，不是合并！

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(new DateTimeTools()) // 默认工具
    .build();

// 这次请求只有 WeatherTools，DateTimeTools 被覆盖了！
chatClient.prompt()
    .tools(new WeatherTools()) // 请求级工具覆盖默认工具
    .call()
    .content();

如果你两个都需要，就在请求级工具中一起传。

问题五：方法的参数类型不支持

Method as Tool 不支持的类型：

• Optional
• CompletableFuture、Future
• Mono、Flux（响应式类型）
• Function、Supplier、Consumer（函数式类型）

Function as Tool（@Bean 方式）不支持的类型：

• 基本类型（int、String 等，必须包装成 POJO）
• 集合类型（List、Map、Set 等）

16. 总结

核心概念速查表

选择工具定义方式的决策树

你能修改工具类的源码吗？
├── 能 → 用 @Tool 注解（声明式）✅ 推荐
└── 不能 → 工具方法的参数是 POJO 吗？
    ├── 是 → 用 @Bean + Function（动态式）
    └── 不是 → 用 MethodToolCallback（编程式）

一句话总结

Tool Calling = 给大模型装上"手和脚"。你定义工具（写 Java 方法），模型决定何时调用（基于工具描述），Spring AI 负责串联整个流程（自动执行工具、传递结果）。三者分工明确，各司其职。

17. 参考资料

官方文档

• Spring AI - Tool Calling
• Spring AI - Tool Calling Observability
• Spring AI - FunctionCallback to ToolCallback Migration

相关博客

• Spring AI 官方示例 - Tool Calling
• DashScope 模型工具调用文档