feat: add DB-backed OAuth token storage for Google toolkits

[Mustafa-Esoofally]

Summary

Persist Google OAuth tokens in the agent's database. Tokens survive server restarts and load automatically on subsequent runs.

Usage

Simple mode — save token to DB

from agno.agent import Agent
from agno.db.sqlite.sqlite import SqliteDb
from agno.tools.google.gmail import GmailTools

agent = Agent(
    tools=[GmailTools(store_token_in_db=True)],
    db=SqliteDb(db_file="tmp/agent.db"),
)
agent.run("check my email")

First run opens a browser for OAuth. Token saves to DB only (not token.json). Next run loads from DB — no browser needed.

GoogleAuth mode — multi-toolkit with consolidated scopes

from agno.tools.google.auth import GoogleAuth
from agno.tools.google.calendar import GoogleCalendarTools

google_auth = GoogleAuth()
agent = Agent(
    tools=[
        google_auth,
        GmailTools(google_auth=google_auth),
        GoogleCalendarTools(google_auth=google_auth),
    ],
    db=SqliteDb(db_file="tmp/agent.db"),
)

GoogleAuth consolidates scopes across toolkits. When no token exists, the agent returns an OAuth URL for the user to visit (designed for Slack/WhatsApp interfaces).

Default — unchanged

agent = Agent(tools=[GmailTools()])  # file-based token.json, same as before

Flow

agent.run("check email", user_id="alice")
  │
  ├─ get_tools() auto-wires: toolkit._db = agent.db
  │
  ├─ model calls get_latest_emails()
  │   └─ @google_authenticate decorator
  │       └─ _auth(user_id="alice")
  │           │
  │           ├─ load_token() → DB lookup by (provider, user_id, service)
  │           │   ├─ found + valid → use cached creds ✅
  │           │   ├─ found + expired → refresh via refresh_token → re-persist ✅
  │           │   └─ not found → continue below
  │           │
  │           ├─ GoogleAuth mode: raise PermissionError → agent returns OAuth URL
  │           └─ Simple mode: file-based OAuth → browser → save to DB
  │
  └─ Gmail API call with valid credentials

Token refresh

Users authenticate once. Expired tokens auto-refresh:

1. load_token() → DB lookup → creds.expired = True
2. creds.refresh(Request()) → Google returns new access_token (~200ms)
3. save_token() → updated token persisted to DB
4. No user interaction needed

DB schema

CREATE TABLE agno_auth_tokens (
    id         VARCHAR PRIMARY KEY,  -- deterministic: "provider:user_id:service"
    provider   VARCHAR NOT NULL,     -- "google"
    user_id    VARCHAR,              -- nullable, from agent.run(user_id=...)
    service    VARCHAR NOT NULL,     -- "google" (consolidated across all Google APIs)
    token_data JSON NOT NULL,        -- serialized Google Credentials
    granted_scopes JSON,
    created_at BIGINT NOT NULL,
    updated_at BIGINT
);

Schema follows the codebase pattern: id as PK (like sessions, memories), user_id nullable (like all other tables), BigInteger timestamps.

Files changed

Layer	Files
DB schema + CRUD	base.py, postgres/schemas.py, postgres.py, async_postgres.py, sqlite/schemas.py, sqlite.py, async_sqlite.py
Migration manager	migrations/manager.py
Auth helpers	tools/google/auth.py — load_token, save_token, get_token_db, GoogleAuth toolkit
Google toolkits	gmail.py, calendar.py, drive.py, sheets.py, slides.py — store_token_in_db flag, _db attribute
Auto-wiring	agent/_tools.py, team/_tools.py — binds agent.db to toolkit _db
Cookbooks	gmail_with_db.py, google_workspace_agent.py, google_auth_db_storage.py, + DB examples in existing cookbooks

Type of change

• New feature

Checklist

• Ran format/validation scripts
• Both sync and async DB implementations
• Backward compatible — file-based OAuth unaffected
• E2E tested with real Gmail API
• Cookbooks included

[Mustafa-Esoofally]

Design Review — DB-Backed OAuth Token Storage

Inline comments explain the architecture decisions for each layer. Summary of the design:

Architecture Layers

┌─────────────────────────────────────────────────────────┐
│ Agent._tools.py — auto-wiring (DB → toolkit._db)        │
│   Guards: sync BaseDb only, must override get_auth_token │
├─────────────────────────────────────────────────────────┤
│ auth.py — decorator + helpers                            │
│   @google_authenticate: RLock, run_context, user_id     │
│   google_auth_or_raise: two-mode (GoogleAuth vs simple) │
│   google_auth_save_to_store: persists after file auth   │
├─────────────────────────────────────────────────────────┤
│ GoogleAuth toolkit — coordinator + OAuth callback        │
│   load_token/store_token: DB CRUD + auto-refresh        │
│   handle_oauth_callback: code→creds→store               │
│   get_oauth_router: FastAPI endpoint                     │
├─────────────────────────────────────────────────────────┤
│ DB layer — BaseDb stubs + Postgres/SQLite implementations│
│   Composite PK: (provider, user_id, service)            │
│   Upsert with ON CONFLICT DO UPDATE                     │
│   Token consolidation: service="google" for all APIs    │
└─────────────────────────────────────────────────────────┘

Two Auth Modes

GoogleAuth mode (interfaces — Slack, WhatsApp):
GoogleAuth() + google_auth= on toolkits + agent.db
→ No token? PermissionError → agent returns OAuth URL → callback stores token

Simple mode (single toolkit):
GmailTools(store_token_in_db=True) + agent.db
→ No token? Fall through to browser OAuth → saves to BOTH file + DB

Token Refresh (no re-auth needed)

1. First auth: user consents → access_token + refresh_token → stored in DB
2. Token valid (~1hr): load_token() → return immediately
3. Token expired: load_token() → refresh(Request()) → re-persist → return
4. Refresh tokens don't expire unless revoked

Known Limitations

• Async DB: Auto-wiring skips AsyncBaseDb — sync PostgresDb works in all contexts (async tools use asyncio.to_thread)
• State param: Base64-encoded, not HMAC-signed (follow-up for CSRF protection)
• Shared instance: Creds cached on shared toolkit object — follow-up PR adds per-request clone()

[Mustafa-Esoofally]

Auto-wiring: Runs during tool resolution (before any tool call). Sets toolkit._db = agent.db so the auth helpers can read/write tokens.

Guards:

• isinstance(agent.db, BaseDb) — skips AsyncBaseDb (auth helpers are sync-only)
• type(db).get_auth_token is not BaseDb.get_auth_token — skips DBs that don't implement token storage
• tool._db is None — won't overwrite explicit db= on GoogleAuth

[Mustafa-Esoofally]

Three helpers:

• get_token_db — resolves DB from GoogleAuth._db or toolkit._db (store_token_in_db mode)
• load_token — DB read + auto-refresh expired tokens + re-persist
• save_token — DB write with deterministic id

user_id flows from run_context (injected by framework). None when no user_id set on agent.

[Mustafa-Esoofally]

Schema matches codebase pattern: id as PK (like sessions, memories, learnings), user_id nullable (like all other tables). id is deterministic from provider:user_id:service so upserts use ON CONFLICT (id).

[Mustafa-Esoofally]

Callback security:

• Google error params surfaced (not hidden as "missing code")
• store_token returns bool — callback fails if DB write fails
• Services validated against registered allow-list before HTML rendering
• All output HTML-escaped

Known limitation: state is base64 JSON, not HMAC-signed (follow-up for CSRF).

[Mustafa-Esoofally]

Auth priority in each toolkit's _auth():

1. self.creds already valid → return
2. Service account → never stored in DB
3. load_token() → tries DB (GoogleAuth mode or store_token_in_db mode)
4. GoogleAuth + DB but no token → PermissionError (agent returns OAuth URL)
5. File-based OAuth → browser opens
6. After auth: save_token() → DB only. File written only if no DB path.

[Mustafa-Esoofally]

Why signature override: @wraps sets wrapped which makes inspect.signature follow to the original function. Without the override, the framework would not see run_context in the signature and would not inject it. The override preserves the original typed params (for LLM schema) and adds run_context (for framework DI). run_context is stripped from the LLM schema at function.py:660-671.