NATS Messaging Infrastructure for Agent Swarm

[wonderwomancode]

Summary

Implement NATS-based agent-to-agent messaging for true swarm coordination, enabling our 5 agents (Senku, Lain, Atlas, Argus, Quinn) to communicate asynchronously.

Documentation

Full plan: https://github.com/alternatefutures/.github/blob/main/AGENTS.md#nats-messaging-infrastructure-planned

Phases

Phase 1: NATS Server Setup

• Deploy NATS with JetStream on Akash
• Configure TLS for secure connections
• Set up authentication (NKeys or JWT)
• Create streams for message persistence
• Configure retention policies

Phase 2: MCP Server Development

• Fork/adapt lizTheDeveloper's ai-agent-messaging
• Add AlternateFutures-specific tools
• Implement agent authentication
• Add message validation schemas
• Create TypeScript types

Phase 3: Agent Integration

• Add nats-mcp to each agent's MCP config
• Update agent prompts with messaging capabilities
• Define subscription patterns per agent
• Test inter-agent communication
• Implement fallback to Discord for humans

Phase 4: Advanced Features

• JetStream consumers for durable subscriptions
• Message deduplication
• Dead letter queues for failed deliveries
• Metrics and monitoring (Prometheus)
• Rate limiting per agent

Subject Hierarchy

agents.
├── broadcast              # All agents
├── leadership             # Senku + Lain only
├── specialist             # Atlas + Argus + Quinn
├── handoff                # Task delegation
├── incident               # Urgent alerts
└── human.discord          # Forward to Discord

Why NATS?

• Pub/Sub for broadcasts
• Request/Reply for synchronous handoffs
• Queue groups for load balancing
• JetStream for message persistence
• Lightweight (<10MB)

References

• lizTheDeveloper/ai-agent-messaging
• NATS Documentation
• NATS.js Client