Gmail

Search, read, and send emails via 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.

from agno.agent import Agent
from agno.context.gmail import GmailContextProvider

gmail = GmailContextProvider()

agent = Agent(
    model=...,
    tools=gmail.get_tools(),
)

agent.print_response("Do I have any unread emails from the engineering team?")

Authentication

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

OAuth (Personal)

Set these environment variables:

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

Opens browser on first use. Token cached to gmail_token.json.

Service Account

export GOOGLE_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
export GOOGLE_DELEGATED_USER=[e-mail]

delegated_user is required because service accounts have no inbox.

Configuration

Parameter	Type	Default	Description
id	str	"gmail"	Tools become query_<id> and update_<id>.
model	Model	None	Model for sub-agents.
read	bool	True	Expose query_gmail.
write	bool	False	Expose update_gmail. Disabled by default for safety.
mode	ContextMode	default	See Mode.

Tools Exposed

Tool	Description
query_gmail	Search emails, get messages, get threads, list labels. Always exposed.
update_gmail	Create drafts, send emails, send replies, manage labels. Requires write=True.

Example queries

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

Query	What happens
”Find emails from Alice about the Q4 report”	Searches with from:alice subject:Q4 report
”Summarize the thread about the API outage”	Gets thread and synthesizes
”Draft a reply saying I’ll review it tomorrow”	Creates draft in thread
”Send a quick update to the team about the fix”	Composes and sends

Resources

GmailTools Reference

All methods and OAuth setup

Cookbook Example

Working example