DocsSwarm Engine

Swarm Engine

The Swarm Engine orchestrates multi-agent collaboration on complex tasks. Instead of a single agent working alone, swarms coordinate teams of agents with different specialties to produce higher-quality outputs through structured collaboration patterns.

What is the Swarm Engine?

The Swarm Engine (Engine #22 in the BOSS architecture) is the orchestration layer that manages multi-agent projects. When a task is too complex for a single agent -- requiring research, analysis, creation, review, and communication -- the Swarm Engine coordinates a team of agents to work together on a shared objective.

Every swarm has an objective, a set of participating agents, a collaboration pattern, a budget, and defined deliverables. The Swarm Engine manages the flow of information between agents, tracks progress, enforces budget limits, and produces the final consolidated output.

Swarms are different from simple agent chaining. In a chain, Agent A finishes before Agent B starts. In a swarm, agents can work in parallel, debate each other, vote on decisions, and iteratively refine each other's outputs. The pattern determines the collaboration structure.

6 swarm patterns

Choose the collaboration pattern that best fits your task. Each pattern defines how agents interact, when they hand off work, and how the final output is assembled.

Sequential

Pipeline pattern

Agents work one after another in a defined order. Each agent receives the output of the previous agent as input. Best for workflows with clear stages where later work depends on earlier results.

Maven (research) → Atlas (plan) → Forge (write) → Reed (review)

Best for: Content creation, report generation, proposal writing

Parallel

Fan-out / fan-in pattern

Multiple agents work simultaneously on different subtasks. Results are collected and merged by a coordinator (usually Ori or Atlas). Best when subtasks are independent and you want speed.

Ori (split) → [Maven, Nova, Forge] (parallel) → Atlas (merge)

Best for: Multi-market research, competitive analysis, data gathering

Debate

Adversarial reasoning

Two or more agents take opposing positions and argue for their viewpoint across multiple rounds. A moderator agent synthesizes the arguments and produces a balanced recommendation. Debate forces deeper analysis and surfaces risks that a single agent might miss.

Round 1: Cipher (build) vs Nova (buy) → Atlas (synthesize)
Round 2: Cipher (rebut) vs Nova (rebut) → Atlas (synthesize)
Round 3: Atlas (final recommendation with pros/cons)

Best for: Build vs buy decisions, strategy selection, risk assessment

Consensus

Voting pattern

All agents independently produce their answer to the same question, then vote on the best approach. The majority opinion wins, but dissenting views are documented. This reduces individual agent bias and produces more reliable answers for factual questions.

[Maven, Atlas, Nova, Cipher] (independent) → Vote → Majority + dissents

Best for: Fact verification, quality assessment, code review

Hierarchical

Manager + team pattern

A leader agent decomposes the objective into subtasks, assigns them to team agents, reviews their outputs, requests revisions, and assembles the final deliverable. The leader has authority to accept, reject, or redirect work. Most similar to how human project teams operate.

Atlas (leader) → assigns [Maven, Forge, Nova, Reed] → reviews → assembles

Best for: Complex projects, GTM plans, business cases, audit prep

Code Swarm

Autonomous development pipeline

A specialized swarm pattern for software development. Similar to Devin-like autonomous coding, but with multi-agent review and safety gates. The pipeline flows through architecture, implementation, security review, testing, and documentation.

Blueprint (architecture) → Cipher (implement) → Sentinel (security) → Gauge (test) → Reed (docs)

Each stage produces artifacts that feed into the next. The Guardian governance agent reviews security-sensitive code before any deployment. Failed tests loop back to Cipher for fixes.

Best for: Feature implementation, bug fixes, refactoring, API development

Creating a swarm project

Swarms can be created from the studio UI (click "New Swarm" in any studio) or via the API. Every swarm requires an objective, a pattern, participating agents, and a budget.

create-swarm.ts

// Create a multi-agent swarm project const swarm = await boss.swarm.create({ name: 'Q3 Go-to-Market Strategy', pattern: 'hierarchical', objective: 'Develop a complete GTM plan for the Q3 product launch including positioning, pricing, channels, and timeline', leader: 'atlas', agents: ['atlas', 'maven', 'forge', 'nova', 'reed'], studioId: 'stu_marketing_01', budget: { maxCost: 25.00, // USD - auto-approved under $50 maxTokens: 500000, alertAt: 0.8, // Alert at 80% budget }, deliverables: [ { type: 'document', title: 'GTM Strategy Doc' }, { type: 'table', title: 'Channel Comparison Matrix' }, { type: 'checklist', title: 'Launch Checklist' }, ], }); // Monitor swarm progress const status = await boss.swarm.getStatus(swarm.id); // { phase: 'execution', progress: 0.65, agents: [...], cost: 12.40 }

Here is an example of a debate swarm for a build-vs-buy decision:

debate-swarm.ts

// Create a debate swarm for a complex decision const debate = await boss.swarm.create({ name: 'Build vs Buy: Customer Portal', pattern: 'debate', objective: 'Should we build a custom customer portal or buy a SaaS solution?', agents: [ { id: 'cipher', position: 'build' }, // Argues for building { id: 'nova', position: 'buy' }, // Argues for buying { id: 'atlas', position: 'moderator' }, // Synthesizes and judges ], rounds: 3, studioId: 'stu_engineering_01', deliverables: [ { type: 'document', title: 'Decision Summary with Recommendation' }, ], });

The debate room

Debate swarms have a dedicated UI called the Debate Room. It displays the arguments from each side in real-time, round by round, with the moderator's synthesis after each round. You can observe the debate as it happens and interject with clarifications or constraints at any point.

Debate Room features:

Split view: Side-by-side display of arguments from each position

Round tracking: Progress indicator showing current round and total rounds

Synthesis panel: Moderator's summary after each round, highlighting key points and areas of agreement

Human interjection: Add constraints, ask for clarification, or redirect the debate at any point

Evidence citations: Each argument cites sources from the knowledge base or external research

Final recommendation: Structured decision document with pros, cons, risks, and the moderator's recommendation

Budget gates

Every swarm has a budget that controls how much it can spend on AI model tokens. The budget is enforced by the Budget governance agent in the Service Engine. Three tiers of approval gates prevent runaway costs:

Auto-approved< $50

Swarms under $50 total estimated cost run automatically. The Budget agent monitors spending in real-time and pauses execution if the estimate is exceeded by more than 20%.

Human approval$50 - $500

Swarms between $50 and $500 require a human to approve the budget before execution begins. The swarm presents its plan, estimated cost breakdown by agent, and expected deliverables. A studio admin or org admin must approve.

Board approval> $500

Swarms over $500 require approval from multiple stakeholders. The request goes to the organization's approval chain (configurable in admin settings). This gate prevents accidental expensive operations.

Budget thresholds are configurable. Organization admins can adjust the auto-approve, human-approve, and board-approve thresholds from /admin/settings/budget. The default values ($50 / $500) work well for most organizations.

Code Swarm: autonomous development

The Code Swarm pattern creates a complete software development pipeline with multiple specialist agents. It is the BOSS equivalent of autonomous coding tools like Devin, but with built-in security review, quality gates, and human checkpoints.

Code Swarm pipeline stages

1. ArchitectureBlueprint

Architecture document, database schema, API contract, component diagram

2. ImplementationCipher

Source code, database migrations, API routes, middleware

3. Security ReviewSentinel

OWASP scan results, vulnerability report, remediation suggestions

4. TestingGauge

Unit tests, integration tests, coverage report, regression results

5. DocumentationReed

API docs, user guide, changelog entry, inline code comments

code-swarm.ts

// Create a Code Swarm (Devin-like autonomous development) const codeSwarm = await boss.swarm.create({ name: 'User Authentication Module', pattern: 'code', objective: 'Implement OAuth2 + MFA authentication with login, register, and password reset flows', stages: [ { agent: 'blueprint', task: 'Design the authentication architecture, database schema, and API contract', output: 'architecture_doc', }, { agent: 'cipher', task: 'Implement the backend: routes, middleware, database models, and tests', output: 'source_code', }, { agent: 'sentinel', task: 'Security review: check for OWASP Top 10 vulnerabilities', output: 'security_report', }, { agent: 'gauge', task: 'Write and run integration tests, report coverage', output: 'test_report', }, { agent: 'reed', task: 'Write API documentation and user-facing help articles', output: 'documentation', }, ], studioId: 'stu_engineering_01', budget: { maxCost: 75.00, maxTokens: 1000000 }, });

Safety gates in Code Swarm:

-Guardian reviews all code changes before they leave the sandbox
-Sentinel checks for hardcoded secrets, SQL injection, and XSS vulnerabilities
-Failed tests loop back to Cipher automatically with the failure report
-Human checkpoint before any code is committed or deployed
-All generated code runs in a sandboxed environment, never on production

Playbooks

Agents Guide