New post on agentic AI patterns

Author: mariofusco

_posts/2025-11-12-agentic-ai-patterns.adoc

@@ -0,0 +1,182 @@
+---
+layout: post
+title: 'Agentic AI Patterns: one size does not fit all'
+date: 2025-11-12T00:00:00Z
+tags: ai llm agents
+synopsis: 'Agentic AI Patterns: one size does not fit all'
+author: mariofusco
+---
+:imagesdir: /assets/images/posts/agentic
+
+At the beginning of 2025 we started doing some experiments with agentic AI, using Quarkus and its LangChain4j extension, that culminated with the publication of a three-part blog post series on this topic, that first https://quarkus.io/blog/agentic-ai-with-quarkus/[introduced agentic AI and workflow patterns], then explored https://quarkus.io/blog/agentic-ai-with-quarkus-p2/[purely AI orchestrated agentic patterns], and finally examined the https://quarkus.io/blog/agentic-ai-with-quarkus-p3/[differences between these two approaches] with a practical example, trying to put in evidence their pros and cons.
+
+Only a handful of months have passed since those articles, but in the meantime the AI ecosystem, and the possibilities it enables, have evolved at an incredible speed, making it increasingly harder to keep up with all the novelties and changes. In fact the initial experiments discussed in that series seem now to come from a different geological era, even though they served as an important starting point to explore the agentic AI landscape.
+
+These experiments and explorations lead to the implementation of a https://docs.langchain4j.dev/tutorials/agents/[new agentic module] in LangChain4j intended to provide a comprehensive framework for building agentic AI systems. This module also includes a set of predefined agentic patterns that can be used as building blocks to coordinate agents in different ways. Unfortunately, continuing with those experiments, and most importantly discussing them with the LangChain4j community, made it clear that the belief that this set of patterns could be quite exhaustive and cover all the possible use cases was naive and the reality is more complex and nuanced.
+
+== Agentic AI at Devoxx Belgium 2025
+
+Agentic AI was, by far, the most discussed topic at Devoxx Belgium 2025 and we had the opportunity to present there the agentic AI patterns implemented in LangChain4j. In fact, we both gave a https://www.youtube.com/watch?v=X9baI7RBhqk[talk] where we simply exposed with practical examples how those patterns work, and how to use them, and another maybe even more interesting https://www.youtube.com/watch?v=mtWHfYTLeKE[session] where we discussed the steps that brought us to implement the agentic framework as it was together with the mistakes we made and the decision that we had to take during that journey.
+
+As usual at Devoxx, even more important than attending the uncountable talks on agentic AI, was the opportunity to meet so many people working in this field, exchanging ideas and sharing experiences, challenges, and solutions.
+
+We learned a lot from these interactions, and returned to home with only one clear thought: we will never find an ultimate agent orchestrator pattern, not only because this is not our domain of expertise, but mostly because such a thing does not exist. The variety and complexity of tasks that can be required to an agentic system implies that there cannot be a pattern that works in all situations, a one-size-fits-all solution for agentic AI orchestration.
+
+In fact, there is a large spectrum of agentic patterns, ranging from reliable but rigid workflows, where agents control flow follows predetermined code paths, to flexible but unpredictable pure agentic orchestration, where LLMs autonomously decide the sequence of actions to be taken, maintaining control over how they execute tasks, and everything in between. In particular this "in between" space could represent the most interesting one, as it allows to balance reliability and flexibility, and considering the difficulties in better identifying it, why at least not giving to users the possibility to shape it in the way they need?
+
+== A generic architecture for agentic AI patterns
+
+The natural consequence of these considerations was deciding to design a generic architecture for agentic AI patterns that would be customizable enough to allow the widest possible variety of patterns, keeping the possibility of using those patterns as combinable building block that could be seamlessly used together and complement each other.
+
+To keep this as flexible as possible, it was necessary to identify the minimal and simplest abstraction that could do the work, thus realizing that an agentic pattern is simply the specification of an execution plan for the subagents that it coordinates. This plan can be defined by implementing the following `Planner` interface:
+
+[source,java]
+----
+public interface Planner {
+
+    default void init(InitPlanningContext initPlanningContext) { }
+
+    default Action firstAction(PlanningContext planningContext) {
+        return nextAction(planningContext);
+    }
+
+    Action nextAction(PlanningContext planningContext);
+}
+----
+
+This interface defines a method to initialize the planner, plus two other methods to plan the first action to be executed and all the subsequent ones. The method returning the first action is optional and by default it simply delegates to the method returning the next action, which is the only one that must be implemented. The `Action` class returned by these two methods represents the next step to be taken by the agentic pattern, and can be one either a list of one or more subagents to be called next, or a signal that the execution has been completed.
+
+All the built-in agentic patterns offered out-of-the-box by the `langchain4j-agentic` module have been rewritten in terms of this `Planner` abstraction. The pull requests implementing this new architecture has been already merged, and this article won't go in many details in how it works here, since you can find all the information in https://github.com/langchain4j/langchain4j/pull/3929[its description].
+
+The other important point that deserves to be considered is that not only this new architecture gives a chance to users to implement their own agentic patterns, but it also allows to easily combine them with any other pattern, either offered by LangChain4j or implemented by the users themselves. In fact, since all the patterns are now defined in terms of a `Planner`, it is possible to use any pattern as a subagent of any other pattern, thus opening the door to an infinite variety of combinations, as the next example is intended to demonstrate.
+
+== Mixing multiple agentic patterns
+
+One of the examples used in the pull request mentioned above to illustrate this new architecture and how to create your own custom agentic pattern through it, is a goal oriented strategy determining the sequence of agents to be invoked in order to perform a specific complex task.
+
+More in detail, in order to put this approach in practice, not only the whole agentic system needs to define a final goal, but also each subagent needs to declare its own preconditions, required to be able to perform its task, and postconditions, that is the outcomes that it guarantees once its execution is completed. However, in agentic LangChain4j, all this information are implicitly already present in the agentic system, as those pre and postconditions are nothing else than the required inputs and produced outputs of each agent, and the final goal is simply the desired outputs of the whole agentic system.
+
+Following this idea, it is possible to calculate a dependency graph of all the subagents participating in the agentic system, and then to implement a `Planner` that is capable of analyzing the initial state of the `AgenticScope`, comparing it with the desired goal, and then using that graph to determine the sequence of agent invocations that can lead to the achievement of that goal.
+
+[source,java]
+----
+public class GoalOrientedPlanner implements Planner {
+
+    private String goal;
+
+    private GoalOrientedSearchGraph graph;
+    private List<AgentInstance> path;
+
+    private int agentCursor = 0;
+
+    @Override
+    public void init(InitPlanningContext initPlanningContext) {
+        this.goal = initPlanningContext.plannerAgent().outputKey();
+        this.graph = new GoalOrientedSearchGraph(initPlanningContext.subagents());
+    }
+
+    @Override
+    public Action firstAction(PlanningContext planningContext) {
+        path = graph.search(planningContext.agenticScope().state().keySet(), goal);
+        if (path.isEmpty()) {
+            throw new IllegalStateException("No path found for goal: " + goal);
+        }
+        return call(path.get(agentCursor++));
+    }
+
+    @Override
+    public Action nextAction(PlanningContext planningContext) {
+        return agentCursor >= path.size() ? done() : call(path.get(agentCursor++));
+    }
+}
+----
+
+As anticipated, here the goal coincides with the final output of the planner-based agentic pattern itself, while the path from the initial state to the goal is calculated using a graph, that is built analyzing the input and output keys of all subagents. The sequence of agents to be invoked is then calculated as the shortest path on that graph from the current state to the desired goal.
+
+The example discussed in that pull request to demonstrate this pattern at work is an agentic system that generates horoscope-based writeups. The complete source code of this example is available https://github.com/langchain4j/langchain4j/tree/main/langchain4j-agentic-patterns/src/test/java/dev/langchain4j/agentic/patterns/goap/horoscope[here]. This system is composed of multiple subagents, each responsible for a specific task, such as extracting the user's data from the prompt, fetching horoscope data from an external source, generating content based on the horoscope, and formatting the final writeup. In this situation the graph of agents dependencies, also determining the sequence of their activations, is the following:
+
+[.text-center]
+.The GOAP-determined sequence of agents invocation to generate an horoscope-based writeup
+image::goap.png[width=50%, align="center", alt="The GOAP-determined sequence of agents invocation to generate an horoscope-based writeup"]
+
+The main advantage of this goal oriented strategy is that it deterministically determines the shortest sequence of steps to be performed from the initial state to the final goal. Nevertheless, in some cases, this sequence of agents invocations purely calculated following the optimal path on that dependency graph, could represent a limitation. For example, a shortest path by definition doesn't contain loops, but sometimes a loop can be necessary to force an agent to reflect on its own work and iteratively refine its outcome.
+
+As anticipated, the LangChain4j agentic framework allows to overcome this limitation making it possible to seamlessly combine this goal oriented agentic system with any other agentic pattern either provided by the framework or custom made. For instance the final agent generating the writeup could be complemented with a reflection loop, using another agent that provides a score for the generated writeup.
+
+[source,java]
+----
+public interface Writer {
+    @UserMessage("""
+            Create an amusing writeup for {{person}} based on the following:
+            - their horoscope: {{horoscope}}
+            - a current news story: {{story}}
+            """)
+    @Agent("""
+           Create an amusing writeup for the target person based
+           on their horoscope and current news stories
+           """)
+    String write(@V("person") Person person,
+                 @V("horoscope") String horoscope,
+                 @V("story") String story);
+}
+
+public interface WriteupScorer {
+
+    @UserMessage("""
+            You are a critical reviewer. Give a review score between 0.0 and 1.0
+            for the following writeup
+            based on how well it aligns with the spirit of the given zodiac sign.
+            Return only the score and nothing else.
+
+            The writeup is: "{{writeup}}"
+            The sign is: "{{sign}}"
+            """)
+    @Agent("Scores a story based on how well it aligns with a given style")
+    double scoreWriteup(@V("writeup") String writeup, @V("sign") Sign sign);
+}
+
+public interface WriteupAndReviewLoop {
+    @Agent
+    String write(@V("person") Person person,
+                 @V("horoscope") String horoscope,
+                 @V("story") String story);
+}
+----
+
+In this way, the single `Writer` agent can be replaced with this loop, so that the final agentic system could overcome one of the typical limitation of the goal oriented strategy and be defined as follows:
+
+[source,java]
+----
+Writer writer = AgenticServices.agentBuilder(Writer.class)
+        .chatModel(baseModel())
+        .outputKey("writeup")
+        .build();
+
+WriteupScorer scorer = AgenticServices.agentBuilder(WriteupScorer.class)
+        .chatModel(baseModel())
+        .outputKey("score")
+        .build();
+
+WriteupAndReviewLoop writeAndReviewLoop = AgenticServices
+        .loopBuilder(WriteupAndReviewLoop.class)
+        .subAgents(writer, scorer)
+        .outputKey("writeup")
+        .exitCondition( agenticScope -> agenticScope.readState("score", 0.0) >= 0.8)
+        .maxIterations(5)
+        .build();
+
+UntypedAgent horoscopeAgent = AgenticServices.plannerBuilder()
+        .subAgents(horoscopeGenerator, personExtractor,
+                   signExtractor, writeAndReviewLoop, storyFinder)
+        .outputKey("writeup")
+        .planner(GoalOrientedPlanner::new)
+        .build();
+----
+
+== Conclusions
+
+An agentic system made of multiple small but specialized agents can often outperform a single AI services based on a huge LLM at a fraction of the cost. The use of many interoperating agents poses the challenge of coordinating them effectively to achieve complex tasks. Different agentic patterns offer various trade-offs between reliability and flexibility, and no single pattern is suitable for all scenarios. Therefore, a customizable architecture that allows users to define and combine different agentic patterns is essential.
+
+By implementing a generic `Planner` interface, LangChain4j enables users to create their own agentic patterns and seamlessly integrate them with existing ones. This flexibility allows for the development of sophisticated agentic systems tailored to specific needs, balancing the strengths of various orchestration strategies.
+
+This also opens the door to users to help enriching the LangChain4j agentic ecosystem, contributing with their own agentic patterns implementations of the `Planner` interface. To this purpose, a https://github.com/langchain4j/langchain4j/tree/main/langchain4j-agentic-patterns[new dedicated module], named `langchain4j-agentic-patterns`, has been added to the LangChain4j project, with the goal of collecting and maintaining a growing set of useful agentic patterns that can be used as building blocks to create complex agentic systems.