How to Connect an AI Agent to Google Workspace: Permissions, Limits, Real Cases
· CompaniesAutomation
Gmail, Calendar, Drive and Sheets as the agent's working surface: the three OAuth connection routes, the scopes you should never request, and the real limits.
Connecting an AI agent to Google Workspace means giving it controlled access to Gmail, Calendar, Drive, Docs and Sheets so it works where your team already works: reading the shared inbox, searching the proposals folder, booking in the real calendar and updating the tracking sheet. It is not a chatbot that "knows about" your company; it is an operator with credentials, scoped permissions and a log of everything it touches.
Workspace is probably the best first surface for an internal agent, because it holds context no new tool has: the client threads, the live documents and the diary. We run this on our own domain, so what follows is what works, what costs more than expected, and what you should never hand over.
What can an agent do across Google Workspace?
It can read, write and act in each application with exactly the scope you grant a person. The practical difference is that it never tires of the repetitive work and leaves a trail on all of it.
| Application | What it handles well | What needs supervision |
|---|---|---|
| Gmail | Triage, summarising long threads, drafting replies, extracting data from inbound mail, flagging what is urgent | Sending to clients unreviewed in the first weeks |
| Calendar | Checking real availability, booking, rescheduling, prepping meetings with context | Cancelling other people's meetings or moving executive time |
| Drive and Docs | Searching thousands of documents, drafting proposals from templates, summarising contracts | Deleting or moving files; always create new versions instead |
| Sheets | Reading and writing trackers, consolidating data from several sources, producing recurring reports | Overwriting sheets that feed management reporting |
| Chat and Meet | Answering internal questions, summarising meetings and assigning follow-ups | Posting in channels shared with external clients |
The value shows up in the combination. An agent that only reads Gmail is a summariser; one that reads the email, finds the contract in Drive, checks the slot in Calendar and records the outcome in Sheets has completed an entire process end to end.
How does it connect, technically?
Three routes exist, and choosing the wrong one is the most expensive mistake in these projects because it forces you to redo the security model. All of them use OAuth 2.0; what changes is who holds the access.
| Route | When to use it | Hidden cost |
|---|---|---|
| Per-user OAuth | The agent acts on behalf of one specific person, who authorises from their own account | Every user has to authorise; tokens expire and need renewal |
| Service account with domain-wide delegation | The agent works across multiple mailboxes or calendars without user involvement | Needs a super admin and, where multi-party approval is enabled, a second admin to confirm |
| Dedicated shared mailbox or drive | The agent only needs a functional mailbox (info@, orders@) and a folder | None meaningful: the cleanest option and the one we recommend starting with |
Our default recommendation for an SME: start with the third. Create a Workspace user for the agent, share what it needs, and you get traceability for free — everything it does is signed by that account. Domain-wide delegation is powerful, but it is the master key to company email and should only be used when the case genuinely demands it.
Permissions: the mistake that gets expensive
The principle is boring and almost never followed: request the narrowest scope that solves the case. Google classes some scopes as restricted — full Gmail access being the classic example — and public apps that use them must pass OAuth verification and, in many cases, an annual CASA security assessment, with its own cost and calendar.
The good news for most companies: if the application is internal, published only to users in your own domain, it does not go through that verification process. That is why a custom agent built for your organisation ships in weeks while an integration intended for resale takes months.
Three rules we always apply:
- Separate read from write. Start with read-only scopes and widen when accuracy is proven. An agent that misreads is annoying; one that miswrites costs money.
- No full Gmail access for convenience. Nearly every case is solved with read-only message scopes plus draft creation.
- Quarterly access review. Which service accounts exist, which scopes they hold, who authorised them. It is the same control we describe in our guide to AI agent governance and permissions.
What limits will you hit?
The real constraints on a Workspace project are rarely permissions; they are quotas and search quality. Google's APIs enforce quotas per project and per user per second — the Admin SDK Directory API, for instance, allows roughly 1,500 queries per 100 seconds per project according to its documentation as consulted in August 2026 — and a badly designed agent polling in a loop burns through them faster than you would expect.
The other three that always appear:
- Drive search is literal, not semantic. It finds "Acme proposal" but not "the document where we agreed the discount". If your use case depends on meaning, you need your own index over the documents, not just the Drive API.
- Long threads do not fit whole. An 80-message thread with attachments has to be summarised in chunks, not dumped into a single request.
- Tokens expire. Any per-user OAuth integration needs renewal and a plan for when it fails: an agent that stops working silently is worse than no agent.
Internal use cases that actually pay
- A shared inbox run by the agent. It triages, answers the repetitive mail as a draft or directly, extracts the order data and writes it to the sheet or the ERP. Best return of the lot and the fastest to notice — we break it down in our guide to email automation in Gmail and Outlook with AI.
- Meeting preparation. Half an hour before, the agent gathers the client history, the last proposal and the open points, and drops them into the calendar invite. Saves 10-15 minutes per meeting for the people whose minutes cost most.
- Proposals from templates. It takes the details from the conversation, fills the Doc, calculates the pricing sheet and leaves the draft for review. Forty minutes becomes five.
- Automatic weekly report. Consolidates several sheets and mailboxes and publishes the summary at 08:00 on Mondays, every week, with nobody chasing it.
- Internal search across Drive. Answering "what terms did we agree with this supplier?" in seconds instead of twenty minutes of folder archaeology.
A simple sizing calculation: if ten people recover 30 minutes a day, that is 1,250 hours a year. At fully loaded internal cost, €25,000-40,000. Against a custom agent project of €15,000-40,000 plus 10-20% annual maintenance, the return is rarely the hard conversation; adoption is.
What not to give an agent in Workspace
Domain admin rights, the ability to delete in Drive, access to executive mailboxes, and unreviewed sending to clients in the early weeks. Nor should it get access to HR and finance shared drives "just in case": most agent incidents are not attacks, they are over-broad scopes someone granted to move faster.
One architectural habit as well: have the agent always create new versions rather than overwrite. A duplicated document is a nuisance; a master template overwritten is a lost afternoon.
How it gets built in four weeks
- Week 1. Pick one measurable use case, create the agent account, share only what it needs.
- Week 2. Connect and run in proposal mode: the agent prepares, a person confirms. Hits and misses get measured.
- Week 3. Raise autonomy where accuracy is proven and leave the rest under review.
- Week 4. Add the second application — usually Calendar or Sheets — and measure against the baseline.
If your team also lives in Chat or other messaging tools, the pattern extends the same way, as we explain in our piece on AI agents in Slack and Teams. And if you would rather have the first deployment done by people who have already tripped over these particular stones, that is how we work as an AI consulting partner.
Frequently asked questions
Do I need Gemini or a specific Workspace plan?
No. A custom agent connects to the Workspace APIs, which are available on the standard business plans, and can use whichever model you prefer underneath. Built-in Gemini and your own agent solve different problems: the first assists inside the interface, the second runs whole processes in the background.
Does Google read the data my agent processes?
The data stays in your domain under your Workspace terms; what changes is which model you send content to for reasoning. That is the decision to document: which provider, in which region, with what retention policy. If you handle sensitive data, settle it contractually before connecting anything.
Can the agent be limited to a single folder or label?
Yes, and it is the recommended setup. With a dedicated agent account, the scope is exactly what you share with it: one shared drive, one Gmail label, one calendar. It is the simplest control and the easiest to audit when someone asks what that agent can see.
What happens if the agent sends the wrong email?
That is why you start in draft mode. Once it sends on its own, three safeguards do the work: an allowed-recipient list, a cap on sends per hour, and an instant notification to an owner for every external send during the first month. With those, a mistake surfaces in minutes and is fixed with an apology rather than a crisis.