Skip to main content

Overview

The Smart Scheduler Assistant is an advanced multi-agent system that automates email management and calendar scheduling. Built with the Agno framework, it leverages multiple specialized AI agents to streamline your productivity workflow by reading Gmail, filtering important messages, and automatically updating Google Calendar.

Features

Smart Email Reading

Automatically fetches and reads latest Gmail messages with detailed content extraction

Intelligent Filtering

AI-powered analysis to distinguish important emails from noise and spam

Automated Calendar

Seamlessly creates, updates, and deletes Google Calendar events from email content

Multi-Agent System

Coordinated team of specialized agents working together for optimal results

Conversational Interface

Interactive CLI for natural language interactions

Persistent Memory

Built-in SQLite database maintains conversation context and history

Tech Stack

Python

Core programming language

Agno Framework

Multi-agent AI orchestration

Nebius AI

Fast LLM inference (Qwen 3 32B model)

Gmail API

Email reading and management

Google Calendar API

Calendar event management

SQLite

Conversation history and agent memory

How It Works

The Smart Scheduler Assistant operates through a coordinated multi-agent system:
1

Email Agent

Retrieves and reads the latest emails from Gmail, summarizes content, and filters unnecessary emails
2

Calendar Agent

Processes filtered emails and updates Google Calendar accordingly
3

Team Coordinator

Orchestrates workflow between agents to ensure seamless operation
The system intelligently extracts event details from emails (dates, times, locations) and automatically schedules them in your calendar, making reasonable assumptions where necessary for missing information.

Prerequisites

Python 3.9+

Python 3.9 or higher required

Nebius API Key

Google Cloud Project

Gmail and Calendar APIs enabled

OAuth Credentials

OAuth 2.0 credentials file (credentials.json)

Google Cloud Setup

1

Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Click on the project dropdown and select β€œNew Project”
  3. Name your project (e.g., β€œSmart Scheduler Assistant”)
  4. Click β€œCreate” and select your newly created project
2

Enable Required APIs

  1. Navigate to β€œAPIs & Services” > β€œLibrary”
  2. Search for β€œGmail API” and click β€œEnable”
  3. Search for β€œGoogle Calendar API” and click β€œEnable”
3

Create OAuth 2.0 Credentials

  1. Go to β€œAPIs & Services” > β€œCredentials”
  2. Click β€œCreate Credentials” > β€œOAuth client ID”
  3. Configure OAuth consent screen if prompted:
    • Select β€œExternal” user type
    • Fill in app name, support email, and developer email
    • Click through scopes and test users sections
  4. Select β€œDesktop app” as application type
  5. Give it a name (e.g., β€œSmart Scheduler Desktop Client”)
  6. Click β€œCreate”
4

Download Credentials

  1. Click β€œDownload JSON” for your OAuth client
  2. Rename the file to credentials.json
  3. Move it to your project root directory
5

Authenticate

Before running the main application:
python authenticate.py
This will:
  • Open a browser for Google account authentication
  • Prompt you to grant Gmail and Calendar permissions
  • Generate a token.json file for future use
You may see a warning that the app isn’t verified. Click β€œAdvanced” and β€œGo to Smart Scheduler Assistant (unsafe)” to proceed.

Installation

1

Clone the Repository

git clone https://github.com/Arindam200/awesome-ai-apps.git
cd awesome-ai-apps/simple_ai_agents/email_to_calendar_scheduler
2

Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
3

Install Dependencies

Using uv (recommended):
uv sync
Or using pip:
pip install -r requirements.txt
4

Configure Environment

Create a .env file:
NEBIUS_API_KEY="your_nebius_api_key_here"
TIMEZONE=America/New_York  # Your timezone in IANA format
5

Place Google Credentials

Ensure credentials.json is in the project root directory

Implementation

Email Agent

The email agent specializes in Gmail operations:
from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.gmail import GmailTools
from agno.db.sqlite import SqliteDb
import os

email_agent = Agent(
    model=Nebius(id="Qwen/Qwen3-32b", api_key=os.getenv("NEBIUS_API_KEY")),
    markdown=True,
    tools=[GmailTools(credentials_path="credentials.json", port=8090)],
    description="You are a Gmail reading specialist that can search and read emails.",
    instructions=[
        "Use the tools to search and read emails from Gmail.",
        "Focus on extracting key details such as sender, subject, and body.",
        "Summarize the body of the email concisely.",
        "Never fabricate email content; only use available information.",
        "If no emails are found, respond with 'No emails found.'",
    ],
    db=db,
    add_history_to_context=True,
    num_history_runs=3,
    read_chat_history=True,
)

Calendar Agent

The calendar agent manages Google Calendar operations:
from agno.tools.googlecalendar import GoogleCalendarTools

calendar_agent = Agent(
    model=Nebius(id="Qwen/Qwen3-32b", api_key=os.getenv("NEBIUS_API_KEY")),
    tools=[
        GoogleCalendarTools(
            credentials_path="credentials.json",
            allow_update=True,
        )
    ],
    instructions=[
        f"""
        You are a scheduling assistant.
        You should help users to perform these actions in their Google calendar:
            - get their scheduled events from a certain date and time
            - create events based on provided details
            - update existing events
            - delete events
            - find available time slots for scheduling
            - all times are in {os.getenv('TIMEZONE')}
        """
    ],
    add_datetime_to_context=True,
    db=db,
    add_history_to_context=True,
    num_history_runs=3,
    read_chat_history=True,
)

Team Orchestration

The team coordinator manages agent collaboration:
from agno.team import Team

team = Team(
    name="Productivity Agent",
    members=[email_agent, calendar_agent],
    description="Team to extract emails, filter important emails and update Google Calendar.",
    model=Nebius(id="Qwen/Qwen3-32b", api_key=os.getenv("NEBIUS_API_KEY")),
    instructions=[
        "First, use the email agent to find and read the latest emails",
        "Extract important emails with key details",
        "Then, use the calendar agent to update Google Calendar",
        "If details are missing, make reasonable assumptions",
        "Output the final calendar updates made",
    ],
    db=db,
    add_history_to_context=True,
    num_history_runs=3,
    read_team_history=True,
)

Usage

1

Run the Application

python main.py
2

Interact with the Assistant

The assistant will greet you with:
🧠 Smart Scheduler Assistant is running. Type 'exit' to quit.
3

Enter Natural Language Commands

Type your requests:
Read my latest 5 emails and schedule any meetings
4

Exit

Type exit or quit to close the assistant

Example Interactions

User: Read my latest 5 emails and schedule any meetingsAssistant:
  1. Reads the 5 most recent emails
  2. Identifies emails with meeting information
  3. Extracts dates, times, and details
  4. Creates calendar events automatically
  5. Reports: β€œCreated 2 new calendar events from your emails”
User: Check my calendar for tomorrowAssistant:
  • Lists all events scheduled for tomorrow
  • Shows times and event details
  • Identifies free time slots
User: Create an event for team meeting on Friday at 3 PMAssistant:
  • Creates a calendar event
  • Sets the date to next Friday
  • Sets time to 3:00 PM in your timezone
  • Confirms: β€œTeam meeting scheduled for Friday, 3:00 PM”

Project Structure

email_to_calendar_scheduler/
β”œβ”€β”€ tmp/                   # SQLite database storage
β”‚   └── data.db            # Agent memory and conversation history
β”œβ”€β”€ .venv/                 # Virtual environment
β”œβ”€β”€ .env                   # Environment variables (API keys)
β”œβ”€β”€ credentials.json       # Google OAuth credentials
β”œβ”€β”€ token.json             # Generated after authentication
β”œβ”€β”€ authenticate.py        # Authentication script
β”œβ”€β”€ main.py                # Main application entry point
β”œβ”€β”€ requirements.txt       # Python dependencies
└── README.md              # Project documentation

Configuration

Customize the assistant’s behavior in main.py:

Timezone Settings

Set your timezone in the .env file using IANA timezone format:
TIMEZONE=America/New_York     # Eastern Time
TIMEZONE=America/Los_Angeles  # Pacific Time
TIMEZONE=Europe/London        # GMT/BST
TIMEZONE=Asia/Kolkata         # Indian Standard Time

Agent Memory

Control conversation history:
num_history_runs=3  # Number of previous interactions to remember
read_chat_history=True  # Enable conversation context

Email Processing

Adjust the number of emails to process:
# In your user message
"Read my latest 10 emails and schedule any meetings"

Security Best Practices

Protect Credentials

Never commit credentials.json or token.json to version control

Environment Variables

Store API keys in .env file, not in code

OAuth Scopes

Only grant necessary permissions during authentication

Token Security

Keep token.json secure; it provides access to your accounts
The token.json file stores your access and refresh tokens. Keep this file secure and do not share it publicly. If compromised, delete it and run authenticate.py again to regenerate.

Troubleshooting

Error: NEBIUS_API_KEY not found in environmentSolution: Ensure your .env file exists and contains the required API key:
NEBIUS_API_KEY=your_key_here
TIMEZONE=America/New_York
Error: credentials.json not foundSolution: Download OAuth credentials from Google Cloud Console and place in project root.
Error: token.json not foundSolution: Run the authentication script:
python authenticate.py
If you encounter authentication issues:
  1. Delete token.json
  2. Run python authenticate.py again
  3. Complete the OAuth flow in your browser
If you encounter database errors:
  1. Ensure tmp/ directory exists
  2. Check write permissions
  3. Delete tmp/data.db to reset (loses conversation history)

Advanced Features

Persistent Memory

SQLite database maintains conversation context across sessions

Multi-Agent Collaboration

Specialized agents work together for complex tasks

Intelligent Filtering

AI distinguishes important emails from spam and noise

Smart Assumptions

Makes reasonable assumptions for missing event details

Next Steps

Agno Framework

Explore Agno’s multi-agent capabilities

Nebius AI

Learn about Nebius AI models

Gmail API

Google Gmail API documentation

Calendar API

Google Calendar API documentation

Build docs developers (and LLMs) love