Multi-Agent Swarms

Coordinate multiple agents to solve complex tasks through decentralized collaboration

Multi-Agent Swarms

AgentOS swarms enable multiple agents to work together on complex tasks through decentralized coordination. Unlike hierarchical systems, swarms use consensus-based decision making where agents observe, propose, vote, and converge on solutions.

Overview

Swarms are implemented in src/swarm.ts:1 and provide four key capabilities:

• Decentralized coordination with up to 20 agents per swarm
• Consensus-based decisions using configurable voting thresholds (default: 66%)
• Message-based communication with observations, proposals, and votes
• Automatic archival to agent memory when swarms dissolve

Creating a Swarm

1. Define the goal and select agents

   import { trigger } from "iii-sdk";
   
   const swarmId = await trigger("swarm::create", {
     goal: "Research and write a technical blog post on distributed systems",
     agentIds: ["researcher", "writer", "editor"],
     maxDurationMs: 600_000,  // 10 minutes
     consensusThreshold: 0.66 // 66% agreement required
   });
   
2. Agents broadcast messages to the swarm

   Each agent can share observations, make proposals, or cast votes:

   // Agent shares an observation
   await trigger("swarm::broadcast", {
     swarmId,
     agentId: "researcher",
     message: "Found 3 key papers on consensus algorithms",
     type: "observation"
   });
   
   // Agent makes a proposal
   await trigger("swarm::broadcast", {
     swarmId,
     agentId: "writer",
     message: "Let's structure the post around Raft and Paxos",
     type: "proposal"
   });
   
   // Agent votes on a proposal
   await trigger("swarm::broadcast", {
     swarmId,
     agentId: "editor",
     message: "Agree with Raft/Paxos focus",
     type: "vote",
     vote: "for"
   });
   
3. Check consensus status

   const consensus = await trigger("swarm::consensus", {
     swarmId,
     proposal: "Let's structure the post around Raft and Paxos"
   });
   
   console.log(consensus);
   // {
   //   hasConsensus: true,
   //   votesFor: 2,
   //   votesAgainst: 0,
   //   threshold: 0.66,
   //   totalVoters: 3
   // }
   
4. Gather findings and dissolve

   // Collect all messages
   const findings = await trigger("swarm::collect", { swarmId });
   console.log(findings);
   // {
   //   totalMessages: 45,
   //   observations: [...],
   //   proposals: [...],
   //   votes: [...],
   //   agents: { researcher: [...], writer: [...], editor: [...] }
   // }
   
   // Dissolve and archive to memory
   await trigger("swarm::dissolve", { swarmId });
   

Swarm Strategies

While the core swarm implementation focuses on consensus, you can implement different coordination strategies:

Parallel

All agents work simultaneously on different aspects of the problem. Best for independent subtasks.

Sequential

Agents take turns, each building on the previous agent’s work. Best for dependent tasks.

Consensus

Agents vote on proposals until reaching agreement threshold. Built into the swarm system.

Hierarchical

One agent coordinates others. Combine with the hierarchy system for org-chart-based coordination.

Real-World Example: Code Review

const { swarmId } = await trigger("swarm::create", {
  goal: "Review PR #42 for security, performance, and code quality",
  agentIds: ["security-auditor", "performance-analyst", "code-reviewer"],
  consensusThreshold: 1.0 // Require unanimous approval
});

// Each agent analyzes the PR
await trigger("swarm::broadcast", {
  swarmId,
  agentId: "security-auditor",
  message: "No SQL injection vulnerabilities found. Input validation looks good.",
  type: "observation"
});

await trigger("swarm::broadcast", {
  swarmId,
  agentId: "performance-analyst",
  message: "Added caching layer reduces DB calls by 60%",
  type: "observation"
});

// Make approval proposal
await trigger("swarm::broadcast", {
  swarmId,
  agentId: "code-reviewer",
  message: "Approve PR #42 for merge",
  type: "proposal"
});

// All agents vote
for (const agentId of ["security-auditor", "performance-analyst", "code-reviewer"]) {
  await trigger("swarm::broadcast", {
    swarmId,
    agentId,
    message: "Approve PR #42 for merge",
    type: "vote",
    vote: "for"
  });
}

// Check if unanimous
const result = await trigger("swarm::consensus", {
  swarmId,
  proposal: "Approve PR #42 for merge"
});

if (result.hasConsensus) {
  console.log("✓ PR approved by all reviewers");
  await trigger("swarm::dissolve", { swarmId });
}

Swarm Limits

From src/swarm.ts:32:

• MAX_AGENTS_PER_SWARM: 20 agents
• MAX_MESSAGES_PER_SWARM: 500 messages
• DEFAULT_MAX_DURATION_MS: 600,000ms (10 minutes)
• DEFAULT_CONSENSUS_THRESHOLD: 0.66 (66% agreement)

HTTP API Endpoints

# Create a swarm
curl -X POST http://localhost:3111/api/swarm/create \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Analyze customer feedback from Q1",
    "agentIds": ["analyst-1", "analyst-2", "analyst-3"]
  }'

# Broadcast a message
curl -X POST http://localhost:3111/api/swarm/:id/broadcast \
  -d '{
    "agentId": "analyst-1",
    "message": "Found 3 major themes in the data",
    "type": "observation"
  }'

# Check status
curl http://localhost:3111/api/swarm/:id/status

# Check consensus
curl -X POST http://localhost:3111/api/swarm/:id/consensus \
  -d '{ "proposal": "Focus on theme A" }'

# Dissolve swarm
curl -X POST http://localhost:3111/api/swarm/:id/dissolve

Security & Auditing

All swarm operations are automatically audited (see src/swarm.ts:80-83):

• swarm_created: Logged with swarmId, goal, and agent count
• swarm_dissolved: Logged with final message count
• Agent membership: Validated before broadcasting messages

Memory Integration

When a swarm dissolves (src/swarm.ts:269-280), findings are automatically stored in each agent’s memory:

for (const agentId of swarm.agentIds) {
  const agentFindings = findings.agents?.[agentId] || [];
  if (agentFindings.length > 0) {
    await trigger("memory::store", {
      agentId,
      sessionId: `swarm:${swarmId}`,
      role: "system",
      content: `Swarm ${swarmId} findings: ${JSON.stringify(agentFindings.slice(0, 10))}`
    });
  }
}

This allows agents to recall swarm insights in future conversations.

Best Practices

Choose the right consensus threshold

• 1.0 (100%): Use for critical decisions (deployments, security approvals)
• 0.66 (66%): Default, good for most collaborative tasks
• 0.5 (50%): Majority rule for faster iteration

Limit swarm size

Smaller swarms (3-5 agents) converge faster. Use hierarchical coordination for larger teams.

Set appropriate timeouts

Match maxDurationMs to task complexity. Long-running research might need 30+ minutes.

Monitor message volume

Watch for chatty agents approaching the 500-message limit. Consider breaking into multiple swarms.

Related Features

• Knowledge Graph - Structure findings from swarm research
• Session Replay - Debug swarm coordination issues
• A2A Protocol - Connect swarms across different AgentOS instances