DEV Community

Solon Framework
Solon Framework

Posted on

TeamAgent Collaboration Protocols in Solon: From Pipelines to Supervisor Orgs

#agents #llm #ai #architecture

If one agent is a specialist, a team is an org chart. The hard part is not adding more agents — it is deciding who speaks next, who reviews, and when the run stops.

Solon AI’s TeamAgent treats that decision as a first-class collaboration protocol. Swap the protocol, keep the members, and the same team moves from a linear pipeline to a manager-led hierarchy without rewriting business logic.

This post walks through the built-in protocols, the builder knobs that matter in production, and two patterns you will actually ship: SEQUENTIAL pipelines and HIERARCHICAL supervisor teams.

Why multi-agent needs a protocol

A single fat prompt often fails for boring reasons:

  • context grows until the model loses the thread
  • roles blur, so every agent tries to do everything
  • handoffs become ad-hoc strings instead of a graph

TeamAgent solves that with three pieces:

  1. Members — specialized agents with clear name / role
  2. Protocol — the social rules of the team
  3. Supervisor chat model — the decision brain that routes work (especially in hierarchical mode)

Dependency:

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-ai-agent</artifactId>
</dependency>
Enter fullscreen mode Exit fullscreen mode

Built-in protocols at a glance

Access them via TeamProtocols.xxx:

Protocol Mode What it optimizes for Best fit
NONE Transparent Zero framework orchestration External hand-drawn flows, extreme customization
HIERARCHICAL Centralized Task split, assign, audit Complex projects, compliance, quality gates
SEQUENTIAL Linear relay Predictable state handoff Translate → polish → publish pipelines
SWARM Dynamic self-org Fast decentralized handoff Support routing, high-churn multi-turn work
A2A Peer transfer Direct expert-to-expert handoff Deep vertical consultation
CONTRACT_NET Bid / award Competition for the best worker Best-of-N selection, distributed assignment
MARKET_BASED Economic game Cost-aware model/resource mix Token-sensitive routing across model tiers
BLACKBOARD Shared context Async experts react to shared state Incident triage, multi-source fusion

Default protocol is HIERARCHICAL. That is intentional: most product teams want a supervisor that can break work down and check quality.

Minimal build: members + protocol 

ReActAgent coder = ReActAgent.of(chatModel)
        .name("coder")
        .role("Write production-quality Java")
        .build();

ReActAgent tester = ReActAgent.of(chatModel)
        .name("tester")
        .role("Write and run unit tests")
        .build();

TeamAgent techTeam = TeamAgent.of(chatModel)
        .name("dev_group")
        .agentAdd(coder)
        .agentAdd(tester)
        .protocol(TeamProtocols.SEQUENTIAL)
        .build();

String result = techTeam.prompt("Implement a sort helper and tests.")
        .call()
        .getContent();
Enter fullscreen mode Exit fullscreen mode

Notes that matter:

  • TeamAgent.of(chatModel) — the team-level model acts as Supervisor
  • agentAdd(...) — members can be ReActAgent, SimpleAgent, or even nested teams
  • protocol(...) — this is the topology switch
  • members execute in add order under SEQUENTIAL

Pattern 1: SEQUENTIAL pipeline

Use this when the path is known and you want deterministic relay:

translate → polish → summarize

TeamAgent simpleTeam = TeamAgent.of(chatModel)
        .name("translator_group")
        .role("Multilingual translation and polish team")
        .agentAdd(ReActAgent.of(chatModel)
                .name("translator")
                .role("Translate Chinese to English")
                .build())
        .agentAdd(ReActAgent.of(chatModel)
                .name("polisher")
                .role("Polish English so it sounds native")
                .build())
        .protocol(TeamProtocols.SEQUENTIAL)
        .build();

String result = simpleTeam.prompt("你好，很高兴认识你")
        .call()
        .getContent();
Enter fullscreen mode Exit fullscreen mode

Why it works:

  • previous agent output becomes the next input
  • less context thrash than free-form multi-agent chat
  • easy to reason about failure points

Choose SEQUENTIAL when stages are independent and ordered. Do not choose it when later stages must re-plan earlier stages.

Pattern 2: HIERARCHICAL supervisor team

This is the “real company” mode. The supervisor parses the user request, assigns specialists, and synthesizes the final answer.

TeamAgent techTeam = TeamAgent.of(chatModel)
        .name("tech_support_center")
        .role("Technical support expert center")
        .instruction("Handle complex customer issues with DB lookup and log triage")

        .agentAdd(ReActAgent.of(chatModel)
                .name("db_expert")
                .role("Database expert; write SQL to inspect user state")
                .defaultToolAdd(dbTool)
                .build())
        .agentAdd(ReActAgent.of(chatModel)
                .name("log_analyser")
                .role("Log analysis expert; extract exceptions from server logs")
                .defaultToolAdd(logTool)
                .build())

        .protocol(TeamProtocols.HIERARCHICAL)
        .maxTurns(12)
        .retryConfig(3, 2000L)
        .modelOptions(options -> {
            options.setTemperature(0.1f); // keep routing strict
        })
        .build();

String finalAnswer = techTeam.prompt(
                "User 9527 reports login failures. Investigate and recommend next steps.")
        .call()
        .getContent();
Enter fullscreen mode Exit fullscreen mode

Production knobs from the config table:

Knob Default Why it exists
protocol HIERARCHICAL Org structure of the team
maxTurns 8 Team-wide fuse against infinite handoffs
maxRetries 3 Supervisor decision/parse retries
retryDelayMs 1000L Backoff between decision retries
modelOptions — Tune supervisor temperature / sampling
graphAdjuster — Fine-tune the generated flow graph
interceptors empty Observe or gate handoffs

maxTurns is not optional in production. Multi-agent systems fail by looping more often than by missing a tool.

Tools still follow the normal Solon AI pattern

Members are ordinary agents. Tools stay on the member that owns the skill:

public static class WeatherService extends AbsToolProvider {
    @ToolMapping(description = "Get live weather for a city")
    public String query(@Param(description = "City name, e.g. Tokyo") String city) {
        return "Heavy rain alert for " + city + ". Outdoor spots closed.";
    }
}

TeamAgent travelTeam = TeamAgent.of(chatModel)
        .name("auto_travel_agent")
        .agentAdd(ReActAgent.of(chatModel)
                .name("searcher")
                .role("Weather lookup expert")
                .defaultToolAdd(new WeatherService())
                .build())
        .agentAdd(ReActAgent.of(chatModel)
                .name("planner")
                .role("Itinerary planner")
                .instruction("Prefer indoor options if weather is bad.")
                .build())
        .maxTurns(8)
        .build(); // default protocol = HIERARCHICAL

AgentSession session = InMemoryAgentSession.of("sn_travel_2026_001");
TeamResponse resp = travelTeam.prompt("I am in Tokyo. Plan one day.")
        .session(session)
        .call();
Enter fullscreen mode Exit fullscreen mode

What to watch in the response:

  • resp.getContent() — final team answer
  • resp.getTrace() — collaboration records / handoff path

That trace is the difference between “multi-agent magic” and a system you can debug at 2 a.m.

How to choose a protocol

A practical decision tree:

  1. Fixed stages, known order → SEQUENTIAL
  2. Need decomposition + quality review → HIERARCHICAL
  3. Many overlapping specialists, pick best worker → CONTRACT_NET / MARKET_BASED
  4. Direct expert transfer without a manager tax → A2A
  5. Shared incident board, async contribution → BLACKBOARD
  6. You already own external orchestration → NONE

Most product teams should start with HIERARCHICAL or SEQUENTIAL. The fancier protocols are powerful, but only after role descriptions and stop conditions are solid.

Role text is not decoration

In a team, role / instruction text is routing data for the supervisor. Weak roles produce weak assignment:

  • bad: "helper"
  • better: "Database expert; write SQL to inspect user login state and recent auth events"

Also keep member names stable. Traces, session recovery, and nested-team routing all benefit from stable identities.

Nested teams are allowed

A TeamAgent can itself be a member of a larger team. That lets you grow from a two-person pipeline into a multi-layer org without inventing a second framework.

Useful when:

  • a support desk team contains a billing sub-team
  • a release team contains a security-review sub-team
  • a research team contains retrieval + synthesis sub-teams

What not to do

  • Do not rely on free chat between agents with no maxTurns
  • Do not put every tool on every member “just in case”
  • Do not switch to CONTRACT_NET / MARKET_BASED before roles are distinguishable
  • Do not invent custom tool interfaces — keep AbsToolProvider + @ToolMapping
  • Do not skip traces when debugging handoff bugs

Quick checklist before production

  • [ ] Each member has a distinct name and actionable role
  • [ ] Protocol matches the real workflow shape
  • [ ] maxTurns is set for the longest healthy path
  • [ ] Supervisor temperature is low enough for routing discipline
  • [ ] Tools live on the specialist that owns them
  • [ ] Session + trace are available for resume/debug

Closing

Multi-agent systems do not become reliable by adding more models. They become reliable when handoffs are explicit.

Solon’s TeamAgent makes that explicit:

  • members define capability
  • TeamProtocols defines organization
  • supervisor + maxTurns define control
  • traces make the whole thing inspectable

Start with a two-agent SEQUENTIAL pipeline. When a task needs re-planning and review, flip to HIERARCHICAL. Keep the members; change the protocol. That is the point.

References

Top comments (0)