simple-agent/README.md

Personal Gmail + Calendar Agent

This project runs a small local API service that:

• scans new Gmail inbox messages
• moves LinkedIn emails to a LinkedIn label/folder
• moves advertising emails to an Advertising label/folder
• exposes a secure availability endpoint powered by Google Calendar free/busy

1) Prerequisites

• Python 3.11+
• A Google account
• A Google Cloud project with:
  • Gmail API enabled
  • Google Calendar API enabled
  • OAuth consent configured
  • OAuth Client ID of type Desktop app

2) Google OAuth setup

1. In Google Cloud Console, create a desktop OAuth client.
2. Download the client JSON file.
3. Save it in this project as credentials.json.

The first run opens a browser window for consent and creates token.json.

3) Install and configure

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env and set:

• AGENT_API_KEY to a strong secret for agent-to-agent calls
• optional scan frequency and Gmail query

4) Run

uvicorn app.main:app --reload

At startup, the scheduler runs every GMAIL_SCAN_INTERVAL_MINUTES.

5) API usage

Health check

curl http://127.0.0.1:8000/health

Manual Gmail scan

curl -X POST "http://127.0.0.1:8000/scan?max_results=100" \
  -H "X-API-Key: your-secret"

Availability for other AI agents

curl -X POST "http://127.0.0.1:8000/availability" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret" \
  -d '{
    "start": "2026-03-09T09:00:00+01:00",
    "end": "2026-03-09T10:00:00+01:00",
    "calendar_ids": ["primary"]
  }'

If available is true, there are no busy slots in that range.

Classification behavior

• LinkedIn detection: sender or subject contains linkedin (LinkedIn has priority).
• Advertising detection: Gmail promotion category, List-Unsubscribe, Precedence: bulk/list/junk, common promo keywords, and marketing sender hints.
• Every scanned message gets an AgentProcessed label to avoid reprocessing loops.

Notes

• Gmail "folders" are labels. This agent creates:
  • LinkedIn
  • Advertising
  • AgentProcessed
• Messages classified as LinkedIn/Advertising are removed from INBOX (moved out of inbox).