🏗️ Complete Multi-Agent System Architecture

Diagrams a multi-agent system with a supervisor that routes user requests to calendar, email, or unified agents.

Amanastel

May 2, 2026

0 downloads

2 views

ai agent

View source

What this file does

Diagrams a multi-agent system with a supervisor that routes user requests to calendar, email, or unified agents.

When to use it

Designing an architecture doc for a multi-agent app
Planning a supervisor agent that delegates to specialized sub-agents
Documenting a FastAPI backend with Google Calendar and Gmail integration
Creating a visual reference for agent routing and decision logic

Assumes this stack

FastAPILangChainOpenAI GPT-4o-miniGoogle Calendar API v3Gmail API v1Pydantic

🏗️ Complete Multi-Agent System Architecture

🎯 System Overview

This document provides a visual representation of the complete multi-agent system architecture, showing how all components interact and work together.

🏛️ High-Level Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              USER INTERFACE                                    │
│                                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐                │
│  │   Web Client    │  │  Mobile App     │  │  API Client     │                │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘                │
│           │                     │                     │                        │
│           └─────────────────────┼─────────────────────┘                        │
│                                 │                                            │
│                                 ▼                                            │
│                    ┌─────────────────────────────────┐                        │
│                    │        FASTAPI SERVER           │                        │
│                    │     (Port 8000)                │                        │
│                    └─────────────────────────────────┘                        │
│                                 │                                            │
│                                 ▼                                            │
│                    ┌─────────────────────────────────┐                        │
│                    │      SUPERVISOR AGENT           │                        │
│                    │   (Intelligent Router)          │                        │
│                    └─────────────────────────────────┘                        │
│                                 │                                            │
│                                 ▼                                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐                │
│  │  CALENDAR       │  │   GMAIL         │  │   UNIFIED       │                │
│  │  AGENT          │  │   AGENT         │  │   AGENT         │                │
│  │  (Specialized)  │  │  (Specialized)  │  │  (Combined)     │                │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘                │
│           │                     │                     │                        │
│           ▼                     ▼                     ▼                        │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐                │
│  │  CALENDAR       │  │   GMAIL         │  │   BOTH          │                │
│  │  SERVICE        │  │   SERVICE       │  │   SERVICES      │                │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘                │
│           │                     │                     │                        │
│           └─────────────────────┼─────────────────────┘                        │
│                                 │                                            │
│                                 ▼                                            │
│                    ┌─────────────────────────────────┐                        │
│                    │      EXTERNAL APIs              │                        │
│                    │  ┌─────────────┐ ┌─────────────┐│                        │
│                    │  │   Google    │ │   Gmail     ││                        │
│                    │  │  Calendar   │ │    API      ││                        │
│                    │  │    API      │ │             ││                        │
│                    │  └─────────────┘ └─────────────┘│                        │
│                    └─────────────────────────────────┘                        │
└─────────────────────────────────────────────────────────────────────────────────┘

🔄 Detailed Component Flow

1. Request Flow

User Request
    │
    ▼
┌─────────────────┐
│   FastAPI       │ ← HTTP POST /api/supervisor/chat
│   Server        │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Supervisor     │ ← Intelligent task analysis
│  Agent          │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Agent          │ ← Route to appropriate agent
│  Selection      │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Selected       │ ← Execute task
│  Agent          │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Service        │ ← Make API calls
│  Layer          │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  External       │ ← Google APIs
│  APIs           │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Response       │ ← Format and return
│  Aggregation    │
└─────────────────┘
    │
    ▼
User Response

🎯 Agent Capabilities Matrix

Agent Type	Calendar Operations	Email Operations	Complex Workflows	Tools Available
Calendar Agent	✅ Full Support	❌ None	❌ None	8 tools
Gmail Agent	❌ None	✅ Full Support	❌ None	12 tools
Unified Agent	✅ Full Support	✅ Full Support	✅ Full Support	15 tools
Supervisor Agent	✅ Routing	✅ Routing	✅ Routing	0 tools

🔧 Technical Stack

Frontend Layer

Web Clients: HTML/JS, React, Vue.js
Mobile Apps: iOS, Android
API Clients: Python, JavaScript, cURL

API Layer

Framework: FastAPI
Port: 8000
Protocol: HTTP/HTTPS
Authentication: API Keys, OAuth 2.0

Agent Layer

Framework: LangChain
LLM: OpenAI GPT-4o-mini
Memory: ConversationBufferMemory
Tools: StructuredTool

Service Layer

Calendar Service: Google Calendar API
Gmail Service: Gmail API
HTTP Client: httpx
Validation: Pydantic

External APIs

Google Calendar API: v3
Gmail API: v1
Authentication: OAuth 2.0

📊 Data Flow Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│ User Input  │───▶│ Supervisor   │───▶│ Task       │
│             │    │ Agent        │    │ Analysis   │
└─────────────┘    └──────────────┘    └─────────────┘
                           │                    │
                           ▼                    ▼
                   ┌──────────────┐    ┌─────────────┐
                   │ Agent        │    │ LLM +       │
                   │ Selection    │    │ Keywords    │
                   └──────────────┘    └─────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │ Route to     │
                   │ Agent        │
                   └──────────────┘
                           │
                           ▼
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
   │ Calendar    │ │ Gmail       │ │ Unified     │
   │ Agent       │ │ Agent       │ │ Agent       │
   └─────────────┘ └─────────────┘ └─────────────┘
           │               │               │
           ▼               ▼               ▼
   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
   │ Calendar    │ │ Gmail       │ │ Both        │
   │ Service     │ │ Service     │ │ Services    │
   └─────────────┘ └─────────────┘ └─────────────┘
           │               │               │
           ▼               ▼               ▼
   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
   │ Google      │ │ Gmail       │ │ Google      │
   │ Calendar    │ │ API         │ │ APIs        │
   │ API         │ │             │ │             │
   └─────────────┘ └─────────────┘ └─────────────┘
           │               │               │
           └───────────────┼───────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │ Response     │
                   │ Aggregation  │
                   └──────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │ API Response │
                   │ to User      │
                   └──────────────┘

🎯 Decision Points

1. Supervisor Agent Decision Tree

User Request
    │
    ▼
┌─────────────────┐
│  Task Analysis  │ ← LLM + Keywords
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Agent          │ ← Calendar | Gmail | Unified
│  Selection      │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Execution      │ ← Route to selected agent
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Response       │ ← Format and return
│  Aggregation    │
└─────────────────┘

2. Agent Selection Logic

Task Analysis
    │
    ▼
┌─────────────────┐
│  Calendar       │ ← Keywords: schedule, meeting, calendar
│  Keywords > 0?  │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Email          │ ← Keywords: email, send, mail
│  Keywords > 0?  │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Complex        │ ← Keywords: and, then, also
│  Keywords > 0?  │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Select Agent   │ ← Calendar | Gmail | Unified
└─────────────────┘

🔧 File Structure

multi_agent_supervisor/
├── app/
│   ├── agents/
│   │   ├── calendar_agent.py      # Calendar operations
│   │   ├── gmail_agent.py         # Email operations
│   │   ├── unified_agent.py       # Combined operations
│   │   └── supervisor_agent.py    # Intelligent router
│   ├── api/
│   │   └── endpoints/
│   │       ├── __init__.py        # Router aggregation
│   │       ├── calendar.py        # Calendar endpoints
│   │       ├── gmail.py           # Gmail endpoints
│   │       ├── unified.py         # Unified endpoints
│   │       └── supervisor.py      # Supervisor endpoints
│   ├── services/
│   │   ├── calendar_service.py    # Google Calendar API
│   │   └── gmail_service.py      # Gmail API
│   ├── tools/
│   │   ├── calendar_tool.py      # Calendar tools
│   │   ├── gmail_tool.py         # Gmail tools
│   │   └── time_tool.py          # Time utilities
│   ├── schema/
│   │   ├── calendar_schema.py    # Calendar models
│   │   └── gmail_schema.py       # Gmail models
│   ├── config.py                 # Environment variables
│   └── main.py                   # FastAPI app
├── tests/
│   ├── test_supervisor_agent.py  # Supervisor tests
│   ├── test_gmail.py             # Gmail tests
│   └── test_unified_agent.py     # Unified tests
├── docs/
│   ├── SUPERVISOR_AGENT_README.md
│   ├── SUPERVISOR_AGENT_FLOW.md
│   ├── GMAIL_README.md
│   └── UNIFIED_AGENT_README.md
├── requirements.txt
└── README.md

📈 Performance Metrics

Response Times

Supervisor Analysis: 1-2 seconds
Calendar Agent: 2-3 seconds
Gmail Agent: 2-3 seconds
Unified Agent: 4-6 seconds

Throughput

Concurrent Requests: 10-50 requests/second
Memory Usage: 100-500 MB
CPU Usage: 20-60%

Scalability

Horizontal: Add more agent instances
Vertical: Scale individual agents
Load Balancing: Route by agent type

🔍 Monitoring Points

1. Request Monitoring

Request volume per agent
Response times per agent
Error rates per agent
Success rates per agent

2. Agent Monitoring

Agent selection frequency
Tool usage patterns
Memory usage per agent
CPU usage per agent

3. API Monitoring

External API response times
API error rates
Rate limiting status
Token usage

4. System Monitoring

Overall system health
Resource utilization
Network connectivity
Database performance

🚀 Deployment Architecture

Development Environment

┌─────────────────┐
│  Local Machine  │
│  (Development)  │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  FastAPI       │
│  (Port 8000)   │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Agents        │
│  (Local)       │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Google APIs   │
│  (External)    │
└─────────────────┘

Production Environment

┌─────────────────┐
│  Load Balancer  │
│  (Nginx)        │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  FastAPI       │
│  (Multiple)    │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Agent Pool    │
│  (Scaled)      │
└─────────────────┘
    │
    ▼
┌─────────────────┐
│  Google APIs   │
│  (External)    │
└─────────────────┘

🎯 Key Benefits

1. Intelligent Routing

Automatically selects most efficient agent
Optimizes performance and cost
Reduces unnecessary complexity

2. Scalable Architecture

Modular design
Independent agent scaling
Easy to add new agents

3. Robust Error Handling

Multiple fallback strategies
Graceful degradation
Comprehensive error reporting

4. User Experience

Single entry point
Consistent interface
Detailed response information

🎉 System Summary

The multi-agent system provides:

4 Specialized Agents: Calendar, Gmail, Unified, Supervisor
Intelligent Routing: Automatic agent selection
Comprehensive APIs: Full calendar and email functionality
Robust Architecture: Scalable and maintainable
Production Ready: Error handling and monitoring

This architecture enables efficient, intelligent, and scalable calendar and email management through a single, unified interface.

What's inside

7 architecture diagrams, 1 agent capabilities matrix, 1 file tree, 1 technical stack table, and 1 deployment diagram

Change this for your project

Replace multi_agent_supervisor/ with your own project name
Replace Amanastel/multi_agent_supervisor with your repository path
Replace OpenAI GPT-4o-mini with your chosen LLM model
Replace Port 8000 with your actual server port

Where it goes

Save in docs/ or the repository root. Gives agents and new contributors a map of the codebase.

Worth borrowing

Use a decision tree diagram to show how the supervisor selects an agent based on keyword presence
Separate agent capabilities into a matrix so readers can see which agent handles which operations at a glance

🏗️ Complete Multi-Agent System Architecture

What this file does

When to use it

Assumes this stack

🏗️ Complete Multi-Agent System Architecture

🎯 System Overview

🏛️ High-Level Architecture

🔄 Detailed Component Flow

1. Request Flow

🎯 Agent Capabilities Matrix

🔧 Technical Stack

Frontend Layer

API Layer

Agent Layer

Service Layer

External APIs

📊 Data Flow Architecture

🎯 Decision Points

1. Supervisor Agent Decision Tree

2. Agent Selection Logic

🔧 File Structure

📈 Performance Metrics

Response Times

Throughput

Scalability

🔍 Monitoring Points

1. Request Monitoring

2. Agent Monitoring

3. API Monitoring

4. System Monitoring

🚀 Deployment Architecture

Development Environment

Production Environment

🎯 Key Benefits

1. Intelligent Routing

2. Scalable Architecture

3. Robust Error Handling

4. User Experience

🎉 System Summary

What's inside

Change this for your project

Where it goes

Worth borrowing

Related Documents

Design Document: BharatSeva AI

OpenClaw Enterprise Transformation Plan

Qwen Image and Edit: Open-sourcing and Local GGUF Generations with Lightning

University of Guelph Rocketry Club - Complete Tech Stack