Topology selection
tnsai-coordination ships eight groups/ topologies. The trap is picking the one that matches an org chart. For a novel problem that needs continuous reasoning, that choice is usually wrong: each hop compresses context, and the whole drifts even when every node looks fine in isolation.
Doctrine: Wiki Context Engineering vs Role-Based. Mechanics of each topology: Topologies. ROMA is a recursive solver, not an organization spec — see Advanced → RecursiveTaskSolver.
Decision matrix
| Task | Use | Avoid |
|---|---|---|
| Sequential deterministic stages (ETL, CI, triage) | pipeline | network, matrix |
| Independent parallel hypotheses (research, search) | swarm, network, or RecursiveTaskSolver (ROMA) | pipeline, team |
| One coordinator with known workers | hubspoke | hierarchy unless a supervision tree adds real gates |
| Novel problem, reasoning must span the whole task | single agent + context engineering, or ROMA | team, hierarchy, pipeline |
| Dynamic membership + consensus | Council & voting | team |
| Quality gate | Judge | team with a reviewer role |
| Negotiation with incentives | Auction / contract-net | debate used as a market |
| Adversarial / sanity check | debate | council (council is consensus, not opposition) |
coalition and matrix are for dynamic alliances and multi-dimension
assignment. They are not a default for “we have several specialists.”
When team, hierarchy, and pipeline fail
These three map onto the role-playing anti-pattern when the task is not a repeatable workflow with deterministic stage boundaries.
- Handoff compression. A 50-line chain of thought becomes a 3-line summary at the next node.
- Fake specialization.
LEAD/REVIEWERare prompt labels, not capacity splits. The same model sits behind each role. - Every node can pass while the whole drifts. Isolated tests stay green; the integrated answer wanders.
They are the right tool for ETL, approval chains, and other pipelines whose stages have fixed contracts. They are the wrong tool for “figure this research question out.”
For novel work prefer:
- One
Agentwith tools, retrieval, and a verifier — no group. com.tnsai.coordination.roma.RecursiveTaskSolverwhen you need parallel decomposition plus a verification gate that is more than a handoff.
When to choose ROMA
ROMA is the default multi-agent answer when:
- the task is not a pipeline with deterministic stages
- sub-problems can be explored independently
- you need a verifier that is not “the next role in the org chart”
Do not treat RecursiveTaskSolver as an org spec. There is no
Organization type on 0.13.0; that hole is
TAN-5675.
Package-info warnings (Forge)
Javadoc warnings on groups/team, groups/hierarchy, groups/pipeline,
and a “when to choose ROMA” section on roma/package-info.java are
framework edits. They are not in this Docs change. Until they land,
this page is the selection signal.
See also
- Topologies — builders and APIs
- Auto Team — LLM-composed
AgentGroup, still not an org - Advanced → ROMA
Advanced Patterns
Advanced coordination patterns in TnsAI.Coordination for production multi-agent systems.
Channels
The Channels module (TnsAI.Channels) is a multi-channel messaging gateway that connects TnsAI agents to external messaging platforms. It uses an adapter pattern with SPI discovery so new platforms can be added without modifying the core routing logic.