AI项目博客声明式规范：@Tool
您可以通过用 @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 注解允许您提供有关 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 实现。有关更多详细信息，请参阅 结果转换。
方法可以是静态的或实例的，并且可以具有任何可见性（public、protected、package-private 或 private）。包含方法的类可以是顶级类或嵌套类，也可以具有任何可见性（只要在您计划实例化它的地方可以访问）。
NOTE: Spring AI 为 @Tool 注解方法的 AOT 编译提供内置支持，只要包含方法的类是 Spring bean（例如 @Component）。否则，您需要向 GraalVM 编译器提供必要的配置。例如，通过用 @RegisterReflection(memberCategories = MemberCategory.INVOKE_DECLARED_METHODS) 注解类。
您可以为方法定义任意数量的参数（包括无参数），支持大多数类型（基元、POJO、枚举、列表、数组、映射等）。同样，方法可以返回大多数类型，包括 void。如果方法返回值，返回类型必须是可序列化类型，因为结果将被序列化并发送回 model。
NOTE: 某些类型不受支持。有关更多详细信息，请参阅 方法 Tool 限制。
Spring AI 将自动为 @Tool 注解方法的输入参数生成 JSON schema。Schema 由 model 用于理解如何调用 tool 并准备 tool 请求。@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。有关更多详细信息，请参阅 JSON Schema。
编程式规范：MethodToolCallback
您可以通过编程方式构建 MethodToolCallback 来将方法转换为 tool。
import org.springframework.util.ReflectionUtils;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.method.MethodToolCallback;
import org.springframework.ai.tool.ToolDefinitions;
class DateTimeTools {
String getCurrentDateTime() {
return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
}
}
Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolCallback toolCallback = MethodToolCallback.builder()
.toolDefinition(ToolDefinitions.builder(method)
.description("Get the current date and time in the user's timezone")
.build())
.toolMethod(method)
.toolObject(new DateTimeTools())
.build();MethodToolCallback.Builder 允许您构建 MethodToolCallback 实例并提供有关 tool 的关键信息：
- toolDefinition：定义 tool 名称、描述和输入 schema 的 ToolDefinition 实例。您可以使用 ToolDefinition.Builder 类构建它。必需。
- toolMetadata：定义附加设置的 ToolMetadata 实例，例如结果是否应直接返回给客户端，以及要使用的结果转换器。您可以使用 ToolMetadata.Builder 类构建它。
- toolMethod：表示 tool 方法的 Method 实例。必需。
- toolObject：包含 tool 方法的对象实例。如果方法是静态的，您可以省略此参数。
- toolCallResultConverter：用于将 tool call 的结果转换为 String 对象以发送回 AI model 的 ToolCallResultConverter 实例。如果未提供，将使用默认转换器（DefaultToolCallResultConverter）。
如果方法是静态的，您可以省略 toolObject() 方法，因为不需要它。
class DateTimeTools {
static String getCurrentDateTime() {
return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
}
}
Method method = ReflectionUtils.findMethod(DateTimeTools.class, "getCurrentDateTime");
ToolCallback toolCallback = MethodToolCallback.builder()
.toolDefinition(ToolDefinitions.builder(method)
.description("Get the current date and time in the user's timezone")
.build())
.toolMethod(method)
.build();方法 Tool 限制
以下类型目前不支持作为用作 tools 的方法的参数或返回类型：
- Optional
- 异步类型（例如 CompletableFuture、Future）
- 响应式类型（例如 Flow、Mono、Flux）
- 函数类型（例如 Function、Supplier、Consumer）。
函数类型使用基于函数的 tool 规范方法支持。有关更多详细信息，请参阅 函数作为 Tools。
本文整理自 Spring AI Alibaba 官方文档《Tools 工具》：https://java2ai.com/docs/frameworks/agent-framework/tutorials/tools
