Spring Boot 4 Complete Guide · Lekcja

Wywoływanie narzędzi i doradcy agentów

Rozszerzaj modele o wywoływalne narzędzia Java i komponuj ich działanie za pomocą doradców żądań i odpowiedzi

Wywoływanie narzędzi i doradcy agentów to bezpłatna lekcja Spring Boot 4 Complete Guide na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Spring Boot 4 Complete Guide, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Spring Boot 4 Complete Guide zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

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.

Często zadawane pytania

Czy lekcja „Wywoływanie narzędzi i doradcy agentów” jest bezpłatna?

Tak — pełny tekst „Wywoływanie narzędzi i doradcy agentów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Spring Boot 4 Complete Guide, przejdź na CoddyKit PRO. Kurs Spring Boot 4 Complete Guide zawiera 4 lekcji w sumie.

Co nauczysz się w „Wywoływanie narzędzi i doradcy agentów”?

Rozszerzaj modele o wywoływalne narzędzia Java i komponuj ich działanie za pomocą doradców żądań i odpowiedzi Ćwiczysz Spring Boot 4 Complete Guide z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Spring Boot 4 Complete Guide?

Nie wymagamy żadnego doświadczenia. Spring Boot 4 Complete Guide w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.

Ile czasu zajmuje lekcja „Wywoływanie narzędzi i doradcy agentów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Spring Boot 4 Complete Guide?

Tak. Każda lekcja Spring Boot 4 Complete Guide zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

ChatClient, prompty i ustrukturyzowane dane wyjściowe
Embeddingi i pobieranie z magazynów wektorowych
Potoki generowania wspomaganego pobieraniem
Wywoływanie narzędzi i doradcy agentów

← Powrót do Spring Boot 4 Complete Guide