Advisor System

Overview

Advisors form a chain-of-responsibility around every LLM call. Each advisor can modify the request before it reaches the LLM, inspect or transform the response after, and add context metadata for downstream advisors. Advisors are organized by domain (e.g., "SECURITY", "AUDIT") and ordered by priority.

The system provides:

• Domain-based organization — Advisors are grouped by domain, enabling bulk enable/disable operations.
• Priority ordering — Advisors execute in order of their getOrder() value (lower runs first).
• Hot reload — Advisors can be registered, unregistered, enabled, and disabled at runtime.
• Error isolation — Non-blocking advisor errors skip the advisor and continue the chain; blocking errors halt execution.

AdvisorRegistry

Central registry for managing advisor lifecycle. Thread-safe with internal caching of the enabled advisor list.

BaseAdvisor

Abstract base class implementing both CallAdvisor and StreamAdvisor. Provides the template method pattern with lifecycle hooks, error handling, and context enrichment.

Constructor

Abstract Methods (Must Implement)

Overridable Hooks

• beforeStream() — Defaults to calling beforeCall(). Override for stream-specific pre-processing.
• afterStream() — No-op by default. Override for stream-specific post-processing.
• enrichContext(Map<String, Object> context) — Adds advisor.domain, advisor.name, and advisor.timestamp to the context.
• handleBlockingError(AdvisorException e, ChatClientRequest request) — Handles blocking errors by setting error context and rethrowing.

Error Handling

AdvisorException supports two modes:

• Blocking — Halts the advisor chain and prevents the LLM call. Used for security enforcement.
• Non-blocking — Logs the error and continues the chain. Used for optional enrichment.

SecurityContextAdvisor

Injects security context (user identity, session, authentication state, authorities) into every LLM request. Supports async security context recovery through AsyncSecurityContextProvider implementations, including Redis-backed providers in distributed deployments.

Injected Context Keys

Code Examples

Implementing a Custom Advisor

@Component
public class RateLimitAdvisor extends BaseAdvisor {

    private final RateLimiter rateLimiter;

    public RateLimitAdvisor(RateLimiter rateLimiter) {
        super("INFRASTRUCTURE", "rate-limit", 10);
        this.rateLimiter = rateLimiter;
    }

    @Override
    protected ChatClientRequest beforeCall(
            ChatClientRequest request) {
        String userId = (String) request.context()
                .get("user.id");

        if (!rateLimiter.tryAcquire(userId)) {
            throw AdvisorException.blocking(
                    getDomain(), getName(),
                    "Rate limit exceeded for user: " + userId);
        }

        return request;
    }

    @Override
    protected ChatClientResponse afterCall(
            ChatClientResponse response,
            ChatClientRequest request) {
        return response;
    }
}

Managing Advisors at Runtime

// Disable all security advisors during maintenance
advisorRegistry.disableDomain("SECURITY");

// Re-enable after maintenance
advisorRegistry.enableDomain("SECURITY");

// Check registry health
AdvisorRegistry.RegistryStats stats =
        advisorRegistry.getStats();
// stats.totalAdvisors, stats.totalDomains,
// stats.advisorsPerDomain

Related