Communication Agent
A stateful email triage and response system for support workflows
Communication Agent is a backend-first system for handling customer email from ingestion to draft generation and final approval. It combines secure Gmail integration, stateful ticket management, and LLM-assisted triage so support work can be automated without losing auditability or operator control.
The Problem
Customer communication is not just about generating replies. A real support workflow needs secure email access, persistent ticket state, approval steps, and clear visibility into who did what and when.
The Outcome
Communication Agent turns email handling into a structured support system with secure ingestion, state-based routing, human-reviewed drafts, and a clear operational workflow from start to finish.
Example: Human-reviewed support reply
A new customer email is synced from Gmail, turned into a ticket, routed into the right state, and given a model-assisted draft. An operator can review that draft, make changes if needed, and approve the final response, while the system keeps a clear record of the workflow.
The Problem: Email automation usually stops too early
Many AI email tools focus on a single step, such as summarizing or drafting, but do not manage the full lifecycle of a support interaction. That leaves important gaps around ticket state, operator control, secure authentication, and operational reporting.
The Outcome: Full lifecycle control for support communication
Communication Agent is designed to make email support more structured and dependable in practice.
- Secure ingestion: Connects to Gmail through OAuth and pulls messages into a controlled backend workflow.
- Stateful handling: Tracks tickets through explicit stages so the workflow remains inspectable and actionable.
- Human-approved responses: Uses model-assisted triage and drafting without removing operator oversight.
Technical Architecture and Production Features
Reasoning Layer
Model-assisted triage and drafting
LLM support without hard-coding the system to one provider.
- Pluggable LLM adapter: The business logic stays separate from the model backend through an adapter layer.
- Draft generation: The system can produce triage suggestions, draft replies, and a structured plan for each ticket.
- Activity logging: Key actions such as drafting, assignment, and send approval are logged for review.
Workflow Integrity
FastAPI and stateful ticket handling
Built around persistence, clear state transitions, and operational reliability.
- Explicit ticket states: Tickets move through a defined support flow such as
NEW,NEEDS_ACTION,WAITING_OTHERS, andDONE. - Async backend: FastAPI and async SQLAlchemy support non-blocking operations across the application.
- Credential handling: OAuth client data and tokens are managed through environment-based configuration rather than hardcoded secrets.
Operations
Reporting and operator control
A backend system that stays visible and manageable in daily use.
- Operational boards: Server-rendered board views show the current state of the support queue.
- Full API surface: Sync, drafting, state changes, and send approval are exposed through the API for scripting and monitoring.
- Optional background sync: The system can continuously poll for new email when needed.
Repository Layout: Designed for clarity
The repository keeps transport, adapters, business logic, and data models clearly separated.
app/
api/ # FastAPI app + routers (The exposed surface)
adapters/ # External dependencies: Gmail, LLM (The pluggable connectors)
services/ # Triage, drafting, sync (The business logic)
models/ # SQLAlchemy entities + Pydantic schemas (The data contracts)
core/ # Config, db, logging (The system foundation)
ui/templates/ # Jinja pages (The simple UX layer)This clear organization is fundamental to building scalable and auditable AI systems.