Mastering Multi‑Agent Patterns with AgentScope and Spring AI Alibaba

Background

Enterprises moving from LLM experimentation to production need to close business loops. Studies show multi‑agent collaboration improves complex reasoning accuracy by ~32% and reduces hallucinations by ~26%.

Single‑Agent First Principle

AgentScope recommends starting with a single ReActAgent that combines a model, a toolkit, and a memory. Most routine tasks can be solved with one model plus appropriate tools, offering low latency, easy debugging, and clear fault isolation.

When to Adopt Multi‑Agent Architectures

Context Management : required knowledge exceeds a single context window, needing step‑wise or agent‑specific presentation.

Division of Labor : different teams maintain specialized expertise and need clear boundaries.

Parallelization : high‑cost sub‑tasks must run concurrently to meet latency targets.

Structured Flow : business processes demand strict sequencing, routing, or role transitions that a single agent cannot guarantee.

In practice a Hybrid Agent Cascade is used: a lightweight model first assesses task complexity; simple requests stay with the single agent, while high‑confidence or complex requests are escalated to a multi‑agent network, reducing compute cost while preserving accuracy.

Core Multi‑Agent Patterns Supported by AgentScope

Pipeline : Fixed sequential, parallel, or looping flows (SequentialAgent, ParallelAgent, LoopAgent). State is passed via OverAllState and linked with instruction / outputKey.

Routing : Classify input, dispatch to expert agents, and merge results. Implemented either with a simple RouterService.run(query) call or with a StateGraph sub‑graph.

Skills : Selective disclosure of expertise. Agents see only skill name and description; full skill definitions are loaded on demand via read_skill("skill_name") and SKILL.md, preventing context pollution.

Subagents : Orchestrator creates stateless sub‑agents via Task. Each sub‑agent runs in an isolated context (Markdown file or Java API) and returns its result as a tool output.

Supervisor : Treat each expert as a tool (e.g., schedule_event, manage_email) and dynamically decides which tool to invoke based on the evolving conversation.

Handoffs : State‑driven role transfer. A tool updates a state variable such as active_agent; the graph follows conditional edges ( ReplaceStrategy) to switch the responsible agent.

Custom Workflow : Combine deterministic business logic with LLM nodes using StateGraph. Allows pre‑processing, routing sub‑graph, and post‑processing while keeping a single shared state.

Implementation Highlights

All patterns share a common building block: AgentScopeAgent (a ReActAgent with a toolkit). Example code for a simple ReActAgent:

public static void main(String[] args) {
    // Prepare tools
    Toolkit toolkit = new Toolkit();
    toolkit.registerTool(new SimpleTools());

    // Create agent
    ReActAgent jarvis = ReActAgent.builder()
        .name("Jarvis")
        .sysPrompt("You are a helpful assistant named Jarvis.")
        .model(DashScopeChatModel.builder()
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .modelName("qwen3-max")
            .build())
        .toolkit(toolkit)
        .build();

    // Send message
    Msg msg = Msg.builder().textContent("Hello! Jarvis, what time is it?").build();
    Msg response = jarvis.call(msg).block();
    System.out.println(response.getTextContent());
}

For each pattern, AgentScope provides concrete examples in the agentscope-examples repository (e.g., agentscope-examples/multiagent-patterns/pipeline, routing, skills, subagent, supervisor, handoffs, workflow). Run the examples with:

mvn spring-boot:run

Choosing the Right Pattern

Use Pipeline for deterministic, repeatable processes; Routing for one‑shot classification‑then‑aggregation; Handoffs when a conversation must switch roles (e.g., sales ↔ support); Skills for a single agent with multiple on‑demand capabilities; Subagents or Supervisor when isolation, security, or tool‑level permission control is required; and Custom Workflow for complex, multi‑stage graphs.

Integration with Spring AI Alibaba

Spring AI Alibaba now includes full support for AgentScope through the AgentScope Starter and AgentScope Runtime Starter. Developers can embed AgentScope agents (ReActAgent, Memory, Toolkit) into a Spring AI StateGraph, achieving a hybrid architecture that combines agentic intelligence with workflow orchestration. This enables durable execution, state persistence, parallelism, and observability (token‑level streaming, node‑level tracing).

Official Examples

All patterns are demonstrated in the open‑source repository

https://github.com/agentscope-ai/agentscope-java/tree/main/agentscope-examples

. Each example can be run with mvn spring-boot:run and includes use‑cases such as SQL generation, RAG retrieval, customer service, multi‑agent debate, and custom workflows.

Version Information

AgentScope Java 1.0.10 source:

https://github.com/agentscope-ai/agentscope-java/tree/main/agentscope-examplesSpring

Spring AI Alibaba 1.1.2.2 release:

https://github.com/alibaba/spring-ai-alibaba/releases/tag/v1.1.2.2

Conclusion

AgentScope Java offers a rich toolbox—Pipeline, Routing, Skills, Subagents, Supervisor, Handoffs, and Custom Workflow—allowing developers to start with a simple ReActAgent and progressively adopt more sophisticated multi‑agent architectures as business needs evolve. Combined with Spring AI Alibaba’s Graph engine, teams gain a unified, observable, and durable platform for building enterprise‑grade AI applications.