AI Agents and Tool Calling in Spring Boot

Quick Start

An AI assistant becomes agentic when it can use controlled tools—not only generate text. This Byte introduces that idea from the beginning and shows how Spring AI's @Tool annotation lets an LLM call approved Spring-managed methods.

Optional foundation: New to agents and tools? Read How an AI Agent Works for a simple conceptual walkthrough.

Meet the Scenario

Meena wants the assistant to do more than answer from documents: "Customers should be able to ask it to check their current balance." Karthik asks: "How can a language model safely access live banking data?" Divya replies: "We expose a narrowly scoped Java method as a tool, then enforce permissions inside the application."

Core Concept

An agent can call a real tool—such as a database query or API—to obtain current information or perform an approved action, then use the result in its response. In Spring AI, annotating a Java method with @Tool makes its purpose and inputs available to the model. The application still controls authentication, authorization and execution.

Think of it like a bank teller who has a phone line directly to the vault. The teller doesn't guess the balance from memory — mid-conversation, they place a real call, get the real number, and answer with confidence.

How It Works Under the Hood

Step 1: Mark an existing method as a tool the model can call:

01@Service02public class AccountTools {0304    private final AccountService accountService;0506    public AccountTools(AccountService accountService) {07        this.accountService = accountService;08    }0910    @Tool(description = "Get the current account balance for a given account ID")11    public BalanceResponse getBalance(String accountId) {12        return accountService.getBalance(accountId);13    }14}

The description matters because the model reads it to decide when the tool is relevant. Write a precise purpose, expected inputs and important limits.

Step 2: Register the tool with ChatClient:

01@Service02public class BankingAssistantService {0304    private final ChatClient chatClient;0506    public BankingAssistantService(ChatClient.Builder builder, AccountTools accountTools) {07        this.chatClient = builder08                .defaultTools(accountTools)09                .build();10    }1112    public String chat(String userMessage) {13        return chatClient.prompt()14                .user(userMessage)15                .call()16                .content();17    }18}

Now, if a customer asks "What's my balance for account 4521?", the model recognizes it needs live data, calls getBalance("4521") behind the scenes, and weaves the real result into its natural-language reply — without the developer writing any manual "if the user asks about balance, call this" logic.

Try It Yourself (Small Snippet)

Apply least privilege in Java: restrict a sensitive tool with a check inside the method itself:

01@Tool(description = "Process a refund for a given transaction ID")02public RefundResponse processRefund(String transactionId, String requestingUserRole) {03    if (!"ADMIN".equals(requestingUserRole)) {04        throw new AccessDeniedException("Refunds require admin privileges");05    }06    return refundService.process(transactionId);07}

The key guardrail is language-independent: authenticate the caller and authorize the specific action before sensitive code runs.

Real Company Angle

Spring AI's tool-calling support also integrates the Model Context Protocol (MCP), functioning as both a client and a server — meaning a Spring Boot application's tools can be exposed to, or can consume tools from, external AI agent ecosystems using a shared standard, rather than one-off custom integrations for each system. MCP can reduce one-off integration work when systems need a shared protocol for exposing or consuming tools, but permissions and trust boundaries still require application-level design.

Common Mistakes

1. Writing a vague @Tool description — if the description doesn't clearly explain when and why to use the tool, the model may call it at the wrong time or not call it when it should.
2. Giving every tool method unrestricted access — as covered in S5, sensitive actions need explicit checks inside the method, not just trust that "the model will behave."
3. Forgetting that tool calls can fail — a database timeout or downstream API error inside a @Tool method should be handled gracefully, not left to crash the whole request.
4. Registering too many unrelated tools on one ChatClient — this can confuse the model about which tool applies when; grouping related tools (like all AccountTools) keeps behavior predictable.

Persona Wrap-Up

Karthik summarizes: "The model interprets the request, selects an approved tool and uses its result." Meena tests it: "Customers can ask natural questions and receive current information." Divya adds: "The tool description guides selection, but Java-side permissions remain the final authority."

Compare & Contrast

Mini Practice Task

Design (on paper) a @Tool-annotated method called freezeCard(String cardId, String requestingUserRole) that should only be callable by users with the "ADMIN" or "FRAUD_TEAM" role. Write the @Tool description you'd use, and the access-check logic inside the method.

Key Takeaways

• Spring AI's @Tool annotation exposes an approved Java method for model-directed tool calling.
• A clear, descriptive description on @Tool is what helps the model decide when to use it — vague descriptions lead to unreliable behavior.
• Least privilege applies to every sensitive tool: grant only the permissions required for the requested action.
• Spring AI integrates the Model Context Protocol (MCP), letting Java-based tools interoperate with a broader, standardized AI agent ecosystem.
• @Tool and .defaultTools(...) provide Java-specific integration, while the application remains responsible for validation, authorization and audit logging.

FAQ / Knowledge Check

Q1: What Spring AI annotation lets an LLM call a real Java method? @Tool — placed on a method, with a description that tells the model when to use it.

Q2: Does adding @Tool to a sensitive method automatically make it safe? No. Sensitive actions still need explicit access and role checks inside the application method.

Q3: What does MCP support in Spring AI enable? It lets Java-based tools be exposed to, or consume tools from, external AI agent systems using a shared, standardized protocol.

Knowledge Check:

1. What determines whether the model correctly decides when to call a given @Tool method?
2. True/False: Once a method is marked @Tool, no additional access control is needed inside it.
3. Which security principle should restrict sensitive @Tool methods?

(Answers: 1. The clarity and accuracy of its description; 2. False—sensitive tools still need explicit application-side access checks; 3. Least privilege)

Next byte: Production Concerns for Java/Spring Boot GenAI Apps — security, observability, scaling, and cost as these systems go live.

Interactive Knowledge Check

References and Further Reading

• Spring AI Reference
• Spring AI ChatClient
• Spring Boot Reference