|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
Defining Tools
Defining Tools
Spring AI offers three ways to define tools, from highest-level to most explicit:
| Style | Use when | Section |
|---|---|---|
Declarative |
You own the method and want minimal ceremony |
|
|
You need programmatic control over a method-backed tool |
|
|
You want to expose a |
All three produce ToolCallback instances that flow through the same loop.
You can mix styles freely.
Declarative: @Tool
Annotate any method — public, package-private, private; static or instance — with @Tool:
class WeatherTools {
@Tool(description = "Get the current weather for a given city")
public String getWeather(String city) {
return weatherService.fetch(city);
}
}
The @Tool annotation supports:
-
name— the tool name. Defaults to the method name. Must be unique within the tool set provided to a model. -
description— what the tool does and when to use it. Strongly recommended; without it the description is the method name, which rarely tells the model when to call the tool. -
returnDirect— return the result directly to the caller instead of feeding it back to the model. See Return Direct. -
requiresConfirmation— pause the tool-calling loop before a call of the tool runs, so that a person can allow or deny it. See Tool Call Confirmation. -
resultConverter— theToolCallResultConverterto use. See Result Conversion.
For AOT compilation (GraalVM native image), the class containing the @Tool methods must be a Spring bean (e.g. @Component).
Otherwise, annotate it with @RegisterReflection(memberCategories = MemberCategory.INVOKE_DECLARED_METHODS).
|
Add @ToolParam to describe individual parameters:
class WeatherTools {
@Tool(description = "Get the weather for a city at a specific time")
public String getWeather(
@ToolParam(description = "City name") String city,
@ToolParam(description = "Time in ISO-8601 format", required = false) String at) {
return weatherService.fetch(city, at);
}
}
By default all parameters are required.
@ToolParam(required = false) or @Nullable makes a parameter optional.
See JSON Schema for the full schema customization options.
Programmatic: MethodToolCallback
For dynamic tool registration — when you don’t control the source class, or you want to build the tool definition at runtime — use MethodToolCallback:
Method method = ReflectionUtils.findMethod(WeatherTools.class, "getWeather", String.class);
MethodToolCallback callback = MethodToolCallback.builder()
.toolDefinition(ToolDefinitions.builder(method)
.description("Get the current weather for a given city")
.build())
.toolMethod(method)
.toolObject(new WeatherTools())
.build();
The toolObject is required for instance methods, optional for static methods.
See Tool Specification Reference for the full builder API.
Programmatic: FunctionToolCallback
For tools backed by a Function, Supplier, Consumer, or BiFunction — including lambdas and method references — use FunctionToolCallback:
FunctionToolCallback callback = FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
.description("Get the weather in location")
.inputType(WeatherRequest.class)
.build();
The factory takes a name and the function reference. The builder sets the description and the input type (used for JSON schema generation).
ToolCallback Beans
Define a tool once as a ToolCallback bean and inject it where needed, then pass it with .tools(…).
Spring AI also registers ToolCallback beans with the ToolCallbackResolver, which resolves a tool by name when the resolution fallback is enabled:
@Configuration(proxyBeanMethods = false)
class WeatherToolsConfig {
@Bean
ToolCallback currentWeather(WeatherService weatherService) {
return FunctionToolCallback.builder("currentWeather", weatherService::getWeather)
.description("Get the weather in location")
.inputType(WeatherRequest.class)
.build();
}
}
Inject and pass the bean to ChatClient:
@Autowired ToolCallback currentWeather;
ChatClient.create(chatModel)
.prompt("What's the weather in Copenhagen?")
.tools(currentWeather)
.call()
.content();
Spring AI 2.0 removes the SpringBeanToolCallbackResolver pattern where bare Function beans were resolved by name via toolNames(…).
Tools must now be registered as explicit ToolCallback beans.
See Upgrading Tool Calling from 1.x to 2.0.
|
Passing Tools to ChatClient
ChatClient exposes two methods for providing tools:
// Per call — tools available only for this single request
chatClient.prompt(...)
.tools(new WeatherTools(), currentWeather)
.call();
// As defaults — tools available on every request built from this client
ChatClient client = ChatClient.builder(chatModel)
.defaultTools(new WeatherTools(), currentWeather)
.build();
Both methods are heterogeneous: they accept @Tool-annotated POJO instances, ToolCallback instances, ToolCallbackProvider instances, and arrays or collections of any of these.
You can mix styles in a single call.
Per-call .tools(…) appends to the client’s defaults — it does not replace them.
The final tool list sent to the model is the union of .defaultTools(…) and any .tools(…) added at the call site.
Default tools are shared across every request built from the same ChatClient.Builder.
They are useful for tools that should always be available, but they can also be dangerous if used carelessly — risk-tier and destructive tools should typically be added per call, not as defaults.
|
Tools registered via ToolCallingChatOptions.toolCallbacks(…) on the underlying ChatModel are overridden by the request-level tool list.
See ChatModel Tool Calling for the precedence rules.
|