Building an AI Document Reviewer with Google ADK, Gemini and the New Google Docs Comments &…

Building an AI Document Reviewer with Google ADK, Gemini and the New Google Docs Comments & Suggested Edits API

GitHub Repository: All complete source code, Dockerfile, and the one-command Cloud Run deployment script (deploy.sh) are available at github.com/rominirani/doc-reviewer-101.

When Google announced the availability of the Comments and Suggested Edits API across Google Docs, Sheets and Slides, I knew that the moment had arrived. The API looked like another one of the many releases that Google does but for some reason, I believe it opens up a world of possibilities and collaboration of a different sort, especially in the world of Agents.

Google Workspace Updates: Programmatic comment and suggestion support now available in the Google Docs, Sheets, and Slides APIs

A couple of points particularly stand out for me:

• I am literally tired of those folks, to whom I send out a document for review because I respect their knowledge specific to the document content. And what do I get in return as feedback? Just a list of grammatical mistakes, typos and stuff like that. I appreciate them doing that but that was not what I was looking for.
• Agents are pushing the limits everyday in terms of what work it can now do for humans and this API when combined with the intelligence of an LLM + Your Agent skills/Instructions could be a new way in which Agents can take over mundane work and free up our time.

Let’s get started.

What we will build

It is important that you take a look at what this blog post will help you do. Knowing this early in the post will help you decide if its interesting enough to go further.

So, here is a document that I have in Google Docs and assume that I have to ask someone for a review. This is a simple example but you can substitute it with any other document that you like, which has tons of mistakes as far as English language and similar issues are concerned.

You can see that there are typical typos, a bit of grammar issues and some bold and unverifiable claims made in the document.

What we are going to build is an Agent that can be invoked on a Google Doc that you have access (rights) to and provide comments and suggested edits, like as if someone manually reviewed and did them for you.

Note: You can argue that I don’t need to send out a document to someone to fix for typos, etc but you get the overall drift to where this is going. You will see later in the blog post that the application supports your own custom rules too.

Imagine if the agent can take our criteria for comments and suggested edits. For e.g. the list shown below and then apply these rules to autonomously go ahead and do the hard work.

The final result after you run the code that this blog post talks about looks something like this:

In summary, we have done a few things here:

1. Our Agent is programmed to use Gemini and the specific instructions that we provide for Comments and Suggested Edits and come up with a list of comments and suggestions.
2. We need to then use the API to create them while carefully ensuring that they are placed at the right point.

Why this approach is better?

First up, it avoids the copy-paste chat loop i.e. you copy paragraphs out of Google Docs, paste them into an AI chat window, ask for feedback, and manually copy the edits back into your document. This might result in losing formatting, tables, and collaborative context.

Yes, you can write a script too using the Google Docs API (deleteContentRange and insertText), but that might end up overwriting the author’s original text. An ideal review process allows us to see what changed, why it changed, or reject an unwanted rewrite without digging through version history.

Now compare this to how you as a human would review a Google Doc?You don’t overwrite the text (ideally). In fact, you would use any of these methods:

• Suggested Edits for objective, mechanical improvements (typos, grammar mistakes, awkward phrasing) that the author can Accept (✓) or Reject (✗) with one click.
• Anchored Margin Comments for high-level editorial feedback (unverified claims, missing citations, ambiguous timelines) that require discussion or author clarification.

What does the Programming Comments and Suggested Edits API provide?

The API introduces programmatic Comments (insertComment) and Suggested Edits (writeControl: {"writeMode": "SUGGEST"}). What this enables is that AI agents can finally participate in Google Docs as first-class human-in-the-loop collaborators.

What We Will Cover

In this tutorial, we will walk through the architecture and then provide a step-by-step Cloud Run deployment of doc-reviewer-101, an open-source web application powered by the Google Agent Development Kit (ADK) and Gemini 3.8 Flash on Gemini Platform (Vertex AI) that anyone can deploy in their own Google Cloud project to review their personal or team Google Docs.

Fear not … there is also a localhost version, should you want to keep things locally and just for yourself.

Architecture

A common stumbling block when building Google Workspace AI apps on Google Cloud is identity management:

• Gemini on Gemini Platform (Vertex AI) lives inside your Google Cloud project and is billed to your GCP account.
• Your Google Docs live inside your personal @gmail.com or Google Workspace account.

If you used a GCP Service Account to call the Google Docs API, every user would have to manually copy Service Account’s .iam.gserviceaccount.com email address and share their document with it before every review. Even worse, every comment in the document would show up as authored by a service account rather than the reviewer.

Instead, our application uses a Dual-Identity Architecture:

+-------------------------------------------------------------------------+
| 1. USER BROWSER (/reviewer)                                             |
|    - Signs in with Personal Google Account (OAuth 2.0)                  |
|    - Browses My Drive / Shared Drives via Google Drive Picker           |
|    - Customizes Suggested Edits & Editorial Comments Templates          |
+------------------------------------+------------------------------------+
                                     |
                                     | POST /api/review
                                     | (doc_id + custom criteria + cookie)
                                     v
+-------------------------------------------------------------------------+
| 2. FASTAPI + GOOGLE ADK SERVER (Local or Google Cloud Run)              |
|                                                                         |
|    ADK Session State:                                                   |
|      - user_access_token (from OAuth 2.0 Sign-In)                       |
|      - suggested_edits_criteria (custom rubric)                         |
|      - comments_criteria (custom rubric)                                |
|                                                                         |
|    ADK Agent (doc_reviewer_101)                                         |
+-----------------+-----------------------------------+-------------------+
                  |                                   |
   Identity 1:    |                                   | Identity 2:
   Cloud Run SA   | (roles/aiplatform.user)           | User's Personal
   (ADC)          v                                   v OAuth 2.0 Token
+----------------------------------+   +----------------------------------+
| 3A. Gemini Platform (VERTEX AI   |   | 3B. GOOGLE DOCS API v1           |
|     Gemini 3.8 Flash             |   |     1. read_google_doc           |
|     (Reasons over document &     |   |     2. insert_comments           |
|      generates structured calls) |   |     3. propose_suggested_edits   |
+----------------------------------+   +----------------------------------+

1. Identity 1 — The Backend Service Account (doc-reviewer-sa): Attached to the Cloud Run service (or your local Application Default Credentials). It has roles/aiplatform.user permission and is used exclusively by the ADK Runner to invoke Gemini 3.8 Flash on Vertex AI.
2. Identity 2 — The Logged-In User’s OAuth 2.0 Token: When the user clicks Sign in with Google in the web UI, the FastAPI backend obtains an OAuth 2.0 access token and passes it into the ADK session.state["user_access_token"]. When the agent invokes read_google_doc, insert_comments, or propose_suggested_edits (in app/tools.py), those tools authenticate to the Google Docs API using the user's token:

Note: If you’d like to dig into any of the code specifics, I suggest to readup the README.md file in the Github project.

doc-reviewer-101/README.md at main · rominirani/doc-reviewer-101

Dynamic Review Templates with Google ADK

Different documents require different editorial lenses. A software engineering design doc needs scrutiny on architecture trade-offs and latency numbers, whereas a marketing blog post needs scrutiny on tone, active voice, and brand terminology.

In app/agent.py, we take advantage of Google ADK's State Templating. When you include {comments_criteria} and {suggested_edits_criteria} inside an ADK agent's instruction string, ADK automatically interpolates those placeholders from session.state at runtime:

# app/agent.py
from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App

from app.tools import insert_comments, propose_suggested_edits, read_google_doc
DEFAULT_SUGGESTED_EDITS_CRITERIA = (
    "- Spelling mistakes and typos.\n"
    "- Grammatical errors (such as subject-verb disagreement, tense errors, or punctuation).\n"
    "- Awkward or redundant word choices."
)
DEFAULT_COMMENTS_CRITERIA = (
    "- Exaggerated or unverified claims that lack citations or benchmark data.\n"
    "- Unrealistic timelines or vague action items that need clear owners or dates.\n"
    "- Sections that are ambiguous and require clarification from the author."
)

def ensure_review_criteria_defaults(callback_context: CallbackContext):
    """Populates default review templates in session state if the user didn't override them."""
    if not callback_context.state.get("suggested_edits_criteria"):
        callback_context.state["suggested_edits_criteria"] = (
            DEFAULT_SUGGESTED_EDITS_CRITERIA
        )
    if not callback_context.state.get("comments_criteria"):
        callback_context.state["comments_criteria"] = DEFAULT_COMMENTS_CRITERIA
    return None

INSTRUCTION = """
You are an AI Document Reviewer for Google Docs.
When given a Google Document ID, execute these steps in exact order:
1. READ:
   Call `read_google_doc` to retrieve the document's text.
2. COMMENT FIRST (Based on User's Comment Criteria):
   Review the document against these specific Comment Criteria:
   {comments_criteria}
   If any phrases or sentences match the Comment Criteria above, call `insert_comments` first with the exact `target_text` from the document and helpful `comment_text`.
3. SUGGEST EDITS SECOND (Based on User's Suggested Edits Criteria):
   Review the document against these specific Suggested Edits Criteria:
   {suggested_edits_criteria}
   If any words or phrases need correction based on the Suggested Edits Criteria above, call `propose_suggested_edits` with each exact `target_text` and its `replacement_text`.
   Include 1-2 surrounding words in `target_text` if a typo is a short word (like "teh") to ensure unique matching.
4. SUMMARIZE:
   Return a clear summary of all comments and suggested edits applied, and provide the link:
   https://docs.google.com/document/d/<DOCUMENT_ID>/edit
"""
root_agent = Agent(
    name="doc_reviewer_101",
    model="gemini-3.8-flash",
    description="Reviews a Google Doc based on customizable criteria and adds comments and suggested edits.",
    instruction=INSTRUCTION,
    tools=[read_google_doc, insert_comments, propose_suggested_edits],
    before_agent_callback=ensure_review_criteria_defaults,
)
app = App(root_agent=root_agent, name="app")

When a user clicks Run AI Review in the web interface, review_document in app/fast_api_app.py seeds the ADK session with both the user's OAuth token and their custom criteria textareas:

await runner.session_service.create_session(
    app_name=app_name,
    user_id=user_id,
    session_id=adk_session_id,
    state={
        "user_access_token": token,
        "suggested_edits_criteria": edits_criteria[:2000],
        "comments_criteria": comments_criteria[:2000],
    },
)

Step-by-Step Guide: Deploy Your Own Google Docs AI Reviewer

Ready to run this in your own Google Cloud project? Follow the steps below to clone github.com/rominirani/doc-reviewer-101, run it locally, and deploy it to Google Cloud Run.

Here are the prerequisites:

• A Google Cloud Project with billing enabled.
• Google Cloud SDK (gcloud) installed.
• Python 3.11+ and uv installed.

Step 1: Clone the Repository & Enable Google Cloud APIs

Clone the repository and install dependencies with uv:

git clone https://github.com/rominirani/doc-reviewer-101.git
cd doc-reviewer-101
uv sync

Next, set your Google Cloud Project ID and enable the required APIs:

• Vertex AI API (aiplatform.googleapis.com): Runs Gemini 3.8 Flash via ADK.
• Google Docs API (docs.googleapis.com): Reads docs and writes comments & suggested edits.
• Google Drive API (drive.googleapis.com) & Google Picker API (picker.googleapis.com): Powers the Google Drive file picker.
• Cloud Run (run.googleapis.com) & Cloud Build (cloudbuild.googleapis.com): Builds and hosts the web container.

export PROJECT_ID="your-gcp-project-id"
gcloud config set project "${PROJECT_ID}"
gcloud services enable \
  aiplatform.googleapis.com \
  docs.googleapis.com \
  drive.googleapis.com \
  picker.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  --project="${PROJECT_ID}"

Also retrieve your Google Cloud Project Number (you’ll need this for .env):

gcloud projects describe "${PROJECT_ID}" --format="value(projectNumber)"

Step 2: Configure the Google OAuth Consent Screen

Because the web app signs you in with your personal Google account, configure your project’s OAuth consent screen once:

1. Open Google Auth Platform → Overview in the Google Cloud Console.
2. Click Get Started:

• App name: Google Docs AI Reviewer
• User support email: Choose your email address.
• Audience: Select External (this allows you to sign in with any personal @gmail.com account).
• Contact Information: Enter your email address and click Create.

3. In the left navigation menu, click Audience:

• Under Test users, click + Add users and enter your personal Google account email address (plus any teammates you want to invite).

Step 3: Create Your OAuth 2.0 Web Client ID

Now create the OAuth 2.0 client that handles the /auth/login and /auth/callback endpoints:

1. Open APIs & Services → Credentials.
2. Click + Create Credentials → OAuth client ID.
3. Select Application type: Web application and name it Docs Reviewer Web Client.
4. Under Authorized JavaScript origins, click + Add URI: http://localhost:8000
5. Under Authorized redirect URIs, click + Add URI: http://localhost:8000/auth/callback

Click Create and copy the Client ID and Client Secret.

Step 4: Create a Browser API Key for the Google Drive Picker

The client-side Google Drive Picker modal requires a Browser API Key:

1. Stay on APIs & Services → Credentials and click + Create Credentials → API key.
2. Copy the generated key (AIzaSy…).
3. Click Edit API key to secure it:

• Under Application restrictions, choose Websites and add: http://localhost:8000/* and http://127.0.0.1:8000/*
• Under API restrictions, select Restrict key and check both: Google Picker API and Google Drive API
• Click Save.

Step 5: Configure .env and Test Locally

Copy .env.example to .env and fill in your values:

cp .env.example .env
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
GOOGLE_CLOUD_LOCATION="global"
GOOGLE_CLOUD_PROJECT_NUMBER="your-gcp-project-number"

OAUTH_CLIENT_ID="your-oauth-client-id.apps.googleusercontent.com"
OAUTH_CLIENT_SECRET="GOCSPX-your-oauth-client-secret"
OAUTH_REDIRECT_URI="http://localhost:8000/auth/callback"
GOOGLE_PICKER_API_KEY="AIzaSy-your-browser-api-key"

Authenticate your local environment for Vertex AI and start the server:

gcloud auth application-default login
uv run uvicorn app.fast_api_app:app --reload --port 8000

Open http://localhost:8000/reviewer in your browser:

1. Click Sign in with Google and sign in with your personal account.
2. Click Browse Google Drive to open the Google Drive Picker and pick any Google Doc.
3. Customize the Suggested Edits Criteria and Editorial Comments Criteria textareas (or leave the default templates).
4. Click Run AI Review.

Within 30–60 seconds, you will see a summary of all edits and comments applied. You can check your Google Doc to view the suggested edits and comments.

Step 6: Deploy to Google Cloud Run for Multi-User Access

To share the reviewer with colleagues or use it from anywhere without running a local server, deploy it to Google Cloud Run.

Our FastAPI app (app/fast_api_app.py) includes automatic proxy header detection (_get_redirect_uri):

• When OAUTH_REDIRECT_URI is set in .env locally, it uses http://localhost:8000/auth/callback.
• When deployed to Cloud Run (where OAUTH_REDIRECT_URI is omitted), it reads the x-forwarded-proto (https) and host headers to automatically construct https://<your-cloud-run-service>.run.app/auth/callback.

Run the included deploy.sh script:

chmod +x deploy.sh
./deploy.sh

Under the hood, deploy.sh:

1. Creates a dedicated least-privilege service account (doc-reviewer-sa@<PROJECT_ID>.iam.gserviceaccount.com).
2. Grants it roles/aiplatform.user (so the Cloud Run container can call Gemini on Vertex AI).
3. Deploys the container using gcloud run deploy –source . with –max-instances=1 (ensuring in-memory OAuth sessions stay pinned to the active instance).

Final Console Step After Deployment

When deploy.sh finishes, it prints your live Cloud Run Service URL (e.g., https://doc-reviewer-101-xxxxx.us-central1.run.app). Add that URL to your credentials in APIs & Services → Credentials:

1. In your OAuth 2.0 Web Client:

• Add https://YOUR-CLOUD-RUN-URL.run.app under Authorized JavaScript origins.
• Add https://YOUR-CLOUD-RUN-URL.run.app/auth/callback under Authorized redirect URIs.

2. In your Browser API Key (if using Website restrictions):

• Add https://YOUR-CLOUD-RUN-URL.run.app/* under Website restrictions.

Wait a minute or two for the OAuth settings to propagate, then visit your Cloud Run URL!

Conclusion

By combining the Google Agent Development Kit (ADK) with the new Google Docs API Comments (insertComment) and Suggested Edits (writeControl: {"writeMode": "SUGGEST"}), we can move beyond chat-based copy-pasting and build AI agents that collaborate inside Google Docs just like a thoughtful human colleague.

Explore the full source code and deploy your own instance today from github.com/rominirani/doc-reviewer-101.

Building an AI Document Reviewer with Google ADK, Gemini and the New Google Docs Comments &… was originally published in Google Cloud – Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Source Credit: https://medium.com/google-cloud/building-an-ai-document-reviewer-with-google-adk-gemini-and-the-new-google-docs-comments-1f79fb6cb86f?source=rss—-e52cf94d98af—4

About the Author

Deven Goratela

Administrator

Visit Website View All Posts