tasq/node_modules/agentic-flow/docs/guides/QUIC-SWARM-QUICKSTART.md

QUIC Swarm Coordination - Quick Start Guide

This guide will help you get started with QUIC-enabled multi-agent swarm coordination in agentic-flow.

Table of Contents

1. Installation
2. Basic Usage
3. Topology Selection
4. Transport Configuration
5. Agent Registration
6. Statistics & Monitoring
7. Common Patterns
8. Troubleshooting

Installation

npm install agentic-flow

Basic Usage

Initialize a Simple Swarm

import { initSwarm } from 'agentic-flow';

const swarm = await initSwarm({
  swarmId: 'my-swarm',
  topology: 'mesh',
  transport: 'quic',
  quicPort: 4433
});

Register Agents

await swarm.registerAgent({
  id: 'agent-1',
  role: 'worker',
  host: 'localhost',
  port: 4434,
  capabilities: ['compute', 'analyze']
});

Get Statistics

const stats = await swarm.getStats();
console.log('Swarm stats:', stats);

Cleanup

await swarm.shutdown();

Topology Selection

Mesh Topology (Peer-to-Peer)

Best for: Small swarms (<20 agents), maximum redundancy

const swarm = await initSwarm({
  swarmId: 'mesh-swarm',
  topology: 'mesh',
  transport: 'quic',
  maxAgents: 10
});

Characteristics:

• All agents connect to all others
• O(n²) connections
• No single point of failure
• Ideal for distributed consensus

Hierarchical Topology (Coordinator-Worker)

Best for: Large swarms (100+ agents), centralized task distribution

const swarm = await initSwarm({
  swarmId: 'hierarchical-swarm',
  topology: 'hierarchical',
  transport: 'quic',
  maxAgents: 100
});

// Register coordinators
await swarm.registerAgent({
  id: 'coordinator-1',
  role: 'coordinator',
  host: 'localhost',
  port: 4433,
  capabilities: ['orchestrate']
});

// Register workers
await swarm.registerAgent({
  id: 'worker-1',
  role: 'worker',
  host: 'localhost',
  port: 4434,
  capabilities: ['compute']
});

Characteristics:

• Workers communicate through coordinators
• O(n) connections
• Scalable to 100+ agents
• Ideal for task distribution

Ring Topology (Circular)

Best for: Ordered processing, pipeline architectures

const swarm = await initSwarm({
  swarmId: 'ring-swarm',
  topology: 'ring',
  transport: 'quic',
  maxAgents: 8
});

Characteristics:

• Each agent connects to next in circle
• O(n) connections
• Predictable message flow
• Ideal for pipelines

Star Topology (Hub and Spoke)

Best for: Simple coordination, fan-out/fan-in patterns

const swarm = await initSwarm({
  swarmId: 'star-swarm',
  topology: 'star',
  transport: 'quic',
  maxAgents: 20
});

// Register central coordinator
await swarm.registerAgent({
  id: 'central',
  role: 'coordinator',
  host: 'localhost',
  port: 4433,
  capabilities: ['coordinate']
});

// Register spoke agents
await swarm.registerAgent({
  id: 'spoke-1',
  role: 'worker',
  host: 'localhost',
  port: 4434,
  capabilities: ['compute']
});

Characteristics:

• All messages through central coordinator
• O(n) connections
• Single coordination point
• Simple to manage

Transport Configuration

QUIC Transport (Recommended)

Fastest option with 0-RTT connection establishment:

const swarm = await initSwarm({
  swarmId: 'quic-swarm',
  topology: 'mesh',
  transport: 'quic',
  quicPort: 4433,
  quicHost: 'localhost'
});

Features:

• 0-RTT connection establishment
• 100+ concurrent streams per connection
• No head-of-line blocking
• Connection migration support

HTTP/2 Transport (Fallback)

Compatible fallback option:

const swarm = await initSwarm({
  swarmId: 'http2-swarm',
  topology: 'mesh',
  transport: 'http2',
  quicPort: 8443  // HTTP/2 port
});

Features:

• Universal compatibility
• Proven reliability
• Standard TLS security

Auto Transport (Default)

Automatically select best available transport:

const swarm = await initSwarm({
  swarmId: 'auto-swarm',
  topology: 'mesh',
  transport: 'auto',  // Try QUIC, fallback to HTTP/2
  enableFallback: true
});

Features:

• Automatic protocol selection
• Transparent fallback
• Continuous health monitoring
• Best performance available

Agent Registration

Basic Agent

await swarm.registerAgent({
  id: 'agent-1',
  role: 'worker',
  host: 'localhost',
  port: 4434,
  capabilities: ['compute']
});

Agent with Metadata

await swarm.registerAgent({
  id: 'agent-2',
  role: 'worker',
  host: 'agent-2.example.com',
  port: 4435,
  capabilities: ['compute', 'analyze', 'aggregate'],
  metadata: {
    region: 'us-east-1',
    instance_type: 'c5.2xlarge',
    max_concurrent_tasks: 10
  }
});

Unregister Agent

await swarm.unregisterAgent('agent-1');

Statistics & Monitoring

Swarm Statistics

const stats = await swarm.getStats();

console.log('Swarm ID:', stats.swarmId);
console.log('Topology:', stats.topology);
console.log('Transport:', stats.transport);
console.log('QUIC Available:', stats.quicAvailable);
console.log('Total Agents:', stats.coordinatorStats?.totalAgents);
console.log('Active Agents:', stats.coordinatorStats?.activeAgents);
console.log('Total Messages:', stats.coordinatorStats?.totalMessages);
console.log('Avg Latency:', stats.coordinatorStats?.averageLatency, 'ms');

Transport Statistics

const stats = await swarm.getStats();

if (stats.transportStats instanceof Map) {
  const quicStats = stats.transportStats.get('quic');
  const http2Stats = stats.transportStats.get('http2');

  console.log('QUIC Stats:', quicStats);
  console.log('HTTP/2 Stats:', http2Stats);
}

Per-Agent Statistics

// Access through coordinator if available
const coordinator = swarm.router?.getCoordinator();
if (coordinator) {
  const agentStats = coordinator.getAgentStats('agent-1');
  console.log('Agent Stats:', agentStats);

  const allStats = coordinator.getAllAgentStats();
  console.log('All Agent Stats:', allStats);
}

Common Patterns

Pattern 1: Distributed Computation

// Initialize mesh swarm for distributed computation
const swarm = await initSwarm({
  swarmId: 'compute-swarm',
  topology: 'mesh',
  transport: 'quic',
  maxAgents: 10
});

// Register compute nodes
for (let i = 1; i <= 10; i++) {
  await swarm.registerAgent({
    id: `compute-${i}`,
    role: 'worker',
    host: `compute-${i}.local`,
    port: 4433 + i,
    capabilities: ['compute', 'verify']
  });
}

// Agents can now communicate peer-to-peer
// for distributed computation tasks

Pattern 2: Task Distribution Pipeline

// Initialize hierarchical swarm for task distribution
const swarm = await initSwarm({
  swarmId: 'pipeline-swarm',
  topology: 'hierarchical',
  transport: 'quic',
  maxAgents: 50
});

// Register task coordinators
for (let i = 1; i <= 5; i++) {
  await swarm.registerAgent({
    id: `coordinator-${i}`,
    role: 'coordinator',
    host: `coordinator-${i}.local`,
    port: 4433,
    capabilities: ['distribute', 'aggregate']
  });
}

// Register processing workers
for (let i = 1; i <= 40; i++) {
  await swarm.registerAgent({
    id: `worker-${i}`,
    role: 'worker',
    host: `worker-${i}.local`,
    port: 4434 + i,
    capabilities: ['process']
  });
}

Pattern 3: Data Processing Pipeline

// Initialize ring swarm for sequential processing
const swarm = await initSwarm({
  swarmId: 'data-pipeline',
  topology: 'ring',
  transport: 'quic',
  maxAgents: 5
});

// Register pipeline stages
const stages = ['ingest', 'validate', 'transform', 'enrich', 'store'];
for (let i = 0; i < stages.length; i++) {
  await swarm.registerAgent({
    id: `stage-${stages[i]}`,
    role: 'worker',
    host: `stage-${i}.local`,
    port: 4433 + i,
    capabilities: [stages[i]]
  });
}

// Data flows through stages in order

Pattern 4: Hub-Based Coordination

// Initialize star swarm for centralized coordination
const swarm = await initSwarm({
  swarmId: 'hub-swarm',
  topology: 'star',
  transport: 'quic',
  maxAgents: 20
});

// Register central hub
await swarm.registerAgent({
  id: 'hub',
  role: 'coordinator',
  host: 'hub.local',
  port: 4433,
  capabilities: ['coordinate', 'aggregate', 'monitor']
});

// Register spoke agents
for (let i = 1; i <= 15; i++) {
  await swarm.registerAgent({
    id: `spoke-${i}`,
    role: 'worker',
    host: `spoke-${i}.local`,
    port: 4434 + i,
    capabilities: ['process']
  });
}

// All communication goes through hub

Troubleshooting

QUIC Not Available

Problem: Swarm falls back to HTTP/2 unexpectedly

Solutions:

1. Check WASM module is loaded:

   import { checkQuicAvailability } from 'agentic-flow';
   const available = await checkQuicAvailability();
   console.log('QUIC available:', available);
   

2. Verify TLS certificates (if using peer verification):

   ls -la ./certs/cert.pem
   ls -la ./certs/key.pem
   

3. Check firewall allows UDP traffic on QUIC port:

   sudo ufw allow 4433/udp
   

High Message Latency

Problem: Messages taking longer than expected

Solutions:

1. Check transport being used:

   const stats = await swarm.getStats();
   console.log('Current transport:', stats.transport);
   

2. Enable QUIC explicitly:

   const swarm = await initSwarm({
     transport: 'quic',
     enableFallback: false
   });
   

3. Monitor QUIC statistics:

   const quicStats = stats.transportStats?.get('quic');
   console.log('RTT:', quicStats?.rttMs, 'ms');
   console.log('Packet loss:', quicStats?.packetsLost);
   

Connection Pool Exhaustion

Problem: "Maximum connections reached" errors

Solutions:

1. Increase max agents:

   const swarm = await initSwarm({
     maxAgents: 50  // Increase from default 10
   });
   

2. Use hierarchical topology for better scaling:

   const swarm = await initSwarm({
     topology: 'hierarchical'  // Better for large swarms
   });
   

Agent Registration Failures

Problem: Cannot register new agents

Solutions:

1. Check max agents limit:

   const stats = await swarm.getStats();
   console.log('Total agents:', stats.coordinatorStats?.totalAgents);
   console.log('Max agents:', stats.coordinatorStats?.maxAgents);
   

2. Verify agent connectivity:

   nc -zv agent-1.local 4434
   

3. Check for duplicate agent IDs:

   await swarm.unregisterAgent('existing-agent-id');
   await swarm.registerAgent({ id: 'existing-agent-id', ... });
   

Next Steps

• Read the Architecture Documentation
• Explore Example Applications
• Learn about Transport Configuration
• See Performance Benchmarks

Support

• GitHub Issues: https://github.com/ruvnet/agentic-flow/issues
• Documentation: https://github.com/ruvnet/agentic-flow/docs
• Examples: https://github.com/ruvnet/agentic-flow/examples