Google Docs Integration for AI Agents

The real problem

Why this is harder than it looks

Most teams look at the Google Docs API and figure the integration is a weekend project. The read and write primitives are clean. The documentation is thorough. The problems start once you try to ship this for real users.

First, there's the OAuth app verification process. Google requires any application that requests Docs API scopes — https://www.googleapis.com/auth/documents — to go through a security review before it can be used by accounts outside your development workspace. Until that review clears, your OAuth consent screen displays an "unverified app" warning that users have to click through manually. For agents interacting with documents, that warning kills trust on the spot. The review takes time, requires a privacy policy and a working demo environment, and blocks production launch for an unpredictable window.

Then there's the scope selection problem. The Docs API and Drive API overlap — you can read and write documents through either, with meaningfully different consent screen footprints. Choosing documents scope without also understanding when you need drive.file or drive.readonly leads to either over-requesting permissions (flagged in review, rejected by cautious users) or under-requesting them (runtime 403s that look like auth bugs but are actually scope gaps). And if your agent's capabilities expand later, adding scopes requires a fresh OAuth authorization from every user who already connected — there's no way to silently widen the token.

In production, each user connects their own Google account. That means per-user token isolation, proactive refresh before expiry, and graceful handling when a user revokes your app from their Google account settings. Revocation doesn't generate a webhook — you discover it on the next API call, as a 401 with no helpful context. Handling all of this correctly, for an organization full of document-writing users, is a month of plumbing that has nothing to do with what your agent actually does.

Scalekit handles the token lifecycle, manages credentials per user, and detects revocation before it causes silent failures. Your agent names a tool and passes a document ID. Everything else is handled.

Capabilities

What your agent can do with Google Docs

Once connected, your agent has 3 pre-built tools for the full Google Docs document lifecycle:

• Create new documents: spin up a blank Google Doc with an optional title and get back the document ID for subsequent operations
• Read document content and structure: retrieve the full document tree — text content, paragraph formatting, tables, inline objects, named styles, and document metadata
• Update documents with batch operations: insert text, apply paragraph and text formatting, manage tables, and manipulate structure using Google's batchUpdate API, with optional write-control for revision safety

Jump to tool reference

Setup context

What we're building

This guide connects a writing assistant agent to Google Docs — helping team members create, read, and update documents without leaving your product.

Setup

¹ Setup: One SDK, One credential

Install the Scalekit SDK. The only credential your application manages is the Scalekit API key — no Google secrets, no user tokens, nothing belonging to your customers.

Connected Accounts

² Per-User Auth: Creating connected accounts

Each user gets their own Connected Account, giving them a dedicated auth context. The _identifier is any unique string from your system — a UUID, email, whatever you use internally.

This call is idempotent — safe to call on every session start. Returns the existing account if one already exists.

Authorization Flow

³ The authorization flow

The user authorizes your agent once. Scalekit generates the OAuth URL with correct scopes, PKCE challenge, and redirect handling pre-configured. After approval, you never see the token.

Calling Google Docs

⁴ Calling Google Docs: What your agent writes

With the connected account active, your agent calls tools using _{actions.execute_tool()}. Name the tool, pass parameters. Scalekit handles token retrieval, request construction, and response parsing.

Create a new document

Spin up a blank Google Doc with a title. The response includes the new document's ID — pass it to subsequent read or update calls.

Read a document

Retrieve the full content and structure of any Google Doc the user has access to. The response includes the complete document tree — paragraphs, tables, inline objects, named styles, and revision metadata. Use _{suggestions_view_mode} to control how tracked changes appear.

Insert text into a document

Update a document using Google's batchUpdate request format. Index ₁ places content at the very beginning of the document body — index ₀ is not a valid insertion point.

Apply paragraph formatting

Batch a style update alongside an insert. All requests in a single _batchUpdate call are applied atomically — if any request is invalid, none are applied.

Framework wiring

⁵ Wiring into your agent framework

Scalekit integrates directly with LangChain. The agent decides what to create or update; Scalekit handles auth on every invocation. No token plumbing in your agent logic.

Tool reference

Google Docs tools

3 pre-built tools covering the full document lifecycle. Your agent calls tools by name — no API wrappers to write.

Connector notes

Google Docs-specific behavior

Infrastructure decision

Why not build this yourself

The Google Docs OAuth flow is documented. Token storage isn't technically hard. But here's what you're actually signing up for:

That's one connector. Your agent product will eventually need Salesforce, Gmail, Slack, Notion, and whatever else your customers ask for. Each has its own OAuth quirks and failure modes.

Scalekit maintains every connector. You maintain none of them.