The Google Workspace Admin Console is great for setting things up, but difficult for auditing at scale. If you want to know "What is the security posture of the 'Marketing' group?", you have to dig deep.
The official Policy API allows you to fetch all these policies programmatically.
I built a Proof-of-Concept Security Agent (with ADK) that reads the API documentation (OpenAPI spec), authenticates securely (OAuth), and answers our questions directly with Gemini 3 Flash.
The Architecture recap
The setup is surprisingly simple. It is about connecting three things:
1. Policy API: The source of truth for your policies.
2. ADK (Agent Development Kit) The framework that handles the plumbing (OAuth, Tool calling).
3. Gemini 3 Flash:: The brain that interprets the policy data.
Agent setup
I will describe my workflow how I did it.
I visited the Cloud Identity API documentation page, because Policy API is part of this endpoint
So how to do it? I wrote a converter app in
Google I Studio that converts JSON format to YAML as OpenAPI.
My prompt was
create an application to convert static google discovery specification to openapi 3 yaml format.
I will paste a google discovery format (as json) and get return in yaml (text)
Once I had the exported YAML file, I was ready for the next step. This file is the "secret sauce" of the whole setup. It serves as a bridge between the complex Policy API and our agent's decision-making process. In the world of AI, agents are essentially a Large Language Model (LLM) paired with a set of tools. While Gemini 3 Flash provides the "brain," the tools provide the "hands" to actually interact with your Google Workspace data.
Usually, you have to define these tools by writing individual Python functions. You’d write the code, add detailed docstrings, and then the agent would use those descriptions to figure out which function to call. It works, but it’s a lot of manual work if you’re dealing with a complex API.
The beauty of using a YAML (OpenAPI schema) definition is that you can skip the manual coding. Instead of writing a separate function for every single API endpoint, you simply provide the YAML file to the Agent Development Kit (ADK) (as seperate file in my case)
The agent is smart enough to parse the specification, understand the available endpoints, and know exactly what parameters are required for each request. It’s a much more efficient way to build, especially when you want your agent to have full access to a comprehensive API like the Policy API.
Since we’re dealing with sensitive organizational data, authentication is a critical piece of the puzzle. Google’s ADK provides built-in OAuth objects that handle the heavy lifting of user authorization.
I visited to the Google Cloud Console (http://console.cloud.google.com/auth/clients/) to generate an OAuth Client ID and OAuth Client Secret in Google Auth Platform.
The trick is to never hardcode these directly into your scripts. I store them in a .env file—it’s a simple way to keep your credentials secure and your code clean.
Note: Model Gemini 3 Flash Preview is available in global region
.env ---
The agent.py file is where the magic happens. It contains the agent’s core definition (Agent()), including specific instructions provided through a prompt. I’ve clearly defined its role: what it should accomplish and which tools it needs to call upon to get the job done. I used best-practices for Gemini 3 prompting (eg. using <meta>tags</meta>
Next, I configured the OAuth flow. This involves specifying the authorization URL and the necessary scopes. For this auditing agent, I used the scope https://www.googleapis.com/auth/cloud-identity.policies.readonly . We only need to read the data to analyze it; there's no need for write access, which follows the principle of least privilege.
The last step was setting up the redirect URI. For local testing, I pointed it to "http://localhost:8000/oauth-callback". Just a small heads-up: you must remember to add this local address to your allow-list in the Google Cloud Console. It’s a common stumbling block, but once that's in place, the authentication handshake works perfectly
agent.py
---
Run Agent
With the agent defined and OAuth ready, it was time to take it for a run.
The Agent Development Kit makes this process incredibly easy with a single command: adk web. Running this in your shell launches a local development interface—a sandbox where you can talk to your agent and see how it thinks.
Once the ADK DEV UI is up, I started with a direct question: "Audit my Google Workspace." Because the agent needs to access live data, it immediately triggered the OAuth flow. I was redirected to a standard Google login screen.
The beauty of this approach is that I didn't have to tell the agent how to call the API. It used the YAML definition to look up the correct endpoints in the Policy API, fetched the current configuration, and compared it against security best practices. It's like giving Gemini 3 a map and a set of keys, and letting it do the exploration for you.
The final result was exactly what I was looking for. Instead of digging through the Admin Console or parsing through raw JSON, I received a concise summary in natural language. The agent pointed out exactly which settings weren't aligned with my security goals.
Now you can audit your Google Workspace with one just specialized agents
Note: Google Cloud credits are provided for this project during #AISprint
