Gmail Tools & Tasks

Relevant source files

The following files were used as context for generating this wiki page:

• server/agents/execution_agent/tools/gmail.py
• server/agents/execution_agent/tasks/search_email/tool.py
• server/agents/execution_agent/tasks/search_email/schemas.py
• server/services/gmail/client.py
• server/services/gmail/processing.py
• server/services/gmail/importance_watcher.py
• server/agents/execution_agent/system_prompt.md

The Gmail Tools & Tasks module provides a comprehensive suite of capabilities for the OpenPoke assistant to interact with user email accounts. It facilitates core email operations such as drafting, sending, replying, and forwarding, alongside advanced agentic search functionalities and proactive importance monitoring. These tools are integrated via the Composio SDK to securely manage OAuth connections and execute Gmail API operations.

This system is divided into two primary layers: low-level Gmail Tools used by the Execution Agent for direct actions, and high-level Agentic Tasks like task_email_search that use an internal LLM loop to perform complex, multi-step information retrieval. Proactive features are handled by background services that monitor for important incoming messages.

Sources: README.md, server/agents/execution_agent/tools/gmail.py:1-10, server/services/gmail/importance_watcher.py:22-30

Architecture and Integration

OpenPoke utilizes a multi-agent architecture where the Interaction Agent communicates with the user and delegates technical operations to the Execution Agent. The Gmail integration relies on the Composio client to bridge the Python backend with the Google People and Gmail APIs.

Service Flow Diagram

The following diagram illustrates the flow from an agent tool call through the service layer to the external Gmail API via Composio.

Core Gmail Tools

The system provides several function-calling schemas that allow the Execution Agent to perform standard email management. These tools require an active Gmail connection managed through the user's settings.

Tool Name	Description	Key Parameters
gmail_create_draft	Creates a new email draft.	recipient_email, subject, body, is_html, thread_id
gmail_execute_draft	Sends an existing draft by ID.	draft_id
gmail_reply_to_thread	Replies to a specific thread.	thread_id, recipient_email, message_body
gmail_forward_email	Forwards a message to a new recipient.	message_id, recipient_email, additional_text
gmail_get_contacts	Retrieves Google People API contacts.	resource_name, person_fields

Sources: server/agents/execution_agent/tools/gmail.py:17-180

Draft Lifecycle

The Execution Agent is strictly instructed never to send an email directly without first creating a draft for user review.

Agentic Email Search

The task_email_search tool is a high-level task that expands a raw user query (e.g., "find my travel receipts from last week") into multiple targeted Gmail search queries.

Search Orchestration Logic

The search process uses a recursive LLM loop (up to 8 iterations) to refine results:

1. Validation: Checks for Gmail connection and OpenRouter API configuration.
2. Query Generation: An internal LLM generates standard Gmail search operators (e.g., after:2023/10/01 subject:receipt).
3. Execution: Calls gmail_fetch_emails (an internal tool) which uses Composio.
4. Processing: Raw API responses are cleaned using the EmailTextCleaner to remove HTML noise and tracking pixels.
5. Completion: The loop continues until the LLM calls return_search_results with a list of relevant message_ids.

Sources: server/agents/execution_agent/tasks/search_email/tool.py:73-130, server/services/gmail/processing.py:18-40

Email Search Data Model

Emails are returned in a structured format optimized for LLM consumption, specifically featuring clean_text.

class GmailSearchEmail(BaseModel):
    id: str           # message_id from Gmail API
    thread_id: Optional[str]
    subject: str
    sender: str
    recipient: str    # 'to' field
    timestamp: datetime
    clean_text: str   # Processed, readable content
    has_attachments: bool

Sources: server/agents/execution_agent/tasks/search_email/schemas.py:50-70

Importance Monitoring and Proactive Alerts

OpenPoke includes a background service, the ImportantEmailWatcher, which proactively identifies critical emails without a direct user request.

Importance Classification Flow

The service polls the inbox for recent messages and uses a specialized LLM classifier to determine if an email warrants an immediate notification.

Classification Criteria

The importance_classifier uses a system prompt that instructs the LLM to filter for:

• Critical security information (OTPs, login notices).
• High-priority updates (interviews, meeting changes).
• Messages requiring a prompt decision or action.
• Excluded: Newsletters, routine marketing, and generic receipts.

Sources: server/services/gmail/importance_classifier.py:46-55

Content Processing and Normalization

The EmailTextCleaner in server/services/gmail/processing.py is critical for reducing token usage and improving LLM accuracy. It performs the following:

• HTML Removal: Decomposes style, script, and meta tags.
• Noise Filtering: Removes common boilerplate like "View this email in your browser" or "Unsubscribe".
• URL Truncation: Limits URL length (default 60 chars) and strips tracking parameters (utm_source, gclid, etc.).
• Text Normalization: Replaces images with alt-text placeholders and collapses excessive whitespace.

Sources: server/services/gmail/processing.py:45-120

Summary

The Gmail Tools & Tasks module enables a robust, agent-led email experience. By combining strict drafting protocols for safety, an agentic search loop for complex retrieval, and a proactive background watcher for importance, the system allows the OpenPoke assistant to act as a semi-autonomous personal inbox manager. All operations are underpinned by the Composio service layer, ensuring consistent API interaction and OAuth session management.