# Google Drive connector

When a user connects their Google Drive, your agent gets four read-only tools to list, search, read and download their files — on their behalf, with no configuration on your side.

## Overview

The Google Drive connector lets your agent work with files in a user's own Drive. The user authorizes ONBF **once** with Google's read-only Drive scope (`drive.readonly`); ONBF vaults and refreshes the OAuth token, and exposes four tools on the run's session token. You never register a Google app, request scopes or handle a callback — see **[Connectors](/docs/connectors)** for the zero-setup model.

> **Read-only, per-user:** This connector uses Google's `drive.readonly` scope: your agent can list, search, read and download the user's files, but never create, edit or delete anything. Access is the individual user's — granted and revocable from their ONBF dashboard.

## Tools

These four tools are exposed when the builder selects Google Drive under Required connectors and the run credential holds `connectors:use`. User connection status is checked when a tool runs.

| Tool | What it does | Key arguments |
| --- | --- | --- |
| `google_drive_list_files` | List the user's Drive files, most-recently-modified first. Returns `id`, `name`, `type`, `size` and a web link for each. | `pageSize` (optional, 1–100), `pageToken` (optional cursor). |
| `google_drive_search_files` | Search the user's Drive by a plain-text query (matches file names and full-text content). Returns matches newest-first with `id`, `name`, `type` and a web link. | `query`; `pageSize` (optional, 1–100), `pageToken` (optional cursor). |
| `google_drive_read_file` | Read the **text** contents of one file by its id. Google Docs export to plain text and Sheets to CSV; other text files return as-is. Large files are truncated. | `fileId` — an id from list/search. |
| `google_drive_download_file` | Download one file so the agent can process it **locally** (PDF, image, spreadsheet, archive, …). Returns a short-lived `downloadUrl` — NOT the bytes. | `fileId` — an id from list/search. `exportMimeType` (optional) — override the export format for Google-native files. |

## read_file vs download_file

Two tools return file data, and picking the right one matters. `google_drive_read_file` is for **text** you want inline — it returns the file's text content directly in the tool result (Docs as plain text, Sheets as CSV). `google_drive_download_file` is for **binaries** you need on disk — it returns a link, not the content.

> **download_file returns a URL, not bytes:** File bytes never ride through an ONBF Tool call. `google_drive_download_file` returns a short-lived, purpose-bound `downloadUrl`; fetch it with a plain HTTPS GET and no auth header. The user's Google token stays server-side and is never exposed to the agent.

Google-native files (Docs, Sheets, Slides) have no raw binary, so `google_drive_download_file` **exports** them automatically:

| Google-native type | Default export |
| --- | --- |
| Google Docs | PDF |
| Google Sheets | `.xlsx` (Excel) |
| Google Slides | PDF |

Pass `exportMimeType` to override the default (e.g. export a Doc as `text/plain` or a Sheet as `text/csv`). For ordinary binaries (PDF, PNG, ZIP, …) `exportMimeType` is ignored — you always get the original bytes.

> **There's a size limit:** Downloads are capped at 25 MB. Larger files return a clear error instead of a link — narrow the selection or prefer `google_drive_read_file` for text-heavy documents.

## Typical flow

- **Discover** — `list_connections` confirms the user has `google-drive` connected and returns the exact tool names.
- **Find the file** — `google_drive_search_files` (by query) or `google_drive_list_files` (browse), keeping the returned `id`.
- **Read or download** — for text, `google_drive_read_file` returns the content inline. For a binary, `google_drive_download_file` returns a `downloadUrl` to fetch over HTTPS.
- **Process it** — parse, summarize or transform the file, then deliver the result back to the user as a reply or an artifact.

## Access & consent

- **Read-only** — the `drive.readonly` scope never permits writes; the connector cannot modify the user's Drive.
- **Per-user & revocable** — each user connects their own account and can disconnect it anytime from their ONBF dashboard under **Connectors**.
- **Allowlisted by the builder** — the tools appear when Google Drive is selected under Required connectors and the credential has the needed scope. If this user has not connected Drive, calls return `{ connected: false, message }` — prompt them to connect, then retry.

> **See also:** The gateway model, discovery via `list_connections` and the `connectors:read` / `connectors:use` scopes are covered on **[Connectors](/docs/connectors)**.