Google Service Account Authentication

This example impersonates one configured Workspace user. Complete the API and domain-wide scope authorization below, and require both credential variables before running. It does not automatically route each Agno user to a different Google identity.

service_account.py

"""
Google Service Account Authentication
======================================

Server-to-server auth without user interaction. No OAuth consent flow needed.
Ideal for backend services, cron jobs, or multi-tenant apps.

When to use Service Account vs OAuth:
  - Service Account: Your server accesses Google APIs on behalf of users
  - OAuth: Users grant access to their own Google data interactively

Authentication (env vars):
  GOOGLE_SERVICE_ACCOUNT_FILE - Path to service account JSON key file
  GOOGLE_DELEGATED_USER       - Email of user to impersonate (required for Gmail)

Setup:
  1. Google Cloud Console -> IAM & Admin -> Service Accounts -> Create
  2. Download JSON key file
  3. For Gmail: Enable domain-wide delegation in Google Workspace Admin
     (Admin Console -> Security -> API Controls -> Domain-wide Delegation)
  4. Set GOOGLE_SERVICE_ACCOUNT_FILE and GOOGLE_DELEGATED_USER env vars

Run:
  .venvs/demo/bin/python cookbook/91_tools/google/workspace/service_account.py
"""

from os import getenv

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.google.auth import AuthConfig
from agno.tools.google.calendar import GoogleCalendarTools
from agno.tools.google.drive import GoogleDriveTools
from agno.tools.google.gmail import GmailTools
from agno.tools.google.sheets import GoogleSheetsTools

# ---------------------------------------------------------------------------
# Service Account Auth Config
# ---------------------------------------------------------------------------
# No OAuth consent needed — credentials come from the JSON key file.
# service_account_path and delegated_user are on AuthConfig

auth = AuthConfig(
    service_account_path=getenv("GOOGLE_SERVICE_ACCOUNT_FILE"),
    delegated_user=getenv("GOOGLE_DELEGATED_USER"),
)

agent = Agent(
    name="Workspace Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[
        GmailTools(auth=auth),
        GoogleCalendarTools(auth=auth),
        GoogleDriveTools(auth=auth),
        GoogleSheetsTools(auth=auth),
    ],
    add_datetime_to_context=True,
    markdown=True,
)

if __name__ == "__main__":
    if not getenv("GOOGLE_SERVICE_ACCOUNT_FILE"):
        print("Set GOOGLE_SERVICE_ACCOUNT_FILE and GOOGLE_DELEGATED_USER env vars")
    else:
        agent.print_response(
            "List my recent emails and today's calendar events", stream=True
        )

The default Gmail and Calendar toolkits also expose write operations. For a read-only service, use the explicit selections from meeting prep and authorize the scopes those instances request. The delegated user must be a Workspace user covered by the administrator's delegation, rather than an arbitrary Gmail account.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno google-api-python-client google-auth google-auth-httplib2 google-auth-oauthlib openai openpyxl python-docx python-pptx

Export environment variables

export GOOGLE_DELEGATED_USER="your_google_delegated_user_here"
export GOOGLE_SERVICE_ACCOUNT_FILE="your_google_service_account_file_here"
export OPENAI_API_KEY="your_openai_api_key_here"

Create the delegated service account

Enable the Gmail, Google Calendar, Google Drive, and Google Sheets APIs in the Google Cloud project. Create a service account, enable domain-wide delegation, and download its JSON key. See Delegating domain-wide authority.

Authorize the Workspace scopes

As a Workspace super admin, add the service account's numeric client ID under Security > Access and data control > API Controls > Manage Domain Wide Delegation. Authorize https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.modify, https://www.googleapis.com/auth/gmail.compose, https://www.googleapis.com/auth/calendar.readonly, https://www.googleapis.com/auth/calendar, https://www.googleapis.com/auth/drive.readonly, and https://www.googleapis.com/auth/spreadsheets.readonly.

Require the delegated user

Replace if not getenv("GOOGLE_SERVICE_ACCOUNT_FILE"): with if not getenv("GOOGLE_SERVICE_ACCOUNT_FILE") or not getenv("GOOGLE_DELEGATED_USER"): in the saved file.

Run the example

Save the code above as service_account.py, then run:

python service_account.py

Full source: cookbook/91_tools/google/workspace/service_account.py