# Spring AI系列之Tool Calling 实战：3 种工具定义方式

在 Spring AI 开发 AI Agent 的过程中，**Tool Calling（工具调用）** 是最核心、最能体现 AI 智能化的能力。
很多同学在实战时都会遇到这些问题：
- 工具到底有几种写法？
- 函数式工具怎么用才规范？
- 编程式 ToolCallback 适合什么场景？
- 项目里到底该选哪种？

今天这篇就带着大家**一次性吃透 Spring AI 3 种标准工具定义方式**，全部是可直接复制运行的企业级代码，图文并茂、一看就会！

环境：
*  Spring AI 1.1.3
* SpringBoot 3.5.7
* JDK 17

---

## 一、先看懂：Tool Calling 执行流程（图文秒懂）
Tool Calling 的本质：
**让大模型自主判断是否需要调用外部方法 → 自动调用 → 取回结果 → 自然语言回答**。

### 🔁 Tool Calling 标准执行流程图
![Tool Calling 完整执行流程](https://developer.qcloudimg.com/http-save/yehe-1208223/7de765c2db8b834a3f6d420e5bf60001.png)

**流程步骤：**
1. 用户提问
2. 模型分析是否需要调用工具
3. Spring AI 自动调度对应工具
4. 执行 Java 方法/函数并返回结果
5. 模型整合结果，给出最终回答

---

## 二、Spring AI 3 种工具定义方式（全文重点）
Spring AI 目前提供 **3 种标准工具定义方式**，覆盖 99% 开发场景：

---

## 方式 1：注解式 @Tool（最简单、企业最常用）
直接在**普通 Java 方法**上加 `@Tool` 注解，Spring AI 自动识别为可调用工具。

### 📦 代码示例
```java
@Component
public class TimeTools {

    /**
     * 获取当前系统时间工具
     */
    @Tool(description = "获取当前系统的日期与时间，格式：yyyy-MM-dd HH:mm:ss")
    public String getCurrentTime() {
        return LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
    }
}
```

### ✅ 优点
- 写法最简单直观
- 业务代码清晰
- 支持复杂逻辑、依赖注入

### 🎯 适用场景
时间查询、天气查询、数据库操作、订单服务、消息推送等**常规业务工具**。

---

## 方式 2：函数式工具 Function / BiFunction（官方推荐、极简）
这是 Spring AI **原生支持**的优雅写法，也是官方文档重点推荐的方式。
**不需要类、不需要注解**，基于 JDK 函数式接口定义。

### 🧩 代码示例 1：编程式构建
```java
// 定义入参、出参
record WeatherRequest(String city, String unit) {}
record WeatherResponse(double temperature, String unit) {}

// 函数式接口
interface WeatherService extends Function<WeatherRequest, WeatherResponse> {
    @Override
    WeatherResponse apply(WeatherRequest request);
}

@Test
void testFunctionTool() {
    // 构建函数式工具
    ToolCallback tool = FunctionToolCallback.builder("currentWeather", new WeatherService() {
                @Override
                public WeatherResponse apply(WeatherRequest request) {
                    return new WeatherResponse(25.5, request.unit());
                }
            })
            .description("获取指定城市的实时天气")
            .inputType(WeatherRequest.class)
            .build();

    // 调用
    String result = ChatClient.create(chatModel)
            .prompt("长沙今天天气怎么样？")
            .tools(tool)
            .call()
            .content();

    System.out.println(result);
}
```

### 🧩 代码示例 2：配置类 Bean 方式（企业推荐）
```java
@Configuration
public class AiToolConfig {
    public static final String WEATHER_TOOL = "currentWeather";

    @Bean(WEATHER_TOOL)
    @Description("获取指定城市的实时天气")
    public Function<WeatherRequest, WeatherResponse> currentWeather() {
        return request -> new WeatherResponse(30.0, request.unit());
    }
}
```

### 🚀 调用方式
```java
@Test
void testConfigFunctionTool() {
    String content = ChatClient.create(chatModel)
            .prompt("今天长沙天气怎么样？")
            .toolNames(AiToolConfig.WEATHER_TOOL)
            .call()
            .content();

    System.out.println(content);
}
```

### ✅ 优点
- 代码极简、无冗余
- 结构化强、支持强类型
- Spring 容器无缝整合

### 🎯 适用场景
轻量工具、结构化工具、快速开发、企业级规范项目。

---

## 方式 3：编程式构建 ToolCallback（最灵活、底层）
完全手动构建工具：**名称、描述、入参 Schema、执行体全部自己控制**。
适合：**动态工具、插件化、运行时注册、多租户场景**。

### ⚙️ 代码示例
```java
// 计算器工具
public class CalcTools {
    public Integer add(int a, int b) {
        return a + b;
    }
}

@Test
void testProgrammaticTool() {
    // 反射获取方法
    Method method = ReflectionUtils.findMethod(CalcTools.class, "add", int.class, int.class);

    // 手动定义工具元数据
    ToolDefinition definition = ToolDefinition.builder()
            .name("add")
            .description("计算两个整数的和")
            .inputSchema("""
                {
                    "type": "object",
                    "properties": {
                        "a": { "type": "integer", "description": "第一个数字" },
                        "b": { "type": "integer", "description": "第二个数字" }
                    },
                    "required": ["a", "b"]
                }
            """)
            .build();

    // 构建 ToolCallback
    ToolCallback callback = MethodToolCallback.builder()
            .toolDefinition(definition)
            .toolMethod(method)
            .toolObject(new CalcTools())
            .build();

    // 调用
    String content = ChatClient.builder(chatModel).build()
            .prompt("100 加 1000 等于多少？")
            .tools(callback)
            .call()
            .content();

    System.out.println(content);
}
```

### ✅ 优点
- 最灵活，完全代码控制
- 支持动态生成工具
- 支持自定义入参 Schema
- 适合高级架构、插件系统

### 🎯 适用场景
动态工具、插件化 AI Agent、工作流、多租户、低代码平台。

---

## 三、3 种工具方式对比（一张表看懂）
| 工具方式 | 难度 | 代码量 | 灵活性 | 企业使用 |
|--------|------|--------|--------|----------|
| **@Tool 注解** | ⭐ | 极少 | 中 | 主流、首选 |
| **函数式 Function** | ⭐⭐ | 极简 | 中高 | 推荐、规范 |
| **编程式 ToolCallback** | ⭐⭐⭐ | 中等 | 最高 | 动态/插件架构 |

**一句话选择：**
- 普通业务 → **@Tool**
- 快速优雅开发 → **函数式工具**
- 动态/插件/高级场景 → **ToolCallback**

---

## 四、企业级最佳实践（必看）
1. **工具描述必须精准**，模型靠它决定是否调用
2. 函数式工具优先使用 **@Bean** 注册，便于管理
3. 工具内部必须**捕获异常**，避免调用失败
4. 敏感操作必须加**权限校验**
5. 生产环境建议使用 **MCP 协议** 做工具网关
6. 开启日志可查看完整调用过程



---

## 五、总结
Spring AI Tool Calling **3 种标准工具定义方式**：
1. **@Tool 注解** → 简单、稳定、业务首选
2. **函数式 Function** → 优雅、强类型、企业推荐
3. **编程式 ToolCallback** → 灵活、动态、高级架构

这一篇吃透，你就能轻松开发企业级 AI 智能体（Agent）！



在 Spring AI 开发 AI Agent 的过程中，Tool Calling（工具调用） 是最核心、最能体现 AI 智能化的能力。很多同学在实战时都会遇到这些问题：

Spring AI系列之Tool Calling 实战：3 种工具定义方式

人工智能

SpringAI开发AIAgent必备的ToolCalling技术详解，3种工具定义方式对比：@Tool注解简单稳定，函数式Function优雅规范，编程式ToolCallback灵活高级。企业级代码示例+最佳实践，助你快速掌握SpringAI智能体开发核心技能。

数据库

智能体

容器

Agent

Java

2026采购季 | AI焕新·智启新局

tencentdb-catalog

weda

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Spring AI系列之Tool Calling 实战：3 种工具定义方式-腾讯云开发者社区-腾讯云

Spring AI系列之Tool Calling 实战：3 种工具定义方式

Spring AI系列之Tool Calling 实战：3 种工具定义方式

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐