Forem: bsorrentino

Skill-Based Sub-Agents with LangGraph4j and Spring AI

bsorrentino — Mon, 04 May 2026 20:27:26 +0000

Combine Tools & Skill to create Agent

Modern agentic systems usually expose two strong but separate abstractions:

Tools, which give an LLM executable capabilities
Skills, which package reusable instructions for a narrow task

This article shows how to combine both ideas in LangGraph4j so that a skill is not just prompt text, but a fully operational sub-agent exposed as a tool. The result is a practical pattern for building modular multi-agent systems in Java with Spring AI and LangGraph4j, while keeping each agent focused, reusable, and low in context cost.

Starting from a standard ReACT agent, the approach implemented is quite simple.

Load a SKILL.md file
Read its front matter to define the tool contract ( name and argument description)
Use the skill body as the sub-agent system prompt
Restrict the sub-agent to only the tools declared by the skill
Register the sub-agent in a parent ReAct agent as if it were a normal tool

In other words, a skill becomes an executable tool-backed agent.

Why This Pattern Matters

The standard ReAct pattern already gives an LLM a strong execution model: reason, choose a tool, inspect the result, and continue until the task is complete. That model is useful because the LLM does not need to commit to a fixed plan up front. It can adapt after every tool call.

The next step is to let a tool itself be implemented by another agent.

Once that happens, the parent agent is no longer forced to know every operational detail. It only needs to know:

which specialized capability exists
when to invoke it
what input to pass

The specialized logic is delegated to a narrower agent with its own instructions and its own restricted toolset. This gives us a clean sub-agent architecture without inventing a new orchestration primitive. We reuse the same tool-calling semantics that ReAct agents already understand well.

Why Reusing Tool Semantics Is Powerful

One of the most valuable properties of LLM-based agents is their ability to build and revise a tool execution plan while reasoning over intermediate results. ReAct made this practical by combining thought, action, and observation in a loop.

When a tool call can transparently invoke another agent, we preserve that planning model instead of replacing it.

The parent agent can:

decide that a specialized capability is needed
provide only the task-relevant context
wait for a result exactly as it would for a standard tool

The child agent can:

run its own reasoning loop
invoke its own allowed tools
return a compact outcome to the parent

This gives hierarchical coordination without exposing the full inner workflow to the parent prompt.

Minimizing Context and Token Usage

This pattern also improves context discipline.

Without sub-agents, a single generalist agent often needs:

every tool definition
all operating instructions for every domain
every procedural rule in one large system prompt

That quickly becomes expensive and unreliable.

With skill-based sub-agents:

the parent only sees high-level capabilities
each child sees only the instructions relevant to its task
each child receives only the tools it is allowed to use

This narrower context has practical benefits:

fewer tokens sent to the model
lower prompt interference between unrelated domains
clearer tool choice
better modularity as the system grows

The allowed-tools skill property plays an important role here anabling tool filtering. It turns tool access into an explicit design decision instead of an accidental side effect of what happened to be registered globally.

Reference implementation

I've started implementation in the new LangGraph4j release stream 1.9 currently in active development. The implementation is centered on [SkilledReactSubAgent], which turns a markdown skill into both:

a compiled LangGraph4j sub-graph
a Spring AI tool (i.e. ToolCallback)

That means the same component can participate in the graph as an agent and present itself to the parent LLM as a callable tool.

In particular the flow is:

Parse the SKILL.md
Extract name and description from front matter
Optionally filter tools using allowed-tools
Use the markdown body as the sub-agent instructions
Compile the agent
Wrap it into a function tool whose input is a single context field

The important design choice is that the tool definition is derived from the skill metadata, while the agent behavior is derived from the skill content.

Skill Format

The supported skill format is

---
name: <agent name>
description: "|"
        <multi line description>
allowed-tools: <list of tools>
---

<skill body>

From Skill to Tool-Backed Agent

The conversion happens in SkilledReactSubAgent.Builder#build(...). This is the crucial bridge where:

the skill metadata defines the external API
the skill body defines the internal operating behavior
the allowed tools define the sub-agent execution boundary

The resulting agent is then wrapped as a Spring AI function tool.

From the parent agent point of view, this is just another tool. Internally, it is a complete ReAct-capable agent workflow.

Examples

Purchase Assistant Agent

This is an agent that allow to select a produdct from a reference marketplace and purchase it. Below the simplified component diagram.

Marketplace Skill

---
name: agent-marketplace
description: |
    marketplace agent, ask for information about products. This is agent that provides the information on the product marketplace.
    required data are:
    * product name
allowed-tools: searchByProduct
---

## Retrieve product information
We need all information about about the product of interest in particular is mandatory to have
* product name

with such information we have to invoke tool `searchByProduct` and return the result

Payment Skill

---
name: agent-payment
description: |
    payment agent, this is the agent that provides payment service.
    required data are:
    * Product name
    * Product price
    * Product currency
    * the International Bank Account Number (IBAN) - optional

allowed-tools:
    - submit-payment
    - retrieve-iban
---

## submit a payment for purchasing a specific product
We need all information about purchasing to allow the payment

* Product name
* Product price
* Product price currency
* International Bank Account Number (IBAN)

With such information you must invoke tool `submit-payment` and return the result of the payment transaction plus the IBAN.
If IBAN is not provided invoke tool `retrieve-iban` to retrieve the required IBAN.

Observing the skills above they define three different concerns:

name: the tool name exposed to the parent agent
description: the tool description shown to the model
allowed-tools: the only tools available inside the sub-agent

Everything after the front matter becomes the sub-agent system prompt.

Again, this is a strong separation of concerns. The parent agent sees a concise tool contract, while the child agent receives richer operating instructions.

Finally the code

Below a representative code snippet that show how wires two skill-based sub-agents into a parent agent:

var subAgentMarketplace = SkilledReactSubAgent.builder()
        .chatModel(chatModel)
        .tools(Marketplace.tools())
        .build(compileConfig,
                SkillSource.of(Paths.get("skills/agent-marketplace/")));

var subAgentPayment = SkilledReactSubAgent.builder()
        .chatModel(chatModel)
        .tools(Payment.tools())
        .build(compileConfig,
                SkillSource.of(Paths.get("skills/agent-payment/")));

var purchaseAssistantAgent = AgentExecutorEx.builder()
        .chatModel(chatModel)
        .tool(subAgentMarketplace)
        .tool(subAgentPayment)
        .build(compileConfig);

var input = """
        search for product 'X'.
        If found proceed to payment with IBAN US82WEST1234567890123456 
        to purchase it
        """;

var result = purchaseAssistantAgent.invoke( 
        GraphInput.args( Map.of("messages", new UserMessage(input) )), runnableConfig);

This composition is interesting because the purchase agent (the parent) does not need detailed knowledge of:

how product lookup works
how payment submission works
when IBAN retrieval is required

Those rules are delegated to the sub agents themselves.

That is a simple but good example of behavioral encapsulation. The parent agent only decides to involve marketplace agent to retrieve product and after that to involve payment agent to purchase.

This is a very basic but representative example, it is useful because it shows the intended layering:

the user gives a single business request
the parent agent decomposes the work
specialized sub-agents execute their own logic
the final answer comes back through the normal tool-response path

Interesting note that each sub agent, potentially, can relies on different LLM chat model so we can further optimize overall agent execution process

Below a more detailed componet diagram generated by LangGraph4j itself.

From this diagram it is quite clear that the sub agents are nothing but sub-graphs

Design Advantages

This approach has several practical advantages.

Reuse Existing Agent Patterns

There is no need to invent a separate orchestration protocol for sub-agents. A sub-agent is exposed as a tool, so the parent agent can use standard ReAct behavior without extra prompting complexity.

Better Modularity

Each skill owns:

its tool-facing identity
its internal instructions
its allowed tool boundary

That makes the system easier to evolve than a single monolithic agent prompt.

Smaller and Cleaner Context

The child agent receives only what it needs. This reduces token usage and lowers the risk that unrelated instructions distort tool choice or task execution.

Safer Capability Scoping

By filtering tools from allowed-tools, the framework prevents a child agent from accidentally seeing tools outside its intended domain.

Better Reusability

A skill can be packaged, versioned, and reused across different parent agents. The same marketplace or payment skill can participate in many workflows as long as the tool contract remains stable.

Tradeoffs and Implementation Considerations

This pattern is strong, but it is not free of tradeoffs.

The Parent Must Summarize Well

Because the child receives a single context field, the parent agent needs to pass the relevant facts clearly. If critical information is omitted, the child may need extra recovery steps or may fail to act.

Tool Descriptions Matter More

Since the parent sees the child as a tool, the name and description fields in the skill front matter become part of the routing surface for the LLM. Weak metadata will reduce invocation quality.

Prompt Boundaries Need Discipline

The skill body is effectively the child system prompt. If it is vague, contradictory, or overloaded, the benefits of modularity disappear. Skills need to stay focused.

Observability Is Important

Nested agents can make execution harder to inspect if tracing is weak. LangGraph4j's graph structure and step streaming help here, but production systems should still invest in logging and traceability.

Why LangGraph4j Fits This Well

LangGraph4j is a good fit for this pattern because it already models agent workflows as explicit graphs and integrates naturally with Spring AI tool abstractions.

That matters for two reasons:

the sub-agent is not just prompt composition; it is a compiled graph with state and execution hooks
the parent integration remains ergonomic because Spring AI already treats capabilities as tools
LangGraph4j support interruptions in subgraph enabling Human In The Loop also when involving sub agents

So the implementation is not forcing two incompatible ideas together. It is aligning:

LangGraph4j graph execution
Spring AI tool calling
markdown-defined skills

into a single reusable agent-building pattern.

Conclusion

Turning a skill into a sub-agent is a small change with a large impact.

It lets us:

preserve the strengths of the ReAct loop
delegate specialized behavior cleanly
reduce context size
constrain tool access per domain
build multi-agent systems out of reusable skill modules

The idea is implemented in a compact and pragmatic way: a SKILL.md file becomes the source of both the sub-agent prompt and the tool contract exposed to the parent agent.

For Java teams building agentic applications with Spring AI and LangGraph4j, this is a practical pattern for moving from a single large agent toward a modular multi-agent design without abandoning the tool semantics that current LLMs already handle well.

The implementation is in progress on release 1.9-SNAPSHOT in develop branch of LangGraph4j repository but the first result are very promising.

Hope this could help and encourage usage of LangGraph4j for your next Agentic Workflow. Checkout project, try it and let me know your feedback and... happy AI coding! 👋

Originally published at https://bsorrentino.github.io on April 28, 2026.

Interesting reading for who are approaching use AI for developing at scale

bsorrentino — Mon, 30 Mar 2026 07:48:38 +0000

Incomplete Developer

Mar 26

Spec-Driven Development: Return of Best Practices

#specdrivendevelopment #vibecoding #ai

Comments

4 min read

Agent Definition Language (ADL): The Open Source Standard for Defining AI Agents 👀. Looks promising https://www.nextmoca.com/blogs/agent-definition-language-adl-the-open-source-standard-for-defining-ai-agents

bsorrentino — Tue, 10 Feb 2026 09:28:44 +0000

Agent Definition Language (ADL): The Open Source Standard for Defining AI Agents — Next Moca

GitHub Repository: https://github.com/nextmoca/adl

nextmoca.com

Observability matter

bsorrentino — Fri, 06 Feb 2026 17:47:43 +0000

bsorrentino

Feb 6

LangGraph4j Hooks and OpenTelemetry

#langgraph4j #agents #observability #opentelemetry

Comments 2

3 min read

LangGraph4j Hooks and OpenTelemetry

bsorrentino — Fri, 06 Feb 2026 17:44:50 +0000

Why Observability Matters

Agentic workflows are dynamic: nodes may run conditionally, in parallel, or be skipped entirely. When something fails, a simple stack trace is rarely enough. Observability gives you a unified view of what happened, where it happened, and why.

In practice, observability helps you:

Understand end-to-end execution flow.
Detect performance bottlenecks early.
Correlate errors with specific nodes, edges, and state transitions.

Why Telemetry Matters

Observability is only possible if you collect high‑quality telemetry. Telemetry is the raw signal: traces, logs, and metrics. Without it, probably, you are debugging your system partially.

In agent graphs, telemetry becomes even more important because state and control flow are distributed across steps. The same workflow can behave differently depending on state, configuration, or external tool results.

The LangGraph4j hooks

LangGraph4j hooks are small, composable interceptors that sit around nodes and conditional edges. They let you run custom logic before, after, or wrapping the core action, without modifying the node itself.
Hooks can be registered globally (applies to all nodes/edges) or by ID (targeted to a specific node/edge), and their execution order is LIFO(Last In First Out) for BeforeCall/AfterCall, FIFO(First In First Out) for WrapCall.
This makes them a precise, low‑friction mechanism for cross‑cutting concerns like tracing, metrics, logging, or state inspection.

How Hooks Enable Observability

Hooks provide lifecycle interception points around node and edge execution. This is the ideal place to add logging, metrics, or traces without contaminating business logic.

In LangGraph4j you can intercept execution before, after, or around node/edge calls. Here is a minimal example that measures node execution time and logs it:

var graph = new StateGraph<>(MyState.SCHEMA, serializer)
    .addWrapCallNodeHook((nodeId, state, config, action) -> { // add Wrap call node hook
        var start = System.currentTimeMillis();
        return action.call()
            .whenComplete((res, err) -> {
                var ms = System.currentTimeMillis() - start;
                log.info("node '{}' took {}ms", nodeId, ms );
            });
    })
    .addNode( "node1", action1 )
    .addNode( "node2", action2 )
    ....
    .compile();

This pattern scales: you can plug in structured logs, metrics counters, or spans with the same hook mechanism.

OpenTelemetry in the Java Ecosystem

OpenTelemetry is the standard for observability across modern platforms. In Java it provides:

Tracing via spans
Metrics via meters
Logs via instrumentation

You configure it once and export telemetry to a backend like Jaeger, Grafana, or the OpenTelemetry Collector. The key benefit here is portability: you are not locked to a single vendor.

How LangGraph4j Hooks Enable OpenTelemetry

LangGraph4j includes a dedicated module, langgraph4j-opentelemetry, that provides hook implementations ready for tracing node and edge execution. Consider it as a reference implementation about how to integrate OpenTelemetry in LangGraph4j

The module includes:

OTELWrapCallTraceHook: creates spans for each node and edge call, adding config/state attributes and start/end events.
OTELWrapCallTraceSetParentHook: creates a parent span so node/edge spans are grouped inside a workflow scope.

A minimal integration looks like this:

var otelHook = new OTELWrapCallTraceHook<MyState>(serializer);
var parentHook = OTELWrapCallTraceSetParentHook.<MyState>builder()
    .scope("MyWorkflow")
    .groupName("stream")
    .build();

var workflow = new StateGraph<>(MyState.SCHEMA, serializer)
    .addWrapCallNodeHook(otelHook)
    .addWrapCallEdgeHook(otelHook)
    .addWrapCallNodeHook(parentHook)
    .addWrapCallEdgeHook(parentHook)
    .addNode( "node1", action1 )
    .addNode( "node2", action2 )
    .addContitionalEdges( "node2", edgeAction, 
            EdgeMappings.builder()
            .to("node1")
            .toEnd()
            .build() )
    ...        
    .compile();

This keeps node logic clean while producing rich, correlated traces for the entire workflow.

Below an example of output in Jaeger tracing platform

Conclusion

Hooks are the foundation for observability in LangGraph4j: they give you structured interception points without affect your main workflow code. OpenTelemetry builds on top of this by standardizing how telemetry is collected and exported in the Java ecosystem.
Combined, they deliver production-grade visibility for complex agent workflows.
Checkout project, try it and let me know your feedback and ... happy AI coding! 👋

References

OpenTelemetry

Originally published at https://bsorrentino.github.io on February 4, 2026.

I read this in a post: "AI agents are 5% models and 95% engineering glue." I completely agree, but I feel like it's not so clear among software engineers. This helps us to understand that we need to focus on adding value around models.

bsorrentino — Sat, 31 Jan 2026 08:55:24 +0000

Top GitHub Users By Public Contributions in Italy https://github.com/gayanvoice/top-github-users/blob/main/markdown/public_contributions/italy.md I'm at 26th place 👨‍💻 🚀😉

bsorrentino — Fri, 23 Jan 2026 15:04:34 +0000

top-github-users/markdown/public_contributions/italy.md at main · gayanvoice/top-github-users · GitHub

Check your ranking in GitHub! Don't forget to star ⭐ this repository. - gayanvoice/top-github-users

github.com

[Top GitHub Users By Public Contributions in Italy] (https://github.com/gayanvoice/top-github-users/blob/main/markdown/public_contributions/italy.md) I'm at 26th place 👨‍💻 🚀😉

bsorrentino — Fri, 23 Jan 2026 14:58:26 +0000

top-github-users/markdown/public_contributions/italy.md at main · gayanvoice/top-github-users · GitHub

Check your ranking in GitHub! Don't forget to star ⭐ this repository. - gayanvoice/top-github-users

github.com

Exploring Javelit, the Java counterpart to Streamlit, for rapid prototyping and AI agents using LangGraph4j.

bsorrentino — Sat, 20 Dec 2025 20:42:38 +0000

bsorrentino

Dec 20 '25

Experimenting with Javelit - The Streamlit for Java

#java #ui #ux #javelit

Comments

4 min read

Experimenting with Javelit - The Streamlit for Java

bsorrentino — Sat, 20 Dec 2025 20:41:56 +0000

Starting from Python development ecosystem

At the beginning of my journey with agentic applications, I started with the Python programming language, leveraging LangChain/LangGraph. For testing and documentation, I relied on the simple yet powerful Jupyter Notebooks. Simultaneously, for rapid prototyping, I adopted the amazing Streamlit framework, which empowered me to quickly develop functional applications with an effective UI and excellent UX.

Moving from Python ecosystem to the Java one

When I started developing LangGraph4j, I tried to replicate my Python development ecosystem in Java. So I've experimented with the Java Notebooks through the rapaio-jupyter-kernel project, which allowed me to replicate the development experience I had with Jupyter Notebooks in Python quite well. For rapid prototyping, I relied almost entirely on Spring Boot framework, which is a fairly fast and enjoyable programming experience.

Javelit come to play 🚀

Going on my efforts on LangGraph4j and continuously monitoring the most interesting and promising Java projects on GitHub, I discovered Javelit. This project intrigued me because of its reference to Streamlit, and after a review, I was amazed to realize that the dynamic programming model popularized by Streamlit had been adapted for Java by this initiative, which is cool.😎
So I started to evaluate it as part of may java development ecosystem and below i'll share with you my experience about it.

What is Javelit 👀

Javelit is a tool to quickly build interactive app frontends in Java, particularly for data apps, but it’s not limited to them. It helps you quickly develop rapid prototypes, with a live-reload loop, so that you can quickly experiment and update the app instantly.

How it works

Javelit’s architecture allows you to write apps the same way you write plain Java methods. Any time something must be updated on the screen, Javelit reruns your entire Java main method from top to bottom.

So you have to think about it as if your entire UI code runs inside a continuous loop that refreshes whenever something needs updating on the screen.

Javelit provides developers with a rich set of prebuilt components that make it easy to get started.

Just to provide you an idea of the Javelit approach below the inevitable "Hello World" code snippet

/// usr/bin/env jbang "$0" "$@" ; exit $?
import io.javelit.core.Jt;

public class App {

    public static void main(String[] args) {
        Jt.title("Hello World!").use();
        Jt.markdown("""
            ## My first official message
            Hello World!
            """).use();
    }
}

Then, once Javelit is installed, you’d run it with the following command:

javelit run App.java

Use Javelit with LangGraph4j

I've decided to use Javelit to develop some examples of LangGraph4j usage and below, I show you how have used Javelit to implement a demo app to run the LangGraph4j powered React Agent.
For simplicity I've reported only the meaningful code snippets, but for a complete code take a look to JtAgentExecutorApp.java for spring AI based implementation.

As Streamlit in Javelit entire application consist in just one main() method.

public class JtAgentExecutorApp {

    public static void main(String[] args) {

        Jt.title("LangGraph4J React Agent").use();

        try {
            // create a LangGraph4j Agent
            var agent = AgentExecutor.builder()
                .chatModel(/* instantiate the preferred ChatModel */)
                .toolsFromObject( new MyTools() /* Custom Tools */  )
                .build()
                .compile(); 

            // input: the user message
            var userMessage = Jt.textArea("user message:")
                    .placeholder("user message")
                    .labelVisibility(JtComponent.LabelVisibility.HIDDEN)
                    .use();

            // button: start agent processing 
            var start = Jt.button("start agent")
                    .disabled(userMessage.isBlank())
                    .use();

            if (start) { // if button pressed

                var outputComponent = Jt.expander("Workflow Steps").use();

                var input = GraphInput.args(Map.of("messages", new UserMessage(userMessage)));

                var generator = agent.stream(input);

                final var startTime = Instant.now();

                for( var step : generator ) {

                    Jt.sessionState().remove("streaming");
                    Jt.info("""
                            #### %s
                            %s
                            """.formatted(s.node(),
                            s.state().messages().stream()
                                    .map(Object::toString)
                                    .collect(Collectors.joining("\n\n")))
                    ).use(outputComponent);
                }

                final var elapsedTime = Duration.between(startTime, Instant.now());

                Jt.success("finished in %ds%n".formatted(elapsedTime.toSeconds())).use();

            }
        } catch (Exception e) {
            Jt.error(e.getMessage()).use();
        }

    }

}

The output of the Javelit app looks like:

Chat model selection view

Start agent view

Results view

👉 try yourself 👀 🚀 🤯

If you want try yourself (after installed javelit) run the command

javelit run https://github.com/langgraph4j/langgraph4j/tree/main/spring-ai/spring-ai-agent/src/test/java

Conclusion

Javelit brings the power of rapid prototyping and interactive web app development to the Java ecosystem, much like Streamlit does for Python. With its simple, loop-based programming model, developers can quickly build data-driven applications without needing extensive frontend knowledge, leveraging familiar Java syntax and the rich JVM ecosystem. The live-reload feature enables instant experimentation and iteration, making it ideal for prototyping AI agents, data visualizations, and interactive tools. By integrating seamlessly with libraries like LangGraph4j combined with both Spring AI and LangChain4j, Javelit empowers Java developers to create engaging user interfaces effortlessly, bridging the gap between backend logic and user-facing applications.

Checkout project, try it and let me know your feedback and ... happy coding! 👋

References

Javelit to create quick interactive app frontends in Java

Originally published at https://bsorrentino.github.io on December 20, 2025.

Very interesting. I agree with sentence "prompts are becoming as important as code dependencies" so it will be important apply the dependencies management approach also for prompt management

bsorrentino — Fri, 12 Dec 2025 10:22:25 +0000

PRPM - The Universal Package Manager for AI Prompts

Dev Diaries ・ Dec 9 '25

#devchallenge #muxchallenge #showandtell #video

🧠🤖 LangGraph4j Deep Agents (Agent 2.0)

bsorrentino — Fri, 17 Oct 2025 15:07:17 +0000

Why Deep Agents (Agent 2.0)?

Classic agents often run a simple loop: think → call a tool → observe → repeat. That’s great for quick, transactional queries, but it breaks down on multi-hour or multi-day tasks (hallucinations, loss of goal, looping, no recovery).

Deep Agents try fix this by changing the architecture (not just the prompt) based on the four pillars below:

Explicit Planning – The agent continuously maintains a plan (e.g., a TODO in Markdown) with clear statuses instead of hiding intent in a just chain-of-thought.
Hierarchical Delegation (Sub-Agents) – An Orchestrator delegates to specialized agents (Researcher, Coder, Writer, …), each working in a clean context and returning synthesized results.
Persistent Memory – Intermediate artifacts (notes, code, data) are written to external storage (filesystem, vector store, …) and referenced by path/query rather than stuffing everything into the context window.
Extreme Context Engineering – Long, specific instructions define: when to plan vs. act, when to spawn sub-agents and the human-in-the-loop(HITL) rules.

Reference Architecture

Reference Implementation in Java using LangGraph4j

Since the LangGraph4j is inpired by (more popular) LangGraph python version, I've decided to adapt its python based Deep Agents reference implementation to Java using LangGraph4j and Spring AI.

The project is on Github. This repository demonstrates the four pillars of Deep Agents, it includes sample code that create a Deep Researcher Agent that use Tavily as web search engine and OpenAI gpt-4o-mini model.

Let's look at a sequence diagram for a Deep Agent handling a complex request:

Below a representative code snippet that implements the Deep Agents in the diagram

// Create a Research Sub Agent
var researchSubagent = DeepAgent.SubAgent.builder()
    .name("research-agent")
    .description("""
        Used to research more in depth questions. Only give this researcher one topic at a time.
        Do not pass multiple sub questions to this researcher.
        Instead, you should break down a large topic into the necessary components, and then call multiple research agents in parallel, one for each sub question.
        """)
    .prompt("""
        You are a dedicated researcher. Your job is to conduct research based on the users questions.
        Conduct thorough research and then reply to the user with a detailed answer to their question

        ........(to be continued).............. 
        """)
    .tools( List.of( "internet_search" ))
    .build();

// Create a Critique Sub Agent
var critiqueSubAgent =  DeepAgent.SubAgent.builder()
        .name("critique-agent")
        .description("Used to critique the final report. Give this agent some information about how you want it to critique the report.")
        .prompt("""
            You are a dedicated editor. You are being tasked to critique a report.

            You can find the report at `final_report.md`.

            You can find the question/topic for this report at `question.txt`.

            ........(to be continued).............. 
            """)
        .build();

// Create a Main Agent
var deepAgent = DeepAgent.builder()
        .instructions("""
        You are an expert researcher. Your job is to conduct thorough research, and then write a polished report.

        The first thing you should do is to write the original user question to `question.txt` so you have a record of it.

        Use the research-agent to conduct deep research. It will respond to your questions/topics with a detailed answer.

        When you think you enough information to write a final report, write it to `final_report.md`

        You can call the critique-agent to get a critique of the final report. After that (if needed) you can do more research and edit the `final_report.md`

        ........(to be continued).............. 

        """)
        .subAgents( List.of( researchSubagent, critiqueSubAgent ))
        .chatModel(chatModel)
        .tools( List.of( tools.internetSearch()) )
        .build()
        .compile( CompileConfig.builder()
                .recursionLimit(100)
                .build());

        var userMessage = """
                        What is langgraph4j project?
                        """;

        var runnableConfig = RunnableConfig.builder().build();

        var result = agent.stream(
                        Map.of("messages", new UserMessage(userMessage), 
                        runnableConfig );

        var output = result.stream()
                .peek(s -> System.out.println(s.node()) )
                .reduce((a, b) -> b)
                .orElseThrow();

        System.out.println( """
        ================================
        TODO
        ================================
        """);
        output.state().todos().forEach((value) -> System.out.printf("""
                -----------
                %s
                -----------
                """, value));
        System.out.println( """
        ================================
        FILES
        ================================
        """);
        output.state().files().forEach((key, value) -> System.out.printf("""
                file: '%s'
                -----------
                %s
                -----------
                """, key, value));

        System.out.println( """
        ================================
        FINAL RESULT
        ================================
        """);
        System.out.printf( "result: %s\n",
                output.state().lastMessage()
                        .map(AssistantMessage.class::cast)
                        .map(AssistantMessage::getText)
                        .orElseThrow());

Conclusions

Deep Agents architecture is a try to move beyond one-loop “shallow” agents to explicit planning hierarchical delegation, persistent memory, and rigorous context engineering. LangGraph4j can help to experiment in Labs and deliver in production complex Agentic Workflow on top of JVM.
Checkout project, try it and let me know your feedback and ... happy AI coding! 👋

References

Originally published at https://bsorrentino.github.io on October 17, 2025.