|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
Tool Calling
Tool calling — the ability for an AI model to invoke application-defined functions and act on their results — is the essential building block of agentic AI systems. A model that can only generate text is a chatbot; a model that can discover information, take action, and loop until a goal is reached is an agent.
Tools are used for two broad purposes:
-
Information retrieval — augmenting the model’s knowledge with data from databases, web services, file systems, or search engines. Examples: fetching the current weather, querying customer records, looking up the latest news.
-
Taking action — executing operations in your system. Examples: sending an email, booking a flight, updating a record, triggering a workflow.
Although we speak of "tool calling" as a model capability, it is the application that owns the tool calling logic. The model can request a tool call and provide input arguments; the application is responsible for executing the tool and returning the result. The model never receives direct access to the APIs behind your tools — a critical security consideration.
Architecture Overview
Spring AI 2.0 makes the tool calling loop a first-class, composable component of the `ChatClient’s advisor chain. The flow at a glance:
-
You define tools (Defining Tools) and pass them to
ChatClient. -
ChatClientauto-registers aToolCallingAdvisor(The Tool Calling Loop) that drives the loop. -
The model decides which tools to call;
ToolCallingManagerexecutes them; the loop continues until the model produces a response without tool calls. -
Other advisors in the chain — memory, observability, retries, custom logic — compose with the loop through a single dial: advisor ordering (Memory and the Tool Loop).
This architecture replaces the per-ChatModel tool execution loops of Spring AI 1.x.
Calling ChatModel directly is still supported for low-level use cases — see ChatModel Tool Calling.
|
| Check the Chat Model Comparisons to see which models support tool calling. |
Quick Start
Define a tool by annotating a method with @Tool:
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;
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(description = "Set a user alarm for the given time, provided in ISO-8601 format")
void setAlarm(String time) {
LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
System.out.println("Alarm set for " + alarmTime);
}
}
Pass the tools to ChatClient via .tools() and ask a question that requires them:
ChatModel chatModel = ...
String response = ChatClient.create(chatModel)
.prompt("Can you set an alarm 10 minutes from now?")
.tools(new DateTimeTools())
.call()
.content();
The model decides to call getCurrentDateTime(), then setAlarm(…) with the computed time.
Spring AI handles the full round-trip automatically.
Scaling to Hundreds of Tools
The default ToolCallingAdvisor sends all registered tool definitions to the model on every request.
With a small tool library this is fine.
At 30+ tools — or in multi-server MCP setups where a session may aggregate hundreds of tool definitions — it creates context bloat, accuracy degradation, and unnecessary token cost.
ToolSearchToolCallingAdvisor is a drop-in replacement that implements the progressive tool disclosure pattern: it indexes the full tool set once per session and injects only a built-in toolSearchTool the model uses to retrieve relevant tools by natural language query.
Only discovered tools are included in subsequent requests.
Enable it with a single property:
spring.ai.chat.client.tool-search-advisor.enabled=true
See Tool Search Tool for the full configuration, indexing strategies, session-ID semantics, and tuning options.
ChatModel Tool Calling
For users who want to drive ChatModel directly — without ChatClient and without ToolCallingAdvisor — Spring AI supports a low-level tool calling path.
This is the right choice when you need full control over the request/response cycle and don’t need the advisor chain’s composition features.
See ChatModel Tool Calling for the API, precedence rules between default and runtime tools, and worked examples.
The per-ChatModel internal tool execution loop of Spring AI 1.x has been removed.
Calling ChatModel with tools sends the tool definitions to the model and returns the model’s response — tool calls in that response are not executed automatically.
You drive the loop yourself, or use ChatClient (which auto-registers ToolCallingAdvisor for you).
|
Ready-Made Tools
|
Community: Spring AI Agent Utils
Spring AI Agent Utils provides ready-made tools for agents: file system, grep, glob, shell, web fetch and web search tools, task lists and Agent Skills. |