Docs / Swarm mode

Swarm mode

RavenClaws supports multi-agent orchestration through swarm mode, where multiple AI agents collaborate on tasks. This guide covers the three swarm topologies and how to use them.

Overview

Swarm mode allows you to run multiple agents simultaneously, each with a different persona or role. Agents can work in parallel on independent subtasks, or collaborate hierarchically with a supervisor.

Quick start

# Run with 3 default agents
ravenclaws --swarm "Research the Rust programming language and create a summary"

# Run with a supervisor decomposing the task
ravenclaws --supervisor "Design a microservice architecture for an e-commerce platform"

Topologies

Flat swarm

In a flat swarm, all agents receive the same prompt and work independently. Results are collected and presented together.

[llm]
provider = "openai"
model = "gpt-4o"

[swarm]
max_workers = 3
topology = "star"

[[swarm.profiles]]
name = "coder"
persona = "You are an expert Rust engineer focused on code quality."

[[swarm.profiles]]
name = "researcher"
persona = "You are a thorough technical researcher."

[[swarm.profiles]]
name = "reviewer"
persona = "You are a meticulous code reviewer."

Use cases: getting multiple perspectives on a problem, parallel research on different aspects of a topic, and code review from different angles.

Hierarchical swarm (supervisor)

A supervisor agent decomposes the task into subtasks, spawns sub-agents for each, and aggregates the results.

[llm]
provider = "openai"
model = "gpt-4o"

[swarm]
max_workers = 4
topology = "hierarchical"

[[swarm.profiles]]
name = "supervisor"
persona = "You are a project manager. Decompose tasks and delegate."

[[swarm.profiles]]
name = "architect"
persona = "You are a systems architect focused on design."

[[swarm.profiles]]
name = "implementer"
persona = "You are an implementer who writes production-quality code."

[[swarm.profiles]]
name = "tester"
persona = "You are a QA engineer who writes tests."

Use cases: complex multi-step projects, software design and implementation, and research reports with multiple sections.

Self-provisioning swarm

The swarm dynamically creates worker profiles based on task requirements. Agents are spawned recursively as needed.

ravenclaws --swarm "Build a complete REST API in Rust with authentication"

The supervisor will:

1. Analyze the task
2. Create appropriate worker profiles (e.g. "auth specialist", "API designer", "database expert")
3. Assign subtasks to each worker
4. Collect and merge results

Inter-agent communication

Agents in a swarm can communicate via the built-in message bus:

• Send — direct a message to a specific agent
• Broadcast — send a message to all agents
• Receive — check for incoming messages

This enables collaborative workflows where agents share intermediate results.

Health monitoring

Swarm health is automatically tracked:

ravenclaws --swarm --swarm-health "Run a long analysis task"

The health monitor tracks heartbeat timestamps per agent, performs dead-agent detection (timeout-based), and reports aggregate metrics (messages sent/received, tasks completed).

Configuration

Best practices

1. Match profiles to tasks — give each agent a clear, specific role.
2. Use hierarchical for complex tasks — let the supervisor decompose the problem.
3. Set appropriate agent counts — 3–5 agents is usually optimal.
4. Monitor health — use --swarm-health for long-running swarms.
5. Provide context — include relevant background in the initial prompt.