Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
245 lines (198 loc) · 6.74 KB

ARCHITECTURE.md

File metadata and controls

245 lines (198 loc) · 6.74 KB

Architecture Documentation

System Overview

The Distributed Multi-Agent Communication Platform is a production-ready system for enabling communication, collaboration, and knowledge sharing between multiple AI agents. It uses AutoGen for agent implementation, ChromaDB for vector storage, Redis for message queuing, and WebSockets for real-time communication.

Architecture Components

1. Agent Layer

Base Agent (BaseAgent)

  • Abstract base class for all agents
  • Integrates with AutoGen framework
  • Provides common functionality (knowledge search, response generation)
  • Manages agent state and capabilities

Specialized Agents

Researcher Agent

  • Gathers and synthesizes information
  • Searches knowledge base for relevant information
  • Provides research summaries with sources

Analyst Agent

  • Performs deep analysis on data
  • Identifies patterns and trends
  • Generates structured analysis reports

Coordinator Agent

  • Orchestrates multi-agent workflows
  • Breaks down complex tasks
  • Coordinates agent collaboration

Knowledge Agent

  • Manages knowledge storage and retrieval
  • Handles semantic search queries
  • Organizes information in vector database

2. Core Services

Agent Manager

  • Manages agent lifecycle (register, unregister, status updates)
  • Handles agent-to-agent messaging
  • Monitors agent health with heartbeat mechanism
  • Integrates with queue and WebSocket services

Message Router

  • Routes messages to appropriate agents
  • Supports direct routing (to specific agent)
  • Content-based routing (based on message type)
  • Broadcast routing (to all agents)

Discovery Service

  • Discovers agents across distributed nodes
  • Maintains registry of available agents
  • Handles node failures and cleanup
  • Subscribes to agent events via Redis

Load Balancer

  • Distributes work across available agents
  • Supports multiple strategies (round-robin, least-busy, random)
  • Selects agents based on type and status

3. Infrastructure Services

Queue Service (Redis)

  • Message queuing for reliable delivery
  • Agent-specific queues for targeted messaging
  • Pub/sub for agent events
  • Fallback to in-memory if Redis unavailable

WebSocket Service

  • Real-time bidirectional communication
  • Agent-to-agent direct messaging
  • Broadcast capabilities
  • Connection management

Vector Service (ChromaDB)

  • Semantic search and retrieval
  • Knowledge storage with embeddings
  • Metadata filtering
  • Collection management

4. API Layer

REST API (FastAPI)

  • Agent management endpoints
  • Message sending
  • System metrics
  • Health checks

WebSocket API

  • Real-time agent connections
  • Message delivery
  • Event streaming

Data Flow

Message Flow

User/Agent → API Endpoint
    ↓
Agent Manager
    ↓
Message Router → Route Decision
    ↓
    ├─→ WebSocket (if agent connected)
    │       ↓
    │   Direct Delivery
    │
    └─→ Queue Service (Redis)
            ↓
        Background Processor
            ↓
        WebSocket Delivery

Agent Discovery Flow

Agent Registration
    ↓
Agent Manager
    ↓
Queue Service (Publish Event)
    ↓
Discovery Service (Subscribe)
    ↓
Update Registry

Knowledge Flow

Agent Request
    ↓
Vector Service
    ↓
ChromaDB Query
    ↓
Semantic Search
    ↓
Return Results

Scalability Considerations

Horizontal Scaling

  • Multiple nodes can run independently
  • Agents distributed across nodes
  • Discovery service maintains global view
  • Load balancer distributes work

Message Queue

  • Redis enables distributed messaging
  • Agent-specific queues prevent conflicts
  • Pub/sub for event distribution

Vector Database

  • ChromaDB supports persistent storage
  • Embeddings cached for performance
  • Collection-based organization

Security Considerations

API Security

  • CORS middleware for cross-origin requests
  • Input validation via Pydantic models
  • Error handling to prevent information leakage

Agent Communication

  • Agent IDs for authentication
  • Message validation
  • Connection management

Monitoring and Observability

Metrics

  • Agent count and status
  • WebSocket connections
  • Vector database statistics
  • Message throughput

Health Checks

  • System health endpoint
  • Agent heartbeat monitoring
  • Service availability checks

Deployment Architecture

Single Node Deployment

┌─────────────────────────────────┐
│  FastAPI Application            │
│  ├─ Agent Manager               │
│  ├─ Message Router              │
│  ├─ Discovery Service           │
│  └─ Load Balancer               │
│                                 │
│  Services:                      │
│  ├─ Queue Service (Redis)       │
│  ├─ WebSocket Service           │
│  └─ Vector Service (ChromaDB)   │
└─────────────────────────────────┘

Multi-Node Deployment

Node 1                    Node 2                    Node 3
┌──────────┐             ┌──────────┐             ┌──────────┐
│ Agents   │             │ Agents   │             │ Agents   │
│ Manager  │             │ Manager  │             │ Manager  │
└────┬─────┘             └────┬─────┘             └────┬─────┘
     │                        │                        │
     └────────────────────────┼────────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │  Shared Services  │
                    │  ├─ Redis         │
                    │  └─ ChromaDB      │
                    └───────────────────┘

Technology Stack

  • Framework: FastAPI
  • Agent Framework: AutoGen
  • Vector Database: ChromaDB
  • Message Queue: Redis
  • Real-time: WebSockets
  • Embeddings: Sentence Transformers
  • Language: Python 3.9+

Future Enhancements

  1. Authentication & Authorization: Add API keys and role-based access
  2. Message Persistence: Store messages in database for history
  3. Advanced Routing: ML-based routing decisions
  4. Agent Marketplace: Dynamic agent registration and discovery
  5. Monitoring Dashboard: Real-time visualization of system state
  6. Distributed Tracing: Track messages across nodes
  7. Rate Limiting: Prevent abuse and manage resources
  8. Multi-tenancy: Support multiple organizations