The `swarm()` Builder

The recommended way to create swarms is the swarm() factory function. It returns a SwarmBuilder with a chainable API for configuring every aspect of your swarm.

import { Cogitator, Agent } from '@cogitator-ai/core';
import { swarm } from '@cogitator-ai/swarms';

const cogitator = new Cogitator({
  /* ... */
});

const team = swarm('my-team')
  .strategy('hierarchical')
  .supervisor(supervisorAgent)
  .workers([workerA, workerB])
  .resources({ maxConcurrency: 4, tokenBudget: 50_000 })
  .errorHandling({ onAgentFailure: 'retry', retry: { maxRetries: 2, backoff: 'exponential' } })
  .build(cogitator);

The build(cogitator) call validates the configuration and returns a ready-to-run Swarm instance.

Builder Methods

Required

Every swarm needs a name (passed to swarm()) and a strategy:

swarm('team-name').strategy('hierarchical'); // required

Agent Configuration

Different strategies expect agents in different roles:

// hierarchical: supervisor + workers
swarm('dev-team').strategy('hierarchical').supervisor(leadAgent).workers([devAgent, qaAgent]);

// consensus, round-robin, auction: flat agent list
swarm('review-board').strategy('consensus').agents([reviewerA, reviewerB, reviewerC]);

// debate: agents + optional moderator
swarm('debate-team')
  .strategy('debate')
  .agents([advocateAgent, criticAgent])
  .moderator(moderatorAgent);

// pipeline: configured via strategy-specific options
swarm('pipeline').strategy('pipeline').pipeline({
  stages: [
    /* ... */
  ],
});

Strategy-Specific Configuration

Each strategy has its own configuration method that matches the strategy name:

swarm('team').strategy('hierarchical').hierarchical({
  maxDelegationDepth: 3,
  workerCommunication: false,
  routeThrough: 'supervisor',
  visibility: 'full',
});

swarm('pool')
  .strategy('round-robin')
  .roundRobin({
    sticky: true,
    stickyKey: (input) => extractSessionId(input),
    rotation: 'sequential',
  });

swarm('board').strategy('consensus').consensus({
  threshold: 0.66,
  maxRounds: 3,
  resolution: 'majority',
  onNoConsensus: 'supervisor-decides',
});

swarm('experts').strategy('auction').auction({
  bidding: 'capability-match',
  selection: 'highest-bid',
  minBid: 0.3,
});

swarm('pipe')
  .strategy('pipeline')
  .pipeline({
    stages: [
      { name: 'research', agent: researchAgent },
      { name: 'write', agent: writerAgent },
      { name: 'review', agent: reviewAgent, gate: true },
    ],
    gates: {
      review: {
        condition: (out) => out.includes('APPROVED'),
        onFail: 'retry-previous',
        maxRetries: 2,
      },
    },
  });

swarm('debate').strategy('debate').debate({
  rounds: 3,
  format: 'structured',
});

Communication

Configure how agents communicate within the swarm:

swarm('team')
  .strategy('hierarchical')
  .messaging({
    enabled: true,
    protocol: 'direct',
    maxMessageLength: 2000,
    maxMessagesPerTurn: 5,
    maxTotalMessages: 100,
  })
  .blackboardConfig({
    enabled: true,
    sections: { tasks: [], results: {} },
    trackHistory: true,
  });

Resources and Error Handling

swarm('team')
  .strategy('hierarchical')
  .resources({
    maxConcurrency: 5,
    tokenBudget: 100_000,
    costLimit: 2.0,
    timeout: 300_000,
  })
  .errorHandling({
    onAgentFailure: 'retry',
    retry: { maxRetries: 3, backoff: 'exponential', initialDelay: 1000, maxDelay: 30000 },
    failover: { 'primary-coder': 'backup-coder' },
    circuitBreaker: { enabled: true, threshold: 5, resetTimeout: 60_000 },
  });

Distributed Mode

Enable Redis-backed distributed coordination:

swarm('distributed-team')
  .strategy('hierarchical')
  .distributed({
    enabled: true,
    redis: { host: 'localhost', port: 6379 },
    queue: 'swarm-agent-jobs',
    timeout: 300_000,
  });

Assessment

Enable automatic model selection with the assessor:

swarm('smart-team')
  .strategy('hierarchical')
  .withAssessor({
    preferLocal: true,
    minCapabilityMatch: 0.3,
    maxCostPerRun: 0.5,
    enabledProviders: ['ollama', 'openai', 'anthropic'],
  });

The `Swarm` Class

If you prefer imperative construction, use the Swarm class directly:

import { Swarm } from '@cogitator-ai/swarms';

const team = new Swarm(cogitator, {
  name: 'dev-team',
  strategy: 'hierarchical',
  supervisor: leadAgent,
  workers: [devAgent, qaAgent],
  resources: { maxConcurrency: 4 },
});

The constructor validates configuration immediately and throws if required fields are missing (e.g. no supervisor for hierarchical, no stages for pipeline).

Running a Swarm

Both Swarm and the builder result expose the same API:

const result = await team.run({
  input: 'Build a REST API for user management',
  context: { language: 'typescript', framework: 'express' },
  saveHistory: false,
});

console.log(result.output);
console.log(result.agentResults);

The SwarmRunOptions:

Field	Type	Description
`input`	`string`	The task to execute
`context`	`Record<string, unknown>`	Additional context passed to all agents
`saveHistory`	`boolean`	Whether to persist conversation history (default `true`)

Swarm Instance API

Once built, a Swarm provides these methods:

// execution
await team.run({ input: '...' });

// introspection
team.name;
team.id;
team.strategyType;
team.getAgents();
team.getAgent('frontend-dev');
team.getResourceUsage();
team.getLastAssessment();

// events
const unsub = team.on('agent:complete', (event) => {
  /* ... */
});
team.once('swarm:complete', (event) => {
  /* ... */
});

// control
team.pause();
team.resume();
team.abort();
team.reset();

// distributed cleanup
await team.close();

Dry Run

Preview model assignments without executing the swarm:

const team = swarm('team')
  .strategy('hierarchical')
  .supervisor(leadAgent)
  .workers([devAgent, qaAgent])
  .withAssessor({ preferLocal: true })
  .build(cogitator);

const assessment = await team.dryRun({ input: 'Build a REST API' });

for (const assignment of assessment.assignments) {
  console.log(`${assignment.agentName}: ${assignment.assignedModel} (score: ${assignment.score})`);
}

console.log(`Estimated cost: $${assessment.totalEstimatedCost.toFixed(4)}`);

Swarm Builder