Agentic systems are moving from demos into production, and Java teams are asking the same question: how do we structure them so they stay reliable, testable, and easy to change? Spring AI gives us the building blocks, but the building blocks alone do not make an agent. The design patterns do.

In this article I walk through five agentic patterns you can build with Spring AI: Router, Retrieval-Augmented Generation (RAG), Chain of Thought, Supervisor, and Guardrails & Validation. For each one I explain the problem it solves, when to use it, and a small Java example. The code is intentionally compact so you can see the structure rather than a full application.

This is the first in a series. The upcoming posts will explain each of the five Spring AI agentic patterns in depth, with complete projects you can run.

The Problem: LLM Calls Are Not Architecture

A single call to a language model is easy. A system that routes requests, looks up company knowledge, reasons through multi-step tasks, delegates work, and checks its own answers is much harder. Without structure, these concerns end up tangled inside one giant prompt and one giant service class.

Agentic patterns separate those concerns. Each pattern is a reusable shape for a specific kind of problem, and you can combine them. A production assistant often uses a router at the entry point, RAG for knowledge, and guardrails on the way out.

All examples below assume a Spring Boot application with a ChatClient bean, which Spring AI auto-configures from your chosen model provider:

@Configuration class AiConfig { @Bean ChatClient chatClient(ChatClient.Builder builder) { return builder.build(); } } 

Pattern 1: Router

The problem

Incoming requests vary widely. A customer asking about a refund should not reach the same logic as a developer asking about an API error. Sending everything to one general prompt makes answers vaguer and prompts longer.

The solution

A router inspects the request, classifies its intent, and dispatches it to a specialized handler. The classification step is itself an LLM call with a constrained output, so the router can only pick from known routes.

Java example

enum Intent { BILLING, TECHNICAL, GENERAL } @Service class RouterService { private final ChatClient chatClient; private final BillingAgent billingAgent; private final TechnicalAgent technicalAgent; private final GeneralAgent generalAgent; RouterService(ChatClient chatClient, BillingAgent billingAgent, TechnicalAgent technicalAgent, GeneralAgent generalAgent) { this.chatClient = chatClient; this.billingAgent = billingAgent; this.technicalAgent = technicalAgent; this.generalAgent = generalAgent; } String handle(String userMessage) { Intent intent = classify(userMessage); return switch (intent) { case BILLING -> billingAgent.answer(userMessage); case TECHNICAL -> technicalAgent.answer(userMessage); case GENERAL -> generalAgent.answer(userMessage); }; } private Intent classify(String userMessage) { String label = chatClient.prompt() .system(""" Classify the user message into exactly one label: BILLING, TECHNICAL, or GENERAL. Reply with the label only. """) .user(userMessage) .call() .content() .trim() .toUpperCase(); try { return Intent.valueOf(label); } catch (IllegalArgumentException ex) { return Intent.GENERAL; // safe fallback for unexpected output } } } 

When to use it

Use a router when you have distinct domains with different tools, data sources, or system prompts. Always keep a fallback route, because the model will occasionally return something you did not expect.

Pattern 2: Retrieval-Augmented Generation (RAG)

The problem

A model knows what it learned during training. It does not know your internal documentation, last week's policy change, or your product catalog. Asking it to answer from memory produces confident but wrong answers.

The solution

RAG retrieves relevant documents at query time and includes them in the prompt. The model answers based on that context. Spring AI provides VectorStore abstractions and advisors that wire retrieval into the chat flow.

Java example

@Configuration class RagConfig { @Bean ChatClient ragChatClient(ChatClient.Builder builder, VectorStore vectorStore) { return builder .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore) .searchRequest(SearchRequest.builder() .topK(4) .similarityThreshold(0.7) .build()) .build()) .build(); } } @Service class PolicyAssistant { private final ChatClient ragChatClient; PolicyAssistant(ChatClient ragChatClient) { this.ragChatClient = ragChatClient; } String ask(String question) { return ragChatClient.prompt() .system("Answer only from the provided context. If the context does not contain the answer, say so.") .user(question) .call() .content(); } } 

Ingestion is a separate step. You split documents into chunks, generate embeddings, and store them in the vector store, typically on application startup or in a scheduled job.

When to use it

Use RAG whenever correct answers depend on data the model does not have, or data that changes often. Keep chunks focused, store metadata such as source and date, and instruct the model to refuse when the context is insufficient.

Pattern 3: Chain of Thought

The problem

Some tasks, such as calculating a loan schedule, comparing options against several constraints, or diagnosing a multi-step failure, produce unreliable results when the model jumps straight to a final answer.

The solution

Chain of Thought asks the model to break the problem into intermediate steps before answering. You can make the reasoning explicit in the prompt, or structure it into separate calls where each step's output feeds the next. The second approach is more controllable and easier to test.

Java example

@Service class RiskAnalysisService { private final ChatClient chatClient; RiskAnalysisService(ChatClient chatClient) { this.chatClient = chatClient; } String assess(String transactionDetails) { // Step 1: extract the facts String facts = chatClient.prompt() .system("Extract the factual fields from the transaction as a short bulleted list. Do not interpret them.") .user(transactionDetails) .call() .content(); // Step 2: reason over the facts, one step at a time String analysis = chatClient.prompt() .system(""" Given these facts, reason step by step: 1. List the signals that increase risk. 2. List the signals that decrease risk. 3. Weigh them and state a risk level: LOW, MEDIUM, or HIGH. """) .user(facts) .call() .content(); // Step 3: produce the final, concise verdict return chatClient.prompt() .system("Summarize the analysis as a one-paragraph recommendation for a human reviewer.") .user(analysis) .call() .content(); } } 

When to use it

Use this pattern when the task has a clear sequence of sub-problems. Splitting steps also makes each stage observable: you can log intermediate outputs, write tests for each stage, and see exactly where a wrong answer started. Keep in mind that every step adds latency and cost, so do not split a simple task.

Pattern 4: Supervisor

The problem

Some goals need several different skills. Writing a technical report might require research, drafting, and editing. One prompt that tries to do all of them tends to do none of them well, and the context window fills up quickly.

The solution

A supervisor agent receives the goal, decides which specialized worker agents to call, collects their results, and synthesizes a final answer. Each worker has its own system prompt, tools, and narrow responsibility. The supervisor coordinates; it does not do the work itself.

Java example

@Service class ReportSupervisor { private final ChatClient chatClient; ReportSupervisor(ChatClient chatClient) { this.chatClient = chatClient; } String produceReport(String topic) { // Worker 1: research String research = worker(""" You are a research analyst. Return key facts, numbers, and sources as bullet points. """, topic); // Worker 2: drafting String draft = worker(""" You are a technical writer. Turn the provided research into a structured draft with an introduction, three sections, and a conclusion. """, research); // Worker 3: editing String edited = worker(""" You are an editor. Improve clarity and remove repetition. Keep the structure. """, draft); // Supervisor: final check and synthesis return chatClient.prompt() .system(""" You are the supervisor. Review the report for completeness against the topic. Return the final report. If something is missing, add a short note at the end. """) .user("Topic: " + topic + "\n\nReport:\n" + edited) .call() .content(); } private String worker(String systemPrompt, String input) { return chatClient.prompt() .system(systemPrompt) .user(input) .call() .content(); } } 

In a larger system, each worker would be its own Spring bean with its own ChatClient, tools, and memory. The supervisor can also decide dynamically which workers to call, rather than following a fixed sequence.

When to use it

Use a supervisor when the work naturally splits into roles and the sequence or selection of roles depends on the input. Keep the number of workers small at first. Every additional worker adds coordination cost and new failure modes.

Pattern 5: Guardrails & Validation

The problem

Model output is probabilistic. It can contain personal data it should not reveal, invented facts, unsafe instructions, or a format your code cannot parse. Trusting it directly in a business workflow is a risk.

The solution

Guardrails sit around the model. Input guardrails screen what goes in. Output guardrails verify what comes out. Validation can be deterministic, such as regular expressions and schema checks, or model-based, where a second model call judges the answer against a policy.

Java example

@Service class GuardedAssistant { private static final Pattern EMAIL = Pattern.compile("[\\w.+-]+@[\\w-]+\\.[\\w.]+"); private final ChatClient chatClient; GuardedAssistant(ChatClient chatClient) { this.chatClient = chatClient; } String answer(String userMessage) { if (containsPersonalData(userMessage)) { return "Please do not share personal contact details in this chat."; } String draft = chatClient.prompt() .system("You are a customer support assistant. Answer briefly and politely.") .user(userMessage) .call() .content(); // Deterministic check: never return personal data in the output if (containsPersonalData(draft)) { return "I cannot share that information."; } // Model-based check: a second call judges the policy compliance String verdict = chatClient.prompt() .system(""" Check the answer against these rules: no promises of refunds, no legal or medical advice, no invented order numbers. Reply with PASS or FAIL only. """) .user(draft) .call() .content() .trim(); return "PASS".equalsIgnoreCase(verdict) ? draft : "Let me connect you with a human agent who can help with this request."; } private boolean containsPersonalData(String text) { return EMAIL.matcher(text).find(); } } 

For structured output, Spring AI can map the response to a Java record using .entity(...). Combined with bean validation, that turns a free-text answer into a typed object you can check before using it.

When to use it

Apply guardrails to every agent that talks to users or triggers actions. Start with deterministic checks because they are cheap, predictable, and easy to test. Add model-based checks where rules are semantic, and remember that the judging model can also make mistakes, so log its verdicts.

Combining the Patterns

These patterns work well together. A production flow might look like this:

  1. A guardrail screens the incoming message.
  2. A router classifies the intent.
  3. A RAG step retrieves policy or product documents for the selected domain.
  4. A supervisor coordinates workers when the task needs several skills.
  5. Chain of thought structures any multi-step reasoning inside a worker.
  6. A final guardrail validates the answer before it reaches the user.

Start with the smallest combination that solves your problem. A router and RAG cover many real assistants. Add supervisor and chain-of-thought steps only when a single agent cannot handle the task reliably.

Best Practices

  • Keep prompts in version control. Treat them as code, and review changes the same way.
  • Test each pattern in isolation. Mock the ChatClient for routing logic and use a fixed set of documents for RAG evaluation.
  • Log intermediate outputs. Routing decisions, retrieved chunks, and validation verdicts are the fastest way to debug an agent.
  • Set timeouts and limits. A supervisor that loops without a stop condition will drain your budget.
  • Prefer narrow agents. A worker with one clear job is easier to evaluate than a general-purpose one.
  • Measure quality. Build a small evaluation set of real questions and expected outcomes before tuning prompts.

What Comes Next

This article introduced the five patterns at a high level. In the next posts, I will explain each Spring AI agentic pattern in depth, one at a time, with complete Spring Boot projects, test strategies, and the trade-offs I have seen in real systems. If you are building agents in Java, follow along and tell me which pattern you want to see first.

Key Takeaways

  • Agentic systems need architecture, not just prompts.
  • Router sends each request to the right specialist.
  • RAG grounds answers in your own data.
  • Chain of Thought makes multi-step reasoning explicit and testable.
  • Supervisor coordinates specialized workers.
  • Guardrails & Validation keep outputs safe, accurate, and compliant.

Start small, measure everything, and add complexity only when the simpler pattern fails.