Building an @ai Comment Assistant in Google Docs with ADK and the New Docs API v1 Comment Primitives
How to use the new Google Docs API v1 CommentThread, CommentAnchor, and AddCommentReplyRequest primitives so any @ai comment in your document automatically proposes a non-destructive Suggested Edit and replies in-thread.
Series Navigation:
In Part 1, we built an AI Document Reviewer using Google ADK, Gemini 3.8 Flash, and the new Google Docs API v1 Comments & Suggested Edits primitives.
In Part 2, we upgraded it into a Hybrid Fact-Checker & Citation Agent powered by the Developer Knowledge MCP Server and Google Search Grounding.
In Part 3 (this blog post), we turn Google Docs comments into an interactive @ai prompt bar.
From Full-Document Scans to precise In-Doc Prompts
In Parts 1 and 2, the interaction model was top-down i.e. you clicked a button and the agent reviewed the entire document from start to finish against a rubric (your custom rules).
But what if you are mid-draft and want targeted help on a single paragraph, code snippet, or claim without leaving Google Docs or copy-pasting text into a chat window?
In Part 3, we flip the interaction model: we turn native Google Docs comments into an inline AI prompt bar (@ai), and use Suggested Edits as the safe, non-destructive output.
All code is available in the companion GitHub repository: rominirani/doc-reviewer-101.
The User Experience: Comments as Prompts, Suggested Edits as Output
With this Part 3 add-on, collaborating with your ADK agent feels identically like collaborating with a human co-author in Google Docs:
- Highlight & Prompt in Google Docs: Highlight any sentence, paragraph, or code block in your Google Doc and leave a regular comment containing @ai (or /ai), such as:
- @ai make this paragraph 50% shorter and executive-friendly
- @ai convert this curl command into a Python requests snippet
- @ai verify if this Cloud Run concurrency limit is accurate and update the sentence with the official quota
2. Trigger the Add-On: In the web UI, click Process @ai Comments in Doc.
Within seconds, two things appear directly inside your open Google Doc:
- An Inline Suggested Edit (writeMode: "SUGGEST"): Your highlighted text is replaced via a Suggested Edit that you can accept (✓) or reject (✗) with one click.
- An In-Thread Reply (addCommentReply): The agent replies directly inside your comment thread explaining what it changed—and if your @ai prompt asked a factual question, it includes the verified answer and citation URL!
Let’s see the before and after results, so that you get an idea of where we are going with this and the experience that we are enabling.
The screenshot below is that of 3 sections in the document where I have put in comments starting with @ai :
Now, all I need to do is select this document in our web application and ask it to process the @ai comments and the results are shown below:
So the experience is almost like you putting in the comments and asking AI to provide you specific suggestions, verifications, etc. You can then review the Suggested Edits just like you would in a normal review process in Google Docs.
Source code
All source code is available in the Github repository and if you’d like to dig into the Google Docs API specifics, please take a look there:
GitHub – rominirani/doc-reviewer-101: AI-powered Google Docs Reviewer built with Google ADK, Gemini on Vertex AI, Google Drive Picker, and the Google Docs Comments & Suggested Edits API
Two Ways to Use It: Standalone Mode or 1-Line Integration
Because app/addons/ai_comments.py is completely modular, you can use it in two ways:
- Dedicated UI Button & Endpoint (POST /api/ai-comments): Out of the box, app/fast_api_app.py mounts ai_comment_app at POST /api/ai-comments and adds Section 3 ( Interactive @ai Comment Assistant) to the web UI at http://localhost:8000/reviewer
The UI is shown below:
2. Integrate it onto your existing ADK Agent in 1 line: If you already built your own custom ADK agent from Part 1 or Part 2, just call attach_ai_comment_tools(your_agent):
from app.agent import root_agent
from app.addons.ai_comments import attach_ai_comment_tools
# Adds `list_open_ai_comments` and `respond_to_ai_comments` to your existing agent!
attach_ai_comment_tools(root_agent)
Try It Yourself
- Start the local server:
uv sync uv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000 --reload
- Open any Google Doc, highlight a paragraph or claim, and add a comment starting with @ai (for example: @ai make this 50% shorter for executives or @ai fact-check this Cloud Run quota against official Google Cloud docs and rewrite).
- In http://localhost:8000/reviewer, select your document with Browse Google Drive and click Process @ai Comments in Doc.
- Switch back to your Google Doc tab to see the inline Suggested Edits and Comment Replies!
Deploying to Cloud Run: Our existing ./deploy.sh script automatically deploys both the Full Document Reviewer (POST /api/review) and the new @ai Comment Assistant (POST /api/ai-comments) to Google Cloud Run with a single command.
Building an @ai Comment Assistant in Google Docs with ADK and the New Docs API v1 Comment… 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-comment-assistant-in-google-docs-with-adk-and-the-new-docs-api-v1-comment-b293aecaa92c?source=rss—-e52cf94d98af—4
About the Author
