Spring AI Tool 机制详解：让大模型调用外部工具

这个循环可能执行多次。如果大模型在看到工具结果后，认为需要调用另一个工具来进一步优化答案，就会继续发起新的 Tool Call，形成一个完整的 Agent 执行流程。

2.2 Tool Calling 的三大关键元素

一个完整的 Tool Calling 系统包含三个关键要素：

其中，参数描述的质量直接决定了大模型能否正确调用工具。如果参数描述不清楚，大模型可能会传递错误的参数值，导致工具执行失败。

三、工具定义：@Tool 注解的使用

3.1 基础工具定义

在 Spring AI 中，使用 @Tool 注解来标记一个可被大模型调用的方法：

@Component
public class ArtisanTools {
    @Tool(description = "获取当前时间")
    LocalDateTime getCurrentDateTime() {
        System.out.println("获取当前时间");
        return LocalDateTime.now();
    }

    @Tool(description = "用指定时间设置闹钟")
    void setAlarm(AlarmRequest alarmRequest) {
        System.out.println("地址：" + alarmRequest.getAddress());
        System.out.println("闹钟时间为：" + alarmRequest.getTime());
    }
}

关键要点：

1. @Component 注解： 必须将工具类注册为 Spring Bean，这样 Spring AI 才能发现和管理它。
2. @Tool 注解： 标记哪些方法是可被大模型调用的工具。
3. description 参数： 这是非常关键的！它用自然语言描述工具的功能。大模型会根据这个描述来决定是否调用该工具。

3.2 Description 的重要性

让我们通过对比来理解 description 为什么关键：

不好的 description 示例：

@Tool(description = "工具") // ❌ 太模糊，大模型不知道这是什么工具
@Tool(description = "调用方法") // ❌ 没有说明具体功能

好的 description 示例：

@Tool(description = "获取当前系统时间，返回格式为 LocalDateTime") // ✅ 清晰、具体
@Tool(description = "根据指定的日期和地点设置闹钟，闹钟会在指定时间触发提醒") // ✅ 详细说明功能和效果

实战技巧：

当你编写 description 时，想象你在向一个助手说话：

• 说清楚 做什么：获取时间、设置闹钟、查询数据库
• 说清楚 返回什么：时间对象、设置成功、查询结果
• 如果有特殊说明，加上去：格式要求、范围限制、副作用

@Tool(description = "获取指定日期的天气预报。返回温度、风力、降雨概率等信息。" +
                    "如果日期超过 7 天，只能返回预测数据，准确度降低。")
WeatherInfo getWeather(String date) { /* ... */ }

四、参数描述：两种方式的区别与选择

工具方法可能需要参数，问题是：如何清楚地告诉大模型这些参数是什么含义？

Spring AI 提供了两种参数描述的方式，它们各有特点：

4.1 方式一：@JsonPropertyDescription（推荐）

public class AlarmRequest {
    @JsonPropertyDescription("用中文中的年月日的格式，比如 2025 年 3 月 31 日")
    private String time;

    @JsonPropertyDescription("闹钟要设置的位置，比如卧室、客厅")
    private String address;

    // getter/setter...
}

特点与优势：

1. Jackson 标准注解： @JsonPropertyDescription 是 Jackson 库提供的标准注解，用于 JSON Schema 描述。
2. 更灵活的描述方式： 可以包含格式示例、取值范围、特殊说明等详细信息。
3. 直观易读： 描述直接关联到字段定义。
4. 最佳实践选择： 在生产环境中广泛使用。

适用场景：

• 复杂的参数类，有多个字段需要描述
• 需要提供详细的格式示例
• 字段有特殊的输入格式要求

4.2 方式二：@ToolParam（备选方案）

public class AlarmRequest {
    // @ToolParam(description = "时间") // ❌ 这样写不推荐
    private String time;

    @ToolParam(description = "地址", required = false)
    private String address;

    // 标记为可选字段
    // getter/setter...
}

特点：

1. Spring AI 原生注解： 专为 Spring AI Tool Calling 而设计。
2. 支持 required 属性： 可以标记字段是否必需。
3. 针对性强： 完全针对 Tool Calling 场景。

使用建议：

public class AlarmRequest {
    @JsonPropertyDescription("用中文中的年月日的格式，比如 2025 年 3 月 31 日")
    private String time; // 必需字段，用 @JsonPropertyDescription

    @ToolParam(description = "地址", required = false)
    private String address; // 可选字段，用 @ToolParam 标记 required=false

    // getter/setter...
}

4.3 两种方式的对比与最佳实践

最佳实践方案：

public class AlarmRequest {
    /**
     * 优先使用 @JsonPropertyDescription 进行主要描述
     * 可以提供详细的格式示例和说明
     */
    @JsonPropertyDescription("用中文中的年月日的格式，比如 2025 年 3 月 31 日。例如：2025 年 3 月 31 日")
    private String time;

    /**
     * 对于可选字段，配合 @ToolParam(required = false)
     * 两者结合，既有详细描述，又有必需性标记
     */
    @JsonPropertyDescription("闹钟要设置的位置，比如卧室、客厅、办公室等")
    @ToolParam(required = false)
    private String address;

    public String getTime() { return time; }
    public void setTime(String time) { this.time = time; }
    public String getAddress() { return address; }
    public void setAddress(String address) { this.address = address; }
}

参数描述写作指南：

❌ 不好的例子：

"时间" // 太简洁，大模型不知道格式
"address" // 中英混用，可读性差
"参数 1、参数 2、参数 3" // 没有实际信息

✅ 好的例子：

"设置闹钟的时间，格式为中文年月日，例如：2025 年 3 月 31 日"
"闹钟要设置的位置，可选值包括：卧室、客厅、办公室、车内等"
"查询的日期范围，格式为 YYYY-MM-DD，最多查询未来 30 天的数据"

五、自动执行模式：让大模型自主调用工具

Spring AI 提供了最简洁的工具调用方式：自动执行模式。在这个模式下，框架自动处理整个 Tool Calling 流程。

5.1 自动执行模式的实现

@RestController
public class ToolController {
    @Autowired
    private ChatClient chatClient;

    @Autowired
    private ArtisanTools artisanTools;

    /**
     * 自动执行模式：最简洁的方式
     * 用户提问 -> 大模型决定调用工具 -> 框架自动执行工具 -> 大模型生成回答 -> 返回结果
     */
    @GetMapping("/tool")
    public String tool(String question) {
        return chatClient
                .prompt()
                .user(question)
                .tools(ArtisanTools) // ← 关键：传入工具对象
                .call()
                .content();
    }
}

执行流程解析：

chatClient.prompt()      // 1. 创建 Prompt 构建器
.user(question)          // 2. 设置用户问题
.tools(ArtisanTools)     // 3. 注册可用工具
.call()                  // 4. 发起调用，框架自动处理 Tool Calling 循环
.content()               // 5. 提取最终文本结果

5.2 自动执行模式的工作原理

让我们用一个具体的例子来追踪这个过程：

用户输入："帮我设置一个明天上午 10 点的闹钟"

幕后执行过程：

┌─ 第 1 轮 ─────────────────────────────────────────┐
│ ChatClient 构造 Prompt：                          │
│ - System: (系统提示词)                            │
│ - User: "帮我设置一个明天上午 10 点的闹钟"       │
│ - Tools: [getCurrentDateTime, setAlarm]         │
│                                                 │
│ 发送给大模型，大模型返回：                        │
│ {
│   "toolCalls": [{                               │
│     "toolName": "setAlarm",                     │
│     "arguments": {                              │
│       "time": "2025 年 3 月 31 日",              │
│       "address": null                           │
│     }                                            │
│   }]                                             │
│ }
│ ✓ 有 Tool Call，继续执行                         │
└────────────────────────────────────────────────┘
┌─ 第 2 轮：框架自动执行工具 ──────────────────────┐
│ 框架识别到 Tool Call，执行：                      │
│ ArtisanTools.setAlarm(                          │
│   AlarmRequest{time: "2025 年 3 月 31 日", ...} │
│ )                                               │
│                                                 │
│ 工具执行成功，返回结果                            │
│ 框架将结果加入 Prompt，再次调用大模型            │
│                                                 │
│ 大模型返回：                                      │
│ {
│   "text": "已为您设置好了明天上午 10 点...",   │
│   "toolCalls": []                              │
│ }
│ ✓ 没有更多 Tool Call，停止循环                   │
└────────────────────────────────────────────────┘
┌─ 最终结果 ──────────────────────────────────────┐
│ "已为您设置好了明天上午 10 点的闹钟"           │
└────────────────────────────────────────────────┘

5.3 自动执行模式的优势与局限

优势：

• ✅ 代码最简洁： 只需一行 .tools(ArtisanTools) 就完成了整个工具调用流程
• ✅ 框架自动处理循环： 无需手动管理 Tool Call 的循环执行
• ✅ 适合大多数场景： 绝大部分的工具调用都可以用这种方式完成

局限：

• ❌ 无法精细控制： 如果你需要在工具执行后做特殊处理（比如持久化、审核、日志），就无法实现
• ❌ 工具执行同步： 所有工具执行都是同步的，不支持异步并发执行
• ❌ 无法中断循环： 如果大模型陷入了无限的 Tool Call 循环，框架会继续执行直到超时

适用场景：

// ✅ 适合自动执行模式
@GetMapping("/simple-tool-call")
public String simpleToolCall(String question) {
    // 简单的、无需特殊处理的工具调用
    return chatClient.prompt().user(question).tools(ArtisanTools).call().content();
}

// ❌ 不适合自动执行模式（需要手动控制模式）
@GetMapping("/complex-tool-call")
public String complexToolCall(String question) {
    // 需要在工具执行后进行特殊处理：
    // 1. 持久化工具调用记录
    // 2. 对工具结果进行验证
    // 3. 控制 Tool Call 的最大次数
    // 4. 在特定条件下中断 Tool Call 循环
    // -> 这些场景需要使用"手动控制模式"
}

六、手动控制模式：精细化控制 Tool Calling

当需要对工具调用流程进行精细控制时，就应该使用手动控制模式。这个模式给予开发者对 Tool Calling 流程的完全掌控权。

6.1 手动控制模式的实现

@RestController
public class ToolController {
    @Autowired
    private ChatClient chatClient;

    /**
     * 手动控制模式：对工具调用过程进行细粒度控制
     */
    @GetMapping("/userControlledTool")
    public String userControlledTool(String question) {
        // 步骤 1：将工具转换为 ToolCallback 数组
        ToolCallback[] toolCallbacks = ToolCallbacks.from(new ArtisanTools());

        // 步骤 2：创建工具调用选项，禁用框架自动执行
        ToolCallingChatOptions toolCallingChatOptions = ToolCallingChatOptions.builder()
                .toolCallbacks(toolCallbacks)
                .internalToolExecutionEnabled(false) // ← 关键：禁用自动执行
                .build();

        // 步骤 3：创建 Prompt，设置工具选项
        Prompt prompt = Prompt.builder()
                .chatOptions(toolCallingChatOptions)
                .content(question)
                .build();

        // 步骤 4：首次调用大模型，获取 Tool Call 信息
        ChatResponse chatResponse = chatClient.prompt(prompt).call().chatResponse();

        // 步骤 5：创建 ToolCallingManager，手动执行工具
        ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();

        // 步骤 6：循环执行 Tool Calling
        while (chatResponse.hasToolCalls()) {
            // 步骤 6.1：执行工具，获取结果
            ToolExecutionResult toolExecutionResult = toolCallingManager
                    .executeToolCalls(prompt, chatResponse);

            // 步骤 6.2：将工具结果反馈给大模型，获取新的响应
            chatResponse = chatClient.prompt(new Prompt(
                    toolExecutionResult.conversationHistory(), // 更新对话历史
                    toolCallingChatOptions
            )).call().chatResponse();
        }

        // 步骤 7：返回最终的文本结果
        return chatResponse.getResult().getOutput().getText();
    }
}

6.2 手动控制模式的核心概念

关键配置详解：

// internalToolExecutionEnabled = false 的含义
ToolCallingChatOptions toolCallingChatOptions = ToolCallingChatOptions.builder()
        .toolCallbacks(toolCallbacks)
        .internalToolExecutionEnabled(false) // false: 框架不自动执行工具
                                             // true: 框架自动执行工具（默认）
        .build();

ToolCallingManager 的职责：

ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();
// 执行工具，返回结果
ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, chatResponse);
// ToolExecutionResult 包含：
// 1. conversationHistory: 更新后的对话历史（工具调用 + 执行结果）
// 2. 工具执行的所有中间结果

对话历史的作用：

初始 Prompt:
[User:"设置闹钟"]
↓ 第 1 轮调用大模型后
对话历史：
[User:"设置闹钟", Assistant:ToolCall->{toolName:"setAlarm", arguments:{...}}]
↓ ToolCallingManager.executeToolCalls() 后
对话历史更新为：
[User:"设置闹钟", Assistant:ToolCall->{toolName:"setAlarm", arguments:{...}}, ToolResult:"闹钟已设置",]
↓ 将更新后的对话历史再次发送给大模型
大模型基于完整的对话历史生成最终答案

6.3 手动控制模式的完整执行流程

┌─────────────────────────────────────────────────────────┐
│ 用户输入：question ="帮我设置一个明天的闹钟"            │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 步骤 1：转换工具为 ToolCallback[]                        │
│ ToolCallbacks.from(new ArtisanTools())                 │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 步骤 2：创建工具调用选项                                │
│ ToolCallingChatOptions                                  │
│ .internalToolExecutionEnabled(false)                    │
│ // 禁用框架自动执行，准备手动控制                        │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────────────────┐
│ 步骤 3：首次调用大模型                                  │
│ chatClient.prompt(prompt).call().chatResponse()        │
│                                                         │
│ 响应包含：ToolCall 信息                                  │
│ hasToolCalls()=true                                    │
└────────────────┬────────────────────────────────────────┘
                 ▼
┌──────────┴──────────┐
│ while(chatResponse  │
│ .hasToolCalls())    │
│                     ▼ ▼
│ ┌─────────────┐ ┌────────────────┐
│ │ ToolCall   │ │ NoToolCalls    │
│ │ 存在        │ │ 循环结束        │
│ └──┬──────────┘ └────────┬───────┘
│    │                     │
│    ▼                     ▼
│ ┌──────────────────────────────────────────────────────────┐
│ │ 步骤 4：执行工具（手动）                                  │
│ │ toolCallingManager.executeToolCalls(prompt, chatResponse)│
│ │                                                         │
│ │ 获得 ToolExecutionResult，包含：                         │
│ │ - 更新的对话历史                                         │
│ │ - 工具执行结果                                           │
│ └──────────────┬───────────────────────────────────────────┘
│                ▼
│ ┌──────────────────────────────────────────────────────────┐
│ │ 步骤 5：将结果反馈给大模型                                │
│ │ chatClient.prompt(                                      │
│ │   newPrompt(                                             │
│ │     toolExecutionResult.conversationHistory(),           │
│ │     toolCallingChatOptions                               │
│ │   )                                                      │
│ │ ).call().chatResponse()                                  │
│ │                                                         │
│ │ 大模型基于工具结果生成新的响应                            │
│ │ 可能包含：                                                │
│ │ - 直接回答（没有更多工具需要调用）                        │
│ │ - 新的 ToolCall（需要调用另一个工具）                     │
│ └──────────────┬───────────────────────────────────────────┘
│                ▼
│ 判断是否还有 ToolCall？ (返回循环判断条件)

6.4 手动控制模式的优势与使用场景

优势：

✅ 完全掌控工具执行流程

// 可以在工具执行前后添加自定义逻辑
ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, chatResponse);
// 例如：持久化工具调用记录
saveToolCallLog(chatResponse.getToolCalls());
// 例如：验证工具执行结果
validateToolResults(result);
// 例如：添加监控和指标
recordToolCallMetrics(toolName, executionTime);

✅ 可以实现复杂的工具调用逻辑

int maxToolCallAttempts = 5;
int attempts = 0;
while (chatResponse.hasToolCalls() && attempts < maxToolCallAttempts) {
    // 有 Tool Call 且未超过最大尝试次数，继续执行
    attempts++;
    // 执行工具...
}
if (attempts >= maxToolCallAttempts) {
    // 超过最大尝试次数，中断循环，返回错误
    return "工具调用已达到最大次数，无法完成任务";
}

✅ 支持条件性工具执行

while (chatResponse.hasToolCalls()) {
    List<ToolCall> toolCalls = chatResponse.getToolCalls();
    // 过滤敏感工具（比如删除操作）
    List<ToolCall> filteredToolCalls = toolCalls.stream()
            .filter(tc -> !isSensitiveTool(tc.getToolName()))
            .collect(Collectors.toList());
    if (filteredToolCalls.isEmpty()) {
        // 如果所有工具都是敏感的，拒绝执行
        return "无法执行此操作：工具调用涉及敏感操作";
    }
    // 继续执行允许的工具
    ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, chatResponse);
}

使用场景：

七、异常处理策略：DefaultToolExecutionExceptionProcessor

在实际的 Tool Calling 过程中，工具执行经常会失败。关键问题是：当工具执行失败时，应该如何处理？

Spring AI 提供了 ToolExecutionExceptionProcessor 接口来处理这种情况。

7.1 问题场景

假设我们的工具中有一个会抛出异常的方法：

@Tool(description = "获取当前时间")
LocalDateTime getCurrentDateTime() {
    System.out.println("获取当前时间");
    throw new RuntimeException("获取当前时间异常"); // ← 工具执行失败！
    // return LocalDateTime.now();
}

当这个工具被调用并抛出异常时，系统有两种处理策略：

策略 1：抛出异常，中断整个流程

Tool Call -> 执行工具 -> 抛出异常 -> 应用程序崩溃 ❌

策略 2：捕获异常，将错误信息返回给大模型

Tool Call -> 执行工具 -> 捕获异常 -> 返回错误信息给大模型 -> 大模型尝试其他方案 ✅

显然，策略 2 更符合 AI Agent 的设计理念：让大模型知道工具执行失败了，并决定下一步该做什么。

7.2 异常处理器的配置

@SpringBootApplication
public class SpringAIApplication {
    /**
     * 配置异常处理器
     * 参数 false 表示：不抛出异常，而是将异常信息返回给大模型
     */
    @Bean
    ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
        return new DefaultToolExecutionExceptionProcessor(false);
    }

    public static void main(String[] args) {
        SpringApplication.run(SpringAIApplication.class, args);
    }
}

7.3 参数详解：true vs false

DefaultToolExecutionExceptionProcessor 的构造函数接受一个布尔参数：

// 参数值为 false
new DefaultToolExecutionExceptionProcessor(false)
// 参数值为 true
new DefaultToolExecutionExceptionProcessor(true)

7.4 执行流程对比

参数为 false 的执行流程：

用户:"帮我查一下现在几点"
↓ 大模型:"我需要调用 getCurrentDateTime 工具"
↓ 框架执行工具 -> 异常！RuntimeException("获取当前时间异常")
↓ 异常处理器捕获 -> 不抛出异常
↓ 异常信息被转换为工具结果:"工具执行失败：获取当前时间异常"
↓ 返回给大模型:"工具返回：执行失败，异常信息为..."
↓ 大模型分析结果:"抱歉，我无法获取当前时间。您可以告诉我您所在的时区，我可以帮您计算时间。"
↓ 用户收到：一个有理有据的错误说明，而不是应用崩溃 ✅ 用户体验好，系统继续运行

参数为 true 的执行流程：

用户:"帮我查一下现在几点"
↓ 大模型:"我需要调用 getCurrentDateTime 工具"
↓ 框架执行工具 -> 异常！RuntimeException("获取当前时间异常")
↓ 异常处理器直接抛出异常
↓ 应用程序崩溃
↓ 用户看到:500InternalServerError ❌ 用户体验差，系统出错

7.5 异常处理的最佳实践

第 1 步：始终配置异常处理器（参数为 false）

@Bean
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
    // 参数为 false：不抛出异常，允许大模型处理失败
    return new DefaultToolExecutionExceptionProcessor(false);
}

第 2 步：在工具方法中添加防御性编程

@Tool(description = "获取当前时间")
LocalDateTime getCurrentDateTime() {
    try {
        // 业务逻辑
        return LocalDateTime.now();
    } catch (Exception e) {
        // 记录详细的错误信息，便于调试
        logger.error("获取时间失败", e);
        // 抛出更有信息的异常
        throw new RuntimeException("系统时间服务暂时不可用，请稍后重试", e);
    }
}

第 3 步：监控和告警工具执行异常

@Component
public class ArtisanTools {
    private static final Logger logger = LoggerFactory.getLogger(ArtisanTools.class);

    @Tool(description = "获取当前时间")
    LocalDateTime getCurrentDateTime() {
        try {
            return LocalDateTime.now();
        } catch (Exception e) {
            // 记录错误日志
            logger.error("Tool execution failed: getCurrentDateTime", e);
            // 发送告警
            alertService.sendAlert("工具异常", "getCurrentDateTime 执行失败");
            // 抛出异常给框架处理
            throw new RuntimeException("获取时间异常：" + e.getMessage());
        }
    }

    @Tool(description = "设置闹钟")
    void setAlarm(AlarmRequest alarmRequest) {
        try {
            // 验证参数
            if (alarmRequest.getTime() == null || alarmRequest.getTime().isEmpty()) {
                throw new IllegalArgumentException("时间不能为空");
            }
            // 业务逻辑
            System.out.println("设置闹钟：" + alarmRequest.getTime());
        } catch (IllegalArgumentException e) {
            // 参数错误，抛出异常给大模型
            throw new RuntimeException("参数错误：" + e.getMessage());
        } catch (Exception e) {
            logger.error("Tool execution failed: setAlarm", e);
            alertService.sendAlert("工具异常", "setAlarm 执行失败");
            throw new RuntimeException("设置闹钟异常：" + e.getMessage());
        }
    }
}

第 4 步：根据异常信息优化工具描述

如果工具经常因为参数不对而失败，说明参数描述不清楚：

// ❌ 描述不清，导致大模型经常传错参数
@JsonPropertyDescription("时间")
private String time;

// ✅ 清晰的描述，大模型知道该传什么格式
@JsonPropertyDescription("闹钟时间，必须使用中文年月日格式，例如：2025 年 3 月 31 日")
private String time;

八、完整的工具调用示例

为了更清楚地展示整个过程，让我们看一个完整的、可运行的例子。

8.1 工具定义 - ArtisanTools.java

package com.Artisan;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;

@Component
public class ArtisanTools {
    /**
     * 获取当前时间
     * 清晰的 description 帮助大模型理解工具的用途
     */
    @Tool(description = "获取当前系统时间，返回格式为 LocalDateTime 对象")
    LocalDateTime getCurrentDateTime() {
        System.out.println("获取当前时间");
        throw new RuntimeException("获取当前时间异常");
        // return LocalDateTime.now();
    }

    /**
     * 设置闹钟
     * 接受一个复杂的参数对象 AlarmRequest
     */
    @Tool(description = "用指定时间和位置设置闹钟，闹钟会在指定时间提醒")
    void setAlarm(AlarmRequest alarmRequest) {
        System.out.println("地址：" + alarmRequest.getAddress());
        System.out.println("闹钟时间为：" + alarmRequest.getTime());
    }
}

8.2 参数模型 - AlarmRequest.java

package com.Artisan;

import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import org.springframework.ai.tool.annotation.ToolParam;

/**
 * 闹钟请求参数
 * 展示了参数描述的最佳实践
 */
public class AlarmRequest {
    /**
     * time 字段：必需
     * 使用 @JsonPropertyDescription 提供详细的格式说明和示例
     */
    @JsonPropertyDescription("闹钟的时间，必须使用中文年月日格式。" +
                             "例如：2025 年 3 月 31 日、2025 年 12 月 25 日。" +
                             "不接受其他格式如 2025-03-31 或 31/03/2025")
    private String time;

    /**
     * address 字段：可选
     * 使用 @ToolParam(required = false) 标记为可选
     */
    @JsonPropertyDescription("闹钟要设置的位置，用于标识闹钟提醒的场景。" +
                             "常见值：卧室、客厅、办公室、车内、客房等")
    @ToolParam(required = false)
    private String address;

    public String getTime() { return time; }
    public void setTime(String time) { this.time = time; }
    public String getAddress() { return address; }
    public void setAddress(String address) { this.address = address; }
}

8.3 控制器 - ToolController.java

package com.Artisan;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.model.tool.ToolCallingChatOptions;
import org.springframework.ai.model.tool.ToolCallingManager;
import org.springframework.ai.model.tool.ToolExecutionResult;
import org.springframework.ai.support.ToolCallbacks;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 工具调用演示控制器
 * 展示自动执行和手动控制两种模式
 */
@RestController
public class ToolController {
    @Autowired
    private ChatClient chatClient;

    @Autowired
    private ArtisanTools artisanTools;

    /**
     * 自动执行模式：最简洁的方式
     *
     * 请求示例：
     * GET /tool?question=帮我设置一个明天上午 10 点的闹钟
     */
    @GetMapping("/tool")
    public String tool(String question) {
        return chatClient
                .prompt()
                .user(question)
                .tools(ArtisanTools) // 注册工具，框架自动处理 Tool Calling
                .call()
                .content();
    }

    /**
     * 手动控制模式：对工具调用过程进行精细控制
     *
     * 请求示例：
     * GET /userControlledTool?question=帮我设置一个明天上午 10 点的闹钟
     */
    @GetMapping("/userControlledTool")
    public String userControlledTool(String question) {
        // 步骤 1：将工具对象转换为 ToolCallback 数组
        ToolCallback[] toolCallbacks = ToolCallbacks.from(new ArtisanTools());

        // 步骤 2：创建工具调用选项，禁用框架自动执行
        ToolCallingChatOptions toolCallingChatOptions = ToolCallingChatOptions.builder()
                .toolCallbacks(toolCallbacks)
                .internalToolExecutionEnabled(false) // 关键：禁用自动执行
                .build();

        // 步骤 3：创建 Prompt
        Prompt prompt = Prompt.builder()
                .chatOptions(toolCallingChatOptions)
                .content(question)
                .build();

        // 步骤 4：首次调用大模型
        ChatResponse chatResponse = chatClient.prompt(prompt).call().chatResponse();

        // 步骤 5：创建 ToolCallingManager，准备手动执行工具
        ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();

        // 步骤 6：循环执行 Tool Calling，直到大模型不再需要调用工具
        while (chatResponse.hasToolCalls()) {
            // 执行大模型指定的所有工具
            ToolExecutionResult toolExecutionResult = toolCallingManager
                    .executeToolCalls(prompt, chatResponse);

            // 将工具执行结果反馈给大模型，获取新的响应
            chatResponse = chatClient.prompt(new Prompt(
                    toolExecutionResult.conversationHistory(), // 包含工具调用和结果的完整对话历史
                    toolCallingChatOptions
            )).call().chatResponse();
        }

        // 步骤 7：返回最终文本结果
        return chatResponse.getResult().getOutput().getText();
    }
}

8.4 应用启动类 - SpringAIApplication.java

package com.Artisan;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.memory.InMemoryChatMemoryRepository;
import org.springframework.ai.chat.memory.MessageWindowChatMemory;
import org.springframework.ai.chat.memory.repository.jdbc.JdbcChatMemoryRepository;
import org.springframework.ai.tool.execution.DefaultToolExecutionExceptionProcessor;
import org.springframework.ai.tool.execution.ToolExecutionExceptionProcessor;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class SpringAIApplication {
    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder.build();
    }

    /**
     * 配置异常处理器
     * 参数 false：不抛出异常，而是将异常信息返回给大模型
     * 这样大模型可以尝试其他方案，而不是导致应用崩溃
     */
    @Bean
    ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
        return new DefaultToolExecutionExceptionProcessor(false);
    }

    public static void main(String[] args) {
        SpringApplication.run(SpringAIApplication.class, args);
    }
}

九、常见问题与最佳实践

9.1 大模型没有调用我定义的工具

可能的原因：

1. 工具 description 不清楚

// ❌ 不好的做法
@Tool(description = "工具")
// ✅ 好的做法
@Tool(description = "根据日期查询该天的天气预报，包括温度、风力、降雨概率等信息")

2. 工具没有被注册为 Bean

// ❌ 缺少 @Component
public class MyTools {
    @Tool(description = "...")
}
// ✅ 正确做法
@Component
public class MyTools {
    @Tool(description = "...")
}

3. 参数描述不清楚，大模型不知道该传什么

// ❌ 参数描述不足
@JsonPropertyDescription("日期")
private String date;
// ✅ 详细的参数描述
@JsonPropertyDescription("要查询的日期，格式为 YYYY-MM-DD，如 2025-03-31。" +
                         "只能查询过去 30 天和未来 7 天的数据")
private String date;

9.2 工具执行失败，导致应用崩溃

解决方案：

确保配置了异常处理器：

@Bean
ToolExecutionExceptionProcessor toolExecutionExceptionProcessor() {
    return new DefaultToolExecutionExceptionProcessor(false); // false 表示不抛出异常
}

9.3 大模型陷入无限循环，不断调用工具

可能的原因：

1. 参数描述歧义 - 大模型理解错了参数含义
2. 工具描述过于宽泛 - 大模型认为所有问题都需要这个工具
3. 工具返回结果不清楚 - 大模型不知道工具是否执行成功

解决方案：

使用手动控制模式，添加最大尝试次数的限制：

int maxToolCallAttempts = 5;
int attempts = 0;
while (chatResponse.hasToolCalls() && attempts < maxToolCallAttempts) {
    attempts++;
    // 执行工具...
}
if (attempts >= maxToolCallAttempts) {
    return "执行失败：工具调用已达到最大次数";
}

9.4 工具有多个参数，大模型总是遗漏某些参数

解决方案：

使用 @ToolParam 明确标记参数的可选性：

public class Request {
    // 必需参数：什么都不加
    @JsonPropertyDescription("用户的 ID 号，例如：12345")
    private String userId;

    // 可选参数：加上 required = false
    @JsonPropertyDescription("查询的开始日期，格式为 YYYY-MM-DD，可选。如果不指定，默认查询最近 30 天")
    @ToolParam(required = false)
    private String startDate;
}

9.5 同一个工具类有很多方法，应该都标记为工具吗？

建议：

只标记那些真正需要被大模型调用的方法。不要把所有方法都标记为工具，这会增加大模型的决策复杂度。

@Component
public class UserService {
    // ✅ 可以标记为工具：用户关心的、需要大模型调用的
    @Tool(description = "根据用户 ID 查询用户信息")
    public User queryUser(String userId) { ... }

    // ✅ 可以标记为工具：用户可能需要的常见操作
    @Tool(description = "根据用户名模糊搜索用户")
    public List<User> searchUsers(String keyword) { ... }

    // ❌ 不要标记为工具：内部方法，用户不需要大模型调用
    private void validateUserId(String userId) { ... }

    // ❌ 不要标记为工具：工具方法的重复，增加混乱
    @Tool
    private void queryUserInternal(String userId) { ... }
}

十、总结与展望

10.1 Tool Calling 的核心价值

Tool Calling 机制打破了大模型与外部世界的隔阂，它让大模型：

1. 能够感知工具的存在 - 通过 @Tool 注解和 description
2. 能够正确选择工具 - 通过清晰的参数描述和工具职责
3. 能够自主调用工具 - 框架自动处理复杂的 Tool Calling 流程
4. 能够基于工具结果进行推理 - 完整的对话历史维护
5. 能够应对工具执行失败 - 异常处理和容错机制

10.2 自动执行 vs 手动控制的选择

选择建议：

• 默认使用自动执行模式，代码简洁
• 如果需要特殊处理（审核、持久化、限流等），升级到手动控制模式
• 不要为了可控性而过度设计，简单就是最好的设计

10.3 参数描述的黄金法则

好的参数描述有三个特征：

1. 清晰 - 用自然语言清楚地说明字段的含义
2. 具体 - 提供具体的格式示例和取值范围
3. 完整 - 说明所有的约束条件和特殊情况

// ✅ 优秀的参数描述
@JsonPropertyDescription("查询的日期范围，格式为 YYYY-MM-DD。" +
                         "示例：2025-03-31。" +
                         "约束：不能查询过去 90 天之前的数据，不能查询未来数据。" +
                         "如果不指定，默认查询今天的数据")
@ToolParam(required = false)
private String queryDate;

10.4 走向 AI Agent 的下一步

掌握了 Tool Calling，你已经拥有了构建真正 AI Agent 的基础。下一步可以探索：

1. 多工具协作 - 设计工具系统，让多个工具协同工作
2. 工具组合 - 复杂任务分解为多个工具的组合调用
3. 工具优先级 - 不同情况下选择不同的工具
4. 工具链路优化 - 监控和优化工具的执行效率
5. Agent 框架 - 集成 Spring AI 的 Agent 框架，实现完整的自主代理

十一、参考资源

• Spring AI 官方文档：https://docs.spring.io/spring-ai/
• Tool Calling 概念：https://en.wikipedia.org/wiki/Tool_use_(artificial_intelligence)