AI Email Agent (Supervisor Mode)

An intelligent email automation system powered by LangGraph and LLM agents with supervisor coordination.

Features

• Supervisor Pattern: Dynamic agent coordination with intelligent routing
• Smart Categorization: Automatically categorizes emails (inquiries, complaints, feedback)
• RAG-Powered Responses: Uses retrieval-augmented generation for accurate answers
• Quality Assurance: AI proofreader ensures professional responses
• Gmail Integration: Seamless inbox monitoring and reply drafting
• Flexible Workflow: Supervisor adapts routing based on context and agent feedback

Architecture

The system uses a supervisor pattern where a supervisor agent coordinates specialized worker agents:

┌─────────────┐
│ Load Emails │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Check Inbox │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│   SUPERVISOR    │◀──────────┐
│   (Coordinator) │           │
└──────┬──────────┘           │
       │                       │
       │ Routes dynamically    │
       │                       │
   ┌───┴───┬─────────┬─────────┴───┐
   ▼       ▼         ▼             ▼
┌──────┐ ┌──────┐ ┌──────┐    ┌────────┐
│ Cat. │ │ RAG  │ │Write │    │Proofread│
└──┬───┘ └──┬───┘ └──┬───┘    └────┬───┘
   │        │        │             │
   └────────┴────────┴─────────────┘
              │
              ▼
         ┌─────────┐
         │  Send   │
         └─────────┘

Supervisor Benefits

• Dynamic Routing: Supervisor makes context-aware decisions
• Agent Coordination: Workers can request supervisor guidance
• Quality Control: Supervisor monitors workflow quality
• Flexibility: Adapts to edge cases and complex scenarios
• No Rigid Flow: Avoids "robotics only working" limitations

Tech Stack

• LangChain & LangGraph - AI workflow orchestration
• Groq API - LLM inference (Llama 3.3)
• Google Gemini - Embeddings for RAG
• ChromaDB - Vector storage
• Gmail API - Email integration
• FastAPI - API deployment

Quick Start

Prerequisites

• Python 3.9+
• Groq API key
• Google Gemini API key
• Gmail API credentials

Installation

# Clone repository
git clone https://github.com/pauxd26/ai-email-agent
cd ai-email-agent

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Create a .env file:

MY_EMAIL=your_email@gmail.com
GROQ_API_KEY=your_groq_key
GOOGLE_API_KEY=your_gemini_key

Build Knowledge Base

python create_index.py

Run

# CLI mode
python main.py

# API mode
python deploy_api.py

Project Structure

ai-email-agent/
├── src/
│   ├── agents.py          # AI agent definitions (with supervisor)
│   ├── graph.py           # Supervisor-based LangGraph workflow
│   ├── nodes.py           # Graph node functions
│   ├── prompts.py         # LLM prompts (including supervisor)
│   ├── state.py           # State definitions (with supervisor context)
│   ├── structure_outputs.py  # Pydantic schemas
│   └── tools/
│       └── gmail_tools.py # Gmail integration
├── data/
│   └── knowledge_base.txt # RAG knowledge source
├── main.py                # CLI entry point
├── create_index.py        # Build vector index
├── deploy_api.py          # API server
└── requirements.txt

Supervisor Mode

The supervisor pattern enables:

1. Context-Aware Routing: Supervisor analyzes state and routes to appropriate agents
2. Dynamic Workflow: No fixed sequence - adapts to each email's needs
3. Quality Monitoring: Supervisor tracks agent performance and workflow quality
4. Error Handling: Supervisor can redirect workflow when issues arise
5. Agent Communication: Workers can flag issues for supervisor review

Migration Notes

This version migrated from a rigid workflow to supervisor pattern to:

• Handle edge cases more gracefully
• Provide more flexible routing
• Enable better quality control
• Support complex multi-step scenarios