Back to .md Directory
🏗️ Complete Multi-Agent System Architecture
Diagrams a multi-agent system with a supervisor that routes user requests to calendar, email, or unified agents.
ai agent
View sourceWhat 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_supervisorwith your repository path - Replace
OpenAI GPT-4o-miniwith your chosen LLM model - Replace
Port 8000with 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
Related Documents
ARCHITECTURE.md
PCB Design Sources for Industry-Scale Testing
Lists GitHub repos and communities where you can download real PCB designs for testing optimization at scale.
0
17
AbiralShakyaARCHITECTURE.md
Design Document: BharatSeva AI
Describes a 10-agent AWS system that helps India's informal workers access government schemes via voice-first, serverless architecture.
aiagentclaude
0
104
Prachet-Dev-SinghARCHITECTURE.md
Qwen Image and Edit: Open-sourcing and Local GGUF Generations with Lightning
Documents the Qwen-Image and Qwen-Image-Edit models, covering architecture, training, benchmarks, ComfyUI setup, and prompting techniques for local GGUF deployment.
aillmrag
0
50
sandner-artARCHITECTURE.md
OpenClaw Enterprise Transformation Plan
Transforms a single-user AI agent into a dual-mode platform supporting both viral open-source and Fortune 500 enterprise deployments through phased security, IAM, audit, multi-tenancy, and Kubernetes features.
aiagentrag
0
50
mholovetskyi