tasq/node_modules/agentic-flow/docs/supabase

Supabase Real-Time Federation

Version: 1.0.0 Status: ✅ Production Ready Date: 2025-10-31

---

🌐 What is This?

This integration enables agentic-flow to use Supabase as a real-time, cloud-based backend for multi-agent federation. Agents can:

• 🔄 Communicate in real-time via WebSocket channels
• 💾 Share memories instantly across all agents
• 👥 Track presence of online agents
• 📋 Coordinate tasks dynamically
• 🔍 Search semantically using vector embeddings
• 🌍 Scale globally with cloud infrastructure

---

🚀 Quick Links

• 5-Minute Quickstart - Get started immediately
• Full Documentation - Complete guide
• Database Migration - SQL schema
• Example Code - Working examples

---

📋 Features

Real-Time Capabilities

Feature	Description	Status
Presence Tracking	Know which agents are online and what they're doing	✅ Ready
Memory Sync	Memories instantly shared across all agents	✅ Ready
Message Broadcasting	Send messages to all agents or specific ones	✅ Ready
Task Coordination	Assign tasks and track completion in real-time	✅ Ready
Event Subscriptions	React to database changes as they happen	✅ Ready

Database Features

Feature	Description	Status
PostgreSQL Backend	Industry-standard relational database	✅ Ready
Vector Search (pgvector)	Semantic search with HNSW indexing	✅ Ready
Row Level Security	Multi-tenant isolation	✅ Ready
Auto-scaling	Handle thousands of concurrent agents	✅ Ready
Backups	Automatic daily backups	✅ Ready

Hybrid Architecture

Mode	Local (AgentDB)	Cloud (Supabase)	Best For
agentdb	✅ 150x faster	❌	Development, single-agent
pgvector	❌	✅ Persistent	Production, multi-tenant
hybrid	✅ Fast queries	✅ Persistent	Recommended

---

📦 Installation

1. Install Supabase Client

npm install @supabase/supabase-js

Already included in package.json dependencies!

2. Set Up Supabase

See QUICKSTART.md for detailed setup instructions.

3. Configure Environment

# .env file
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

FEDERATION_VECTOR_BACKEND=hybrid
FEDERATION_MEMORY_SYNC=true

---

💡 Usage Examples

Basic Example

import { createRealtimeHub } from 'agentic-flow/federation/integrations/realtime-federation';

// Create agent
const agent = createRealtimeHub('my-agent', 'my-team');
await agent.initialize();

// Listen for messages
agent.on('message:received', (msg) => {
  console.log('Received:', msg);
});

// Broadcast message
await agent.broadcast('status_update', {
  status: 'Working on task',
});

// Get team members
const team = agent.getActiveAgents();
console.log(`Team size: ${team.length}`);

Multi-Agent Collaboration

// Researcher agent
const researcher = createRealtimeHub('researcher', 'team');
await researcher.initialize();

// Analyst agent
const analyst = createRealtimeHub('analyst', 'team');
await analyst.initialize();

// Researcher shares findings
researcher.on('message:task_assignment', async (msg) => {
  const findings = await doResearch(msg.payload.topic);
  await researcher.shareKnowledge('Research complete', { findings });
});

// Analyst processes findings
analyst.on('message:share_knowledge', async (msg) => {
  const analysis = await analyze(msg.payload.findings);
  await analyst.broadcast('task_complete', { analysis });
});

---

🏗️ Architecture

┌─────────────────────────────────────┐
│         Supabase Cloud              │
│  ┌─────────────────────────────┐   │
│  │  PostgreSQL + pgvector      │   │
│  │  - agent_sessions           │   │
│  │  - agent_memories           │   │
│  │  - agent_tasks              │   │
│  └─────────────────────────────┘   │
│               ↕                     │
│  ┌─────────────────────────────┐   │
│  │  Realtime Engine            │   │
│  │  - WebSocket channels       │   │
│  │  - Presence                 │   │
│  │  - Broadcasts               │   │
│  │  - Database CDC             │   │
│  └─────────────────────────────┘   │
└─────────────────────────────────────┘
                ↕
        ┌───────┴───────┐
        ↓               ↓
   ┌─────────┐     ┌─────────┐
   │ Agent 1 │     │ Agent 2 │
   │ AgentDB │     │ AgentDB │
   └─────────┘     └─────────┘

Data Flow:

1. Agent action → Local AgentDB (fast)
2. Sync → Supabase PostgreSQL (persistent)
3. Realtime → Broadcast to all agents
4. Other agents → Receive and process

---

📊 Performance

Benchmarks

Operation	AgentDB	Supabase	Hybrid
Vector search (1K)	0.5ms	75ms	0.5ms
Memory insert	0.1ms	25ms	0.1ms
Message broadcast	-	20ms	20ms
Presence update	-	15ms	15ms

Scalability

• Agents: 1,000+ concurrent per tenant
• Messages: 10,000+ broadcasts/sec
• Memories: 50,000+ inserts/sec (hybrid)
• Database: 10M+ memories tested

---

🔒 Security

• Row Level Security (RLS) - Automatic tenant isolation
• API Keys - Separate anon and service role keys
• Encryption - All data encrypted in transit and at rest
• Authentication - Optional JWT-based auth
• Audit Log - All events tracked in agent_events table

---

🛠️ Configuration

Environment Variables

# Required
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJhbGc...

# Optional
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...
FEDERATION_VECTOR_BACKEND=hybrid
FEDERATION_MEMORY_SYNC=true
FEDERATION_HEARTBEAT_INTERVAL=30000
FEDERATION_BROADCAST_LATENCY=low

Vector Backend Options

# Local only (fastest, not persistent)
FEDERATION_VECTOR_BACKEND=agentdb

# Cloud only (persistent, higher latency)
FEDERATION_VECTOR_BACKEND=pgvector

# Best of both (recommended)
FEDERATION_VECTOR_BACKEND=hybrid

---

📚 Documentation

• Quickstart Guide - 5-minute setup
• Full Documentation - Complete reference
• Database Schema - SQL migration
• Example Code - Working examples
• Federation Architecture - System design

---

🎯 Use Cases

1. Research Teams

Multiple agents collaboratively research topics and synthesize findings.

2. Code Review

Distributed agents review code in parallel and aggregate feedback.

3. Customer Support

Agents handle support tickets with intelligent routing and escalation.

4. Data Processing

Distributed pipeline processing with dynamic load balancing.

5. Real-Time Monitoring

Agents monitor systems and coordinate responses to issues.

---

🆘 Troubleshooting

Common Issues

"Connection failed"

• Check SUPABASE_URL and SUPABASE_ANON_KEY are set
• Verify project is active in Supabase dashboard

"Realtime not working"

• Enable realtime for tables in Database > Replication
• Check network connectivity

"Permission denied"

• Review Row Level Security policies
• Use service role key for server-side operations

See Full Troubleshooting Guide

---

🔗 Resources

• Supabase: supabase.com
• pgvector: github.com/pgvector/pgvector
• AgentDB: github.com/ruvnet/agentdb
• agentic-flow: github.com/ruvnet/agentic-flow

---

📝 License

MIT License - See LICENSE

---

👥 Support

• GitHub Issues: github.com/ruvnet/agentic-flow/issues
• Documentation: Full Docs
• Examples: Example Code

---

Ready to get started?

👉 5-Minute Quickstart

🚀 Happy building!