Multi-Agent Orchestration

Designing multi-agent coordination systems in Codebolt. This section is about how agents cooperate inside one Codebolt system: swarms, flows, shared state, review loops, and orchestration patterns.

If you want to run an already-designed swarm, see Multi-Agent Usage. This section is for the person designing the system underneath.

What this section covers

1. Multi-Agent Orchestration Management — swarms, flows, roles, shared state, and how agents access orchestration primitives.
2. When multi-agent — an honest answer to "do I actually need more than one agent?" (often: no).
3. Patterns — the small number of orchestration patterns that cover almost every real use case.
4. Agent flows — the graph runtime for fixed pipelines.
5. Stigmergy and reputation — emergent coordination through shared state.
6. Drift detection — keeping long-running swarms on-task.
7. Review & merge design — human-in-the-loop patterns.

Where this sits in Codebolt

This section lives primarily in the Agent Subsystem and the orchestration-facing parts of @codebolt/codeboltjs.

The coordination side looks like this:

Feature	Provides	Pages
Swarms	Dynamic groups of cooperating agents	Patterns, Stigmergy
Agent flows	Graph runtime for fixed pipelines	Agent flows
Roles & teams	High-level vocabulary on top of swarms	Patterns
Portfolios	Curated sets of agents per workspace	Multi-Agent Usage
Review & merge	Human-in-the-loop with LLM reviewers	Review & merge design

The core design principle

Multi-agent is a cost, not a feature. Every additional agent multiplies your token bill, adds coordination overhead, and introduces new ways to fail. The goal of good orchestration design is not to use many agents — it's to use the smallest number of agents that gives you a capability a single agent can't.

Common reasons a single agent isn't enough:

• Separation of concerns — a reviewer that reads code with fresh eyes is more useful than the coder second-guessing itself.
• Parallelism — embarrassingly parallel work (e.g. refactor N independent files) benefits from real concurrency.
• Specialization — different agents can use different models, different prompts, different tool allowlists.
• Safety — a privileged "committer" agent reviewing proposals from unprivileged "worker" agents is a real security boundary.

If none of these apply, use one agent.

See also

• Multi-Agent Orchestration Management
• Multi-Environment Orchestration
• Agent Subsystem — the runtime this section builds on
• Planning Hierarchy — orchestration often shows up as planned blocks assigned to different agents
• Multi-Agent Usage — running, not designing