Multi-agent topologies

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.

#See also

• Durable execution — wrap the whole topology in a step log.
• Background agents — run a topology on a schedule.