Swarms API

SwarmCopy Anchor Link

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);

SwarmConfigCopy Anchor Link

SwarmRunOptions and ResultsCopy Anchor Link

interface SwarmRunOptions {
  input: string;
  context?: Record<string, unknown>; // 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<string, RunResult>;
  votes?: Map<string, unknown>; // consensus
  bids?: Map<string, number>; // auction
  auctionWinner?: string;
  debateTranscript?: SwarmMessage[];
  pipelineOutputs?: Map<string, unknown>;
  negotiationResult?: NegotiationResult;
}

StrategiesCopy Anchor Link

Every strategy class takes (coordinator, config). See Strategies.

CoordinatorsCopy Anchor Link

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.

CommunicationCopy Anchor Link

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.

Swarm ToolsCopy Anchor Link

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:

SwarmToolContext: { coordinator, blackboard, messageBus, events, agentName, agentWeight?, swarmId? }.

Workflow NodesCopy Anchor Link

SwarmNodeOptions: { inputMapper?: (state, input?) => string; stateMapper?: (result: StrategyResult) => Partial<S>; runOptions?: Partial<SwarmRunOptions> }. With a SwarmConfig, the node builds the swarm from the cogitator in the node context.

AssessorCopy Anchor Link

See Assessment.

EventsCopy Anchor Link

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.

TypesCopy Anchor Link

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, …).