> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Drive and Sheets
> Connect Google Drive once for file workflows and native Google Sheets range operations
## Overview
The Google Drive integration gives configured agents access to Drive files and
shared drives. The same durable OAuth connection also authorizes native Google
Sheets tools for spreadsheet metadata, bounded ranges, cell edits, and creation.
There is no separate Google Sheets connection or token store.
Choose one authorization mode:
* **Each member connects:** tools use the acting member's Google account and
inherit that person's Drive and spreadsheet permissions.
* **Org service account:** an administrator connects one intentionally shared
Google account whose access is used by the organization's configured agents.
Both modes store refresh tokens server-side and refresh access tokens when
needed. If Google revokes a grant, reconnect Google Drive in Control Hub.
Choose an access level independently of the authorization mode:
* **Read only (recommended):** uses Google's `drive.readonly` grant. Agents can
search, list, inspect, read, export, and download Drive files and Google Docs,
and can read Google Sheets metadata and bounded ranges. Server-side policy
rejects create, upload, copy, move, edit, append, and clear operations.
* **Read and write:** uses Google's full `drive` grant and enables those
mutation workflows for agents that are also configured with mutation tools.
The runtime applies the stricter of the organization policy and the actual
OAuth token scope. Downgrading the policy blocks writes immediately; reconnect
to replace the previously broad Google grant with a read-only refresh token.
Upgrading also requires reconnecting before writes become available. In
per-user mode, each member reconnects their own account after an access-level
change.
## Setup
An organization admin opens **Control Hub → Integrations → Google Drive**,
selects the per-user or shared-account mode, chooses read-only or
read-and-write access, and completes Google OAuth.
Each member authorizes their own Google account. Agent calls then see only
files and spreadsheets that member can access.
Add only the Drive and Sheets tools the agent needs. Read, edit, and create
are separate capabilities so mutation access can be withheld.
Use a dedicated non-sensitive test spreadsheet. Read metadata first, make a
narrow write, verify the returned range and cell count, and test clear only
against a disposable explicit range.
## Native Google Sheets tools
| Tool | Capability |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `google_sheets_read` | Returns spreadsheet/tab metadata and up to 20 bounded A1 ranges in one call. Supports formatted values, raw values, formulas, and date/time rendering. |
| `google_sheets_edit` | Applies an ordered array of explicit `write`, `append`, and `clear` operations to an existing spreadsheet. |
| `google_sheets_create` | Creates a new spreadsheet with optional initial tabs and bounded initial data. |
All three tools require the Google Drive integration (`google_drive`). They do
not add a Sheets OAuth card, alter Clerk login, delete spreadsheets, or delete
tabs.
In read-only mode, `google_sheets_read` is available while
`google_sheets_edit` and `google_sheets_create` fail before sending a mutation
to Google. Tool selection still provides a second layer of control: omit
mutation tools from agents that should never request them, even in an
organization with read-and-write Drive access.
## Read behavior and limits
Omit `ranges` from `google_sheets_read` to inspect only the spreadsheet and tab
metadata. With ranges, use bounded A1 notation such as `'Revenue 2026'!A1:F100`.
Whole-row and whole-column ranges are rejected so a call cannot accidentally
load an arbitrarily large workbook.
* A request accepts at most 20 ranges covering at most 50,000 addressable cells.
* Output defaults to at most 10,000 non-empty cells and 100,000 text characters.
* Results report whether they were truncated and how many returned cells were
omitted. Read smaller ranges to continue.
* `formatted` returns the display value and is the default. `raw` returns the
underlying unformatted value. `formula` returns formula expressions where
present. Date/time output can be serial numbers or formatted strings for
raw/formula reads; Google ignores that choice for formatted reads.
* Empty ranges return an empty values array with `empty: true`.
For a whole-workbook copy, `google_drive_download_file` exports XLSX. The Drive
text reader can export the first tab as CSV. These remain better fits for file
download workflows; Sheets-native reads are designed for selected tabs and
ranges.
## Edit safety and concurrency
Every `google_sheets_edit` call requires a spreadsheet ID and an operations
array. Every operation requires a bounded, tab-qualified range. The tool
validates operation shapes, tab names, grid bounds, row/column/cell counts, and
serialized payload size before the first mutation.
* `write` stores a two-dimensional value matrix inside the exact range.
* `append` uses the explicit range to locate a table and inserts supplied rows
after it.
* `clear` removes values only; formatting and data validation remain.
* Input defaults to `raw`, which stores strings literally. Select
`user_entered` only when Sheets should interpret formulas, dates, or numbers
as if a person typed them.
Compatible consecutive writes or clears use Google batch APIs. Operations still
run in the supplied order, but a call that mixes write, append, and clear API
endpoints is not fully transactional: an earlier group remains applied if a
later group fails. Every operation receives a success, error, or not-executed
result.
For best-effort optimistic concurrency, pass `expected_modified_time` from a
prior read. The edit is rejected before mutations if the Drive modification time
has already changed. This preflight comparison is not an atomic spreadsheet
lock; collaborators can still edit after the check.
## OAuth scopes
Aster does not request a Sheets- or Docs-specific scope. Google's
[Sheets scope table](https://developers.google.com/workspace/sheets/api/scopes)
and official
[`values.get`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get)
and
[`values.update`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update)
method references document the Drive scopes used by this integration:
* `https://www.googleapis.com/auth/drive.readonly` authorizes spreadsheet
metadata and value reads, as well as Drive file reads.
* `https://www.googleapis.com/auth/drive` authorizes spreadsheet creation and
value writes, appends, and clears, plus Drive mutation workflows.
The optional `drive.readonly` scope is introduced solely to offer a genuinely
read-only Drive connection. It does not change Clerk's Google login scopes and
does not create another OAuth client, connection card, or token store.
## Troubleshooting
Confirm the spreadsheet ID, exact tab name, and the connected account's
access. Quote tab names that contain spaces, such as `'Sales Plan'!A1:C20`.
Use a start and end cell, for example `Sheet1!A1:D100`. Whole columns such
as `A:D` and whole rows such as `1:100` are intentionally rejected.
Reconnect Google Drive in **Control Hub → Integrations**. In per-user mode,
the acting member reconnects their own account; shared mode uses the
administrator-selected shared account.
Share the spreadsheet with the connected Google account and ensure the
Google Sheets API is enabled on Aster's OAuth project. Protected ranges can
also reject an otherwise valid edit.
Retry after a short delay and split the request into fewer or smaller ranges
or operation batches.