Gmail

Gmail enables an Agent to interact with Gmail, allowing it to read, search, send, manage emails, and organize them with labels. Supports both OAuth and service account authentication.

Prerequisites

Install dependencies

uv pip install agno google-api-python-client google-auth-httplib2 google-auth-oauthlib openai

Set up Google OAuth

Follow the Gmail Python quickstart:

1. Create or select a Google Cloud project and enable the Gmail API.
2. Configure Google Auth Platform > Branding, including the app name and support contact.
3. Under Audience, choose the appropriate Internal or External audience. For an external app in Testing, add the Google accounts that will authorize it as test users.
4. Configure the required Gmail scopes under Data Access. Use gmail.readonly for a tool selection that only reads mail; writing and composing require the corresponding Gmail scopes.
5. Under Clients, create a Desktop app OAuth client and download its JSON credentials.
6. Pass its path as credentials_path. The initial interactive sign-in stores access and refresh tokens in token.json in the current directory, or at the writable token_path you supply.

For client credentials from environment variables, set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_PROJECT_ID. Publishing an external app with sensitive or restricted scopes may require Google's verification process.

Shared authentication and headless servers

Google toolkits accept one shared AuthConfig, which aggregates their scopes before authentication. For example:

from agno.tools.google.auth import AuthConfig
from agno.tools.google.gmail import GmailTools

auth = AuthConfig(interactive=False, http_timeout=60)
gmail = GmailTools(auth=auth)

This headless configuration requires existing usable credentials or a delegated service account. Gmail tool calls return an authentication error if a browser sign-in would be needed; for the initial local OAuth flow, set interactive=True and provide your client credentials.

AuthConfig(db=...) can store tokens in a supported Agno database. Encryption is enabled by default and requires token_encryption_key or GOOGLE_TOKEN_ENCRYPTION_KEY. The stored Google token uses a shared provider identity (google, with no user ID); an agent's user_id does not choose a separate mailbox. Configure separate credential boundaries in applications that serve different Google accounts.

When using auth=, put service_account_path and delegated_user on AuthConfig. Passing them alongside auth= on GmailTools raises an error. See the AuthConfig source for its full configuration.

Service Account Authentication (Alternative)

For server/bot deployments without browser access:

1. Create a service account at IAM & Admin > Service Accounts in Google Cloud Console
2. Download the JSON key file
3. Configure domain-wide delegation in Google Workspace Admin Console (required for Gmail)
4. Set environment variables:

export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service-account-key.json
export GOOGLE_DELEGATED_USER=user@yourdomain.com  # Required for Gmail

Example

from agno.agent import Agent
from agno.tools.google.gmail import GmailTools

agent = Agent(tools=[GmailTools()])
agent.print_response("Show me my latest 5 unread emails", markdown=True)

Quick Start Examples

# OAuth authentication (browser-based)
from agno.agent import Agent
from agno.tools.google.gmail import GmailTools

agent = Agent(
    tools=[GmailTools(
        credentials_path="path/to/credentials.json"
    )],
    instructions=["You help users manage their Gmail inbox."],
)

# Service account authentication (no browser needed)
agent = Agent(
    tools=[GmailTools(
        service_account_path="path/to/service-account.json",
        delegated_user="user@domain.com"  # Required for Gmail
    )],
)

Toolkit Params

Toolkit Functions

Reading Emails

Managing Emails

Composing & Sending

Label Management

You can use include_tools or exclude_tools to modify the list of tools the agent has access to. Learn more about selecting tools.

Cookbook Examples

The agno cookbook includes several Gmail examples demonstrating different use cases:

For send_email_reply, supply the recipient (to), subject, and body along with the original message/thread identifiers. The current validator still requires recipient and subject; a call with only message_id and body fails.

Tips for Using Gmail Tools

1. Authentication:

   • Use OAuth for user-facing applications (requires browser)
   • Use service accounts for server/bot deployments (requires domain-wide delegation)

2. Search Queries: Agent instructions guide the model to translate a request into Gmail syntax, such as is:unread newer_than:7d. The Python tool forwards that query unchanged.

3. Attachments: When sending emails with attachments, provide file paths as strings or a list of strings.

4. Thread Management: Use thread operations (get_thread, trash_thread, etc.) to manage entire conversations.

5. Label Operations: Gmail's label system is hierarchical - use forward slashes for nested labels (e.g., "Work/Projects").

6. Rate Limits: Be mindful of Gmail API quotas when performing bulk operations.

Developer Resources

• Source Code
• Cookbook Examples