spring.ai.openai.api-key=<YOUR_OPENAI_API_KEY>
# Or for Gemini:
# spring.ai.google.gemini.api-key=<YOUR_GOOGLE_GEMINI_API_KEY>
3.3 Define Your Weather Tool
First, let's create a simple service that simulates fetching weather data. In a real application, this would call an external weather API.

Create src/main/java/com/example/aichatbot/WeatherService.java:

Java

package com.example.aichatbot;

import org.springframework.stereotype.Service;

// Define a record for the weather response, mapping to tool's output schema
record WeatherResponse(String city, String temperature, String conditions, String unit) {}

@Service
public class WeatherService {

    /**
     * Retrieves the current weather for a given city.
     * This method acts as a "tool" for the LLM.
     * @param city The city name for which to get the weather.
     * @param unit The unit of temperature (e.g., "celsius" or "fahrenheit").
     * @return Weather information in a structured format.
     */
    public WeatherResponse getCurrentWeather(String city, String unit) {
        // In a real app, this would call an external weather API
        // For demonstration, we'll return mock data based on city/unit
        System.out.println("DEBUG: Calling WeatherService for city: " + city + ", unit: " + unit); // Log tool call

        if ("london".equalsIgnoreCase(city) && "celsius".equalsIgnoreCase(unit)) {
            return new WeatherResponse(city, "15�C", "Cloudy", "celsius");
        } else if ("london".equalsIgnoreCase(city) && "fahrenheit".equalsIgnoreCase(unit)) {
            return new WeatherResponse(city, "59�F", "Cloudy", "fahrenheit");
        } else if ("new york".equalsIgnoreCase(city) && "fahrenheit".equalsIgnoreCase(unit)) {
            return new WeatherResponse(city, "72�F", "Sunny", "fahrenheit");
        } else if ("new york".equalsIgnoreCase(city) && "celsius".equalsIgnoreCase(unit)) {
            return new WeatherResponse(city, "22�C", "Sunny", "celsius");
        }
        return new WeatherResponse(city, "N/A", "Unknown", unit);
    }
}
3.4 Create Your AI Controller with Tool Registration
Now, let's integrate this WeatherService as a tool with our ChatClient.

Create src/main/java/com/example/aichatbot/AiToolController.java:

Java

package com.example.aichatbot;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.Request;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.model.function.FunctionCallback;
import org.springframework.ai.model.function.FunctionCallbackWrapper;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;
import java.util.function.Function;

@RestController
public class AiToolController {

    private final ChatClient chatClient;

    // Inject the WeatherService
    private final WeatherService weatherService;

    // The FunctionCallbackWrapper requires a Function. We'll define a record for input.
    // This record's fields define the parameters the LLM can use for the tool.
    record WeatherFunctionInput(String city, String unit) {}

    public AiToolController(ChatClient.Builder chatClientBuilder, WeatherService weatherService) {
        this.weatherService = weatherService;

        // 1. Define the FunctionCallbackWrapper for our tool
        FunctionCallback weatherFunction = FunctionCallbackWrapper.builder(
                "getCurrentWeather", // This is the name the LLM will see and try to call
                "Get the current weather for a specified city.", // Description for the LLM
                (json) -> { // Lambda that processes the JSON arguments from the LLM
                    // Convert JSON arguments into our input record
                    WeatherFunctionInput input = new WeatherFunctionInput(
                            (String) json.get("city"),
                            (String) json.get("unit"));
                    // Call our actual Java service method with the extracted arguments
                    return weatherService.getCurrentWeather(input.city(), input.unit());
                })
                .with  (new Function<WeatherFunctionInput, WeatherResponse>() {
                    @Override
                    public WeatherResponse apply(WeatherFunctionInput weatherFunctionInput) {
                        return weatherService.getCurrentWeather(weatherFunctionInput.city(), weatherFunctionInput.unit());
                    }
                })
                .build();


        // 2. Build the ChatClient and register the tool
        this.chatClient = chatClientBuilder
                .functions(weatherFunction) // Register our tool with the ChatClient
                .build();
    }

    @GetMapping("/weather-chat")
    public String chatWithWeatherTool(@RequestParam(value = "message", defaultValue = "What's the weather like in London?") String message) {
        ChatResponse response = chatClient.prompt()
                .user(message)
                .call()
                .chatResponse(); // Get the full chat response object

        // Check if the LLM decided to call a tool
        if (response.getResult().getOutput().getFunctionCall() != null) {
            // In a real scenario, you'd handle the tool call, execute the function,
            // and then potentially send the result back to the LLM.
            // For now, let's just indicate that a tool was called.
            return "The AI decided to call the 'getCurrentWeather' tool. " +
                   "Output: " + response.getResult().getOutput().getContent();
        } else {
            return response.getResult().getOutput().getContent();
        }
    }

    @GetMapping("/weather-agent")
    public String weatherAgent(@RequestParam(value = "query", defaultValue = "What is the temperature in New York in Celsius?") String query) {
        // This demonstrates a more "agent-like" flow where the LLM can use the tool
        // and then provide a human-readable answer.

        // The chatClient is configured with the tool.
        // We prompt the LLM. Spring AI will handle the function calling mechanism.
        // If the LLM decides to call the 'getCurrentWeather' function,
        // our WeatherService will be invoked and its result fed back to the LLM.
        return chatClient.prompt()
                .user(query)
                .call()
                .content(); // This directly gets the final content from the LLM, after tool use
    }
}
A note on the FunctionCallbackWrapper: The FunctionCallbackWrapper setup is where you define the name of your tool, its description, and the lambda that extracts arguments from the JSON provided by the LLM and calls your actual Java method (weatherService.getCurrentWeather).

3.5 Run and Test Your Agent
Run your Spring Boot application (e.g., from your IDE or ./mvnw spring-boot:run).

Open your web browser or use Postman/curl:

http://localhost:8080/weather-chat?message=What is the weather like in London right now?

Expected behavior: The LLM should recognize it needs weather data and try to invoke the getCurrentWeather tool. You should see DEBUG: Calling WeatherService... in your application logs. The response in your browser will indicate the tool was called.

http://localhost:8080/weather-agent?query=What is the temperature in New York in Celsius?

Expected behavior: The LLM should understand the query, call the getCurrentWeather tool (you'll see the DEBUG log), and then use the result to provide a natural language answer like "The temperature in New York is 22�C, and it's Sunny."

http://localhost:8080/weather-chat?message=Tell me a joke.

Expected behavior: The LLM will not call the weather tool, as it's not relevant. It will just tell you a joke directly.

This demonstrates how Spring AI bridges the gap, allowing your LLM to intelligently decide when and how to interact with your Java business logic.

4. Building More Sophisticated LLM Agents
The weather example is a starting point. Real-world LLM agents are more complex, involving multiple tools and a sophisticated decision-making process.

4.1 Orchestrating Multiple Tools
Your agent can have access to many tools: a product search API, an order placement API, an email sender, a knowledge base lookup, etc. The LLM's role is to decide which tool (or sequence of tools) to use to achieve the user's goal.

Spring AI allows you to register multiple FunctionCallbackWrapper instances with your ChatClient.Builder.

Java

// Example: Adding another tool
FunctionCallback sendEmailFunction = FunctionCallbackWrapper.builder(
        "sendEmail",
        "Send an email to a recipient with a subject and body.",
        (json) -> { /* logic to send email */ })
        .build();

this.chatClient = chatClientBuilder
        .functions(weatherFunction, sendEmailFunction) // Register multiple tools
        .build();
4.2 Handling Complex Agentic Workflows
For truly complex tasks, a simple single-turn tool call might not suffice. LLM agents often involve:

Planning: The LLM internally outlines a plan (e.g., "First, search for product. If found, add to cart. Then, confirm order.").

Execution: Executing steps based on the plan, possibly calling multiple tools sequentially.

Observation: The agent observes the results of tool calls.

Re-planning/Iteration: If a tool call fails or doesn't yield expected results, the agent can re-plan or ask for clarification.

While Spring AI provides the core tool-calling mechanism, building a full-fledged autonomous agent often involves combining it with:

State Management: Storing conversation history and intermediate steps.

Feedback Loops: Feeding tool output back to the LLM prompt.

Error Handling: Gracefully managing failed tool calls.

4.3 Agent Frameworks (Conceptual)
More advanced agentic behaviors might leverage higher-level frameworks (which Spring AI is continuously evolving to support):

Chains: A predefined sequence of LLM calls and tool uses.

Agents: The LLM decides the sequence and tools dynamically.

5. Agent Design Principles for Enterprise Java
When building LLM agents in production Java environments, consider:

Security: Ensure tool functions have appropriate access control. LLMs should only be able to invoke functions they are authorized for.

Auditability: Log all LLM inputs, tool calls, and outputs for debugging, compliance, and monitoring.

Idempotency: Design your tool functions to be idempotent where possible, meaning repeated calls have the same effect, to gracefully handle retries.

Latency & Performance: LLM API calls and tool executions can introduce latency. Design for asynchronous operations where appropriate (e.g., using Spring WebFlux or Java's Virtual Threads for non-blocking I/O).

Cost Optimization: Monitor token usage. Design prompts and tools efficiently to minimize unnecessary LLM calls.

6. The Future of Intelligent Java Applications
The ability to build LLM agents and use tools is a pivotal moment for Java development. It transforms LLMs from mere content generators into powerful, interactive components within your existing enterprise architectures.

Imagine:

An internal HR assistant that can retrieve employee data, update records, and draft emails based on natural language commands.

A customer support agent that can check order status, initiate refunds, and troubleshoot issues by integrating with your backend systems.

A financial analyst tool that queries real-time market data, performs calculations, and generates detailed reports, all orchestrated by an LLM.

Spring AI is rapidly evolving to support even more sophisticated agentic workflows, paving the way for a new generation of intelligent, automated, and hyper-responsive Java applications. The blend of Java's enterprise readiness with AI's intelligence is truly powerful.

Are you ready to build the next generation of intelligent, tool-using Java applications? Share your insights in the comments below!