agentic-flow 1.6.3 → 1.6.4

package/docs/guides/QUIC-SWARM-QUICKSTART.md

@@ -0,0 +1,543 @@
+# 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](#installation)
+2. [Basic Usage](#basic-usage)
+3. [Topology Selection](#topology-selection)
+4. [Transport Configuration](#transport-configuration)
+5. [Agent Registration](#agent-registration)
+6. [Statistics & Monitoring](#statistics--monitoring)
+7. [Common Patterns](#common-patterns)
+8. [Troubleshooting](#troubleshooting)
+
+## Installation
+
+```bash
+npm install agentic-flow
+```
+
+## Basic Usage
+
+### Initialize a Simple Swarm
+
+```typescript
+import { initSwarm } from 'agentic-flow';
+
+const swarm = await initSwarm({
+  swarmId: 'my-swarm',
+  topology: 'mesh',
+  transport: 'quic',
+  quicPort: 4433
+});
+```
+
+### Register Agents
+
+```typescript
+await swarm.registerAgent({
+  id: 'agent-1',
+  role: 'worker',
+  host: 'localhost',
+  port: 4434,
+  capabilities: ['compute', 'analyze']
+});
+```
+
+### Get Statistics
+
+```typescript
+const stats = await swarm.getStats();
+console.log('Swarm stats:', stats);
+```
+
+### Cleanup
+
+```typescript
+await swarm.shutdown();
+```
+
+## Topology Selection
+
+### Mesh Topology (Peer-to-Peer)
+
+Best for: Small swarms (<20 agents), maximum redundancy
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+await swarm.registerAgent({
+  id: 'agent-1',
+  role: 'worker',
+  host: 'localhost',
+  port: 4434,
+  capabilities: ['compute']
+});
+```
+
+### Agent with Metadata
+
+```typescript
+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
+
+```typescript
+await swarm.unregisterAgent('agent-1');
+```
+
+## Statistics & Monitoring
+
+### Swarm Statistics
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// 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:
+   ```typescript
+   import { checkQuicAvailability } from 'agentic-flow';
+   const available = await checkQuicAvailability();
+   console.log('QUIC available:', available);
+   ```
+
+2. Verify TLS certificates (if using peer verification):
+   ```bash
+   ls -la ./certs/cert.pem
+   ls -la ./certs/key.pem
+   ```
+
+3. Check firewall allows UDP traffic on QUIC port:
+   ```bash
+   sudo ufw allow 4433/udp
+   ```
+
+### High Message Latency
+
+**Problem**: Messages taking longer than expected
+
+**Solutions**:
+1. Check transport being used:
+   ```typescript
+   const stats = await swarm.getStats();
+   console.log('Current transport:', stats.transport);
+   ```
+
+2. Enable QUIC explicitly:
+   ```typescript
+   const swarm = await initSwarm({
+     transport: 'quic',
+     enableFallback: false
+   });
+   ```
+
+3. Monitor QUIC statistics:
+   ```typescript
+   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:
+   ```typescript
+   const swarm = await initSwarm({
+     maxAgents: 50  // Increase from default 10
+   });
+   ```
+
+2. Use hierarchical topology for better scaling:
+   ```typescript
+   const swarm = await initSwarm({
+     topology: 'hierarchical'  // Better for large swarms
+   });
+   ```
+
+### Agent Registration Failures
+
+**Problem**: Cannot register new agents
+
+**Solutions**:
+1. Check max agents limit:
+   ```typescript
+   const stats = await swarm.getStats();
+   console.log('Total agents:', stats.coordinatorStats?.totalAgents);
+   console.log('Max agents:', stats.coordinatorStats?.maxAgents);
+   ```
+
+2. Verify agent connectivity:
+   ```bash
+   nc -zv agent-1.local 4434
+   ```
+
+3. Check for duplicate agent IDs:
+   ```typescript
+   await swarm.unregisterAgent('existing-agent-id');
+   await swarm.registerAgent({ id: 'existing-agent-id', ... });
+   ```
+
+## Next Steps
+
+- Read the [Architecture Documentation](../architecture/QUIC-SWARM-INTEGRATION.md)
+- Explore [Example Applications](../../examples/)
+- Learn about [Transport Configuration](../guides/QUIC-TRANSPORT-CONFIG.md)
+- See [Performance Benchmarks](../validation-reports/QUIC-PERFORMANCE.md)
+
+## 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