This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

Advisors and Memory in ChatClient

Advisors

Every ChatClient call is executed by a chain of advisors. Advisors explains the advisor chain, the order of the advisors and the context they share. This page shows how to configure advisors on a ChatClient.

A common pattern when calling an AI model with user text is to append or augment the prompt with contextual data.

This contextual data can be of different types. Common types include:

  • Your own data: This is data the AI model hasn’t been trained on. Even if the model has seen similar data, the appended contextual data takes precedence in generating the response.

  • Conversational history: The chat model’s API is stateless. If you tell the AI model your name, it won’t remember it in subsequent interactions. Conversational history must be sent with each request to ensure previous interactions are considered when generating a response.

Advisor Configuration in ChatClient

The ChatClient fluent API provides an AdvisorSpec interface for configuring advisors. This interface offers methods to add parameters, set multiple parameters at once, and add one or more advisors to the chain.

interface AdvisorSpec {
    AdvisorSpec param(String k, Object v);
    AdvisorSpec params(Map<String, Object> p);
    AdvisorSpec advisors(Advisor... advisors);
    AdvisorSpec advisors(List<Advisor> advisors);
}
The chain runs the advisors sorted by their getOrder() value, not in the order in which you register them. The advisor with the lowest order runs first on the way to the model, and last on the way back. Each advisor modifies the prompt or the context in some way, and the changes made by one advisor are passed on to the next in the chain. See Order for the default order of the built-in advisors.

The following example combines session memory with retrieval:

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(SessionAdvisors.builder(sessionService).build())
    .build();

String answer = chatClient.prompt()
    .advisors(QuestionAnswerAdvisor.builder(vectorStore).build())
    .advisors(SessionAdvisors.session(sessionId))
    .user(userText)
    .call()
    .content();

SessionAdvisors builds a SessionTurnAdvisor (order HIGHEST_PRECEDENCE + 200) and a SessionMemoryAdvisor (order HIGHEST_PRECEDENCE + 1000), and the QuestionAnswerAdvisor has the order 0. The SessionTurnAdvisor runs first and records the turn once, outside the tool-calling loop. The SessionMemoryAdvisor then adds the conversation history to the prompt. The QuestionAnswerAdvisor runs after them, searches the vector store for the user’s question and adds the documents it finds. Registering the advisors in another order gives the same chain.

Every call must carry a session id, here through SessionAdvisors.session(sessionId). There is no default session.

Retrieval Augmented Generation

Refer to the Retrieval Augmented Generation guide.

Logging

The SimpleLoggerAdvisor is an advisor that logs the request and response data of the ChatClient. This can be useful for debugging and monitoring your AI interactions.

Spring AI supports observability for LLM and vector store interactions. Refer to the Observability guide for more information.

To enable logging, add the SimpleLoggerAdvisor to the advisor chain when creating your ChatClient. Its default order is 0, which places it inside the tool-calling loop, so it logs every request to the model and every response. To log at another place in the chain, pass a different order:

ChatResponse response = ChatClient.create(chatModel).prompt()
        .advisors(new SimpleLoggerAdvisor())
        .user("Tell me a joke?")
        .call()
        .chatResponse();

To see the logs, set the logging level for the advisor package to DEBUG:

logging.level.org.springframework.ai.chat.client.advisor=DEBUG

Add this to your application.properties or application.yaml file.

You can customize what data from ChatClientRequest and ChatResponse is logged by using the following constructor:

SimpleLoggerAdvisor(
    Function<ChatClientRequest, String> requestToString,
    Function<ChatResponse, String> responseToString,
    int order
)

Example usage:

SimpleLoggerAdvisor customLogger = new SimpleLoggerAdvisor(
    request -> "Custom request: " + request.prompt().getUserMessage(),
    response -> "Custom response: " + response.getResult(),
    0
);

This allows you to tailor the logged information to your specific needs.

Be cautious about logging sensitive information in production environments.

Tool Calling

The ChatClient always auto-registers a ToolCallingAdvisor in the advisor chain unless auto-registration is explicitly disabled (see below). This ensures that tools injected dynamically at runtime by another advisor are handled correctly, even when no static tools are configured on the call.

String response = ChatClient.builder(chatModel)
    .build()
    .prompt("What day is tomorrow?")
    .tools(new DateTimeTools())   // ToolCallingAdvisor is auto-registered
    .call()
    .content();

The ToolCallingAdvisor is registered at Ordered.HIGHEST_PRECEDENCE + 300 by default.

Disabling Auto-Registration

Globally (all calls)

Set spring.ai.chat.client.tool-calling.enabled=false to disable auto-registration for every call made from the auto-configured ChatClient:

spring.ai.chat.client.tool-calling.enabled=false

When this property is set, tools are still sent to the AI model as definitions, but tool calls in the response are not executed automatically. Use user-controlled tool execution to drive the loop yourself.

Per call

You can disable auto-registration for a single call using AdvisorParams.toolCallingAdvisorAutoRegister(false):

chatClient.prompt("What day is tomorrow?")
    .tools(new DateTimeTools())
    .advisors(AdvisorParams.toolCallingAdvisorAutoRegister(false))
    .call()
    .content();

Or you can provide your own ToolCallingAdvisor (or any other advisor implementing ToolAdvisor) — in that case auto-registration is suppressed automatically because the chain already contains a ToolAdvisor.

You can pass a custom advisor via .advisors():

chatClient.prompt("What day is tomorrow?")
    .tools(new DateTimeTools())
    .advisors(customAdvisor)    // auto-registration suppressed
    .call()
    .content();

Customizing the Default ToolCallingAdvisor

The spring.ai.chat.client.tool-calling.* properties control the auto-configured ToolCallingAdvisor:

Property Default Description

spring.ai.chat.client.tool-calling.enabled

true

Set to false to disable ToolCallingAdvisor auto-registration for all calls. Tools are still sent to the model, but tool calls are not executed automatically.

spring.ai.chat.client.tool-calling.advisor-order

Ordered.HIGHEST_PRECEDENCE + 300

Position of the auto-registered ToolCallingAdvisor in the advisor chain.

Spring Boot: advisor order property

The simplest way to tune the auto-registered advisor is through the spring.ai.chat.client.tool-calling.advisor-order property. It controls where in the advisor chain the ToolCallingAdvisor is inserted:

spring.ai.chat.client.tool-calling.advisor-order=0

The value must be lower than the order of any advisor that should run inside the tool-call loop (i.e., repeated on every iteration), and higher than any advisor that should run outside it (i.e., executed only once per user request). The default is ToolCallingAdvisor.DEFAULT_ORDER.

Spring Boot: user-controlled tool execution

To observe each iteration of the tool-calling loop — for example to forward intermediate chunks to a UI — disable the auto-registered advisor per-call and drive the loop yourself using AdvisorParams.toolCallingAdvisorAutoRegister(false). See User-Controlled Tool Execution — With ChatClient for a complete example.

Spring Boot: custom ToolCallingAdvisor.Builder bean

For deeper customization — for example to supply a custom ToolCallingManager — declare a ToolCallingAdvisor.Builder<?> bean. Spring Boot’s @ConditionalOnMissingBean on the auto-configured bean means your bean takes precedence:

@Bean
ToolCallingAdvisor.Builder<?> toolCallingAdvisorBuilder(ToolCallingManager myToolCallingManager) {
    return ToolCallingAdvisor.builder()
        .toolCallingManager(myToolCallingManager)
        .advisorOrder(Ordered.LOWEST_PRECEDENCE);
}

The ChatClient.Builder bean is then automatically wired with this custom builder.

Without Spring Boot

When not using Spring Boot auto-configuration, pass a pre-configured ToolCallingAdvisor.Builder directly to ChatClient.builder():

ToolCallingManager customManager = ToolCallingManager.builder()
    // custom resolver, exception processor, etc.
    .build();

ChatClient chatClient = ChatClient
    .builder(chatModel, observationRegistry, null, null,
            ToolCallingAdvisor.builder().toolCallingManager(customManager))
    .build();

// Every prompt that registers tools will use customManager in the auto-registered advisor
chatClient.prompt("What day is tomorrow?")
    .tools(new DateTimeTools())
    .call()
    .content();

ToolAdvisor Marker Interface

ToolAdvisor is a marker interface that signals to the ChatClient that the advisor chain already handles tool execution. Implementing this interface on a custom advisor prevents the auto-registration of a second ToolCallingAdvisor.

Chat Memory

MessageChatMemoryAdvisor and the ChatMemory API are deprecated since 2.1.0, for removal in 3.0.0, in favor of session memory; see Migrating to Session Memory.

The interface ChatMemory represents a storage for chat conversation memory. It provides methods to add messages to a conversation, retrieve messages from a conversation, and clear the conversation history.

There is currently one built-in implementation: MessageWindowChatMemory.

MessageWindowChatMemory is a chat memory implementation that maintains a window of messages up to a specified maximum size (default: 20 messages). When the number of messages exceeds this limit, older messages are evicted, but system messages are preserved. If a new system message is added, all previous system messages are removed from memory. This ensures that the most recent context is always available for the conversation while keeping memory usage bounded.

The MessageWindowChatMemory is backed by the ChatMemoryRepository abstraction which provides storage implementations for the chat conversation memory. There are several implementations available, including the InMemoryChatMemoryRepository, JdbcChatMemoryRepository, CassandraChatMemoryRepository, Neo4jChatMemoryRepository, MongoChatMemoryRepository, and RedisChatMemoryRepository.

The MemoryAdvisor.CONVERSATION_ID parameter is required for all memory advisors. It must be supplied on every call via .advisors(a → a.param(MemoryAdvisor.CONVERSATION_ID, conversationId)). Omitting it throws an IllegalArgumentException. There is no default conversation ID.

For more details and usage examples, see the Chat Memory documentation.

MemoryAdvisor Marker Interface

MemoryAdvisor is a marker interface extended by BaseChatMemoryAdvisor. DefaultChatClient uses this marker to detect downstream memory advisors in the auto-registration logic.

Custom memory advisors that do not extend BaseChatMemoryAdvisor but should participate in this detection should implement MemoryAdvisor.