building an agent email tool with google adk and vertex ai

Google's Agent Development Kit (ADK) gives you a clean way to build AI agents that call external tools. Define a Python function, register it with an LlmAgent, and the model decides when to invoke it based on conversation context. Email is one of the most requested tool integrations.

The standard approach is wiring up the Gmail API as the sending backend. It works for demos. But once you deploy to Vertex AI Agent Engine and your agent starts handling real email volume, the gaps show up quickly: token expiration, rate limits, a shared personal inbox, and the question of whether your Gmail should be the return address for an autonomous process.

This guide walks through building a Google ADK agent email tool for Vertex AI, the practical limitations of Gmail API as your sending layer, and a simpler path that removes the OAuth overhead entirely. If you'd rather skip the Gmail plumbing, get your agent its own inbox in about two minutes and drop the credentials into your tool function.

How to build an email tool with Google ADK and Vertex AI#

1. Install ADK with pip install google-adk and create a new agent project directory.
2. Define your email-sending logic as a plain Python function with typed parameters for recipient, subject, and body.
3. Register the function in your LlmAgent using the tools=[your_email_fn] parameter.
4. Configure Gmail API credentials (or SMTP/REST API credentials) as environment variables.
5. Test locally with adk web to verify the model triggers your email tool at the right moments.
6. Wrap your agent with AdkApp and deploy to Vertex AI Agent Engine using the Vertex AI SDK for Python.
7. Monitor tool invocations in the Vertex AI console to confirm production sends are working.

That's the skeleton. The model handles intent detection and parameter extraction, then your function does the actual sending. But the complexity hides in steps 4 through 7, and that's where most developers get stuck.

What is Google ADK?#

Google's Agent Development Kit is an open-source Python framework for building AI agents that use tools, manage state, and coordinate with sub-agents. It's optimized for Gemini models but works with any LLM that supports function calling. The core abstraction is LlmAgent: you provide a model, a set of instructions, and a list of callable Python functions. The model reads user input, determines whether a tool call is needed, extracts the right parameters, and invokes your function.

Vertex AI Agent Engine is the managed Google Cloud runtime where you deploy ADK agents to production. It handles scaling, session management, and monitoring. Think of ADK as the build framework and Vertex AI Agent Engine as the execution environment. You develop locally with adk web, then package with AdkApp and push to Vertex AI when you're ready to go live.

The Gmail API ceiling#

Most ADK email tutorials point you at the Gmail API. You authenticate with OAuth2, obtain an access token, and your tool function calls gmail.users().messages().send(). For a local demo using adk web, this gets the job done.

Production changes the equation. OAuth tokens expire. Refresh tokens can be revoked by the user or by Google's security systems at any time. When your agent runs autonomously on Vertex AI, there's no human around to re-authorize the connection. You need either a service account with domain-wide delegation (which requires Google Workspace, not a consumer Gmail account) or a token-refresh pipeline that handles silent failures. Most tutorials skip this part.

Rate limits hit harder than expected. Consumer Gmail accounts allow roughly 100 emails per 24 hours through the API. Google Workspace accounts get up to 2,000 per day, but per-minute burst limits still apply. If your agent processes a batch of 50 customer inquiries and responds to each one in sequence, you'll see 429 Too Many Requests before the batch finishes. And these quotas are per-user, not per-project. If a human and an agent share the same Gmail account, both compete for the same allocation.

Then there's the identity problem. When your agent sends from your Gmail, replies land in your personal inbox. Bounce notifications, out-of-office auto-replies, and confused responses from recipients all mix with your regular email. If the agent sends something wrong, your name is on it. We wrote about this dynamic in why your AI agent shouldn't use your Gmail.

The authentication complexity compounds everything. Creating OAuth2 credentials in Google Cloud Console, configuring consent screens, wiring up the token refresh flow, storing secrets securely on Vertex AI. If you've fought with the OAuth problem in Gmail integration before, you know this isn't a one-afternoon task. It's a recurring maintenance burden.

What production agents actually need#

An autonomous agent sending email from Vertex AI needs capabilities Gmail API wasn't designed to provide.

The agent should create its own email address without a human completing an OAuth flow. No consent screens, no token rotation, no shared personal account. Self-provisioning is the baseline for autonomous operation. If your agent can't set up its own communication channel, it's not really autonomous.

Isolation matters just as much. If your agent sends a poorly worded email or triggers a spam complaint, that shouldn't poison your personal domain reputation or flood your inbox with bounces. The agent's email identity should live in its own space, separate from yours.

Most email tool tutorials only demonstrate outbound sending. Real agents need to receive email too: verification codes from services they sign up for, confirmation links, replies from people they contacted. Gmail API can poll for incoming mail, but you're right back to OAuth and rate limits for every inbox check.

There's also a security dimension most developers overlook. Email is an attack vector. When your agent reads inbound messages and acts on the content, a malicious sender can embed prompt injection instructions in the email body. Raw Gmail API gives you message content with zero analysis of what's safe for an LLM to process.

Wiring agent-first email into your ADK tool#

Instead of pointing your tool function at Gmail API, you can use email infrastructure that was built for agents from the ground up. Here's what that looks like with LobsterMail as the backend:

import os
import requests

LOBSTERMAIL_TOKEN = os.environ["LOBSTERMAIL_TOKEN"]
INBOX_ID = os.environ["LOBSTERMAIL_INBOX_ID"]

def send_email(to: str, subject: str, body: str) -> dict:
    """Send an email from the agent's own inbox."""
    resp = requests.post(
        f"https://api.lobstermail.ai/v1/inboxes/{INBOX_ID}/send",
        headers={"Authorization": f"Bearer {LOBSTERMAIL_TOKEN}"},
        json={"to": to, "subject": subject, "body": body},
    )
    return resp.json()
Register it the same way you would any ADK tool:

from google.adk.agents import LlmAgent

agent = LlmAgent(
    model="gemini-2.5-flash",
    name="email_agent",
    instruction="You are an assistant that can send and receive emails.",
    tools=[send_email],
)

No OAuth flow. No token refresh logic. The agent gets its own address (like your-agent@lobstermail.ai), its own sender reputation, and its own inbox for receiving replies. Inbound emails come with injection risk scoring so the agent knows which messages are safe to act on.

The inbox creation can be part of the agent's startup logic, too. Using the LobsterMail SDK, the agent pinches its own address on first run and stores the credentials for future sessions. No human touches anything.

Deploying to Vertex AI Agent Engine#

Once your email tool works locally with adk web, deploying to Vertex AI follows the standard ADK pattern:

from vertexai.preview.reasoning_engines import AdkApp, ReasoningEngine
import vertexai

vertexai.init(project="your-project", location="us-central1")

app = AdkApp(agent=agent)
remote_app = ReasoningEngine.create(app)

The difference from a Gmail-based tool: you don't need to bundle OAuth credentials or manage token storage on the remote instance. An API token in an environment variable is all your tool function needs. Vertex AI handles the compute. Your email tool makes stateless REST calls.

This also simplifies testing. The same tool function runs identically on your laptop and in production. No "works locally but fails on Vertex AI because the OAuth redirect URI doesn't match" debugging sessions.

Choose the right email backend for your agent#

Google ADK is a solid framework for building tool-using agents. The function-as-tool pattern is clean, Vertex AI deployment is well-documented, and Gemini handles tool-calling reliably. Where it gets messy is when you bolt on email infrastructure that expects a human in the loop.

If your agent sends a handful of internal notifications during development, Gmail API works fine. If your agent needs its own email identity, sends and receives at any real volume, or runs on Vertex AI without a human on call to fix authentication failures, point your tool function at something that doesn't require any of that.