Google Service Account Authentication

The pinned setup omits required API enablement and Workspace scope authorization. Its run path is stale, and its environment guard checks only the service-account file even though Gmail requires GOOGLE_DELEGATED_USER. Complete the generated setup and use the generated run command below.

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/google_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
        )

Run the Example

Set up your virtual environment

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

uv venv --python 3.12
.venv\Scripts\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"

$Env:GOOGLE_DELEGATED_USER="your_google_delegated_user_here"
$Env:GOOGLE_SERVICE_ACCOUNT_FILE="your_google_service_account_file_here"
$Env: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

Examples

Primitives

Context

Models

Tools

More

Google Service Account Authentication

Run the Example

​Run the Example

Run the Example