02 / AI / SOFTWARE / AUTOMATION
A human-in-the-loop email agent that turns inbox clutter into reviewed actions and structured tasks.
THE CASE STUDY
Important messages, promotions, receipts, and low-value notifications compete for attention in the same inbox. Manual triage is repetitive, while fully autonomous deletion or task creation would create an unacceptable trust and safety risk.
The project explores an intermediate model: let an agent read and organize the decision space, but keep the user in control before anything destructive or externally visible happens.
The user asks for recent or filtered email through a Gmail-inspired chat interface. The agent loads remembered sender preferences, fetches messages, groups them into Important, Promotional, Spam, and FYI categories, summarizes the result, and proposes a concrete action plan.
After confirmation, it can archive or trash selected messages and turn actionable email into a Notion task. A user can also teach durable rules such as always treating a sender as important or promotional.
A React and Vite single-page interface sends chat messages to a FastAPI `/chat` endpoint. The backend lazily initializes a Google ADK `LlmAgent`, an in-memory session service, and the agent runner so MCP subprocess startup does not delay the server’s basic health path.
The agent combines three tool groups: custom Gmail tools, local sender-preference tools, and Notion tools discovered through a standard-input/output MCP server. Gemini performs classification, summarization, recommendation, and tool selection while FastAPI streams ADK events into a single response for the client.
The Gmail service uses OAuth credentials with the `gmail.modify` scope. It refreshes stored credentials when possible, initiates a local authorization flow when needed, and keeps secrets and generated tokens outside source control.
Recent messages are queried by date, then normalized into message ID, sender, subject, received date, snippet, and a bounded body. Archive removes the Inbox label; trash uses Gmail’s message trash operation.
The agent instruction defines the categories, presentation contract, available actions, and a sequential flow with a conditional review loop. It must load sender rules first, classify immediately, explain its recommendation, and wait for confirmation before executing the proposed plan.
This makes the language model responsible for interpreting context while deterministic tools own side effects. The separation is important: the model chooses an action, but Gmail and Notion operations remain explicit functions with narrow inputs.
A small JSON-backed preference store maps senders to rules such as `always_important`, `always_archive`, `always_trash`, or `promotional`. The design provides visible, inspectable memory without introducing a database for a single-user prototype.
The tradeoff is deliberate: it demonstrates preference recall clearly, but production multi-user use would require authenticated sessions, tenant-scoped durable storage, and stronger normalization of sender identity.
A Python FastMCP server exposes task creation as a tool rather than coupling the agent directly to a UI-specific integration. It maps a generated title, description, sender, action item, due date, and received date into a configured Notion database and returns the created page URL.
This boundary makes the integration discoverable by the agent and demonstrates how external capabilities can be added without expanding the core Gmail service.
The React client renders model responses as structured Markdown, visually separates user and assistant messages, indicates work in progress, and supports keyboard submission. Recommendations are presented as a distinct review block so the user sees the proposed next step before approving it.
The confirmation loop is the central product decision: automation reduces inbox effort, while review keeps destructive actions and task creation understandable and reversible where the underlying service allows it.
The current backend uses a single in-memory ADK session and local JSON preferences, which is appropriate for a capstone prototype but not multi-user deployment. A production version would add authentication, per-user encrypted credential storage, durable session and rule storage, finer Gmail scopes where possible, structured action previews, and audit records.
The completed capstone demonstrates an end-to-end agentic workflow across a custom interface, API boundary, model orchestration, memory, OAuth-protected email tools, MCP tool discovery, and an external task system. More importantly, it treats confirmation and explainability as part of the architecture rather than as UI decoration.
TECHNOLOGY MAP