# Swarms API URL: https://cogitator.app/docs/api-reference/swarms > Public exports of @cogitator-ai/swarms — the Swarm class and builder, strategies, communication, distributed execution, swarm tools, workflow nodes and the assessor — with their signatures. ## Swarm ```typescript import { Cogitator, Agent } from '@cogitator-ai/core'; import { Swarm, swarm } from '@cogitator-ai/swarms'; const team = new Swarm(cog, { name: 'dev-team', strategy: 'hierarchical', supervisor: lead, workers: [developer, reviewer], hierarchical: { maxDelegationDepth: 2 }, }); const sameTeam = swarm('dev-team') .strategy('hierarchical') .supervisor(lead) .workers([developer, reviewer]) .hierarchical({ maxDelegationDepth: 2 }) .build(cog); const result = await team.run({ input: 'Build a landing page' }); console.log(result.output, result.agentResults.get('developer')?.output); ``` | Member | Signature | Purpose | | --------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | constructor | `new Swarm(cogitator: Cogitator, config: SwarmConfig, assessorConfig?: AssessorConfig)` | With `assessorConfig`, the first `run()` assigns models first | | `run` | `run(options: SwarmRunOptions): Promise` | Run the swarm on an input | | `dryRun` | `dryRun(options: { input: string }): Promise` | Assess models without running (throws without an assessor) | | `getLastAssessment` | `getLastAssessment(): AssessmentResult \| undefined` | The assessment the last run used | | `on` / `once` | `on(event: SwarmEventType \| '*', handler: SwarmEventHandler): () => void` | Subscribe to [events](#events); returns an unsubscribe function | | `getAgents`, `getAgent` | `getAgents(): SwarmAgent[]`, `getAgent(name: string): SwarmAgent \| undefined` | Agents with their metadata, state and usage | | `getResourceUsage` | `getResourceUsage(): SwarmResourceUsage` | Tokens, cost, elapsed time, per-agent usage | | `pause`, `resume`, `abort` | `(): void` | Control a running swarm | | `isPaused`, `isAborted` | `(): boolean` | State | | `respondToApproval` | `respondToApproval(requestId: string, response: NegotiationApprovalResponse): void` | Answer a negotiation approval gate (`request.id` from `negotiation:approval-required`); throws for other strategies | | `reset` | `reset(): Promise` | Clear messages, blackboard, usage and agent state | | `close` | `close(): Promise` | Release resources (Redis connections when distributed) | | `name`, `id`, `strategyType`, `isDistributed` | getters | The swarm's identity | | `messageBus` | `ReadTrackingMessageBus` | `MessageBus` plus `markAsRead(agentName, ids)`, `resetTurnCounts(agentName?)`, `onMessage(listener)` | | `blackboard` | `ObservableBlackboard` | `Blackboard` plus `onWrite(listener)` | | `events` | `QueryableSwarmEventEmitter` | `SwarmEventEmitter` plus `getEventsByType(type)`, `getEventsByAgent(name)`, `clearEvents()` | | Export | Signature | Purpose | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `swarm` | `swarm(name: string): SwarmBuilder` | Fluent builder | | `SwarmBuilder` | `strategy`, `supervisor`, `workers`, `agents`, `moderator`, `router`, `agentMetadata`, `observability`, `hierarchical`, `roundRobin`, `consensus`, `auction`, `pipeline`, `debate`, `negotiation`, `messaging`, `blackboardConfig`, `agentTools`, `resources`, `errorHandling`, `distributed`, `withAssessor(config?)`, `build(cogitator): Swarm` | One method per `SwarmConfig` field | | `SwarmTimeoutError` | `class extends Error { swarmName; timeoutMs }` | Thrown by `run()` when its `timeout` elapses | ### SwarmConfig | Field | Type | Used by | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `name` | `string` | all | | `strategy` | `SwarmStrategy` | all | | `supervisor`, `workers` | `Agent`, `Agent[]` | `hierarchical` (supervisor required) | | `agents` | `Agent[]` | `round-robin`, `consensus`, `auction`, `debate`, `negotiation` | | `moderator`, `router` | `Agent` | `debate` moderator, specialist routing | | `stages` | `PipelineStage[]` | pipeline stages (alternative to `pipeline.stages`; different stages in both throw) | | `agentMetadata` | `Record` | role, expertise, priority, weight, `locked` per agent name | | `hierarchical`, `roundRobin`, `consensus`, `auction`, `pipeline`, `debate`, `negotiation` | strategy configs | the matching strategy; `consensus`, `auction`, `pipeline` and `debate` are required for theirs | | `messaging`, `blackboard` | `MessageBusConfig`, `BlackboardConfig` | communication (`messaging.protocol` and `blackboard.locking` are deprecated, no effect) | | `agentTools` | `SwarmAgentToolsConfig` (`{ messaging?: boolean; blackboard?: boolean }`) | built-in messaging / blackboard tools for every agent; local swarms only | | `resources` | `SwarmResourceConfig` | `maxConcurrency` (default 4), `tokenBudget`, `costLimit`, `timeout`, `perAgent` | | `errorHandling` | `SwarmErrorConfig` | retry / skip / failover / abort on agent failure | | `distributed` | `DistributedSwarmConfig` | run agents as Redis jobs | | `observability` | `{ tracing?; messageLogging?; blackboardLogging? }` | logging; `tracing` logs each agent run's trace (spans) | ### SwarmRunOptions and Results ```typescript interface SwarmRunOptions { input: string; context?: Record; // passed to all agents threadId?: string; userId?: string; // every agent run acts for this user timeout?: number; saveHistory?: boolean; // default: true onAgentStart?: (agentName: string) => void; onAgentComplete?: (agentName: string, result: RunResult) => void; onAgentError?: (agentName: string, error: Error) => void; onMessage?: (message: SwarmMessage) => void; onEvent?: (event: SwarmEvent) => void; } interface StrategyResult { output: unknown; structured?: unknown; agentResults: Map; votes?: Map; // consensus bids?: Map; // auction auctionWinner?: string; debateTranscript?: SwarmMessage[]; pipelineOutputs?: Map; negotiationResult?: NegotiationResult; } ``` ## Strategies | `strategy` | Class | Config (`SwarmConfig` field) | Needs | | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `'hierarchical'` | `HierarchicalStrategy` | `hierarchical?: { maxDelegationDepth? (3), workerCommunication?, routeThrough?, visibility? }` | `supervisor` | | `'round-robin'` | `RoundRobinStrategy` | `roundRobin?: { sticky?, stickyKey?, rotation?: 'sequential' \| 'random' }` | 1+ `agents` | | `'consensus'` | `ConsensusStrategy` | `consensus: { threshold, maxRounds, resolution: 'majority' \| 'unanimous' \| 'weighted', onNoConsensus, weights? }` | 2+ `agents` | | `'auction'` | `AuctionStrategy` | `auction: { bidding: 'capability-match' \| 'custom', bidFunction?, selection, minBid? }` | 1+ `agents` | | `'pipeline'` | `PipelineStrategy` | `pipeline: { stages: PipelineStage[], stageInput?, gates? }` (or top-level `stages`) | 1+ stages | | `'debate'` | `DebateStrategy` | `debate: { rounds, maxTokensPerTurn?, reasoningTokensPerTurn?, format?, synthesisPrompt? }` | 2+ `agents`, `rounds` ≥ 1 | | `'negotiation'` | `NegotiationStrategy` | `negotiation?: Partial` | 2+ `agents` | | Export | Signature | Purpose | | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------- | | `createStrategy` | `createStrategy(coordinator: SwarmCoordinatorInterface, config: SwarmConfig): IStrategy` | The strategy for a config | | `getDefaultStrategyConfig` | `getDefaultStrategyConfig(strategy: SwarmStrategy)` | Default config of a strategy | | `BaseStrategy` | `abstract class BaseStrategy implements IStrategy` (`new (coordinator)`) | Base for your own strategy | | `TurnManager`, `ConvergenceCalculator`, `ApprovalIntegration` | classes | Building blocks of the negotiation strategy | Every strategy class takes `(coordinator, config)`. See [Strategies](/docs/swarms/strategies). ## Coordinators | Export | Signature | Purpose | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `SwarmCoordinator` | `new SwarmCoordinator(cogitator: Cogitator, config: SwarmConfig)` | In-process coordinator `Swarm` uses | | `DistributedSwarmCoordinator` | `new DistributedSwarmCoordinator(options: { config; distributed: DistributedSwarmConfig; resolveModel? })` — `initialize()`, `reset()`, `close()` | Runs agent turns as jobs on a Redis queue for `@cogitator-ai/worker` | | `BaseSwarmCoordinator` | abstract class — `runInScope(scope: SwarmRunScope, work)` binds a strategy run to its run's `threadId`, `userId` and `signal` | Shared coordinator logic | | `swarmJobQueueKey` | `swarmJobQueueKey(keyPrefix?: string, queue?: string): string` | Redis key of the agent job queue | | `ResourceTracker` | `new ResourceTracker(config?: SwarmResourceConfig)` — `trackAgentRun`, `isWithinBudget`, `checkLimit`, `getUsage`, `getAgentUsage`, `getRemainingBudget`, `reset` | Budgets | | `CircuitBreaker` | `new CircuitBreaker(config: { threshold; resetTimeout; successThreshold? })` — `canExecute`, `recordSuccess`, `recordFailure`, `getState`, `onStateChange`, `reset` | Per-agent failure breaker | `DistributedSwarmConfig`: `{ enabled, queue? ('swarm-agent-jobs'), timeout? (300000), redis?: { host?, port?, password?, keyPrefix?, db? }, retry?, cleanupAfter? (3600000), workerConcurrency? }`. `retry: { maxRetries? (3), backoff? ('exponential'), initialDelay? (1000), maxDelay? (30000) }` re-dispatches jobs that fail on a worker or time out (no retries without it). `cleanupAfter` is how long the swarm's Redis state is kept after `close()` (`0` deletes it at once). `workerConcurrency` is deprecated and has no effect; set `concurrency` on `DistributedSwarmWorker`. The job payload and result types are `SwarmAgentJobPayload`, `SwarmAgentJobResult` and `SerializedSwarmAgentConfig`. See [Distributed Swarms](/docs/swarms/distributed). ## Communication | Export | Signature | Purpose | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `InMemoryMessageBus` | `new InMemoryMessageBus(config: MessageBusConfig)` | `MessageBus` in process memory | | `RedisMessageBus` | `new RedisMessageBus(config: MessageBusConfig, options: { redis; swarmId; keyPrefix? })` | `MessageBus` over Redis | | `InMemoryBlackboard` | `new InMemoryBlackboard(config: BlackboardConfig)` | `Blackboard` in process memory | | `RedisBlackboard` | `new RedisBlackboard(config: BlackboardConfig, options: { redis; swarmId; keyPrefix? })` | `Blackboard` over Redis | | `SwarmEventEmitterImpl` | `new SwarmEventEmitterImpl(maxEvents?: number)` | `QueryableSwarmEventEmitter` in process memory | | `RedisSwarmEventEmitter` | `new RedisSwarmEventEmitter(options: { redis; swarmId; keyPrefix?; maxEvents? })` | `QueryableSwarmEventEmitter` over Redis pub/sub | | `isReadTrackingMessageBus`, `isObservableBlackboard` | type guards | Optional capabilities of a bus / blackboard | | `ReadTrackingMessageBus`, `ObservableBlackboard`, `QueryableSwarmEventEmitter` | types | The extended interfaces `swarm.messageBus`, `swarm.blackboard` and `swarm.events` return | `MessageBus`: `send(message)`, `broadcast(from, content, channel?)`, `subscribe(agentName, handler)`, `getMessages(agentName, limit?)`, `getConversation(a, b)`, `getAllMessages()`, `getUnreadMessages(agentName)`, `clear()`. `Blackboard`: `read(section)`, `write(section, data, agentName)`, `append(section, item, agentName)`, `has`, `delete`, `subscribe(section, handler)`, `getSections()`, `getSection(section)`, `getHistory(section)`, `clear()`. See [Communication](/docs/swarms/communication). ## Swarm Tools Inside a swarm, the hierarchical supervisor gets the delegation tools, consensus voters the voting tools and negotiating agents the negotiation tools automatically; `agentTools` adds the messaging and blackboard tools to every agent. The factories build the same tools for custom strategies: | Export | Signature | Tools | | ------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createSwarmTools` | `createSwarmTools(context: SwarmToolContext): Tool[]` | all of the tools below | | `createStrategyTools` | `createStrategyTools(strategy, context: SwarmToolContext): Tool[]` | the set for a strategy | | `createMessagingTools` | `createMessagingTools(messageBus, currentAgent, swarmId?, options?)` | `send_message`, `read_messages`, `broadcast_message`, `reply_to_message` | | `createBlackboardTools` | `createBlackboardTools(blackboard, currentAgent)` | `read_blackboard`, `write_blackboard`, `append_blackboard`, `list_blackboard_sections`, `get_blackboard_history` | | `createDelegationTools` | `createDelegationTools(coordinator, blackboard, currentAgent)` | `delegate_task`, `check_progress`, `request_revision`, `list_workers` | | `createVotingTools` | `createVotingTools(blackboard, events, currentAgent, agentWeight?)` | `cast_vote`, `get_votes`, `change_vote`, `get_consensus_status` | | `createNegotiationTools` | `createNegotiationTools(blackboard, events, currentAgent, agentWeight?)` | `make_offer`, `counter_offer`, `accept_offer`, `reject_offer`, `get_negotiation_status`, `get_current_offers`, `propose_coalition`, `join_coalition`, `declare_interests` | `SwarmToolContext`: `{ coordinator, blackboard, messageBus, events, agentName, agentWeight?, swarmId? }`. ## Workflow Nodes | Export | Signature | Purpose | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | | `swarmNode` | `swarmNode(swarmOrConfig: Swarm \| SwarmConfig, options?: SwarmNodeOptions): WorkflowNode` | Run a swarm as a workflow node | | `conditionalSwarmNode` | `conditionalSwarmNode(swarmOrConfig, condition: (state: S, ctx) => boolean, options?)` | Run only when `condition` holds | | `parallelSwarmsNode` | `parallelSwarmsNode(swarms: { swarm; key; options? }[], mergeResults?: (results: Record) => Partial)` | Several swarms at once | `SwarmNodeOptions`: `{ inputMapper?: (state, input?) => string; stateMapper?: (result: StrategyResult) => Partial; runOptions?: Partial }`. With a `SwarmConfig`, the node builds the swarm from the `cogitator` in the node context. ## Assessor | Export | Signature | Purpose | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `SwarmAssessor` | `new SwarmAssessor(config?: AssessorConfig, runtime?: AssessorRuntime)` | Pick models per agent for a task; with `runtime` (a Cogitator) `'ai'` / `'hybrid'` analysis runs and cloud models are limited to routable providers | | `assessor.analyze` | `analyze(task: string, swarmConfig: SwarmConfig, resolveModel?): Promise` | Requirements, candidates and assignments | | `assessor.assignModels` | `assignModels(config: SwarmConfig, result: AssessmentResult): SwarmConfig` | Apply an assessment | | `assessor.suggestModels` | `suggestModels(requirements: TaskRequirements): Promise` | Ranked models for requirements | | `createAssessor` | `createAssessor(config?: AssessorConfig, runtime?: AssessorRuntime): SwarmAssessor` | Factory | | `TaskAnalyzer` | `new TaskAnalyzer()` — `analyze(task: string): TaskRequirements` | Rule-based task analysis | | `AiTaskAnalyzer` | `new AiTaskAnalyzer(runtime: Pick, model?: string)` — `analyze(task: string): Promise` | Model-based task analysis (`'ai'` / `'hybrid'` modes) | | `AssessorRuntime` | `Pick` | What the assessor needs from a Cogitator | | `ModelDiscovery` | `new ModelDiscovery(config: AssessorConfig, canRunModel?: (model: DiscoveredModel) => boolean)` — `discoverAll`, `discoverOllama`, `getCloudModels`, `checkOllamaAvailability` | Available models | | `ModelScorer` | `new ModelScorer()` — `score(model, requirements)`, `scoreAll(models, requirements)` | Score models (`ScoredModel`) | | `RoleMatcher` | `new RoleMatcher()` — `analyzeRole(agent, taskReqs)`, `extractAgentsFromConfig(config)` | Requirements per role | See [Assessment](/docs/swarms/assessment). ## Events `SwarmEventType` covers the swarm lifecycle (`swarm:start`, `swarm:complete`, `swarm:error`, `swarm:paused`, `swarm:resumed`, `swarm:aborted`, `swarm:reset`), agents (`agent:start`, `agent:complete`, `agent:error`), messaging (`message:sent`, `message:received`, `blackboard:write`), each strategy (`consensus:*`, `auction:*`, `debate:*`, `pipeline:*`, `round-robin:assigned`, `negotiation:*`) and `assessor:complete`. A `SwarmEvent` is `{ type, timestamp, agentName?, data? }`; subscribe to `'*'` for all of them. ## Types Re-exported from `@cogitator-ai/types`: `SwarmStrategy`, `SwarmConfig`, `SwarmRunOptions`, `SwarmAgent`, `SwarmAgentMetadata`, `SwarmAgentState`, `SwarmMessage`, `SwarmMessageType`, `MessageBus`, `MessageBusConfig`, `Blackboard`, `BlackboardConfig`, `BlackboardEntry`, `SwarmEventEmitter`, `SwarmEventType`, `SwarmEvent`, `SwarmEventHandler`, the strategy configs (`HierarchicalConfig`, `RoundRobinConfig`, `ConsensusConfig`, `AuctionConfig`, `PipelineConfig`, `PipelineStage`, `PipelineContext`, `PipelineGateConfig`, `DebateConfig`, `NegotiationConfig`, …), the negotiation types (`NegotiationOffer`, `NegotiationAgreement`, `NegotiationResult`, `Coalition`, …), `StrategyResult`, `IStrategy`, `SwarmCoordinatorInterface`, `SwarmResourceConfig`, `SwarmErrorConfig`, `SwarmAgentToolsConfig` and the assessor types (`TaskRequirements`, `RoleRequirements`, `ModelCandidate`, `ModelAssignment`, `AssessmentResult`, `AssessorConfig`, `DiscoveredModel`, …).