Spring AI-@Tool使用-平芜编程栈

Tools

许多 AI 应用程序通过自然语言与用户交互。然而，某些业务场景需要模型使用结构化输入直接与外部系统（如 API、数据库或文件系统）进行交互。

Tools 是 agents 调用来执行操作的组件。它们通过定义良好的输入和输出让模型与外部世界交互，从而扩展模型的能力。Tools 封装了一个可调用的函数及其输入模式。我们可以把工具定义传递给兼容的 models，允许模型决定是否调用工具以及使用什么参数。在这些场景中，工具调用使模型能够生成符合指定输入模式的请求。

注意：服务器端工具使用

某些聊天模型（例如 OpenAI、Anthropic 和 Gemini）具有在服务器端执行的内置工具，如 Web 搜索和代码解释器。请参阅提供商概述以了解如何使用特定聊天模型访问这些工具。

TIP: 迁移与更多 Tool Calling 说明请参考：Tool Calling 使用指南。

Tool calling（也称为 function calling）是 AI 应用程序中的常见模式，允许 model 与一组 API 或 tools 交互，增强其能力。

Tools 主要用于：

信息检索：此类别中的 tools 可用于从外部源检索信息，例如数据库、Web 服务、文件系统或 Web 搜索引擎。目标是增强 model 的知识，使其能够回答原本无法回答的问题。因此，它们可以在 Retrieval Augmented Generation (RAG) 场景中使用。例如，可以使用 tool 检索给定位置的当前天气、检索最新新闻文章或查询数据库中的特定记录。
执行操作：此类别中的 tools 可用于在软件系统中执行操作，例如发送电子邮件、在数据库中创建新记录、提交表单或触发工作流。目标是自动化原本需要人工干预或显式编程的任务。例如，可以使用 tool 为与聊天机器人交互的客户预订航班、填写网页上的表单，或在代码生成场景中基于自动化测试（TDD）实现 Java 类。

尽管我们通常将 tool calling 称为 model 能力，但实际上由客户端应用程序提供 tool calling 逻辑。Model 只能请求 tool call 并提供输入参数，而应用程序负责从输入参数执行 tool call 并返回结果。Model 永远无法访问作为 tools 提供的任何 API，这是一个关键的安全考虑。

Spring AI 提供了便捷的 API 来定义 tools、解析来自 model 的 tool call 请求并执行 tool calls。

@Tool在Spring AI中的应用

Spring AI 提供了两种从方法指定 tools（即ToolCallback(s)）的内置支持：

声明式：使用@Tool注解
编程式：使用低级MethodToolCallback实现。

@Tool是Spring AI 提供实现 Function‑Calling（工具调用）的注解。

配套注解：@ToolParam，用来描述每一个入参，告诉大模型参数含义、是否必填

核心作用：把你写的普通 Java Bean 的方法，暴露给大模型作为可调用工具，用来做 Agent。

包：org.springframework.ai.tool.annotation.Tool

@Tool注解示例

@Component public class OrderTools { @Tool(description = "根据订单编号查询订单状态") public String queryOrder( @ToolParam(description = "订单编号",必填) String orderNo ){ // 业务逻辑：查DB、调用接口 return "订单："+orderNo+"，状态：已发货"; } }

@Tool注解允许您提供有关 tool 的关键信息：

name：tool 的名称。如果未提供，将使用方法名称。AI model 使用此名称在调用时识别 tool。因此，不允许在同一类中有两个同名 tools。名称必须在特定聊天请求中提供给 model 的所有 tools 中唯一。
description：tool 的描述，model 可以使用它来理解何时以及如何调用 tool。如果未提供，方法名称将用作 tool 描述。但是，强烈建议提供详细描述，因为这对于 model 理解 tool 的用途以及如何使用它至关重要。未能提供良好的描述可能导致 model 在应该使用时不使用 tool 或错误使用它。
returnDirect：tool 结果是否应直接返回给客户端或传递回 model。
resultConverter：用于将 tool call 的结果转换为String object以发送回 AI model 的ToolCallResultConverter实现。

Spring AI 将自动为@Tool注解方法的输入参数生成 JSON schema。Schema 由 model 用于理解如何调用 tool 并准备 tool 请求。@ToolParam注解可用于提供有关输入参数的附加信息，例如描述或参数是必需还是可选的。默认情况下，所有输入参数都被视为必需

使用@Toolparam注解示例

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 = "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注解允许您提供有关 tool 参数的关键信息：

description：参数的描述，model 可以使用它来更好地理解如何使用它。例如，参数应该是什么格式，允许什么值等。
required：参数是必需还是可选的。默认情况下，所有参数都被视为必需。

如果参数用@Nullable注解，除非使用@ToolParam注解明确标记为必需，否则将被视为可选。

除了@ToolParam注解外，您还可以使用来自 Swagger 的@Schema注解或来自 Jackson 的@JsonProperty。有关更多详细信息

配置注册工具：

@Bean public ChatClient chatClient(ChatModel chatModel, OrderTools orderTools){ return ChatClient.builder(chatModel) .defaultTools(orderTools) //扫描类中所有@Tool方法 .build(); }