Building Governed Agents for Gemini Enterprise: Combining Remote MCP Servers, Skills, and Agent Runtime
The goal of enterprise AI is to empower employees to interact with key systems and live cloud data using natural language.
Both Model Context Protocol (MCP) servers and Agent Skills provide the critical pieces to make this happen.
We will bring together different pieces lik MCP Servers, Skills, Agents built using ADK, Agent Runtime and all being made available in Gemini Enterprise. The exact pieces fit into the puzzle as shown below:
By pairing a remote MCP Server with a specialized Skill inside an Agent Development Kit (ADK) Agent, and hosting it on Vertex AI Agent Runtime, we create a production-grade agent that is cataloged in Google Cloud Agent Registry and surfaced directly into Gemini Enterprise, where everyday business teams collaborate.
What is the value does this approach gives us, apart from the fact that bringing these agents into Gemini Enterprise, allows users to interact with live systems through conversational language?
The goal of this post is also to propose a reference implementation that allows you the following:
- While this reference implementation focuses on Google Cloud’s official Recommender MCP Server, the architecture is completely generic:
- You can bring any Google-Managed Remote MCP Server to this. Swap to Compute Engine, BigQuery, Cloud Storage, or Cloud Billing by updating the target URL and attaching the appropriate domain skill.
- Bring your own custom remote MCP Server to this. Connect internal company databases, proprietary ERP systems, ServiceNow, or internal microservices hosted on Cloud Run, GKE, or on-premises.
- The runtime contracts, dynamic OAuth2 credential flow, session management, and Gemini Enterprise publishing remain identical.
This blog post is not going to be discussion on Skills v/s MCPs. Rather it makes a case that creating an Agent which wraps the MCP Server with a Skill is probably the recommended solution.
In summary, this guide will help you learn:
- How to build a production-ready solution that wraps any Google Cloud remote MCP server using the Google Agent Development Kit (ADK) and an Agent Skill
- Deploy it to Cloud Run and register it in Agent Registry
- Publish the solution into a speficic Gemini Enterprise App.
We use the Google Cloud Recommender MCP server as our concrete reference implementation. But we will also see how we can use the existing code to simply swap to another MCP Server.
Companion Code Repository
The complete working codebase for this tutorial is maintained as an open-source reference implementation on GitHub:
👉 https://github.com/rominirani/google-cloud-mcp-bridge
To follow along with the code walkthroughs, inspect the configuration files, or run the local tests and deployment scripts on your machine:
# 1. Clone the companion repository
git clone https://github.com/rominirani/google-cloud-mcp-bridge.git
cd google-cloud-mcp-bridge
# 2. Set up Python virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Every file explained below corresponds directly to an active file inside the repository.
(Optional Reading) A few foundational concepts
First up is the Model Context Protocol (MCP), which is an open standard that standardizes how Large Language Models (LLMs) connect to external tools, databases, and APIs.
Instead of writing unique API integration code for every tool, MCP defines a unified contract:
- tools/list: The client asks the server, "What tools do you have?" The server responds with a list of tools, descriptions, and parameter schemas.
- tools/call: The client instructs the server, "Run tool X with arguments Y." The server executes the operation and returns the result.
MCP Servers could be local or remote:
- Local MCP Servers: Run on a local machine over standard input/output (stdio). They require local runtimes (Node.js, Python), local container engines, and process monitoring.
- Remote MCP Servers: Run on remote cloud infrastructure and expose an HTTPS endpoint. They communicate using standard HTTP POST requests with JSON-RPC payloads.
Google Cloud provides Remote MCP Servers. The Recommender MCP server is hosted at https://recommender.googleapis.com/mcp. You do not need to host or scale the tool server; Google hosts it and protects it with Google Cloud IAM. Let’s call them Fully-managed MCP Servers for various Google Cloud Services, hosted and managed by Google Cloud.
Check out the full list of MCP Servers provided by Google Cloud:
Supported products | Google Cloud MCP servers | Google Cloud Documentation
From an organizational perspective, if I need to deploy the MCP Servers and Agents, where do I maintain a list of them, so that other applications can them into what has been configured for the organization? Enter the Google Cloud Agent Registry.
Google Cloud Agent Registry is a centralized catalog inside Google Cloud that indexes two types of resources:
- Agents: Conversational services capable of autonomous reasoning.
- MCP Servers: Tool-providing services that can be discovered and mounted by agents.
When you enable a supported Google Cloud API (like Recommender or Compute Engine), Google Cloud automatically populates its remote MCP server into your project’s Agent Registry catalog under the global location.
For a majority of the users in the organization, they are simply going to interact with these Agents via a conversational interface and in natural language. Let’s assume that this application from where they can chat with these Agents is going to be Gemini Enterprise.
Gemini Enterprise is Google Cloud’s conversational AI platform for organizations. It provides employees with a web chat portal (and Google Workspace integrations) to interact with AI models grounded in corporate data.
Under the hood, Gemini Enterprise applications are managed by the Discovery Engine service. Within Gemini Enterprise, an App (also called an Engine) represents an assistant environment with its own:
- Grounded data stores (Google Drive, BigQuery, websites).
- System instructions and corporate guardrails.
- Connected Agents and Tools.
Agent Runtime (formerly Vertex AI Reasoning Engine) is Google Cloud’s fully managed, serverless execution platform built specifically for AI agents developed with the Google Agent Development Kit (ADK).
When you deploy an ADK agent to Agent Runtime:
- Google Cloud packages your agent container and auto-scales compute from zero to thousands of concurrent requests, billing only during active query processing.
- Agent Runtime connects directly to ADK agents through native :streamQuery and :query interfaces without requiring intermediate translation layers.
- Gemini Enterprise invokes Agent Runtime reasoning engines natively via Discovery Engine’s Assistant API with end-to-end IAM authentication.
- Deployed agents are automatically cataloged in Google Cloud Agent Registry, capturing their runtime identities, framework tags (google-adk), and protocol bindings.
What are these Agent Skills (SKILL.md) and what role do they play? While the MCP server provides the tools, the Agent Skill provides the reasoning instructions. It teaches the model:
- Which Recommender ID to query (idle disks vs. idle instances vs. right-sizing).
- How to extract and validate the Google Cloud project ID.
- How to calculate monthly and annualized savings from raw API data.
- How to present the output in clean Markdown tables.
- Safety boundaries (enforcing read-only discovery before any cleanup actions).
We will see how to construct this Skill (in Markdown format) in a later section in this article.
Architecture and System Design
While we will be covering step by step details here, it is sufficient to understand in this section, how it all works. You can directly skip to the next section (Prerequisites) if this theory is known to you.
At a high level, this solution bridges the gap between business users and Google Cloud APIs by connecting three distinct layers:
- The Conversational Interface: Gemini Enterprise, where team members type questions in natural language.
- The Reasoning Brain: Your ADK Agent (running on Cloud Run or Agent Runtime), which interprets the user’s question, applies your team’s rules (SKILL.md), and decides what tools to call.
- The Managed Tools: Google Cloud’s Remote MCP Server, which securely executes requests against backend Google Cloud services.
How the Architecture Works in Practice
The entire system operates as a simple four-step pipeline:
Step 1: User Asks a Question in Natural Language
An employee (such as a FinOps analyst, DevOps engineer, or engineering manager) opens the company’s Gemini Enterprise chat portal and types a question:
“@GCP Recommender Agent, find unused disks in project PROJECT_ID and calculate potential savings.”
Step 2: Gemini Enterprise Routes the Request
The Gemini Enterprise App receives the user’s message. Because the agent was published using agents-cli publish gemini-enterprise –registration-type=adk, Gemini Enterprise knows:
- The exact Reasoning Engine resource path (projects/…/locations/…/reasoningEngines/…).
- The agent’s specialized domain (Google Cloud cost recommendations and resource audits).
Gemini Enterprise makes an authenticated call to your agent using Vertex AI’s native Reasoning Engine streaming API (:streamQuery).
Step 3: Your ADK Agent Analyzes and Calls Tools
Your agent receives the prompt. Instead of returning a generic canned answer, it combines the user’s question with the instructions in SKILL.md:
- The skill instructs the model to extract the project ID (e.g.prod-ecommerce) and identify the target resource type (idle persistent disks).
- The model decides to invoke the list_recommendations tool for google.compute.disk.IdleResourceRecommender.
- Google ADK’s native McpToolset automatically generates a secure OAuth 2.0 Bearer token and sends a JSON-RPC request over HTTPS to Google's remote MCP endpoint (https://recommender.googleapis.com/mcp).
Step 4: Google Remote MCP Server Executes and Returns Data
Google Cloud’s remote MCP server authenticates the request using Google Cloud IAM (roles/mcp.toolUser and roles/recommender.viewer), fetches the live recommendation data from Google Cloud Recommender, and returns the raw JSON results back to your ADK agent.
Your agent then:
- Parses the monetary savings from the raw response.
- Formats the findings into a clear, executive-ready Markdown table (following the formatting rules in SKILL.md).
- Sends the formatted response back to Gemini Enterprise, where the user sees the final report in their chat window.
Why This Design is Secure and Low-Maintenance
- Zero Tool Infrastructure to Maintain: Google Cloud hosts, scales, and updates the remote MCP endpoints. You do not maintain database drivers, API client libraries, or tool containers.
- Zero Hardcoded Secrets: Authentication between your agent and Google’s remote MCP server uses Google Application Default Credentials (ADC). When running on Agent Runtime, the service account dynamically fetches short-lived tokens from the metadata server.
- Strict Boundary Control: The agent operates strictly within the permissions granted by Google Cloud IAM (roles/mcp.toolUser and roles/recommender.viewer). It cannot access resources or projects beyond what the service account is explicitly allowed to see.
- Standard Protocols Throughout: Communication uses standardized protocols at every boundary — native Reasoning Engine event streaming between Gemini Enterprise and your agent runtime, and Model Context Protocol (MCP) between your agent and Google Cloud.
Prerequisites
Before building or deploying the agent, you must set up your local development environment, enable Google Cloud APIs, and configure your IAM permissions. Follow these steps sequentially.
Ensure you have Python 3.10, 3.11, or 3.12 installed. We have already set up this environment earlier in the article, but if you have not done so, please clone the repository, navigate into the root folder and create a Python virtual environment and install the dependencies as per the commands given below:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Make sure you have a Google Cloud Project with Billing enabled and the gcloud CLI is configured and ready in your environment and for the specific Google Cloud project. Ensure you have logged in too.
#1 Set your active Google Cloud project and default location
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud config set project "$GOOGLE_CLOUD_PROJECT"
gcloud auth application-default login
gcloud auth application-default set-quota-project
You must enable several Google Cloud APIs to support remote MCP communication, Agent Registry and more.
The table below shows the APIs that we will be enabling and what each API does?
Enable all the APIs with the single command shown below:
gcloud services enable \
aiplatform.googleapis.com \
agentregistry.googleapis.com \
discoveryengine.googleapis.com \
recommender.googleapis.com \
--project="$GOOGLE_CLOUD_PROJECT"
Wait a minute or two for the APIs enabled to propagage through.
Finally, we are going to create a Service Account for our Agent to use.
Create a dedicated service account for the agent:
gcloud iam service-accounts create mcp-bridge-agent-sa \
--display-name="MCP Bridge Agent SA" \
--project="$GOOGLE_CLOUD_PROJECT"
Grant the required least-privilege IAM roles:
# 1. Permission to execute tool calls on Google Remote MCP servers
gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
--member="serviceAccount:mcp-bridge-agent-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--role="roles/mcp.toolUser"
# 2. Permission to read recommendations and insights from the Recommender API
gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
--member="serviceAccount:mcp-bridge-agent-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--role="roles/recommender.viewer"
# 3. Permission for the agent to call Vertex AI / Gemini models in Google Cloud
gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
--member="serviceAccount:mcp-bridge-agent-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
# 4. Permission to inspect Compute Engine disk and virtual machine metadata
gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
--member="serviceAccount:mcp-bridge-agent-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--role="roles/compute.viewer"
- roles/mcp.toolUser: Grants mcp.tools.call. Google Cloud enforces this role on all remote MCP endpoints. Without it, requests return HTTP 403 Forbidden.
- roles/recommender.viewer: Allows reading recommendations, telemetry insights, and cost projections from the Recommender service.
- roles/aiplatform.user: Required for the containerized agent running on Cloud Run to send prompts to the Gemini model (gemini-2.5-flash) via the Vertex AI API without needing an external API key.
- roles/compute.viewer: Allows viewing Compute Engine resource details (e.g. disk sizes, attach status, VM states) corresponding to recommendations.
Installing and Setting Up agents-cli
agents-cli is Google Cloud's official developer CLI and toolkit for scaffolding, evaluating, deploying, and governing AI agents across Google Cloud. It integrates natively with the Google Agent Development Kit (ADK), Agent Runtime, and Google Cloud Agent Registry.
1. Install uv (Fast Python Package and Tool Runner)
agents-cli is distributed as a standalone tool package via Astral's uv. If you do not have uv installed, install it via the official installer:
curl -LsSf https://astral.sh/uv/install.shsh
2. Install google-agents-cli
Once uv is available, install agents-cli globally as a tool:
uv tool install google-agents-cli
Upgrade Tip: If you already have agents-cli installed and wish to ensure you are on the latest release:
uv tool upgrade google-agents-cli
3. Verify the Installation
Confirm that the CLI binary is available on your system path and check the active version:
agents-cli info
Expected Output:
agents-cli version: 1.4.1
CLI install path: ...
OS info: ...
Installed skills: ...
...
Bootstrapping and Scaffolding with agents-cli
IMPORTANT
Using the Companion Repository? You Can Skip scaffold create!
If you cloned the companion repository (github.com/rominirani/google-cloud-mcp-bridge), you do NOT need to run agents-cli scaffold create.
The complete project layout, agent package (gcp_agent/), domain skill (skills/recommender/), test harnesses (test_client.py, test_chat.py), and deployment scripts are already pre-built and ready to run. Just make sure that you have setup your virtual environment and you can go directly to the section on testing it locally.
If you wish to scaffold your own project from scratch?
1. Run the agents-cli scaffold create command below to generate a fresh ADK project skeleton.
2. Then, copy over the essential bridge files from this repository into your new project:
– gcp_agent/agent.py — The core ADK Agent definition with McpToolset and Vertex AI Reasoning Engine routes.
– gcp_agent/__init__.py — Package entrypoint exposing root_agent.
– skills/recommender/SKILL.md — Domain reasoning instructions for analyzing idle disks and cloud spend.
– requirements.txt — Project dependencies (google-adk[mcp,gcp]).
– test_client.py & test_chat.py — Local validation scripts.
– deploy.sh — Deployment and Gemini Enterprise registration script.
To create a new ADK agent project configured for Vertex AI Agent Runtime:
agents-cli scaffold create gcp-recommender-agent \
--agent adk \
--deployment-target agent_runtime \
--region us-central1 \
--prototype
Let’s dissect what each flag does:
- –agent adk: Selects the Google Agent Development Kit (ADK) framework template (Google's standard Python framework for enterprise agents).
- –deployment-target agent_runtime: Configures the project for serverless deployment to Google Cloud Agent Runtime (Vertex AI Reasoning Engine).
- –region us-central1: Sets the default Google Cloud deployment and model inference region.
- –prototype: Selects the recommended "Prototype-First" workflow. This skips generating heavyweight Terraform modules and CI/CD pipelines upfront, allowing you to focus entirely on agent prompt engineering, tool integration (McpToolset), and local validation.
Enhancing an Existing Project (scaffold enhance)
If you started with a prototype or already have existing agent code, you can enhance it with deployment infrastructure at any time:
agents-cli scaffold enhance . --deployment-target agent_runtime
Upgrading Scaffolding (scaffold upgrade)
When Google releases newer versions of agents-cli or template improvements, you can upgrade your project while automatically preserving your custom agent logic and tool implementations:
# Preview changes without modifying files
agents-cli scaffold upgrade --dry-run
# Apply upgrades intelligently
agents-cli scaffold upgrade --auto-approve
The Scaffolding State Manifest (agents-cli-manifest.yaml)
agents-cli records your architecture decisions in agents-cli-manifest.yaml. This manifest allows subsequent commands (agents-cli deploy, agents-cli publish gemini-enterprise, agents-cli run, agents-cli eval run) to automatically know your agent directory, deployment target, and project metadata without having to re-enter flags every time.
The Minimal Codebase Implementation
If you cloned the repository (github.com/rominirani/google-cloud-mcp-bridge), you will find the complete solution:
google-cloud-mcp-bridge/
├── gcp_agent/ # ADK Agent package
│ ├── __init__.py # Exports root_agent for ADK loader
│ └── agent.py # Native ADK Agent using McpToolset & Reasoning Engine routes
├── skills/
│ └── recommender/
│ └── SKILL.md # Skill instructions for cost and idle resource analysis
├── agents-cli-manifest.yaml # Project descriptor and deployment target metadata
├── Dockerfile # Container image build for Agent Runtime
├── requirements.txt # Python dependencies (google-adk[mcp,gcp])
├── test_client.py # Local script to verify ADK McpToolset discovery
├── test_chat.py # Local script to run conversational prompts via ADK Runner
├── deploy.sh # Script to deploy to Agent Runtime and publish via agents-cli
└── README.md # Project documentation
Let’s examine each core file in depth.
1. The Core ADK Agent (gcp_agent/agent.py)
In an agents-cli scaffolded project, the developer focuses entirely on writing pure agent logic. You declare your model, instructions, and tools without writing HTTP JSON-RPC boilerplate:
"""gcp_agent/agent.py: Pure ADK Agent Definition with Remote MCP Toolset."""
import os
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
import google.auth
from google.auth.transport.requests import Request as GoogleAuthRequest
SERVICE_NAME = os.getenv("ACTIVE_MCP_SERVICE", "recommender").lower()
MCP_URL = os.getenv("MCP_SERVER_URL", "https://recommender.googleapis.com/mcp")
MODEL_NAME = os.getenv("MODEL_NAME", "gemini-2.5-flash")
def get_auth_headers(ctx=None):
"""Provide fresh Google Cloud OAuth2 Bearer token for remote MCP calls.
ADK invokes this callable dynamically for every tool request, ensuring
tokens never expire during long-running sessions.
"""
credentials, project = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
if not credentials.valid:
credentials.refresh(GoogleAuthRequest())
headers = {
"Authorization": f"Bearer {credentials.token}",
"Content-Type": "application/json",
}
quota_project = (
os.getenv("GOOGLE_CLOUD_PROJECT")
or getattr(credentials, "quota_project_id", None)
or project
)
if quota_project:
headers["X-Goog-User-Project"] = quota_project
return headers
def load_instructions() -> str:
"""Load skill instructions from SKILL.md."""
skill_file = os.path.join(os.path.dirname(__file__), "..", "skills", SERVICE_NAME, "SKILL.md")
if os.path.exists(skill_file):
with open(skill_file, "r", encoding="utf-8") as f:
return f.read()
return f"You are a helpful assistant with access to Google Cloud {SERVICE_NAME} tools."
# Declare the ADK Agent
root_agent = Agent(
name=f"gcp_{SERVICE_NAME}_agent",
model=MODEL_NAME,
instruction=load_instructions(),
tools=[
McpToolset(
connection_params=StreamableHTTPConnectionParams(url=MCP_URL),
header_provider=get_auth_headers,
)
],
)
Notice what is absent:
- Zero JSON-RPC client boilerplate: No custom HTTP dispatch loops, error wrappers, or manual session handshakes.
- Zero schema maintenance: Google Cloud’s remote MCP server advertises its tools via tools/list, and ADK automatically binds them to Gemini function declarations.
2. The Agent Skill (skills/recommender/SKILL.md)
The Agent Skill provides domain reasoning rules to the model:
---
name: gcp-recommender-finops
metadata:
category: CloudManagement
description: Audits Google Cloud resources and discovers cost optimization recommendations.
---
# Google Cloud Recommender & FinOps Skill
## Workflow Steps
1. **Identify Project & Scope**: If not specified, prompt the user for the Google Cloud project ID and zone.
2. **Fetch Recommendations**: Query `google.compute.disk.IdleResourceRecommender` or `google.compute.instance.IdleResourceRecommender`.
3. **Calculate Impact**: Extract `primaryImpact.costProjection` and aggregate monthly and annualized savings.
4. **Output Presentation**: Format findings in an executive Markdown table with recommended cleanup actions.
3. Scaffolded Infrastructure Files
agents-cli scaffold create generates the surrounding deployment and configuration assets:
Testing Locally Before Deployment
One of the great advantages of Google ADK is that you can thoroughly test your agent on your local machine before deploying a single container to Google Cloud.
If you have cloned the companion repository (github.com/rominirani/google-cloud-mcp-bridge), you have pre-built test scripts ready to execute immediately.
There are four complementary ways to test locally:
- Remote MCP Tool Discovery Test: Verifies that ADK establishes an authenticated session with Google’s remote MCP endpoint and dynamically registers available tools.
- Conversational Prompt Test (test_chat.py): Runs prompts through the ADK Runner to verify model reasoning, SKILL.md instruction adherence, and actual MCP tool execution.
- Local HTTP & A2A Endpoint Test (uvicorn): Runs the FastAPI web server locally to verify the /.well-known/agent-card.json manifest and /a2a JSON-RPC endpoint.
- Visual Chat Testing via adk web: Launches ADK's built-in developer server with a full graphical browser Web UI and real-time execution graphs.
Method 1: Remote MCP Tool Discovery (test_client.py)
Run test_client.py to verify that McpToolset successfully connects to Google's remote MCP server (https://recommender.googleapis.com/mcp) using your local Google Cloud credentials:
python test_client.py
Expected Output:
============================================================
ADK Remote MCP Toolset - Connection Test
============================================================
Agent Name : gcp_recommender_agent
Model : gemini-2.5-flash
------------------------------------------------------------
Fetching tools via native ADK McpToolset...
[SUCCESS] Discovered 4 tools from Google Cloud:
1. get_insight
Description: Gets a specific insight.
2. get_recommendation
Description: Gets a specific recommendation.
3. list_insights
Description: Lists insights for a given cloud resource.
4. list_recommendations
Description: Lists recommendations for a given cloud resource.
============================================================
All connection checks passed successfully!
============================================================
Method 2: Conversational Prompt Execution (test_chat.py)
To test how the model reasons, consults SKILL.md, and interacts with users, use test_chat.py. This script uses ADK's Runner and InMemorySessionService to run end-to-end conversations locally.
Set your project environment variables for Vertex AI:
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
Then run a test prompt:
python test_chat.py "What recommendations can you provide for persistent disks?"
Expected Output:
Agent Response:
============================================================
ADK Local Agent Runner Test
============================================================
Agent Name : gcp_recommender_agent
Model : gemini-2.5-flash
User Prompt: What recommendations can you provide for persistent disks?
------------------------------------------------------------
For Google Cloud **Persistent Disks**, the GCP Recommender service provides targeted recommendations to optimize costs and eliminate waste:
---
### 1. **Idle Persistent Disk Recommendations**
- **Recommender ID:** `google.compute.disk.IdleResourceRecommender`
- **Scope:** Zonal or Regional (e.g., `us-central1-a` or `us-central1`)
- **What it detects:**
- Disks that have been detached/unattached from any VM instance for an extended period (typically >14 days).
- Disks attached to stopped or idle VMs with negligible I/O activity.
- **Recommended Action:**
- Create a snapshot of the disk (for backup/recovery retention) and delete the persistent disk.
- **Primary Benefit:** Direct monthly storage cost savings (standard PD, SSD, balanced PD, or extreme PD charges).
---
### 2. **Related Disk & VM Optimizations**
While idle disk recommendations focus directly on disk resources, related recommenders also impact disk storage:
- **Idle VM Recommender (`google.compute.instance.IdleResourceRecommender`):** Identifies idle compute instances where boot/attached disks are incurring ongoing storage fees.
- **VM Right-Sizing (`google.compute.instance.MachineTypeRecommender`):** Helps identify if attached disks or machine storage throughput are over-provisioned.
---
### How to Check Recommendations for Your Project
If you would like me to audit your GCP project for idle persistent disks, please provide:
1. **GCP Project ID** (or Project Number)
2. **Location/Zone** (e.g., `us-central1-a`, `us-east1-b`, etc., or your primary region)
Once provided, I can fetch the active disk recommendations and summarize the estimated monthly and annual cost savings for you.
Notice how the agent strictly followed the instruction in SKILL.md: Step 1: If the user does not mention a Google Cloud project ID, ask for it before proceeding.
You can also pass a query with a project ID to trigger live tool calling:
python test_chat.py "Check for idle persistent disks in project my-project-id in zone us-central1-a"
Method 3: Direct CLI Smoke Testing (agents-cli run)
The fastest way to test your agent directly from your terminal without writing custom test harnesses is using agents-cli run:
# General greeting / tool availability check:
agents-cli run "Hello! What tools do you have available?"
This gives the following output:
[user]: Hello! What tools do you have available?
[gcp_recommender_agent]: Hello! I have access to the **Google Cloud Recommender** tools, which allow me to inspect, analyze, and retrieve optimization insights and recommendations for your Google Cloud resources:
1. **`list_recommendations`**: Lists recommendations for a given Google Cloud container (project, billing account, folder, or organization), location, and recommender type (e.g., idle VM instances, unattached persistent disks, machine type right-sizing, committed use discounts, IAM policy recommendations).
2. **`get_recommendation`**: Fetches specific details and action steps for a particular recommendation ID.
3. **`list_insights`**: Retrieves the underlying telemetry insights backing recommendations (e.g., usage patterns, underutilized resources, security over-privileging).
4. **`get_insight`**: Retrieves detailed information for a specific insight ID.
---
### How I can help:
- **Cost Optimization & FinOps**: Find idle resources (VMs, disks), right-size underutilized compute instances, and calculate potential monthly/annual cost savings.
- **Performance & Reliability**: Identify configuration improvements and risks across your workloads.
- **Security & IAM**: Review over-privileged IAM bindings and access recommendations.
If you would like to run a cost audit or review recommendations, please share your **GCP Project ID** and preferred **region/zone** (or `global`).
You can now give a proper query as shown below:
# Conversational audit query:
agents-cli run "Check for idle persistent disks in project my-project-id in zone us-central1-a"
Method 4: Visual Chat Testing via adk web
The Google Agent Development Kit CLI includes a built-in development server with a full graphical Web UI (adk web). This gives you a browser-based chat window, real-time tool execution traces, and session inspection.
1. Set Environment Variables
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
2. Start the ADK Web Server
Launch the development server pointing to your project directory. Adding –a2a enables the Agent-to-Agent protocol routes alongside the UI:
adk web gcp_agent
3. Open the Developer UI
Open your browser with the URL that the above output indicates
Inside the UI:
- Interactive Chat: Chat with your agent in real time (e.g. “Audit project PROJECT_ID for idle persistent disks”).
- Live Execution Trace: Inspect the step-by-step function calling sequence, latency, and exact JSON parameters sent to https://recommender.googleapis.com/mcp.
- State & Sessions: View and debug conversational session history and memory.
Deploying to Agent Runtime and Google Cloud Agent Registry
When bringing an ADK agent to production in Google Cloud, Agent Runtime (part of the Gemini Enterprise Agent Platform, built on Vertex AI Reasoning Engine) is the native hosting environment.
Unlike generic compute targets that require you to manage web frameworks, container routing, and health probes yourself, Agent Runtime is designed specifically for conversational AI agents and does a lot of heavy lifting on its own.
Why Agent Runtime for Google ADK Agents?
- Native ADK Integration: Agent Runtime understands the Google Agent Development Kit lifecycle natively. It directly invokes your agent via :streamQuery and :query, handling token streaming and event dispatch without web server translation overhead.
- Built-in Session State: Agent Runtime automatically integrates with managed session services, preserving conversational state across user turns without requiring external database setups.
- Enterprise Identity & Least-Privilege IAM: Your agent executes using a dedicated Google Cloud Service Account (mcp-bridge-agent-sa), inheriting permissions for Vertex AI Gemini models and Google Cloud Remote MCP servers seamlessly.
- Serverless Auto-Scaling: Scales from zero to thousands of concurrent queries automatically, billing only for active execution resources.
Automated Deployment via agents-cli deploy
Deploying an ADK agent to Agent Runtime is executed with a single command using agents-cli:
agents-cli deploy \
--deployment-target="agent_runtime" \
--project="$GOOGLE_CLOUD_PROJECT" \
--region="$GOOGLE_CLOUD_LOCATION" \
--service-name="gcp-recommender-agent" \
--service-account="mcp-bridge-agent-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \
--update-env-vars="ACTIVE_MCP_SERVICE=recommender,GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT},GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"
This command will take a while to execute (5–10 minutes). It starts off with the following message:
🤖 Deploying agent to Agent Runtime...
📋 Deployment Parameters:
Project: PROJECT_ID
Location: us-central1
Display Name: gcp-recommender-agent
Min Instances: 0
Max Instances: 10
CPU: 1
Memory: 4Gi
Container Concurrency: 8
Service Account: mcp-bridge-agent-sa@PROJECT_ID.iam.gserviceaccount.com
🌍 Environment Variables:
ACTIVE_MCP_SERVICE: recommender
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS: false
AGENT_VERSION: 0.0.0
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: true
GOOGLE_CLOUD_LOCATION: us-central1
GOOGLE_GENAI_USE_VERTEXAI: true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: NO_CONTENT
🚀 Creating agent: gcp-recommender-agent (this can take a few minutes)...
INFO:agentplatform_genai.agentengines:Creating in-memory tarfile of source_packages
INFO:agentplatform_genai.agentengines:Using agent framework: google-adk
Operation: projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_RUNTIME_ID/operations/2633662216351514624
Monitor deploy logs: https://console.cloud.google.com/logs/query;query=resource.labels.reasoning_engine_id%3D%224870165259198922752%22?project=PROJECT_ID
If this command is interrupted, run 'agents-cli deploy --status' to check progress.
What agents-cli deploy Executes Under the Hood:
- Source Packaging: Packages your agent code (gcp_agent/), skills (skills/), and dependencies (requirements.txt).
- Container Build: Builds the runtime container image on Google Cloud infrastructure.
- Reasoning Engine Provisioning: Creates or updates the Vertex AI Reasoning Engine resource in your project.
- Deployment Metadata: Writes deployment_metadata.json to the project root with the assigned runtime ID:
{
"remote_agent_runtime_id": "projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_RUNTIME_ID",
"deployment_target": "agent_runtime",
"is_a2a": false,
"language": "python",
"agent_directory": "gcp_agent",
"deployment_timestamp": "2026-09-10T05:42:21.165448+00:00"
}
A final output with the Agent Runtime ID is shown below:
✅ Deployment successful!
Agent Runtime ID: projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/AGENT_RUNTIME_ID
Service Account: ...
📊 View in Console: <SOME_URL>
Automated Cataloging in Google Cloud Agent Registry
A major advantage of deploying to Agent Runtime is automatic fleet governance.
When you deploy an agent to Agent Runtime, Google Cloud automatically registers the agent into Google Cloud Agent Registry without any manual registration commands.
You can inspect the auto-cataloged agent immediately via gcloud:
gcloud alpha agent-registry agents list \
--project="$GOOGLE_CLOUD_PROJECT" \
--location="$GOOGLE_CLOUD_LOCATION"
Real Agent Registry Entry:
agentId: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:us-central1:aiplatform:reasoningEngines:AGENT_RUNTIME_ID
attributes:
agentregistry.googleapis.com/system/Framework:
framework: google-adk
agentregistry.googleapis.com/system/RuntimeIdentity:
principal: sa://mcp-bridge-agent-sa@PROJECT_ID.iam.gserviceaccount.com
agentregistry.googleapis.com/system/RuntimeReference:
uri: //aiplatform.googleapis.com/projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/AGENT_RUNTIME_ID
createTime: '2026-09-10T05:42:18.683227Z'
displayName: gcp-recommender-agent
location: us-central1
name: projects/PROJECT_ID/locations/us-central1/agents/agentregistry-00000000-0000-0000-08d0-c6460eafcc6b
protocols:
- interfaces:
- protocolBinding: HTTP_JSON
url: https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/AGENT_RUNTIME_ID:query
- protocolBinding: HTTP_JSON
url: https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/AGENT_RUNTIME_ID:streamQuery
type: CUSTOM
uid: agentregistry-00000000-0000-0000-08d0-c6460eafcc6b
updateTime: '2026-09-10T05:42:18.683227Z'
Notice what Agent Registry captures automatically:
- Framework Tag: Marked as google-adk.
- Runtime Reference: Bound directly to the underlying Reasoning Engine resource (Agent Runtime ID).
- Native Protocol Interfaces: Exposes :query and :streamQuery HTTP+JSON endpoints.
You can also check for the Agent being available in the Agent Deployment in Google Cloud Console. Launch Google Cloud Console and go to Agent Deployment. You should see the gcp-recommender-agent present in the list of agents.
You can click on the gcp-recommender-agent to see the details.
You can go to the Playground tab and try out the agent too.
Excellent ! We have made it this far with developing our agent with ADK and then deploying and testing it in the Agent Runtime Engine on Google Cloud. Its time to complete the last mile i.e. integrate the Agent in Gemini Enterprise Applications.
Step-by-Step: Integrating with Gemini Enterprise & Agent Registry
I suggest to zoom into this image and see how the integration and flow comes along.
Prerequisites: Gemini Enterprise App, Licensing, & Permissions
Before publishing an agent into Gemini Enterprise, ensure the following requirements are met in your Google Cloud environment:
- Enterprise Licensing & Active API:
- End-user chat requires an active Gemini Enterprise for Google Workspace license or a Gemini for Google Cloud enterprise subscription in your organization.
- The hosting Google Cloud project must have active billing and the Discovery Engine API (discoveryengine.googleapis.com) enabled. Discovery Engine is the underlying platform engine powering Gemini Enterprise apps, enterprise grounding, and agent orchestration.
2. A Pre-Created Gemini Enterprise App:
- An agent must be registered into an existing Gemini Enterprise Application (internally managed as an engine resource in Discovery Engine).
- If your organization has not yet created one:
- Open Google Cloud Console and navigate to Gemini Enterprise.
- Click Apps → Create App
- Specify an Application Name (e.g. enterprise-finops-portal), set the region to global.
3. Required IAM Permissions:
- Publishing User / CI/CD: Requires roles/discoveryengine.editor (Discovery Engine Editor) on the project hosting the Gemini Enterprise app, and roles/aiplatform.user on the project hosting Vertex AI Agent Runtime.
- Service Agent Invocation: The Discovery Engine service agent (service-${PROJECT_NUMBER}@gcp-sa-discoveryengine.iam.gserviceaccount.com) automatically requires roles/aiplatform.user to invoke the Reasoning Engine on Vertex AI when enterprise users chat.
4. Deployed Agent Runtime Artifact:
- The agent must already be deployed to Agent Runtime (via agents-cli deploy), which automatically writes deployment_metadata.json to your local project root with the runtime resource ID. We have already done that.
Once the Prerequisites are in place, we can integrate the Agent into the Gemini Enterprise App with the following steps:
Step 1: Discover Your Gemini Enterprise App via agents-cli
- agents-cli provides direct discovery of your Gemini Enterprise applications right from the terminal, no browser navigation or manual resource ID copying required.
- To list all available Gemini Enterprise apps in your current project, run:
agents-cli publish gemini-enterprise --list
This queries Discovery Engine and lists each available app with its full resource path. I have create a single application and this is what I see.
{
"apps": [
{
"display_name": "ge-adk-agent-integration",
"location": "global",
"name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/YOUR_APP_ID"
}
]
}
Copy your engine resource URI, or export it to an environment variable:
export GEMINI_ENTERPRISE_APP_ID="projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/YOUR_APP_ID"
Zero-Friction Alternative: Interactive Publishing:
You can also bypass manual flags completely by running:
agents-cli publish gemini-enterprise — interactive
This command will query the API, list your available Gemini Enterprise apps interactively in the terminal, prompt you to pick one, auto-detect your deployed agent runtime ID, and publish the agent in one single step!
Step B: Publish the Agent via agents-cli
Run agents-cli publish gemini-enterprise targeting agent_runtime with ADK registration:
agents-cli publish gemini-enterprise \
--gemini-enterprise-app-id="$GEMINI_ENTERPRISE_APP_ID" \
--display-name="GCP Recommender Agent" \
--description="Audits Google Cloud resources and discovers cost optimization recommendations using Google's remote MCP server." \
--tool-description="Audits Google Cloud resources for idle persistent disks, underutilized VMs, and cost savings." \
--deployment-target="agent_runtime" \
--registration-type="adk"
Automatic Metadata Detection: Because agents-cli deploy generated deployment_metadata.json in your project directory, agents-cli publish automatically detects the deployed Reasoning Engine resource ID (remote_agent_runtime_id). You do not need to manually copy or paste resource URIs.
Chatting in the Gemini Enterprise Application
Once published, your end users can immediately interact with the agent in Gemini Enterprise:
Launch the specific Gemini Enterprise Application. You can see that the GCP Recommender Agent is now listed among the Agents available for the user of this application to interact with:
You can pin the Agent, so that it is available in the left navigation bar:
You can now interact with it:
Give a prompt like:
What idle disks exist in project PROJECT_ID, and what are our estimated monthly savings?
Gemini Enterprise routes the query directly to the Reasoning Engine on Agent Runtime, which invokes Google Cloud’s Remote MCP server, evaluates live project metadata, and streams back the synthesized Markdown audit report!
Adapting This Reference Implementation to Other Google Cloud Services
One of the advantages of this architecture is how easy it is to change the agent’s target MCP server. Because Google ADK dynamically introspects tools at runtime using tools/list, you do not have to write or rewrite any tool code, JSON schemas, or API callers.
How to Switch to Another Google Cloud Remote MCP Server
Switching the agent to another service takes three simple steps:
Step 1: Update the Target Endpoint (Zero Code Changes)
In gcp_agent/agent.py, the target URL is already mapped to the ACTIVE_MCP_SERVICE environment variable.
You can switch the entire agent by setting a single environment variable:
# Example: Switch to Google Compute Engine Remote MCP
export ACTIVE_MCP_SERVICE="compute"
# Example: Switch to Google BigQuery Remote MCP
export ACTIVE_MCP_SERVICE="bigquery"
# Example: Switch to Google Cloud Storage Remote MCP
export ACTIVE_MCP_SERVICE="storage"
If you prefer to configure the URL directly in Python, it is a one-line change:
# Point directly to any Google Cloud Remote MCP endpoint:
MCP_URL = "https://compute.googleapis.com/mcp"
When the application boots, ADK’s McpToolset queries the new endpoint's tools/list method. It immediately discovers the new tools (for example, list_instances, get_instance, list_disks for Compute Engine) and provides them to Gemini.
Step 2: Provide Domain Instructions in SKILL.md
While ADK handles the tools automatically, the language model still needs domain instructions explaining your team’s operational workflows and table formatting.
Create a new file at skills//SKILL.md. For example, for Compute Engine (skills/compute/SKILL.md):
---
name: gcp-compute-auditor
metadata:
category: InfrastructureManagement
description: >
Audits Google Compute Engine virtual machines, checks machine status,
and inspects attached persistent disks using the Compute Engine Remote MCP server.
---
# Google Compute Engine Auditor Skill
## Workflow Steps
### Step 1: Discover Instances
- Call `list_instances` for the specified project and zone.
- If no zone is specified, check the primary project zones.
### Step 2: Identify Inefficiencies
- Flag instances that are in a `TERMINATED` or `STOPPED` state for over 7 days.
- Identify instances with legacy machine types (e.g. `n1-standard`).
### Step 3: Present Results
Format findings in an executive Markdown table:
| Instance Name | Zone | Machine Type | Status | Attached Disks | Recommendation |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `web-legacy-01` | `us-central1-a` | `n1-standard-2` | TERMINATED | `disk-1 (100GB)` | Delete or archive disk |
Step 3: Grant the IAM Viewer Role for That Service
The roles/mcp.toolUser permission is already granted and applies across all Google Cloud remote MCP servers. You only need to grant the service account the viewer role for the specific Google Cloud product:
# For Compute Engine:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:mcp-bridge-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/compute.viewer"
# For BigQuery:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:mcp-bridge-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/bigquery.dataViewer"
# For Cloud Storage:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:mcp-bridge-agent-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="roles/storage.objectViewer"
To update your deployed Agent Runtime instance with the new service:
agents-cli deploy \
--deployment-target="agent_runtime" \
--update-env-vars="ACTIVE_MCP_SERVICE=compute"
Multi-MCP Architecture: Connecting Multiple MCP Servers to a Single Agent
You do not need to limit an agent to one Google Cloud product. With Google ADK, you can attach multiple remote MCP servers to the same agent by listing multiple McpToolset instances:
root_agent = Agent(
name="gcp_platform_agent",
model="gemini-2.5-flash",
instruction="You are an enterprise cloud platform assistant with access to cost recommendations, compute infrastructure, and BigQuery telemetry.",
tools=[
# Toolset 1: Recommender (Cost & Optimization)
McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://recommender.googleapis.com/mcp"
),
header_provider=get_auth_headers,
),
# Toolset 2: Compute Engine (Virtual Machines & Disks)
McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://compute.googleapis.com/mcp"
),
header_provider=get_auth_headers,
),
# Toolset 3: BigQuery (Data Warehouses & Queries)
McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://bigquery.googleapis.com/mcp"
),
header_provider=get_auth_headers,
),
],
)
How Gemini Handles Multiple Toolsets:
When a user asks:
“Check project PROJECT_ID for idle disk recommendations, and verify if the parent VMs are stopped.”
- Gemini automatically invokes list_recommendations from the Recommender MCP server.
- It parses the returned unattached disk names.
- It immediately invokes get_instance from the Compute Engine MCP server to verify the VM status.
- It synthesizes a combined, highly contextual response for the user in Gemini Enterprise.
Google Cloud Remote MCP Server Catalog & IAM Mapping
The table below lists several remote MCP servers supported by Google Cloud and their corresponding IAM requirements:
Conclusion
By pairing Google Cloud’s remote MCP servers with Google ADK and an Agent Skill, you eliminate custom client boilerplate. ADK natively bridges tool discovery and execution, while Gemini Enterprise delivers the conversational experience directly to employees.
Building Governed Agents for Gemini Enterprise: Combining Remote MCP Servers, Skills, and Agent… 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-governed-agents-for-gemini-enterprise-combining-remote-mcp-servers-skills-and-agent-298ab526f09a?source=rss—-e52cf94d98af—4
About the Author
