Connect a Google account for agents to work with Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts and Tasks.
Agents work with the account's email, calendars, files, contacts and tasks, as the person who signs in. Every request goes to Google live; the only thing kept is a copy of a Drive file before an agent first changes it, as under Version history. One sign-in covers Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts and Tasks, and one connection holds them all. Gmail needs no app password, so it works for accounts that can't make one.
Before you start: a Google Cloud OAuth client
Hosted Personal Agent Proxy has its own Google client, so skip to Connect Google. A self-hosted Personal Agent Proxy needs one of its own, made in a Google Cloud project you own. Google's console changes its layout from time to time; the names below are the ones it shows today.
Use the client from Google sign-in
If you set up Google sign-in, use the same client. Otherwise, in the Google Cloud console, create an OAuth client ID of the type Web application.
Add the redirect URI
Under Authorized redirect URIs, add your Personal Agent Proxy's address followed by
/api/connections/google/callback, beside the one sign-in uses:
https://proxy.example.com/api/connections/google/callbackGoogle takes redirect URIs on https:// with a real domain, or on http://localhost. A LAN
address, such as http://192.168.1.20 or http://nas.lan, won't register.
Enable the APIs
Enable the Gmail API, Google Calendar API, Google Drive API, Google Sheets API, Google Docs API,
Google Slides API, People API and Google Tasks API in the client's project. This link
asks for the project and enables all eight. The Docs and Slides APIs are only used to edit a
document's or a presentation's text in place, as under Editing in place; a
project without them has everything else, and those tools answer with the link enabling them. They
take the same drive scope as the rest of Drive, so no scope is added for them.
Add the scopes
On the Data Access page, Add or remove scopes and add these, the ones a sign-in asks for:
openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.events.freebusy
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/contacts
https://www.googleapis.com/auth/contacts.other.readonly
https://www.googleapis.com/auth/tasksChoose the audience
On the Audience page, the user type and publishing status decide who can connect and for how long:
- A Google Workspace organization. Choose the user type Internal. Everyone in the organization can connect, with every scope, without verification, a user limit or a warning.
- A gmail.com account, or anyone outside one organization. Choose the user type External, then Publish app so the status reads In production. Don't submit it for verification. Signing in shows "Google hasn't verified this app"; the person clicks Advanced and continues. That is expected on a self-hosted Personal Agent Proxy for a handful of people: Google allows 100 such users per project, for the life of the project.
Never leave the app in Testing. Google ends every sign-in, refresh token included, 7 days after consent, whatever the scopes, and the connection stops working until the person signs in again.
Set the variables
If they aren't set already for sign-in:
GOOGLE_CLIENT_ID="…apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="…"Cloud projects made since May 2026 have Google's standard quotas, far above what a few people use, except Gmail's: each account gets 6,000 units a minute, and a page of 50 emails costs about 1,000 of them, since each email in it is asked for on its own. An agent paging through more than a few lists a minute is told the provider could not be reached, and can try again a minute later.
Connect Google
Sign in with Google
Open Connections and permissions, then Add connection, and Sign in with Google. Connecting another Google account makes another connection; signing in again with the same account gives its connection new tokens and keeps its settings.
Approve access
Google's consent screen lists every permission Personal Agent Proxy asks for, and the person can untick some. An action whose permission was unticked is unavailable to every agent, marked "Not allowed at sign-in", until the person signs in again from the connection's page. A connection made before an action joined, such as Calendar, Contacts, who is free, other contacts or Tasks, has that action marked the same way, until it is signed in again.
Review the defaults
A new connection gives agents nothing, as a new mailbox gives agents no access to its email. The connection's page shows the actions under Gmail, Calendar, Drive, Contacts and Tasks, each saying how many are on, with Enable all above them, or Disable all once every one is on. Turn actions on or off for every agent there, or only for one agent on the agent's page. A line above the permissions says what that means for the account: what is ticked is what agents can read and do with it.
What agents can do
Agents see Gmail as one list, the newest first, 50 to a page: all mail but Spam and Trash, as
Gmail's All Mail is, or one folder of it, the inbox, drafts, sent mail, the archive, Trash or Spam.
A search is Gmail's own, as in its search box, such as from:sam has:attachment newer_than:7d. You
can allow each action separately:
- Read email lists, opens and searches email. An email opens as its text, or its HTML as text where it has none, with its attachments listed. Each comes with its link in Gmail, in this account, for the agent to give you; a draft's opens it to be written. An attachment is read as text: a spreadsheet's tabs as CSV, a PDF's or a Word document's text, a forwarded email, or a text file as it is, the first 100,000 characters of it. Images and other files can't be read, but any attachment can be made a blob, to put in a drive or attach to another email.
- Mark read or unread, Star, Archive and Move email to Trash act on messages in the inbox, and require Read email. Archived email stays in All Mail, and Gmail keeps Trash 30 days before deleting it; nothing is deleted for good.
- Label puts the account's own labels on email and takes them off, in any folder, and requires
Read email. A label is named as Gmail shows it, a nested one with slashes, such as
Clients/Acme; putting on a label the account has none of makes it. Taking a label off leaves the label, and the email, where they are. Gmail's own labels, such as Inbox, Starred and Unread, are only changed by the actions above, and drafts aren't labelled. With Read email alone, agents list the account's labels and see those on an email they open, and a search such aslabel:receiptsfinds the email under one. - Write drafts creates, edits and deletes drafts, and requires Read email. A draft takes a Cc and a Bcc beside its To, and an edit can change them. An edit keeps the draft's thread, and its formatting while its text is unchanged; text written anew goes out as plain text. A draft keeps the attachments it has when it is edited. Received messages are never edited or deleted. A reply to an email is saved as a draft in its thread.
- Send sends a new email or a saved draft from the account's own address, and Gmail files it in Sent. It does not require Read email, so an agent can send without seeing the mailbox. Sending a reply needs Read email too, since it reads the email it answers.
- A draft, a reply or an email sent at once goes out with the files the agent attaches, by naming blobs it made: another email's attachment, to forward it, a file from Drive, or a file from its own shell. They go out under their own names, 25 MB together at most, as Gmail takes.
A reply goes to whoever the email asks replies to go to, else its sender, or, for an email you sent, to whom it went, under the email's subject with "Re:", in the email's thread in Gmail. A reply to all also goes to everyone else the email went to and copies whom it copied, never the account itself. An email opens with its Message-ID and its Gmail thread, and a reply says its own id and thread, so an agent can check it landed in the conversation.
For Calendar, agents see the calendars in the account's list, the primary one first, and inside
each its events from now on, the soonest first, 50 to a page, each time a repeating event comes
round its own. A search is Google's, in titles, descriptions, locations and guests; one that begins
with a day, such as 2026-10-15 standup, lists from that day on, earlier days too. Times read
with their offset, 2026-10-15T14:00:00+02:00, and an all-day event as its first and last day.
- Read events lists, searches and opens events: their times, location, description, guests and their answers, the organizer, the video call and whether they repeat.
- See when people are free checks when the account and the people named, by their addresses, are busy, as Google's free/busy says, without what they are doing, and answers the times all of them are free, nights included. It doesn't require Read events. It checks from the time given to the time given, from now and for a week where they are left out; a time is written as an event's is, and a day alone is the whole day. Every time is answered on the primary calendar's clock. Someone whose calendar the account can't see, as is usual outside a Google Workspace organization, is said to be so rather than free, and the free times say they leave them out.
- Create and edit events makes events in a calendar the account can edit, the primary one
unless another is named, and changes their title, times, location and description, and requires
Read events. A time is written as
2026-10-15T14:00, on the calendar's clock, or with an offset; a day alone makes an all-day event. Without an end an event lasts an hour, or the day, and a start moved without a new end keeps the event as long as it was. An event made or changed without guests tells no one. - Invite guests adds guests to events and lets an agent change an event that has guests, and requires Create and edit events. Google emails the guests the invitation and every change, as Google Calendar does, so an agent with Create and edit events alone can't touch an event someone else is invited to.
- Answer invitations accepts or declines an event someone else invited the account to, or answers maybe, and requires Read events. Google tells the organizer.
Events are never deleted.
For Drive, Docs, Sheets and Slides:
- Read files browses and searches Drive and opens files. At the top are four places: My Drive,
Shared with me, Shared drives and Recent. My Drive, folders and shared drives list their files
folders first, Shared with me the last shared first, and Recent the files the account opened,
in shared drives too, the last opened first, 50 to a page; trashed files are never listed. A
search looks for words in file names and contents, anywhere in Drive, or among the files in the
folder opened. A document opens as Markdown and a presentation as text, as Google exports them,
up to Google's limit of 10 MB; past it, the content says the file is too large, and the file can
still be renamed or moved to Trash. A spreadsheet opens into its tabs, and a tab into its rows,
50 to a page, each row's values as
Header: valuelines, the headers from the tab's first row; a header used twice, or a column without one, goes by its column's letter,Status (E). Other files, shortcuts included, open as their name, kind, owner, last change and link. - Create files makes folders, documents and spreadsheets in My Drive, a folder or a shared
drive, uploads other files, such as PDFs and pictures, copies files into them, and adds rows to a
spreadsheet's tabs, and requires Read files. A document is written as Markdown and a spreadsheet
as CSV, and Google converts them as they are uploaded. Any other file goes up as its bytes
from a blob, as under Putting files in Drive.
Copying is done by Google, so a file of any size already in Drive is copied into a folder, a
shared drive or My Drive, under its own name or a new one; folders aren't copied. A row is
written as
Header: valuelines, under the headers of the tab's first row, and goes after the last row holding anything, from column A. - Edit files renames files and a spreadsheet's tabs, and changes rows, and requires Read files. A file's content is never written over whole: a document replaced from Markdown would lose its comments, suggestions and formatting, so a content written differently from how it read is refused, and renaming a file leaves its content alone. Shared drives aren't renamed or trashed. A row changes only in the values written differently, so a formula in another of its cells stays. It also edits a document's and a presentation's text in place and inserts and deletes a spreadsheet's rows, columns and tabs, as under Editing in place; puts a blob's bytes over a file of its own bytes that is there; gives a file an earlier version back; and undoes a change to a spreadsheet's cells, as under Putting files in Drive and Version history.
- Move files to Trash moves files and folders to Drive's Trash, where Drive keeps them 30 days before deleting them, and requires Read files. Nothing is deleted for good.
Agents can also read and write a range of a spreadsheet, in A1 notation with its tab, such as
'Q1 Sales'!A1:F20, given the spreadsheet's link or id, which covers tabs without a header row.
A range without a tab is in the first one. Reading needs Read files and answers the values as
Sheets shows them, as CSV, one row a line, 1000 rows at most, or, with Formulas, each cell's
formula as it was typed in, =SUM(B2:B9), and a cell without one as its value unformatted.
Writing needs Edit files and takes CSV the same way, each value as if typed into its cell, so
=SUM(B2:B9) is a formula, and "" empties a cell; it answers what the range holds afterwards,
as formulas with Formulas.
Editing in place
A Doc, Sheet or Slides file is never written over whole, from Markdown, CSV or an Office file, which would drop its comments, suggestions and whatever the format can't hold. Agents edit a document's and a presentation's text in place instead, through Google's Docs and Slides APIs, keeping its comments, suggestions, formatting and layout, and a spreadsheet's structure through the Sheets API. Reading needs Read files; every edit needs Edit files.
- Read document text,
docs_read, answers a document's text as the Docs API has it, paragraph by paragraph, the paragraphs in tables' cells too, and the revision the document is at. A document with several tabs is read in its first, or the one asked for by its title or id, and the answer lists the others. Its table of contents, headers, footers and footnotes are left out. An image or a chip in the text shows as. - Edit document,
docs_edit, takes the document, that revision and a list of edits. Each edit finds text that must appear exactly once in the textdocs_readanswers, case and all: in the tab the edit names, or, naming none, in the whole document, every tab of it. It then replaces it, writes text just before or after it, or styles it: bold, italic, underlined, linked, or its paragraphs made a heading, a title or normal text. Text found may run across paragraphs, but not across an image, a chip or a table's cells. An edit whose text appears nowhere, or more than once, is turned down saying how often it appears, and so is one finding the same text as another; then no edit is made. The edits are made together, in one change, only to the revision given: if the document changed since it was read, Google turns them all down, and the agent reads it again. Replaced text keeps the style of the text it replaces. - Read presentation text,
slides_read, answers a presentation's text, slide by slide, what its shapes and tables hold, and the revision it is at. - Replace text in presentation,
slides_edit, replaces text in a presentation, matched with its case, as Slides' find and replace does, only at the revision given, and answers how many times each text was replaced. As with a document, each text must appear exactly once, on the slide the replacement names or in the whole presentation, unless it says to replace every one; otherwise nothing is replaced, and the agent is told how often and on which slides it appears. - Insert or delete rows,
sheets_rows, inserts empty rows or columns into a spreadsheet's tab, at a row's number or a column's letter, or deletes them with what they hold. - Add or delete tab,
sheets_tabs, adds an empty tab after a spreadsheet's others, or deletes one with everything on it. A tab is renamed as a record, with the files tools.
Sheets deletes rows, columns and tabs by where they are, with no way to make a change only to the version an agent read, so a delete names a short checksum of what it takes away: its cells' values and formulas. A delete without it deletes nothing and answers what those cells hold and their checksum; the agent deletes them by asking again with it. Where the cells changed in between, as when someone inserted a row above them, the checksum no longer matches and nothing is deleted.
Each edit is a change in the file's Version history, with a copy kept before a task first changes the file. Rows, columns and tabs inserted or deleted have no exact undo: an agent reads what they took away in the copy, and you give the whole spreadsheet back from File > Version history.
Putting files in Drive
A file of its own bytes, a PDF, a picture, a video, a docx, goes into Drive as a
blob, the way files move between
connections: an email's attachment made one with attachments_blob, a file of another drive with
files_blob, or a file from the agent's shell sent to the URL pap.upload() gives. files_upload
puts the blob in Drive, in the folder or shared drive given, My Drive if it names none, or over a
file at the version given, checking that the agent may add files, or edit them to write over one,
and that the file is still at that version. A copy is kept first, as under
Version history, the bytes are sent on to Drive as they come, and the file is
logged in its history as the agent's, for its task. The agent is answered with its id, version and
link. A file can be as large as the server takes, 100 MB unless its FILES_MAX_MB says otherwise.
files_blob makes a blob of a file in Drive the other way: a file of its own bytes as it is, now
or at an earlier revision, and a Doc, Sheet or Slides file as Drive exports it, as pap files pull
below does.
A new file keeps its own type, as its name's extension says, such as report.pdf, or as the agent
says where the name has none. With convert, it becomes one of Google's own instead: a docx or
Markdown a Doc, an xlsx or CSV a Sheet, and a pptx a Slides file, named without the extension.
Over a file that is there, only a file of its own bytes takes bytes, of any type. A Doc, Sheet or
Slides file is never uploaded over, since it would lose its comments, suggestions and formatting:
the agent is pointed to editing it in place, or to uploading the file as a new
one.
The version a write is checked against is the file's head revision in Drive, which
files_versions says it is at now.
Version history
Personal Agent Proxy keeps its own history of the Drive files agents change, beside Drive's. Every change made through it, a file made, copied, renamed, written, moved to Trash, a document's or a presentation's text edited, a range or a row of a spreadsheet written, its rows, columns or tabs inserted, added or deleted, a tab renamed, is logged with who made it: the agent and the task it was for, or you, from the web app. Before a task first changes what a file holds, a copy is kept:
- a file uploaded to Drive, such as a PDF or a picture, as its bytes, to give back;
- a Doc as Markdown, a Sheet as an xlsx and a Slides file as text, as Google exports them, with Drive's revision it was taken of, for agents to read. A Doc, Sheet or Slides file is never given a version back by Personal Agent Proxy: Google's API can only write one over whole, which loses its comments, suggestions and what others changed since. An agent reads the version and makes the changes back in place, or you give it back from File > Version history in the file.
A copy is kept in the same store as Files (FILES_DIR or FILES_S3_BUCKET), up to
DRIVE_COPY_MAX_MB, 25 MB unless set otherwise. A larger file isn't copied: an uploaded file's revision is kept for good in Drive instead, and a Doc's,
Sheet's or Slides file's revision is only noted, for Drive's own version history (Google exports
at most 10 MB anyway). A copy the latest version holds already, the same revision or the same
bytes, isn't kept twice. Renaming a file or moving it to Trash leaves what it holds alone, and
takes no copy. Copies, the revisions kept for good in their place and the history of the changes
are all kept for good.
Writing a range or a row of a spreadsheet also keeps the cells it changes as they were and as it left them, formulas as formulas, up to 10,000 cells, so the change can be undone exactly.
- List versions,
files_versions, needs Read files: a file's versions, newest first, each kept here or only in Drive, and the changes made to it, who made each and for which task, with the version the file is at now in Drive, which an upload over it gives. - Read version,
files_version_read, needs Read files: what a version held, as text, 50,000 characters at a time: a Doc as Markdown, a Sheet's tabs as CSV, a Slides file's text, and an uploaded file where it is text, a PDF or an Office file. A Doc's, Sheet's or Slides file's version kept only in Drive is read in Drive's own version history. - Restore version,
files_restore, needs Edit files: gives an uploaded file a version back as its newest revision, keeping its id and link, from its copy, or downloaded from Drive where only Drive kept it. What the file held until then is kept as a version too. For a Doc, Sheet or Slides file the agent is told to read the version and make the changes back in place, or to have you give it back from File > Version history, picking the version from that time. - Undo change,
files_undo, needs Edit files: puts a spreadsheet's cells back as they were before a change, only while they still hold what it wrote; otherwise the agent is pointed to Read version.
You see the same history on the Google connection's page, under File history: the files changed through Personal Agent Proxy, the latest changed first, each with its last change and who made it. A file opens with its versions, each kept here or only in Drive, and its changes, each with the agent and the task it was for. Restore gives an uploaded file a version back and Undo puts a spreadsheet's cells back, each once you confirm, as your own change in the file's history. A Doc, Sheet or Slides file has no Restore: open the file and give a version back from File > Version history, picking the version from that time.
Files in a sandbox
An agent that also runs commands in a sandbox moves files between Drive
and the sandbox with pap files, as it does with Files.
A path starts at one of Drive's own places: My Drive/Reports/q3.pdf,
Shared drives/Research/plan.docx, or Shared with me/brief.pdf; pap files ls <connection>
lists the three. Drive lets two files in a folder have the same name, so where a name matches
more than one, pap says so and lists their ids, and the file is named with --id, which takes a
file's link too.
pap files pullbrings a file of its own bytes, a PDF or a picture, as it is, through Personal Agent Proxy as Drive sends it. A Doc comes as Markdown, a Sheet as an xlsx and a Slides file as a pptx, named with the extension, unless--asasks for another: a Doc asmd,docx,pdfortxt, a Sheet asxlsx,csvorpdf, a Slides file aspptx,pdfortxt. A Sheet as CSV is its first tab, or the one--tabnames. Google exports at most 10 MB of a file: past that, the agent is told to pull a PDF, or something smaller, as one tab.papnotes the file's id, the version it was at and what it was exported as.pap files pushsends a file back, as a blob put in Drive. A new file goes up as its bytes; with--converta docx or Markdown becomes a Doc, an xlsx or CSV a Sheet, and a pptx a Slides file. The folders on its way that are missing are made, as the agent's. Over a file that is there, the push names the version that was pulled, or is made with--force, and a copy is kept first, as under Version history. A Doc, Sheet or Slides file is never pushed over: the agent is pointed todocs_editfor a Doc's text,ranges_write,sheets_rowsandsheets_tabsfor a Sheet,slides_editfor a Slides file's text, or to push it as a new file with--convert. All of it is checked before any of the file is sent, so a push Drive would refuse sends nothing.
A pull is a read, a push to a new path an added file, and a push over a file an edit, each checked against what the agent may do and in the activity log as from a sandbox.
For Contacts, agents see the account's contacts in Google Contacts, the most recently changed
first, 50 to a page. A search is Google's, matching the start of a name, email address, phone
number or company, and answers the first 30 it finds. Emails and phone numbers are comma-separated,
addresses one a line, and a birthday is 1990-04-12, or 04-12 without the year.
- Read contacts lists, searches and opens contacts.
- Read other contacts lists, searches and opens the people Gmail keeps on its own under Other contacts: those the account emailed or was emailed by but never saved. Google keeps only their names, email addresses and phone numbers, and they are only read. With Add and edit contacts as well, an agent can save one, which copies it into Google Contacts as a contact of its own.
- Add and edit contacts adds contacts and changes their details, and requires Read contacts. An edit changes only the fields written differently, and an email, number or address still there keeps its label, such as work or home.
Contacts are never deleted.
For Tasks, agents see the account's task lists, and inside each its tasks in Google's own order,
subtasks and tasks assigned from Docs and Chat among them, 50 to a page: all of them, or only those
still to do or done. Tasks completed in Google Tasks, which it hides there, are listed as done. A due date is a day
alone, 2026-10-15, as Google Tasks keeps no time of day.
- Read tasks lists and opens task lists and tasks: their title, notes, due day, list, whether they are done and when, the task a subtask is under, and the email a task was made from in Gmail.
- Add and edit tasks adds a task at the top of a list, the default list unless another is named, changes its title, notes and due day, moves it to another list when that list's name is written, and completes or reopens it, and requires Read tasks. A subtask moved to another list goes to its top level; Google doesn't move a repeating task to another list.
Tasks and task lists are never deleted, and lists are only read.
Troubleshooting
redirect_uri_mismatchon Google's page: the client doesn't have the exact redirect URI. Add your Personal Agent Proxy's address, exactly asAPP_URLhas it, followed by/api/connections/google/callback.- "Access blocked: … has not completed the Google verification process", or a message that the app is being tested: the app is in Testing and the account isn't a test user. Publish it, as under Choose the audience.
- A connection stops working a week after connecting, and agents are told "The provider turned this connection's sign-in down": the app was in Testing. Publish it, then sign in with Google again with the same account.
- Connecting fails, and the api's log shows
invalid_clientin Google's answer: the client secret doesn't belong to the client. Copy both again from the client's page intoGOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET. - A run answers that an API "has not been used in project … before or it is disabled": enable that API from the link in the message, then try again a few minutes later.
org_internal: the client's user type is Internal, and the account isn't in the Google Workspace organization that owns the project.- "This email already has an account" is about signing in to Personal Agent Proxy with Google, not about connecting a Google account; see Sign-in.
Disconnecting
Deleting the connection revokes its tokens at Google. Google's grant is the account's for the whole client, so while another connection is for the same Google account, in any organization on the same Personal Agent Proxy, it is kept, and that connection goes on working. The person can also revoke Personal Agent Proxy's access from their Google account, at Third-party apps & services.