how to build a google adk agent with email and calendar tools

Google's Agent Development Kit (ADK) is one of the more interesting frameworks to land in 2026. It gives you a Python-native way to build agents that call tools, coordinate sub-agents, and plug into Google's ecosystem. If you've been wanting an AI agent that can check your calendar, schedule meetings, and fire off emails without you touching a keyboard, ADK is a solid starting point.

But the email side of that equation gets messy fast. The Calendar API is straightforward: authenticate, read events, create events. Email through Gmail's API? That's where you hit the OAuth problem that makes Gmail integration painful for agents. Scopes, token refresh, consent screens, and the fundamental issue that Gmail accounts are designed for humans, not autonomous software.

I spent a week building a Google ADK agent that handles both calendar and email. Here's what worked, what didn't, and a shortcut that saved me from OAuth purgatory.

How to build a Google ADK agent with email and calendar tools#

If you want the quick overview before we get into details, here's the full process:

1. Install ADK and dependencies with pip install google-adk google-auth google-api-python-client
2. Enable the Gmail and Calendar APIs in your Google Cloud Console project
3. Configure OAuth2 credentials and download credentials.json
4. Define Python tool functions that wrap Calendar and Gmail API calls
5. Register tools with the ADK Agent class and configure the model
6. Test locally with adk web to verify tool calls work
7. Deploy to Cloud Run or Vertex AI Agent Engine for production use

Each of those steps hides varying amounts of complexity. Steps 2 and 3 are where most people lose an afternoon. Let's walk through them.

Setting up your ADK environment#

ADK runs on Python 3.10+. Start with a virtual environment and install the core packages:

pip install google-adk google-auth google-api-python-client google-auth-oauthlib

You'll also need a Google Cloud project with the Calendar API and Gmail API enabled. Head to the Cloud Console, create a project (or use an existing one), navigate to "APIs & Services," and enable both.

For OAuth2 credentials, create an "OAuth consent screen" and then generate a "Desktop app" credential. Download the resulting credentials.json to your project root. This file is what your agent uses to request access tokens.

Here's the authentication helper I used:

from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from google.auth.transport.requests import Request
import os, pickle

SCOPES = [
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/gmail.send",
    "https://www.googleapis.com/auth/gmail.readonly",
]

def get_google_creds():
    creds = None
    if os.path.exists("token.pickle"):
        with open("token.pickle", "rb") as f:
            creds = pickle.load(f)
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file("credentials.json", SCOPES)
            creds = flow.run_local_server(port=0)
        with open("token.pickle", "wb") as f:
            pickle.dump(creds, f)
    return creds

That SCOPES list is important. calendar gives full read/write access to events. gmail.send lets the agent compose and send. gmail.readonly lets it read incoming messages. You can narrow these if your agent only needs a subset, and Google recommends you do.

The catch: run_local_server() opens a browser window for a human to approve access. That works during development. In production, when your agent is running on a server with no browser, you need a different flow (service accounts, or pre-authorized refresh tokens). This is the first sign that Gmail wasn't built for agents.

Building the calendar tool#

The calendar tool is the easy win. Google Calendar's API is clean and well-documented:

from googleapiclient.discovery import build
from datetime import datetime, timedelta

def list_upcoming_events(n: int = 5) -> list[dict]:
    """Return the next n calendar events."""
    creds = get_google_creds()
    service = build("calendar", "v3", credentials=creds)
    now = datetime.utcnow().isoformat() + "Z"
    result = service.events().list(
        calendarId="primary",
        timeMin=now,
        maxResults=n,
        singleEvents=True,
        orderBy="startTime",
    ).execute()
    return [
        {"summary": e.get("summary", "No title"), "start": e["start"].get("dateTime", e["start"].get("date"))}
        for e in result.get("items", [])
    ]

def create_event(summary: str, start_iso: str, duration_minutes: int = 60) -> dict:
    """Create a calendar event and return its details."""
    creds = get_google_creds()
    service = build("calendar", "v3", credentials=creds)
    start = datetime.fromisoformat(start_iso)
    end = start + timedelta(minutes=duration_minutes)
    event = service.events().insert(
        calendarId="primary",
        body={
            "summary": summary,
            "start": {"dateTime": start.isoformat(), "timeZone": "UTC"},
            "end": {"dateTime": end.isoformat(), "timeZone": "UTC"},
        },
    ).execute()
    return {"id": event["id"], "link": event.get("htmlLink")}

Register these with your ADK agent and it can check what's on the calendar, create new events, and answer questions like "Am I free at 3pm tomorrow?" ADK handles the function-calling plumbing: it inspects your type hints and docstrings to generate the tool schema automatically.

Error handling matters here. The Calendar API can throw HttpError for quota limits, invalid time ranges, or permission issues. Wrap your calls in try/except and return a clear error message so the agent can tell the user what went wrong instead of crashing silently.

The email problem (and two ways to solve it)#

Now the hard part. Building a Gmail send tool looks simple on the surface:

import base64
from email.mime.text import MIMEText

def send_email(to: str, subject: str, body: str) -> dict:
    """Send an email via Gmail API."""
    creds = get_google_creds()
    service = build("gmail", "v1", credentials=creds)
    message = MIMEText(body)
    message["to"] = to
    message["subject"] = subject
    raw = base64.urlsafe_b64encode(message.as_bytes()).decode()
    sent = service.users().messages().send(
        userId="me", body={"raw": raw}
    ).execute()
    return {"id": sent["id"], "threadId": sent["threadId"]}

This works. In development. On your personal Gmail account. With your OAuth tokens cached locally.

In production, the problems stack up. Gmail's API has a send limit of 2,000 messages per day for Workspace accounts and 500 for free accounts. Your OAuth tokens expire and need refreshing. If the agent runs headless, there's no browser to re-authenticate. And the fundamental issue: the agent is borrowing a human's Gmail identity. Every email it sends comes from you@gmail.com, not from the agent itself.

If you're building an agent that schedules meetings over email, that might be fine. It's acting on your behalf, using your calendar, sending from your address.

But if you want the agent to have its own email identity, its own inbox, its own address that isn't tied to any human's Google account, the Gmail API path doesn't work. You'd need to create a Google Workspace account for the agent ($7.20/mo minimum), configure it, set up the OAuth flow for that account, and maintain the whole thing.

There's a simpler approach. Give the agent a dedicated inbox through LobsterMail, where provisioning takes one API call instead of an afternoon in the Google Cloud Console:

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'Calendar Agent' });
// inbox.address → calendar-agent@lobstermail.ai

No OAuth. No token refresh. No human account required. The agent owns its inbox from the moment it's created.

If you want your ADK agent to have its own email, set up LobsterMail here and your agent handles the rest.

Wiring it all together with ADK's agent class#

Here's where ADK shines. You define your agent, register the tools, and let the framework handle routing:

from google.adk.agents import Agent

agent = Agent(
    model="gemini-2.5-flash",
    name="calendar_email_agent",
    instruction="""You are a scheduling assistant. You can check the calendar,
    create events, and send email confirmations. When asked to schedule a
    meeting, check availability first, then create the event, then email
    the attendees.""",
    tools=[list_upcoming_events, create_event, send_email],
)

ADK's multi-agent pattern lets you split responsibilities further. You could have a calendar sub-agent and an email sub-agent, each with their own tools and instructions, coordinated by a root agent. For a simple assistant this is overkill. For a production system handling dozens of calendars and email accounts, it keeps things organized.

Test locally with adk web, which launches a browser UI where you can chat with the agent and watch tool calls execute in real time. This is genuinely useful for debugging; you can see exactly which tool the model chose, what arguments it passed, and what came back.

What I'd do differently#

After building this, here's my honest take. The Calendar integration is clean and works well through ADK. Google clearly designed the Calendar API for programmatic access.

The Gmail integration is functional but fragile. Token management alone adds enough complexity that I'd recommend it only when you specifically need to send from a human's existing Gmail address. For anything where the agent needs its own identity, skip the OAuth maze entirely.

If I were starting over, I'd use ADK for calendar and LobsterMail for email. Two tools, two different providers, each doing what they're good at. The agent doesn't care where its email comes from. It just calls the tool.