Multi-agent topologies

Ready-made supervisor, swarm, hierarchical, and blackboard builders — four ways to combine agents into one.

Picking a topology is half the battle with multi-agent systems. @agentskit/runtime ships the four patterns that actually show up in production; each takes AgentHandles (anything with a name + run(task) method) and returns a new AgentHandle you can plug back into the rest of your system.

Install

Ships with @agentskit/runtime.

Supervisor

A planner agent delegates to workers, then synthesizes. Good for "decompose → delegate → merge" patterns.

import { supervisor } from '@agentskit/runtime'

const team = supervisor({
  supervisor: plannerAgent,
  workers: [researcherAgent, coderAgent],
  maxRounds: 2,
  route: (task, workers) => (/code/i.test(task) ? workers[1]! : workers[0]!),
})

await team.run('Research quantum sort, then implement it in Python.')

Swarm

Every member sees the same task, runs in parallel, results get merged. Good for ensembling answers, voting, or "fan out and pick the best."

import { swarm } from '@agentskit/runtime'

const team = swarm({
  members: [anthropicAgent, openAiAgent, geminiAgent],
  timeoutMs: 30_000,
  merge: results => results.map(r => r.output).join('\n\n---\n\n'),
})

One or more members can fail — the merger still runs as long as any member returned.

Hierarchical

A routing tree. Start at the root, descend as long as a child matches (by tag or custom route), then execute the leaf.

import { hierarchical } from '@agentskit/runtime'

const tree = hierarchical({
  root: {
    agent: triageAgent,
    children: [
      { agent: billingAgent, tags: ['refund', 'invoice', 'billing'] },
      { agent: technicalAgent, tags: ['bug', 'error', 'crash'] },
    ],
  },
  maxDepth: 3,
})

Blackboard

Every agent reads and writes a shared scratchpad. Iterate until isDone says stop. Good for planner + critic loops or collaborative drafting.

import { blackboard } from '@agentskit/runtime'

const team = blackboard({
  agents: [plannerAgent, coderAgent, criticAgent],
  maxIterations: 3,
  isDone: board => board.includes('FINAL OUTPUT:'),
})

Observing

Every topology accepts an onEvent observer:

supervisor({
  supervisor,
  workers,
  onEvent: e => logger.info('[topo]', e.topology, e.phase, e.agent),
})

Phases: dispatch / agent:start / agent:end / merge / done.