The Spring AI ChatClient offers a fluent API for communicating with an AI model. The fluent API provides methods for building the constituent parts of a prompt that gets passed to the AI model as input.

Advisors are a key part of the fluent API that intercept, modify, and enhance AI-driven interactions. The key benefits include encapsulating common Generative AI patterns, transforming data sent to and from Large Language Models (LLMs), and providing portability across various models and use cases.

Advisors process ChatClientRequest and ChatClientResponse objects. The framework chains advisors by their getOrder() values (lower values execute first), with the final advisor calling the LLM.

Spring AI provides built-in advisors for Conversation Memory, Retrieval Augmented Generation (RAG), Logging, and Guardrails. Developers can also create custom advisors.

Typical advisor structure:

public class MyAdvisor implements CallAdvisor {
    
    // 1. Sets the advisor orders
    public int getOrder() { return MY_ADVISOR_ORDER; } 

    // 2. Sets the advisor name
    public String getName() { return MY_ADVISOR_NAME; } 

    public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) {
        // 3. Pre-process the request (modify, validate, log, etc.)
        request = preProcess(request);
        // 4. Call the next advisor in the chain
        ChatClientResponse response = chain.nextCall(request);
        // 5. Post-process the response (modify, validate, log, etc.)
        return postProcess(response);
    }
}

Recursive Advisors

Here's the basic pattern for implementing a recursive advisor:

public class MyRecursiveAdvisor implements CallAdvisor {
    
    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request, CallAdvisorChain chain) {
        
        // Call the chain initially
        ChatClientResponse response = chain.nextCall(request);
        
        // Check if we need to retry
        while (!isConditionMet(response)) {
            // Modify the request based on the response
            ChatClientRequest modifiedRequest = modifyRequest(request, response);
            
            // Create a sub-chain and recurse
            response = chain.copy(this).nextCall(modifiedRequest);
        }
        
        return response;
    }
}

The key difference from non-recursive advisors is using chain.copy(this).nextCall(...) instead of chain.nextCall(...) to iterate on a copy of the inner chain. This ensures each iteration goes through the complete downstream chain, allowing other advisors to observe and intercept while maintaining proper observability.

⚠️ Important Note

Recursive Advisors are a new experimental feature in Spring AI 1.1.0-M4. They are non-streaming only, requires careful advisor ordering, can increase costs due to multiple LLM calls.

Be especially careful with inner advisors that maintain external state - they may require extra attention to maintain correctness across iterations.

Always set termination conditions and retry limits to prevent infinite loops.

Consider whether your use case benefits more from recursive advisors or from implementing an explicit while loop around ChatClient calls in your application code.

Built-in Recursive Advisors

Spring AI 1.1.0-M4 provides two recursive advisors:

ToolCallAdvisor

Example Usage:

var toolCallAdvisor = ToolCallAdvisor.builder()
    .toolCallingManager(toolCallingManager)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
    .build();
        
public record Request(String location) {}

var weatherTool = FunctionToolCallback.builder("getWeather", (Request request) -> "15.0°C")
        .description("Gets the weather for a location")
        .inputType(Request.class)
        .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultToolCallbacks(weatherTool) // Tools registration
    .defaultAdvisors(toolCallAdvisor) // Tool Call Execution as Advisor
    .build();

String response = chatClient.prompt()
    .user("What's the weather in Paris and Amsterdam and convert the temperature to Fahrenheit?")
    .call()
    .content();

Note: By default, the ToolCallAdvisor's order is set close to Ordered.HIGHEST_PRECEDENCE to ensure the advisor executes first in the chain (first for request processing, last for response processing), allowing inner advisors to intercept and process tool request and response messages.

When a tool execution has returnDirect=true, the advisor executes the tool, detects the flag, breaks the loop, and returns the output directly to the client without sending it to the LLM. This reduces latency when the tool's output is the final answer.

💡 Demo Project: See a complete working example of the ToolCallAdvisor in the Recursive Advisor Demo project.

StructuredOutputValidationAdvisor

The StructuredOutputValidationAdvisor validates structured JSON output against a generated schema and retries if validation fails:

• Automatically generates JSON schemas from expected output types
• Validates LLM responses againsts the schema and retries with validation error messages
• Configurable maximum retry attempts
• Supports custom ObjectMapper for JSON processing

Example Usage:

public record ActorFilms(String actor, List<String> movies) {}

var validationAdvisor = StructuredOutputValidationAdvisor.builder()
    .outputType(ActorFilms.class)
    .maxRepeatAttempts(3)
    .build();

var chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(validationAdvisor)
    .build();

ActorFilms actorFilms = chatClient.prompt()
    .user("Generate the filmography for Tom Hanks")
    .call()
    .entity(ActorFilms.class);

When validation fails, the advisor augments the prompt with error details and retries up to the configured maximum attempts.

Note: By default, the StructuredOutputValidationAdvisor's order is set close to Ordered.LOWEST_PRECEDENCE to ensure the advisor executes toward the end of the chain (but before the model call), meaning it's last for request processing and first for response processing.

Best Practices

• Set Clear Termination Conditions: Ensure loops have definite exit conditions to prevent infinite loops
• Use Appropriate Ordering: Place recursive advisors early in the chain to allow other advisors to observe iterations, or late to prevent observation
• Provide Feedback: Augment retry requests with information about why the retry is needed to help the LLM improve
• Limit Iterations: Set maximum attempt limits to prevent runaway execution
• Monitor Execution: Use Spring AI's observability features to track iteration counts and performance
• Choose the Right Approach: Evaluate whether recursive advisors or explicit while loops around ChatClient calls better suit your specific use case and architecture

Performance Considerations

Recursive advisors increase the number of LLM calls, affecting:

• Cost: More API calls increase costs
• Latency: Multiple iterations add processing time
• Token Usage: Each iteration consumes additional tokens

To optimize set reasonable retry limits and monitor iteration counts. Cache intermediate results when possible

Resources

• Recursive Advisors Documentation
• Advisors API Guide
• ChatClient API Documentation
• Spring AI GitHub Repository