Building Modular Multi-Agent Systems with LangGraph4j and Spring AI Skills

Combine Tools & Skill to create Agent

LangGraph4j 1.9 introduces a pattern where markdown-defined skills are transformed into executable tool-backed sub-agents. This architecture allows a parent ReAct agent to delegate complex tasks while maintaining a clean tool-calling interface.

Why This Matters

Monolithic agents often suffer from high token costs and prompt interference due to overloaded system instructions and excessive tool definitions. By using the SkilledReactSubAgent pattern, developers can enforce context discipline, ensuring sub-agents only see relevant tools and instructions, which significantly improves reliability and lowers costs as agentic systems scale.

Key Insights

• LangGraph4j 1.9 release stream implements SkilledReactSubAgent to bridge markdown skills and executable graphs.
• The ReAct pattern allows sub-agents to build and revise execution plans independently of the parent’s reasoning loop.
• Front matter in SKILL.md files defines the ToolCallback contract, including name and argument descriptions for Spring AI.
• The allowed-tools property provides explicit capability scoping, preventing sub-agents from accessing unauthorized global tools.
• Sub-agents enable hierarchical coordination by returning compact outcomes to parents without exposing full inner workflows.

Working Examples

Supported skill format for defining sub-agent metadata and instructions.

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

Implementation of a parent agent wiring two skill-based sub-agents for marketplace and payment tasks.

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);

Practical Applications

• Use case: A Purchase Assistant Agent delegating to specialized Marketplace and Payment sub-agents for modular product discovery and transaction handling.
• Pitfall: Weak tool metadata in the SKILL.md front matter can cause the parent LLM to fail at correctly routing tasks to the appropriate sub-agent.
• Use case: Multi-model execution optimization where different sub-agents utilize different LLMs tailored to their specific domain tasks.
• Pitfall: Parent agents omitting critical facts in the ‘context’ field, leading to sub-agent execution failure due to insufficient information.

References:

• https://dev.to/bsorrentino/skill-based-sub-agents-with-langgraph4j-and-spring-ai-52b0
• https://bsorrentino.github.io