tasq/node_modules/agentic-flow/docs/supabase/QUICKSTART.md

Supabase Federation Quick Start

Get up and running with Supabase real-time federation in 5 minutes!

---

⚡ 5-Minute Setup

Step 1: Create Supabase Project (2 minutes)

1. Go to supabase.com
2. Click Start your project
3. Create new project:
   • Name: agentic-flow-federation
   • Database Password: (save this!)
   • Region: Choose closest to you
4. Wait for project to provision

Step 2: Get API Keys (30 seconds)

1. Go to Project Settings > API
2. Copy these values:

   Project URL: https://xxxxx.supabase.co
   anon/public key: eyJhbGc...
   service_role key: eyJhbGc... (keep secret!)
   

Step 3: Run Database Migration (1 minute)

1. In Supabase dashboard, go to SQL Editor
2. Click New query
3. Copy the entire contents of: docs/supabase/migrations/001_create_federation_tables.sql
4. Paste and click Run
5. You should see: ✅ Federation Hub schema created successfully!

Step 4: Enable Realtime (30 seconds)

1. Go to Database > Replication
2. Find and enable these tables:
   • ✅ agent_sessions
   • ✅ agent_memories
   • ✅ agent_tasks
   • ✅ agent_events
3. Click Save

Step 5: Configure Environment (1 minute)

Create or update your .env file:

# Supabase credentials
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGc...

# Federation settings
FEDERATION_VECTOR_BACKEND=hybrid
FEDERATION_MEMORY_SYNC=true
FEDERATION_HEARTBEAT_INTERVAL=30000
FEDERATION_BROADCAST_LATENCY=low

Step 6: Test It! (30 seconds)

# Install dependencies if needed
npm install @supabase/supabase-js

# Run the example
npx tsx examples/realtime-federation-example.ts

You should see agents joining, communicating, and collaborating in real-time!

---

🎯 What You Get

After setup, you have:

✅ PostgreSQL database with federation schema ✅ Real-time subscriptions for instant updates ✅ Vector search using pgvector ✅ Multi-agent coordination infrastructure ✅ Presence tracking for online agents ✅ Task orchestration system ✅ Tenant isolation via Row Level Security

---

🚀 Next Steps

Try the Examples

# Multi-agent research team
npx tsx examples/realtime-federation-example.ts

# Or run specific examples programmatically

Start Federation Hub

# Start the hub server
npx agentic-flow federation start --db-url $SUPABASE_URL

# In another terminal, spawn an agent
npx agentic-flow federation spawn \
  --agent-id my-agent \
  --tenant-id my-tenant \
  --hub-endpoint $SUPABASE_URL

Build Your First Multi-Agent System

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:task_assignment', async (msg) => {
  console.log('Got task:', msg.payload.description);
  // Do work...
  await agent.reportTaskComplete(msg.payload.task_id, {
    status: 'success',
  });
});

// Update presence
await agent.updateStatus('online', 'Ready for tasks');

// Get team members
const team = agent.getActiveAgents();
console.log(`${team.length} agents online`);

---

💡 Common Use Cases

1. Research Team

Multiple agents collaborate on research:

const researcher = createRealtimeHub('researcher', 'team');
const analyst = createRealtimeHub('analyst', 'team');
const writer = createRealtimeHub('writer', 'team');

// Researcher → Analyst → Writer workflow

2. Code Review

Agents review code in parallel:

const reviewer1 = createRealtimeHub('reviewer-1', 'code-review');
const reviewer2 = createRealtimeHub('reviewer-2', 'code-review');

// Assign files to different reviewers
// Aggregate feedback

3. Customer Support

Agents handle support tickets:

const router = createRealtimeHub('router', 'support');
const specialist1 = createRealtimeHub('billing-expert', 'support');
const specialist2 = createRealtimeHub('tech-expert', 'support');

// Route tickets to specialists based on type

4. Data Processing Pipeline

Distributed data processing:

const coordinator = createRealtimeHub('coordinator', 'pipeline');
const worker1 = createRealtimeHub('worker-1', 'pipeline');
const worker2 = createRealtimeHub('worker-2', 'pipeline');
const worker3 = createRealtimeHub('worker-3', 'pipeline');

// Distribute work, track progress, aggregate results

---

🔧 Configuration Options

Vector Backend

Choose storage strategy:

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

# Supabase pgvector only (persistent, slower)
FEDERATION_VECTOR_BACKEND=pgvector

# Hybrid (recommended - fast + persistent)
FEDERATION_VECTOR_BACKEND=hybrid

Performance Tuning

# Lower latency, higher bandwidth
FEDERATION_BROADCAST_LATENCY=low
FEDERATION_HEARTBEAT_INTERVAL=15000  # 15s

# Higher latency, lower bandwidth
FEDERATION_BROADCAST_LATENCY=high
FEDERATION_HEARTBEAT_INTERVAL=60000  # 60s

Memory Management

# Enable auto-sync to Supabase
FEDERATION_MEMORY_SYNC=true

# Disable for local-only
FEDERATION_MEMORY_SYNC=false

---

📊 Verify Setup

Check Database

-- In Supabase SQL Editor
SELECT * FROM agent_sessions;
SELECT * FROM agent_memories;
SELECT * FROM agent_tasks;

-- Check realtime is enabled
SELECT schemaname, tablename,
       CASE WHEN oid IN (SELECT objid FROM pg_publication_tables WHERE pubname = 'supabase_realtime')
            THEN 'enabled'
            ELSE 'disabled'
       END as realtime_status
FROM pg_tables
WHERE tablename IN ('agent_sessions', 'agent_memories', 'agent_tasks', 'agent_events');

Test Realtime

import { createClient } from '@supabase/supabase-js';

const client = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

// Subscribe to changes
const channel = client
  .channel('test')
  .on(
    'postgres_changes',
    {
      event: 'INSERT',
      schema: 'public',
      table: 'agent_sessions',
    },
    (payload) => {
      console.log('New session:', payload);
    }
  )
  .subscribe();

// Test: Insert a session
await client.from('agent_sessions').insert({
  session_id: 'test-session',
  tenant_id: 'test-tenant',
  agent_id: 'test-agent',
  status: 'active',
});

// You should see "New session:" logged

---

🐛 Troubleshooting

"Connection failed"

Check your credentials:

echo $SUPABASE_URL
echo $SUPABASE_ANON_KEY

Make sure they're set correctly.

"Table does not exist"

Run the migration again:

# Copy docs/supabase/migrations/001_create_federation_tables.sql
# Paste into Supabase SQL Editor
# Run it

"Realtime not working"

Enable realtime in Supabase dashboard:

1. Database > Replication
2. Enable for all federation tables
3. Save

"Permission denied"

Check Row Level Security:

-- Disable RLS for testing (not for production!)
ALTER TABLE agent_sessions DISABLE ROW LEVEL SECURITY;
ALTER TABLE agent_memories DISABLE ROW LEVEL SECURITY;

Or set tenant context:

SET app.current_tenant = 'your-tenant-id';

---

📚 Learn More

• Full Documentation
• Federation Architecture
• API Reference
• Examples

---

🆘 Getting Help

• GitHub Issues: github.com/ruvnet/agentic-flow/issues
• Supabase Docs: supabase.com/docs
• pgvector Guide: github.com/pgvector/pgvector

---

Ready to build? Start with the examples and customize for your use case!

🚀 Happy building!