gsuite-sdk guide: read Google Sheets with an agent and verify the summary

gsuite-sdk gives an agent a Python SDK and CLI for Google Workspace. It can read documents and also perform actions such as updating sheets, sending mail and managing events. Start with a smaller task: read a spreadsheet you created, summarize unfinished work, and check every item against the original.

This guide uses SDK 0.5.0 and the current official Skill. The exercise is a designed example, not a test against a real account. You need Python 3.11+, access to Google APIs, your own Google account, and Claude Code or Codex with local command execution. Attaching a Skill to a regular web chat does not supply a local CLI or Google authorization.

Understand the three layers

The Skill teaches the agent how to work. The gsuite-sdk[cli] package supplies the executable gsuite command. OAuth controls what that command can access for your account. Installing only the Skill does not connect Google.

The project also offers a Claude Code plugin with MCP and a REST API. Use Skill + CLI for this exercise; you do not need a server or a second MCP integration. This path is useful if you want to grow into Python workflows. For an occasional summary, exporting a sanitized sheet to your assistant can be simpler than configuring OAuth.

1. Install the CLI and Skill

Open a terminal in a dedicated practice directory. These virtual-environment commands are for macOS/Linux; on Windows activate the environment with .venv\Scripts\Activate.ps1 after creating it.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "gsuite-sdk[cli]==0.5.0"
gsuite --help

Your Python executable may be called python; verify that it is at least 3.11. The help output establishes that the CLI is available, not that Google authorization works.

Install the official Skill in the project where you will use your agent:

npx skills add PabloAlaniz/google-suite --skill gsuite-sdk

Choose your agent in the install picker, then open a fresh session. The agent must also be able to reach the Python environment. If a new terminal cannot find gsuite, reactivate the environment before attempting OAuth again. If you already use the official plugin, check its existing Skill rather than installing another copy.

2. Authorize the spreadsheet exercise

Create or select your own project in Google Cloud Console and enable Google Drive API and Google Sheets API. Configure the application's information and audience in Google Auth Platform. For an External application in Testing, add your account as a test user. Create a Desktop app OAuth client and download its JSON. This is neither an API key nor a service-account key.

Store it in a private location outside your source project. In the practice terminal, replace these sample paths:

export GSUITE_CREDENTIALS_FILE="/absolute/private/credentials.json"
export GSUITE_TOKEN_DB_PATH="/absolute/private/tokens.db"
export GSUITE_DEFAULT_TIMEZONE="America/Los_Angeles"
gsuite auth login --scopes drive,sheets
gsuite auth status

Complete sign-in yourself in the browser, checking the account, application name and permissions. If Google or your organization blocks access, resolve the configuration or policy problem first. This exercise does not need Gmail, Calendar, Tasks or Contacts. However, drive,sheets selects full Drive and Sheets permission sets: it is not read-only authorization. Running only read commands does not make the token read-only. Default login without a scopes argument also requests Gmail and Calendar.

The login token is stored in tokens.db. Keep the client file and token out of Git, websites and chats. Set these absolute paths in the agent's environment too. This type of External + Testing authorization can require sign-in again after seven days; that is separate from routine access-token refresh.

3. Create data with a clear answer

Manually create a Google spreadsheet, rename its worksheet tab to Tasks, and enter these four rows. A named tab avoids dependence on the account's localized default tab name.

Copy the spreadsheet URL. First read it directly in your terminal, replacing YOUR_SPREADSHEET_ID with the part between /d/ and /edit:

gsuite sheets read YOUR_SPREADSHEET_ID --sheet Tasks --range "A1:C4" -o json

--sheet selects the tab and --range selects cells within it. The range is an option, not a second positional argument. A nonempty result is an array of row arrays: three headers followed by three tasks. Check names, owners and statuses against the browser before introducing summarization.

In this version an empty range prints No data found rather than JSON []. A successful exit alone is not proof of usable data. In automation, validate the structure and required headers and handle empty data separately. Trailing empty cells can be omitted, so rows need not have equal lengths.

4. Ask the agent to summarize

In a Claude Code or Codex session with the Skill loaded and the virtual environment accessible, try this example:

Use gsuite-sdk to read this test spreadsheet: [paste URL].
Read only Tasks!A1:C4. Check the three headers and three tasks first.
Do not write, send, share or delete anything.
List unfinished tasks grouped by owner, preserving task names and raw statuses.
State which tab and range you read. Stop and explain if reading fails or data is missing.

For the sample, the unfinished list should contain Signup form (Bo, doing) and Release notes (Ana, todo). Landing page must be excluded. This is an acceptance criterion derived from the exercise data, not a guaranteed model response. Verify the range, two tasks and two owners before expanding to real documents; the agent saying “done” is not a substitute for checking.

Extend the workflow deliberately

Weekly project updates: expand to the actual task range and define which statuses count as unfinished and the reporting cutoff. Preserve raw statuses and list missing owners or dates separately. Reading a summary and writing a revised plan are two distinct tasks: review first, then decide whether to update the sheet.

Python processing: fixed formats, validation and repeated jobs are easier to control in code. Open by ID and explicitly select the worksheet:

from gsuite_core import GoogleAuth
from gsuite_sheets import Sheets

doc = Sheets(GoogleAuth()).open_by_key("YOUR_SPREADSHEET_ID")
ws = doc.worksheet("Tasks")
if ws is None:
    raise ValueError("Tasks worksheet is missing")
rows = ws.get("A1:C4")
print(rows)

Run under the same environment variables. open(title) opens by title; open_by_key(id) opens by ID. Values from get_all_records() are strings, so monetary calculations need explicit handling of formatting and missing values.

Writing and sharing: make these separately confirmed tasks. Show the target file, worksheet, range and proposed values before applying them. SDK update and append_rows accept two-dimensional lists: even one cell is [["done"]]. Importing CSV can replace data rather than append. Sending mail, inviting attendees and sharing files also affect people outside the conversation.

Troubleshoot the right layer

A 403 may reflect file permissions or a disabled API as well as a missing scope. Do not immediately expand authorization to all. When adding a service, enable its API, understand its permissions, and reauthorize with --force --scopes ... as needed.

Where your data goes

The local CLI uses your OAuth token to call Google. Data read by the agent may also enter the model provider's conversation, so a local command does not mean an offline workflow. Practice with a test sheet and follow your organization's rules for real data. This exercise needs neither gsuite serve nor a publicly exposed REST endpoint.

This guide focuses on the 0.5.0 spreadsheet task; the Skill covers other Workspace services too. It is a third-party project, not an official Google product, and does not supply unlimited API quota. Choose it when you want a Python path beyond the CLI. For a different terminal-oriented office workflow, see the GOG guide; its commands, authorization and token storage are separate.