Spring Boot 4 Complete Guide · Lezione

Chiamate agli strumenti e advisor degli agenti

Estenda i modelli con strumenti Java invocabili e componga il comportamento usando advisor per richieste e risposte.

Chiamate agli strumenti e advisor degli agenti è una lezione Spring Boot 4 Complete Guide gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Spring Boot 4 Complete Guide, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Spring Boot 4 Complete Guide include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Why Tool Calling Matters

Large language models can reason over text, but they cannot fetch a live order status, query your database, or call a payment gateway on their own. Tool calling (also called function calling) bridges that gap.

The model decides when a tool is needed based on the user's request.
Spring AI invokes the matching Java method and feeds the result back into the conversation.
The model then produces a grounded, final answer.

In Spring AI, a tool is just an ordinary Java method annotated with @Tool. The framework reads the method signature and JavaDoc-style description, generates a JSON schema, and exposes it to the model.

Defining a Tool with @Tool

Annotate a method with @Tool and give it a clear description. The model uses that description to decide whether to call it, so write it as if you were instructing a junior developer.

Use @ToolParam to describe individual arguments.
Return types are serialized to JSON automatically.
Keep the method deterministic and side-effect-aware.

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import java.time.LocalDate;

@Component
class DateTools {

    @Tool(description = "Get the number of days between today and a given target date")
    int daysUntil(@ToolParam(description = "Target date in ISO-8601 format, e.g. 2026-12-31") String targetDate) {
        LocalDate target = LocalDate.parse(targetDate);
        return (int) java.time.temporal.ChronoUnit.DAYS.between(LocalDate.now(), target);
    }
}

Registering Tools on a ChatClient Call

Tools are attached per request through the fluent ChatClient API. Pass an instance whose annotated methods become callable tools for that exchange.

.tools(Object...) registers one or more tool-bearing beans.
The model may issue zero, one, or several tool calls before answering.
Spring AI runs the full call loop transparently and returns the final text.

import org.springframework.ai.chat.client.ChatClient;

class AssistantService {
    private final ChatClient chatClient;

    AssistantService(ChatClient.Builder builder, DateTools dateTools) {
        this.chatClient = builder.build();
    }

    String ask(String userText, DateTools dateTools) {
        return chatClient.prompt()
                .user(userText)
                .tools(dateTools)
                .call()
                .content();
    }
}

The Tool Call Loop

Understanding the loop is essential for C2-level work. When the model requests a tool, Spring AI does not return control to you by default; it executes the tool and continues the conversation automatically.

The model returns an assistant message containing one or more tool call requests.
Spring AI matches each request to a registered method and invokes it.
Results are wrapped as tool response messages and appended to the prompt.
The model is called again with the enriched context until it emits a normal text answer.

This default behavior is driven by the framework's ToolCallingManager.

Programmatic Tools with FunctionToolCallback

Annotations are convenient, but sometimes you need tools defined at runtime or from a lambda. Use FunctionToolCallback to register a Function with an explicit name, description, and input type.

The input type drives JSON schema generation.
You stay in full control of serialization and naming.
Useful for dynamically discovered capabilities.

import org.springframework.ai.tool.function.FunctionToolCallback;
import java.util.function.Function;

record WeatherRequest(String city) {}
record WeatherResponse(String city, double tempC) {}

class WeatherTool {
    static FunctionToolCallback<WeatherRequest, WeatherResponse> callback() {
        Function<WeatherRequest, WeatherResponse> fn =
                req -> new WeatherResponse(req.city(), 21.5);
        return FunctionToolCallback.builder("currentWeather", fn)
                .description("Get the current temperature in Celsius for a city")
                .inputType(WeatherRequest.class)
                .build();
    }
}

Controlling Execution: returnDirect

Sometimes a tool's raw result should be returned straight to the caller without another model round-trip, for example when the tool already produced the final user-facing payload.

Set returnDirect = true on @Tool to short-circuit the loop.
The framework returns the tool result instead of feeding it back to the model.
This saves tokens and latency but skips the model's natural-language framing.

import org.springframework.ai.tool.annotation.Tool;

class TicketTools {

    @Tool(description = "Open a support ticket and return its tracking id", returnDirect = true)
    String openTicket(String summary) {
        // Persist and return immediately; the id is the final answer
        return "TICKET-" + Math.abs(summary.hashCode() % 100000);
    }
}

Introducing Advisors

Where tools extend what the model can do, advisors intercept and shape how each request and response flows. An advisor is a middleware in the ChatClient pipeline.

Request advisors mutate the prompt before it reaches the model (inject context, retrieve documents, add system instructions).
Response advisors post-process the model's output (logging, redaction, safety checks).
Advisors are chained and ordered, much like servlet filters.

Spring AI ships several built-in advisors and lets you write your own by implementing the advisor interfaces.

Built-in Memory and RAG Advisors

Two of the most used built-in advisors:

MessageChatMemoryAdvisor — injects prior conversation turns so the model has memory across requests, backed by a ChatMemory store.
QuestionAnswerAdvisor — performs retrieval-augmented generation by querying a VectorStore and prepending relevant documents.

You register them on the builder so they apply to every call, or per-prompt for one-off behavior.

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.memory.ChatMemory;
import org.springframework.ai.chat.client.advisor.vectorstore.QuestionAnswerAdvisor;
import org.springframework.ai.vectorstore.VectorStore;

class RagChatConfig {
    ChatClient chatClient(ChatClient.Builder builder, ChatMemory memory, VectorStore store) {
        return builder
                .defaultAdvisors(
                        MessageChatMemoryAdvisor.builder(memory).build(),
                        QuestionAnswerAdvisor.builder(store).build())
                .build();
    }
}

Writing a Custom Advisor

Implement CallAdvisor to participate in the synchronous call chain. The key method receives the request, calls chain.nextCall(...), and can transform the response.

getName() identifies the advisor.
getOrder() controls position; lower runs earlier on the request side.
Wrap nextCall to add logging, timing, or content filtering.

import org.springframework.ai.chat.client.ChatClientRequest;
import org.springframework.ai.chat.client.ChatClientResponse;
import org.springframework.ai.chat.client.advisor.api.CallAdvisor;
import org.springframework.ai.chat.client.advisor.api.CallAdvisorChain;

class LoggingAdvisor implements CallAdvisor {

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) {
        long start = System.nanoTime();
        ChatClientResponse response = chain.nextCall(request);
        long ms = (System.nanoTime() - start) / 1_000_000;
        System.out.println("[advisor] call took " + ms + "ms");
        return response;
    }

    @Override
    public String getName() { return "logging"; }

    @Override
    public int getOrder() { return 0; }
}

Advisor Ordering and the Chain

Advisors form an ordered chain. Picture an onion: on the way in advisors run from lowest order to highest, and on the way out the responses unwind in reverse.

A memory advisor with a low order injects history early so RAG and tools see it.
A safety/redaction advisor often sits at a high order to inspect the final text last.
Order ties are resolved by registration sequence; be explicit with getOrder() to avoid surprises.

Because tools and advisors both operate on the same prompt, design their interaction deliberately: advisors prepare context, tools fetch live data, and a final response advisor can sanitize the merged result.

Composing Tools and Advisors Together

Real agents combine both mechanisms in a single fluent call. Here the client carries default memory and RAG advisors, while a domain tool is attached for this request.

Advisors enrich the prompt with history and retrieved knowledge.
The model may still call the tool to obtain live, authoritative data.
The result is an agent that remembers, grounds, and acts.

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.api.Advisor;

class OrderAgent {
    private final ChatClient chatClient;

    OrderAgent(ChatClient chatClient) { this.chatClient = chatClient; }

    String handle(String conversationId, String userText, OrderTools tools) {
        return chatClient.prompt()
                .user(userText)
                .advisors(a -> a.param("chat_memory_conversation_id", conversationId))
                .tools(tools)
                .call()
                .content();
    }
}

class OrderTools { /* @Tool methods omitted */ }

Quick Check

Test your understanding of the tool call loop and advisor design.

Recap

You now know how to extend models with callable Java code and compose request/response behavior:

Tools are Java methods marked with @Tool (or built via FunctionToolCallback) that the model invokes to fetch data or act.
Spring AI runs the tool call loop automatically; returnDirect = true short-circuits it.
Advisors are pipeline middleware: request advisors enrich the prompt (memory, RAG), response advisors post-process output (logging, safety).
Advisors are ordered and unwind like an onion; design tool/advisor interaction deliberately.
Combine memory + RAG advisors with domain tools to build agents that remember, ground, and act.

Domande Frequenti

La lezione «Chiamate agli strumenti e advisor degli agenti» è gratuita?

Sì — il testo completo di «Chiamate agli strumenti e advisor degli agenti» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Spring Boot 4 Complete Guide, passa a CoddyKit PRO. Il corso Spring Boot 4 Complete Guide include 4 lezioni in totale.

Cosa imparerò in «Chiamate agli strumenti e advisor degli agenti»?

Estenda i modelli con strumenti Java invocabili e componga il comportamento usando advisor per richieste e risposte. Eserciti Spring Boot 4 Complete Guide con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Spring Boot 4 Complete Guide?

Non è richiesta alcuna esperienza precedente. Spring Boot 4 Complete Guide su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Chiamate agli strumenti e advisor degli agenti»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Spring Boot 4 Complete Guide?

Sì. Ogni lezione Spring Boot 4 Complete Guide include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

ChatClient, prompt e output strutturato
Embeddings e recupero da vector store
Pipeline di generazione aumentata dal recupero
Chiamate agli strumenti e advisor degli agenti

← Torna a Spring Boot 4 Complete Guide