Agentic Patterns

package com.example.docsassistant;

import java.util.List;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Component;

/** Prompt chaining: each step receives the previous step's output. */
@Component
public class DocsChainWorkflow {

    private static final List<String> STEPS = List.of(
            "Extract the technical claims from the text below as a bullet list.",
            "Remove every claim that is not about Spring AI, then keep the bullet list format.",
            "Rewrite the bullets as a two-sentence summary for a release note.");

    private final ChatClient chatClient;

    public DocsChainWorkflow(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String run(String text) {
        String current = text;
        for (String step : STEPS) {
            current = this.chatClient.prompt()
                    .system(step)
                    .user(current)
                    .call()
                    .content();
        }
        return current;
    }
}

package com.example.docsassistant;

import java.util.Map;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Component;

/** Routing: classify first with a typed reply, then answer with the specialist prompt. */
@Component
public class DocsRoutingWorkflow {

    public enum Route { HOW_TO, REFERENCE, TROUBLESHOOTING }

    record Classification(Route route, String reason) { }

    private static final Map<Route, String> SPECIALISTS = Map.of(
            Route.HOW_TO, "You write short step-by-step guides. Use numbered steps.",
            Route.REFERENCE, "You answer with exact names and property keys, no prose around them.",
            Route.TROUBLESHOOTING, "You ask for the error message first, then list the three likeliest causes.");

    private final ChatClient chatClient;

    public DocsRoutingWorkflow(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String run(String question) {
        Classification c = this.chatClient.prompt()
                .system("Classify the question into one route: HOW_TO, REFERENCE or TROUBLESHOOTING.")
                .user(question)
                .call()
                .entity(Classification.class);
        Route route = c == null || c.route() == null ? Route.HOW_TO : c.route();
        return this.chatClient.prompt()
                .system(SPECIALISTS.get(route))
                .user(question)
                .call()
                .content();
    }
}

package com.example.docsassistant;

import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Component;

/** Parallelisation (sectioning): the same instruction applied to independent inputs at once. */
@Component
public class DocsParallelWorkflow {

    private final ChatClient chatClient;

    // one virtual thread per call; the model provider's rate limit is the real bound
    private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

    public DocsParallelWorkflow(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public List<String> summarise(List<String> pages) {
        List<CompletableFuture<String>> futures = pages.stream()
                .map(page -> CompletableFuture.supplyAsync(() -> this.chatClient.prompt()
                        .system("Summarise the page in one sentence.")
                        .user(page)
                        .call()
                        .content(), this.executor))
                .toList();
        return futures.stream().map(CompletableFuture::join).toList();
    }
}

package com.example.docsassistant;

import java.util.List;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Component;

/** Orchestrator-workers: the model decides the sub-tasks at run time, workers execute them. */
@Component
public class DocsOrchestratorWorkers {

    record Plan(String analysis, List<SubTask> tasks) { }

    record SubTask(String title, String instruction) { }

    private final ChatClient chatClient;

    public DocsOrchestratorWorkers(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String run(String request) {
        Plan plan = this.chatClient.prompt()
                .system("Split the documentation request into at most four independent sub-tasks.")
                .user(request)
                .call()
                .entity(Plan.class);
        if (plan == null || plan.tasks() == null) {
            return "";
        }
        StringBuilder result = new StringBuilder();
        for (SubTask task : plan.tasks()) {
            String section = this.chatClient.prompt()
                    .system("You are a technical writer. Do exactly the sub-task you are given.")
                    .user(task.instruction())
                    .call()
                    .content();
            result.append("## ").append(task.title()).append("\n\n").append(section).append("\n\n");
        }
        return result.toString();
    }
}

package com.example.docsassistant;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.stereotype.Component;

/** Evaluator-optimizer: generate, judge, feed the critique back, stop on PASS or after a fixed budget. */
@Component
public class DocsEvaluatorOptimizer {

    public enum Verdict { PASS, NEEDS_WORK }

    record Evaluation(Verdict verdict, String feedback) { }

    private static final int MAX_ROUNDS = 3;

    private final ChatClient chatClient;

    public DocsEvaluatorOptimizer(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String run(String task) {
        String draft = this.chatClient.prompt().user(task).call().content();
        for (int round = 1; round < MAX_ROUNDS; round++) {
            Evaluation evaluation = this.chatClient.prompt()
                    .system("Judge the draft against the task. Reply PASS only if it is complete and accurate.")
                    .user("Task: " + task + "\n\nDraft:\n" + draft)
                    .call()
                    .entity(Evaluation.class);
            if (evaluation == null || evaluation.verdict() == Verdict.PASS) {
                break;
            }
            draft = this.chatClient.prompt()
                    .user("Task: " + task + "\n\nPrevious draft:\n" + draft
                            + "\n\nFeedback to address:\n" + evaluation.feedback())
                    .call()
                    .content();
        }
        return draft;
    }
}

package com.example.docsassistant;

import static org.assertj.core.api.Assertions.assertThat;

import java.util.List;

import org.junit.jupiter.api.Test;
import org.springframework.ai.chat.client.ChatClient;

class WorkflowsTest {

    @Test
    void chainPassesEachOutputToTheNextStep() {
        ScriptedChatModel model = new ScriptedChatModel(false)
                .then(ScriptedChatModel.text("claims"))
                .then(ScriptedChatModel.text("spring ai claims"))
                .then(ScriptedChatModel.text("summary"));
        String result = new DocsChainWorkflow(ChatClient.builder(model)).run("input");
        assertThat(result).isEqualTo("summary");
        assertThat(model.prompts.get(1).getContents()).contains("claims");
        assertThat(model.prompts.get(2).getContents()).contains("spring ai claims");
    }

    @Test
    void routingUsesTheSpecialistForTheClassifiedRoute() {
        ScriptedChatModel model = new ScriptedChatModel(false)
                .then(ScriptedChatModel.text("{\"route\":\"REFERENCE\",\"reason\":\"asks for a key\"}"))
                .then(ScriptedChatModel.text("spring.ai.retry.max-attempts"));
        String result = new DocsRoutingWorkflow(ChatClient.builder(model)).run("Which key sets retries?");
        assertThat(result).isEqualTo("spring.ai.retry.max-attempts");
        assertThat(model.prompts.get(1).getSystemMessage().getText()).contains("exact names");
    }

    @Test
    void orchestratorRunsOneWorkerPerSubTask() {
        ScriptedChatModel model = new ScriptedChatModel(false)
                .then(ScriptedChatModel.text("{\"analysis\":\"two parts\",\"tasks\":["
                        + "{\"title\":\"Setup\",\"instruction\":\"write setup\"},"
                        + "{\"title\":\"Usage\",\"instruction\":\"write usage\"}]}"))
                .then(ScriptedChatModel.text("setup text"))
                .then(ScriptedChatModel.text("usage text"));
        String result = new DocsOrchestratorWorkers(ChatClient.builder(model)).run("document the starter");
        assertThat(result).contains("## Setup", "setup text", "## Usage", "usage text");
        assertThat(model.prompts).hasSize(3);
    }

    @Test
    void evaluatorOptimizerStopsOnPassAndOtherwiseAfterThreeRounds() {
        ScriptedChatModel passes = new ScriptedChatModel(false)
                .then(ScriptedChatModel.text("draft 1"))
                .then(ScriptedChatModel.text("{\"verdict\":\"PASS\",\"feedback\":\"\"}"));
        assertThat(new DocsEvaluatorOptimizer(ChatClient.builder(passes)).run("task")).isEqualTo("draft 1");
        assertThat(passes.prompts).hasSize(2);

        ScriptedChatModel stubborn = new ScriptedChatModel(false)
                .then(ScriptedChatModel.text("draft 1"))
                .then(ScriptedChatModel.text("{\"verdict\":\"NEEDS_WORK\",\"feedback\":\"add units\"}"))
                .then(ScriptedChatModel.text("draft 2"))
                .then(ScriptedChatModel.text("{\"verdict\":\"NEEDS_WORK\",\"feedback\":\"add example\"}"))
                .then(ScriptedChatModel.text("draft 3"));
        assertThat(new DocsEvaluatorOptimizer(ChatClient.builder(stubborn)).run("task")).isEqualTo("draft 3");
        assertThat(stubborn.prompts).hasSize(5);
    }

    @Test
    void parallelWorkflowKeepsInputOrder() {
        // a model that answers with the page it was given, so the order can be checked
        org.springframework.ai.chat.model.ChatModel echo = prompt -> ScriptedChatModel.text(
                "sum:" + prompt.getUserMessage().getText());
        List<String> result = new DocsParallelWorkflow(ChatClient.builder(echo)).summarise(List.of("a", "b", "c"));
        assertThat(result).containsExactly("sum:a", "sum:b", "sum:c");
    }
}

package com.example.docsassistant;

import org.springaicommunity.agent.advisors.AutoMemoryToolsAdvisor;
import org.springaicommunity.agent.tools.SkillsTool;
import org.springaicommunity.agent.tools.TodoWriteTool;
import org.springaicommunity.agent.tools.task.TaskTool;
import org.springaicommunity.agent.tools.task.claude.ClaudeSubagentReferences;
import org.springaicommunity.agent.tools.task.claude.ClaudeSubagentType;
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.tool.ToolCallback;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * DocsAssistant as a small agent: skills loaded on demand, a task tool that delegates to subagents defined in
 * Markdown files, a to-do list the model keeps up to date, and a per-user memory directory it can read and write through six tools.
 * The main agent has no ShellTools or FileSystemTools, but TaskTool with ClaudeSubagentType always adds the built-in
 * Bash and general-purpose subagents, which have a shell and file writes: run this only inside a sandbox.
 */
@Configuration(proxyBeanMethods = false)
class DocsAgentConfig {

    @Bean
    ChatClient docsAgent(ChatClient.Builder builder, ChatMemory chatMemory, DocsTools docsTools) {
        ToolCallback skills = SkillsTool.builder()
                .addSkillsDirectory("src/main/resources/skills")
                .build();

        // the "default" builder every subagent starts from; tools set here reach every subagent
        ChatClient.Builder subagentBuilder = builder.clone().defaultTools(docsTools);

        ToolCallback task = TaskTool.builder()
                .subagentTypes(ClaudeSubagentType.builder()
                        .chatClientBuilder("default", subagentBuilder)
                        .build())
                .subagentReferences(ClaudeSubagentReferences.fromRootDirectory("src/main/resources/agents"))
                .build();

        return builder
                .defaultSystem("You are DocsAssistant. Plan with the to-do list, load a skill before using its topic, "
                        + "and delegate research to a subagent instead of doing it in this conversation.")
                .defaultTools(docsTools, skills, task,
                        TodoWriteTool.builder().build())
                .defaultAdvisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
                .build();
    }

    /**
     * The six memory tools and their system prompt, confined to one user's directory. This client is shared by every
     * user, so attach this per request: docsAgent.prompt(question).advisors(memoryFor(userId)).call().content().
     */
    static AutoMemoryToolsAdvisor memoryFor(String userId) {
        // an internal id, not an e-mail address: it becomes a directory name
        if (!userId.matches("[A-Za-z0-9_-]{1,64}")) {
            throw new IllegalArgumentException("userId is not a safe directory name");
        }
        return AutoMemoryToolsAdvisor.builder().memoriesRootDirectory("build/agent-memory/" + userId).build();
    }
}

---
name: release-notes
description: How DocsAssistant writes release notes. Use when asked to summarise changes between versions.
---

# Release notes

1. Group changes as Added, Changed, Fixed.
2. Name each property key exactly as it appears in the docs.
3. Never invent a version number; ask the user if it is missing.

---
name: docs-researcher
description: Finds and quotes the documentation sections that answer a question. Use for research before writing.
tools: searchDocs
---

You research documentation. Call searchDocs as often as needed, then return the section names and one sentence each.
Do not answer the user's question yourself.