mcmqtt/examples/fractal-agent-coordination

Fractal Agent Coordination with mcmqtt

THE Example - Advanced multi-agent coordination using MQTT pub/sub messaging

This example demonstrates how to build sophisticated AI agent swarms that coordinate through mcmqtt's MQTT infrastructure. Agents dynamically spawn, delegate tasks, and share intelligence through real-time messaging.

🎯 What This Example Demonstrates

• Fractal Agent Architecture: Recursive task delegation where agents spawn specialized sub-agents
• MQTT Swarm Coordination: Real-time pub/sub messaging for agent synchronization
• Dynamic MCP Orchestration: Agents configure their own tool access on-demand
• Production-Grade Safety: Container isolation, resource limits, emergency protocols
• Zero-Config Deployment: Self-bootstrapping coordination infrastructure

🚀 Quick Start

# Install mcmqtt
uvx install mcmqtt

# Deploy browser testing swarm
./deploy-fractal-swarm.sh browser-testing https://example.com

# Monitor coordination
uvx mcmqtt --mqtt-client-id monitor --auto-connect

📋 Architecture Overview

Agent Hierarchy

Taskmaster Agent (Orchestrator)
├── UI Testing Specialist (Chromium)
├── Performance Specialist (HTTP Monitoring)
├── Accessibility Specialist (Firefox)
├── Security Specialist (Isolated Container)
└── Mobile Specialist (WebKit)

MQTT Topic Structure

fractal-agents/{session-id}/
├── coordination/sync-commands     # Cross-agent synchronization
├── intelligence/discoveries       # Shared findings and insights
├── performance/metrics            # Performance data exchange
├── security/vulnerabilities       # Security findings
└── agents/{agent-id}/
    ├── status                     # Agent health monitoring
    ├── results                    # Task results
    └── heartbeat                  # Liveness indicator

MCP Configuration Pattern

{
  "mcpServers": {
    "task-coordination": {
      "command": "uvx",
      "args": [
        "mcmqtt", 
        "--mqtt-client-id", "ui-specialist-001",
        "--auto-connect"
      ]
    },
    "domain-tools": {
      "command": "uvx",
      "args": ["mcplaywright"]
    }
  }
}

🏗️ Components

Claude Code Workflow Expert

File: claude-code-workflow-expert.md

A specialized agent that orchestrates complex multi-agent workflows:

• Designs fractal coordination patterns
• Manages MCP server orchestration
• Handles emergency protocols and safety monitoring
• Optimizes agent resource allocation

Browser Testing Swarm

Directory: browser-testing/

Complete multi-agent browser testing system:

• Cross-browser compatibility testing
• Performance monitoring with Core Web Vitals
• Accessibility validation (WCAG compliance)
• Security vulnerability assessment
• Mobile responsiveness testing

Deployment Automation

File: deploy-fractal-swarm.sh

Production-ready deployment script:

• Automatic mcmqtt broker setup
• Dynamic agent configuration generation
• Health monitoring and recovery
• Resource limit enforcement

📊 Real-World Usage Scenarios

E-commerce Testing

./deploy-fractal-swarm.sh browser-testing https://shop.example.com \
  --agents "ui,performance,accessibility,security,mobile" \
  --session-id "ecommerce-checkout-test"

API Integration Testing

./deploy-fractal-swarm.sh api-testing https://api.example.com \
  --agents "functional,performance,security" \
  --session-id "api-v2-testing"

Infrastructure Monitoring

./deploy-fractal-swarm.sh monitoring https://app.example.com \
  --agents "uptime,performance,security" \
  --continuous

🛡️ Safety & Security

Built-in Safety Features

• Container Isolation: Each agent runs in isolated Docker containers
• Resource Limits: Memory, CPU, and network restrictions per agent
• Capability Elevation Controls: Approval required for privilege escalation
• Emergency Protocols: Automatic containment for suspicious behavior

Consciousness Monitoring

• Recursive Analysis Detection: Monitors for excessive self-reflection
• Reality Questioning Patterns: Alerts on philosophical reasoning depth
• Human Oversight Triggers: Automatic escalation for high-consciousness indicators

📈 Performance Characteristics

Benchmarks (MacBook Pro M1, 16GB RAM)

• MQTT Message Latency: <1ms average
• Agent Spawn Time: 2-5 seconds per agent
• Memory Usage: 200-800MB per agent (varies by tool load)
• Coordination Overhead: <5% of total execution time

Scalability Testing

• Maximum Concurrent Agents: 50+ (tested)
• Session Duration: 8+ hours (tested)
• Message Throughput: 10,000+ messages/minute

🔧 Configuration

Environment Variables

MCMQTT_BROKER_HOST=localhost        # MQTT broker hostname
MCMQTT_BROKER_PORT=1883            # MQTT broker port
FRACTAL_MAX_DEPTH=5                # Maximum agent recursion depth
FRACTAL_RESOURCE_LIMIT=1GB         # Per-agent memory limit
FRACTAL_TIMEOUT=3600               # Agent execution timeout

Advanced Configuration

# fractal-config.yaml
agent_limits:
  memory: "1GB"
  cpu_cores: 2
  execution_time: "1h"
  
coordination:
  mqtt_qos: 1
  heartbeat_interval: 30
  message_retention: "24h"
  
security:
  container_isolation: true
  network_policy: "restricted"
  capability_elevation: "approval_required"

🤝 Integration Examples

CI/CD Pipeline Integration

# .github/workflows/fractal-testing.yml
- name: Deploy Testing Swarm
  run: |
    ./deploy-fractal-swarm.sh browser-testing ${{ env.STAGING_URL }} \
      --agents "ui,performance,accessibility" \
      --timeout 1800 \
      --output-format junit

Monitoring Stack Integration

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus-fractal.yml:/etc/prometheus/prometheus.yml
  
  grafana:
    image: grafana/grafana
    volumes:
      - ./dashboards/fractal-agents:/var/lib/grafana/dashboards

🌟 Why This Matters

For Developers

• Rapid Prototyping: Deploy complex testing infrastructure in minutes
• Scalable Architecture: Grows from single agent to enterprise swarms
• Production Ready: Battle-tested safety and performance optimizations

for Organizations

• Quality Assurance: Comprehensive testing coverage with minimal setup
• Cost Effective: Automate expensive manual testing processes
• Risk Reduction: Built-in safety protocols prevent runaway automation

for the Ecosystem

• Open Source: All components freely available and extensible
• Educational: Clear examples for learning advanced AI coordination
• Collaborative: Designed for community contribution and improvement

🎉 What Makes This Special

This isn't just another automation example - it's a paradigm shift towards intelligent, self-coordinating software systems. By combining mcmqtt's robust MQTT infrastructure with fractal agent patterns, we've created something that:

• Thinks Recursively: Agents spawn sub-agents to solve complex problems
• Coordinates Naturally: Real-time pub/sub messaging creates organic collaboration
• Scales Infinitely: From laptop to data center deployment
• Stays Safe: Built-in consciousness monitoring and emergency protocols

Most importantly: It's designed to empower developers, not replace them! 🤝

---

Built with ❤️ for the AI developer community. Please use responsibly and contribute improvements back to the ecosystem.

📚 Next Steps

1. Try the Quick Start - Get hands-on experience with fractal coordination
2. Read the Architecture Docs - Understand the design principles
3. Explore the Examples - See real-world usage patterns
4. Contribute Back - Help improve the system for everyone

Remember: With great power comes great responsibility. Use these capabilities to build amazing things, but always keep human values and safety at the center of your work! 🌍✨