Swarm Configs

Swarm configs let you define multi-agent runs with a coordinator and named worker delegates. Configs are loaded from ~/.dreadnode/swarms/ and can be started from the CLI.

YAML config format

Swarm configs are YAML files with a top-level name, optional default model, a coordinator prompt, and a list of workers (delegates). Each worker includes an input seed.

name: incident-response
model: anthropic/claude-sonnet-4-20250514

coordinator:
  prompt: |
    You coordinate the incident response swarm. Assign tasks, collect results,
    and publish a final summary to shared state.

workers:
  - name: timeline
    prompt: Build a timeline of the incident.
    input: Start with system logs and note key timestamps.

  - name: iocs
    prompt: Extract indicators of compromise.
    input: List hashes, IPs, and domains.

  - name: containment
    prompt: Recommend containment steps.
    input: Propose immediate containment actions.

Save the file as ~/.dreadnode/swarms/incident-response.yaml and run it with:

/swarm incident-response

SharedState and messaging

Swarm agents share a SharedState instance. Agents can communicate using the built-in swarm tools (read_state, write_state, send_message, read_messages), which write to the same state log.

import { anthropic } from '@ai-sdk/anthropic';
import { Agent, createGenerator, withSwarm } from '@dreadnode/agents';

async function main(): Promise<void> {
  const generator = await createGenerator(anthropic('claude-sonnet-4-20250514'));
  const coordinator = new Agent({ name: 'coordinator', generator });
  const researcher = new Agent({ name: 'researcher', generator });

  const swarm = withSwarm(coordinator, [
    { name: 'researcher', agent: researcher, input: 'Find related incidents.' },
  ]);

  const result = await swarm.run({ input: 'Coordinate the swarm.' });
  const summary = result.state.get('summary');
  console.log('SharedState summary:', summary);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Delegates and direct delegation tools

Workers are the delegates in a swarm. If you want to expose explicit delegation tools, use the delegate() helper to create delegate_<name> tools for direct hand-offs.