add effective agents section (spring-projects#3247)

Signed-off-by: Solomon Hsu <[email protected]>

Author: markpollack

spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc

@@ -117,6 +117,7 @@
 * Guides
 ** https://github.com/spring-ai-community/awesome-spring-ai[Awesome Spring AI]
 ** xref:api/chat/prompt-engineering-patterns.adoc[]
+** xref:api/effective-agents.adoc[Building Effective Agents]
 ** xref:api/cloud-bindings.adoc[Deploying to the Cloud]
 
 // * xref:contribution-guidelines.adoc[Contribution Guidelines]

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/effective-agents.adoc

@@ -0,0 +1,256 @@
+In a recent research publication, https://www.anthropic.com/research/building-effective-agents[Building Effective Agents], Anthropic shared valuable insights about building effective Large Language Model (LLM) agents. What makes this research particularly interesting is its emphasis on simplicity and composability over complex frameworks. Let's explore how these principles translate into practical implementations using https://docs.spring.io/spring-ai/reference/index.html[Spring AI].
+
+image::https://raw.githubusercontent.com/spring-io/spring-io-static/refs/heads/main/blog/tzolov/spring-ai-agentic-systems.jpg[Agent Systems, width=350]
+
+While the pattern descriptions and diagrams are sourced from Anthropic's original publication, we'll focus on how to implement these patterns using Spring AI's features for model portability and structured output. We recommend reading the original paper first.
+
+The https://github.com/spring-projects/spring-ai-examples/tree/main/agentic-patterns[agentic-patterns] directory in the spring-ai-examples repository contains all the code for the examples that follow.
+
+== Agentic Systems
+
+The research publication makes an important architectural distinction between two types of agentic systems:
+
+. *Workflows*: Systems where LLMs and tools are orchestrated through predefined code paths (e.g., prescriptive systems)
+. *Agents*: Systems where LLMs dynamically direct their own processes and tool usage
+
+The key insight is that while fully autonomous agents might seem appealing, workflows often provide better predictability and consistency for well-defined tasks. This aligns perfectly with enterprise requirements where reliability and maintainability are crucial.
+
+Let's examine how Spring AI implements these concepts through five fundamental patterns, each serving specific use cases:
+
+=== 1. https://github.com/spring-projects/spring-ai-examples/tree/main/agentic-patterns/chain-workflow[Chain Workflow]
+
+The Chain Workflow pattern exemplifies the principle of breaking down complex tasks into simpler, more manageable steps.
+
+image::https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F7418719e3dab222dccb379b8879e1dc08ad34c78-2401x1000.png&w=3840&q=75[Prompt Chaining Workflow]
+
+*When to Use:*
+- Tasks with clear sequential steps
+- When you want to trade latency for higher accuracy
+- When each step builds on the previous step's output
+
+Here's a practical example from Spring AI's implementation:
+
+[source,java]
+----
+public class ChainWorkflow {
+    private final ChatClient chatClient;
+    private final String[] systemPrompts;
+
+    public String chain(String userInput) {
+        String response = userInput;
+        for (String prompt : systemPrompts) {
+            String input = String.format("{%s}\n {%s}", prompt, response);
+            response = chatClient.prompt(input).call().content();
+        }
+        return response;
+    }
+}
+----
+
+This implementation demonstrates several key principles:
+
+- Each step has a focused responsibility
+- Output from one step becomes input for the next
+- The chain is easily extensible and maintainable
+
+=== 2. https://github.com/spring-projects/spring-ai-examples/tree/main/agentic-patterns/parallelization-workflow[Parallelization Workflow]
+
+LLMs can work simultaneously on tasks and have their outputs aggregated programmatically.
+
+image::https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F406bb032ca007fd1624f261af717d70e6ca86286-2401x1000.png&w=3840&q=75[Parallelization Workflow]
+
+*When to Use:*
+- Processing large volumes of similar but independent items
+- Tasks requiring multiple independent perspectives
+- When processing time is critical and tasks are parallelizable
+
+[source,java]
+----
+List<String> parallelResponse = new ParallelizationWorkflow(chatClient)
+    .parallel(
+        "Analyze how market changes will impact this stakeholder group.",
+        List.of(
+            "Customers: ...",
+            "Employees: ...",
+            "Investors: ...",
+            "Suppliers: ..."
+        ),
+        4
+    );
+----
+
+=== 3. https://github.com/spring-projects/spring-ai-examples/tree/main/agentic-patterns/routing-workflow[Routing Workflow]
+
+The Routing pattern implements intelligent task distribution, enabling specialized handling for different types of input.
+
+image::https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F5c0c0e9fe4def0b584c04d37849941da55e5e71c-2401x1000.png&w=3840&q=75[Routing Workflow]
+
+*When to Use:*
+- Complex tasks with distinct categories of input
+- When different inputs require specialized processing
+- When classification can be handled accurately
+
+[source,java]
+----
+@Autowired
+private ChatClient chatClient;
+
+RoutingWorkflow workflow = new RoutingWorkflow(chatClient);
+
+Map<String, String> routes = Map.of(
+    "billing", "You are a billing specialist. Help resolve billing issues...",
+    "technical", "You are a technical support engineer. Help solve technical problems...",
+    "general", "You are a customer service representative. Help with general inquiries..."
+);
+
+String input = "My account was charged twice last week";
+String response = workflow.route(input, routes);
+----
+
+=== 4. https://github.com/spring-projects/spring-ai-examples/tree/main/agentic-patterns/orchestrator-workers-workflow[Orchestrator-Workers]
+
+image::https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F8985fc683fae4780fb34eab1365ab78c7e51bc8e-2401x1000.png&w=3840&q=75[Orchestration Workflow]
+
+*When to Use:*
+- Complex tasks where subtasks can't be predicted upfront
+- Tasks requiring different approaches or perspectives
+- Situations needing adaptive problem-solving
+
+[source,java]
+----
+public class OrchestratorWorkersWorkflow {
+    public WorkerResponse process(String taskDescription) {
+        // 1. Orchestrator analyzes task and determines subtasks
+        OrchestratorResponse orchestratorResponse = // ...
+
+        // 2. Workers process subtasks in parallel
+        List<String> workerResponses = // ...
+
+        // 3. Results are combined into final response
+        return new WorkerResponse(/*...*/);
+    }
+}
+----
+
+Usage Example:
+
+[source,java]
+----
+ChatClient chatClient = // ... initialize chat client
+OrchestratorWorkersWorkflow workflow = new OrchestratorWorkersWorkflow(chatClient);
+
+WorkerResponse response = workflow.process(
+    "Generate both technical and user-friendly documentation for a REST API endpoint"
+);
+
+System.out.println("Analysis: " + response.analysis());
+System.out.println("Worker Outputs: " + response.workerResponses());
+----
+
+=== 5. https://github.com/spring-projects/spring-ai-examples/tree/main/agentic-patterns/evaluator-optimizer-workflow[Evaluator-Optimizer]
+
+image::https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2F14f51e6406ccb29e695da48b17017e899a6119c7-2401x1000.png&w=3840&q=75[Evaluator-Optimizer Workflow]
+
+*When to Use:*
+- Clear evaluation criteria exist
+- Iterative refinement provides measurable value
+- Tasks benefit from multiple rounds of critique
+
+[source,java]
+----
+public class EvaluatorOptimizerWorkflow {
+    public RefinedResponse loop(String task) {
+        Generation generation = generate(task, context);
+        EvaluationResponse evaluation = evaluate(generation.response(), task);
+        return new RefinedResponse(finalSolution, chainOfThought);
+    }
+}
+----
+
+Usage Example:
+
+[source,java]
+----
+ChatClient chatClient = // ... initialize chat client
+EvaluatorOptimizerWorkflow workflow = new EvaluatorOptimizerWorkflow(chatClient);
+
+RefinedResponse response = workflow.loop(
+    "Create a Java class implementing a thread-safe counter"
+);
+
+System.out.println("Final Solution: " + response.solution());
+System.out.println("Evolution: " + response.chainOfThought());
+----
+
+== Spring AI's Implementation Advantages
+
+Spring AI's implementation of these patterns offers several benefits that align with Anthropic's recommendations:
+
+=== https://docs.spring.io/spring-ai/reference/api/chat/comparison.html[Model Portability]
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.springframework.ai</groupId>
+    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
+</dependency>
+----
+
+=== https://docs.spring.io/spring-ai/reference/api/structured-output-converter.html[Structured Output]
+
+[source,java]
+----
+EvaluationResponse response = chatClient.prompt(prompt)
+    .call()
+    .entity(EvaluationResponse.class);
+----
+
+=== https://docs.spring.io/spring-ai/reference/api/chatclient.html[Consistent API]
+
+- Uniform interface across different LLM providers
+- Built-in error handling and retries
+- Flexible prompt management
+
+== Best Practices and Recommendations
+
+- *Start Simple*
+- Begin with basic workflows before adding complexity
+- Use the simplest pattern that meets your requirements
+- Add sophistication only when needed
+
+- *Design for Reliability*
+- Implement clear error handling
+- Use type-safe responses where possible
+- Build in validation at each step
+
+- *Consider Trade-offs*
+- Balance latency vs. accuracy
+- Evaluate when to use parallel processing
+- Choose between fixed workflows and dynamic agents
+
+== Future Work
+
+These guides will be updated to explore how to build more advanced Agents that combine these foundational patterns with sophisticated features:
+
+*Pattern Composition*
+- Combining multiple patterns to create more powerful workflows
+- Building hybrid systems that leverage the strengths of each pattern
+- Creating flexible architectures that can adapt to changing requirements
+
+*Advanced Agent Memory Management*
+- Implementing persistent memory across conversations
+- Managing context windows efficiently
+- Developing strategies for long-term knowledge retention
+
+*Tools and Model-Context Protocol (MCP) Integration*
+- Leveraging external tools through standardized interfaces
+- Implementing MCP for enhanced model interactions
+- Building extensible agent architectures
+
+== Conclusion
+
+The combination of Anthropic's research insights and Spring AI's practical implementations provides a powerful framework for building effective LLM-based systems.
+
+By following these patterns and principles, developers can create robust, maintainable, and effective AI applications that deliver real value while avoiding unnecessary complexity.
+
+The key is to remember that sometimes the simplest solution is the most effective. Start with basic patterns, understand your use case thoroughly, and only add complexity when it demonstrably improves your system's performance or capabilities.