Gmail

Search, read, and send emails. By default, exposes query_gmail for searching and reading. Enable write=True to also expose update_gmail for drafting and sending.

Create a virtual environment, then install the Google Workspace clients and the model SDK:

uv pip install -U agno openai google-api-python-client google-auth-httplib2 google-auth-oauthlib
export OPENAI_API_KEY="your-openai-api-key"

For the personal OAuth example, enable the relevant Google API in your Cloud project, configure its consent screen, and create a Desktop OAuth client. Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET and GOOGLE_PROJECT_ID using that client. Authorize access in the browser on first use. The authentication section below also covers service accounts.

For a headless service, provision credentials first and set GOOGLE_OAUTH_NONINTERACTIVE=1. Gmail and Calendar also accept auth=AuthConfig(interactive=False) from agno.tools.google.auth; the current Drive provider does not accept auth=. If credentials cannot be loaded or refreshed, authentication reports an error instead of opening a browser. Provider configuration selects the credentials; forwarding a run’s user ID does not switch Google accounts.

Save as gmail_context.py and run python gmail_context.py after configuring authentication:

import asyncio

from agno.agent import Agent
from agno.context.gmail import GmailContextProvider
from agno.models.openai import OpenAIResponses

async def main():
    gmail = GmailContextProvider(model=OpenAIResponses(id="gpt-5.4-mini"))
    agent = Agent(
        model=OpenAIResponses(id="gpt-5.4"),
        tools=gmail.get_tools(),
        instructions=gmail.instructions(),
    )
    await agent.aprint_response("Do I have any unread emails from the engineering team?")

if __name__ == "__main__":
    asyncio.run(main())

Authentication

Gmail requires Google OAuth or a service account with domain-wide delegation.

export GOOGLE_CLIENT_ID=...
export GOOGLE_CLIENT_SECRET=...
export GOOGLE_PROJECT_ID=...

export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
export GOOGLE_DELEGATED_USER=user@domain.com

Configuration

The read/write flags below describe the default tool surface. See read/write control for mode and authorization boundaries.

Tools Exposed

Example queries

For draft/send queries, enable writes: GmailContextProvider(write=True)

Resources