Data Manager API Audience Ingestion

Implementation Workflow

Prerequisites

• Authentication & Library Installation: If you need to set up access to the Data Manager API or install the client and utility libraries, refer to the data-manager-api-setup skill.

Step 1: Identify Use Case & Read Documentation

• Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Display & Video 360, etc.) BEFORE generating any code. Do not assume Google Ads by default. This maps to the account_type field of the operating_account in the Destination.
• Read Documentation: [CRITICAL] Follow the upload guide for your destination to implement the integration, as steps for configuring and sending the request may vary between destinations:
  • Google Ads Customer Match: Upload members to an audience
  • DV360 Customer Match: Upload members to an audience

Step 2: Retrieve Code Sample

[!IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Step 3: Retrieve Migration Guides

[!CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

Google Ads

• Google Ads API Customer Match: Google Ads API to Customer Match Migration Field Mappings

Display & Video 360

• Display & Video 360 API Customer Match: Display & Video 360 API to Customer Match Migration Field Mappings

Step 4: Implementation

Implement the ingestion logic using the following checkpoints:

• Initialize Client: Instantiate the Data Manager client (IngestionServiceClient).
• Define Destinations: Build the Destination object using the product_destination_id and the appropriate account configurations: operating_account (target account receiving data), login_account (if authenticating using a manager account or a data partner account), and linked_account (if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
• Format User Data: Use the utility library helpers to normalize and hash user identifiers correctly.
• Construct Payload: Build the request payload (IngestAudienceMembersRequest) containing the destinations, formatted members, and consent permissions.
• Support Validation: Support sending the validate_only boolean option on the IngestAudienceMembersRequest to allow developers to validate schemas without actually uploading data.
• Send Request: Execute ingest_audience_members and record the returned request ID for logging/troubleshooting.
• Retrieve Request Status: Check the status of the ingestion request using diagnostics. Since request processing is asynchronous, a successful ingestion response (HTTP 200 OK returning a request_id) only indicates the payload was received. To check if the records actually succeeded, partially succeeded, or failed to process, query client.retrieve_request_status using the request_id. Skipping this step is a common user mistake.

Formatting

• Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

• Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

  Python Example:

  from google.ads.datamanager_util import Formatter
  from google.ads.datamanager_util.format import Encoding
  
  formatter: Formatter = Formatter()
  
  processed_email: str = formatter.process_email_address(
      email, Encoding.HEX
  )
  

Critical Gotchas

• Only set the address field on UserIdentifier if all required fields (postal_code, family_name, given_name, region_code) are present; incomplete address fields will cause the API request to fail.
• product_destination_id must be a numeric string. It is NOT a resource name.
• The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
• Field names on UserIdentifier are email_address and phone_number. Do not use the Google Ads API field names hashed_email and hashed_phone_number.
• Do not call the diagnostics endpoint (retrieve_request_status) if validate_only is set to true.

Error Handling & Troubleshooting

Inspecting Error Payloads

[!IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

Retrieving Request Status (Diagnostics)

Periodically poll for status using exponential backoff, starting at least 30 minutes after sending the IngestAudienceMembersRequest.

1. Call client.retrieve_request_status using RetrieveRequestStatusRequest(request_id=...).
2. Loop through request_status_per_destination in the response to inspect each target's request_status.
3. If processing is complete and request_status is SUCCESS, PARTIAL_SUCCESS, or FAILED, inspect diagnostic values:
   • Audience Ingestion Status: Check the data-type-specific status nested under audience_members_ingestion_status (for example, composite_data_ingestion_status).
     • Record Count: Check record_count (includes both success and failure).
     • Identifier Counts: Check the data-type-specific count field (e.g., data_type_counts for composite_data_ingestion_status or user_identifier_count for user_data_ingestion_status; see the Diagnostics Guide for other status types).
     • Match Rate Range: For user_data and composite_data uploads, check upload_match_rate_range.
   • Error Details: If status is FAILED or PARTIAL_SUCCESS, inspect each error's reason and record_count under error_info.error_counts.
   • Warning Details: Inspect each warning's reason and record_count under warning_info.warning_counts (even if the destination status is SUCCESS).

API Reference

• Send audience members guide
• REST API Reference

Data Manager API Event Ingestion

Implementation Workflow

Prerequisites

• Authentication & Library Installation: If you need to set up access to the Data Manager API or install the client and utility libraries, refer to the data-manager-api-setup skill.

Step 1: Identify Use Case & Read Documentation

• Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Floodlight, Google Analytics) BEFORE generating any code. Do not assume Google Ads by default. This maps to the account_type field of the operating_account in the Destination, and also determines valid event identifiers and requirements.
• Read Documentation: [CRITICAL] Follow the Send events guide to implement the integration, as steps for configuring and sending the request may vary between destinations.

Step 2: Retrieve Code Sample

[!IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Step 3: Retrieve Migration Guides

[!CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

Google Ads

• Google Ads API Offline Conversions: Google Ads Offline Conversions Migration Field Mappings
• Google Ads API Store Sales: Google Ads Store Sales Migration Field Mappings

Google Analytics

• Measurement Protocol (Google Analytics): Google Analytics Measurement Protocol Migration Field Mappings

Campaign Manager 360 (CM360)

• Campaign Manager 360 API Offline Conversions: Campaign Manager 360 Offline Conversions Migration Field Mappings

Step 4: Implementation

Implement the ingestion logic using the following checkpoints:

• Initialize Client: Instantiate the Data Manager client (IngestionServiceClient).
• Define Destinations: Build the Destination object using the product_destination_id and the appropriate account configurations: operating_account (target account receiving data), login_account (if authenticating using a manager account or a data partner account), and linked_account (if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
• Prepare Event Data: Use the utility library helpers to format and normalize user identifiers correctly.
• Construct Payload: Build the request payload (IngestEventsRequest) containing the destinations, event records, and consent permissions.
• Support Validation: Support sending the validate_only boolean option on the IngestEventsRequest to allow developers to validate schemas without actually uploading data.
• Send Request: Execute ingest_events and record the returned request ID for logging/troubleshooting.
• Retrieve Request Status: Check the status of the ingestion request using diagnostics. Since request processing is asynchronous, a successful ingestion response (HTTP 200 OK returning a request_id) only indicates the payload was received. To check if the records actually succeeded, partially succeeded, or failed to process, query the client.retrieve_request_status endpoint using the request_id. Skipping this step is a common user mistake.

Formatting

• Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

• Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

  Python Example:

  from google.ads.datamanager_util import Formatter
  from google.ads.datamanager_util.format import Encoding
  
  formatter: Formatter = Formatter()
  
  processed_email: str = formatter.process_email_address(
      email, Encoding.HEX
  )
  

Critical Gotchas

• Format product_destination_id as a numeric string. It is NOT a resource name path.
• Format event_timestamp strictly in RFC 3339 format. Use the SDK's typed timestamp object instead of a raw string where available.
• Nest click identifiers (gclid, gbraid, wbraid) inside the ad_identifiers block, not directly on the base event payload.
• The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
• Note that consent can be set globally on the IngestEventsRequest or on individual Events.
• Verify that UserIdentifier uses email_address and phone_number. Do not use the Google Ads API fields hashed_email and hashed_phone_number.
• Ensure the currency field on the event is named currency, not currency_code.
• Do not call the diagnostics endpoint (retrieve_request_status) if validate_only is set to true.

Error Handling & Troubleshooting

Inspecting Error Payloads

[!IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

Retrieving Request Status (Diagnostics)

Periodically poll for status using exponential backoff, starting at least 30 minutes after sending the IngestEventsRequest.

1. Call client.retrieve_request_status using RetrieveRequestStatusRequest(request_id=...).
2. Loop through request_status_per_destination in the response to inspect each target's request_status.
3. If processing is complete and request_status is SUCCESS, PARTIAL_SUCCESS, or FAILED, inspect diagnostic values:
   • Event Record Counts: Check events_ingestion_status.record_count (includes both success and failure).
   • Error Details: If status is FAILED or PARTIAL_SUCCESS, inspect each error's reason and record_count under error_info.error_counts.
   • Warning Details: Inspect each warning's reason and record_count under warning_info.warning_counts (even if the destination status is SUCCESS).

API Reference

• REST API Reference
• Diagnostics Guide

Data Manager API Setup

Setup Authentication

Refer to Set up API access for more details.

1. Enable API (Prerequisite): Check that the user has enabled the Data Manager API in their Google Cloud project.
2. Generate ADC: Authenticate the local workspace using Application Default Credentials (ADC) via gcloud auth application-default login.
   • Required Scopes: Include scopes https://www.googleapis.com/auth/datamanager and https://www.googleapis.com/auth/cloud-platform.
   • Multi-API Scopes: If using the same credentials for other APIs, append their scopes (e.g., https://www.googleapis.com/auth/adwords).
   • Service Accounts: Ensure the Service Account has the Service Usage Consumer IAM role, and the user executing gcloud has the Token Creator role (roles/iam.serviceAccountTokenCreator) on that Service Account for impersonation.

Install Client & Utility Libraries

Refer to Install a client library for more details.

The companion utility libraries provide pre-built helper classes and functions to correctly format, hash, and encrypt user identifiers (such as emails, phone numbers, and physical addresses) prior to API ingestion. Use of these libraries is highly recommended to ensure that user identifier formatting matches the API's specifications.

Select the language-specific installation guide below:

• Python Setup Reference (packages: google-ads-datamanager and google-ads-datamanager-util)
• Java Setup Reference (packages: com.google.api-ads:data-manager and data-manager-util)
• Node Setup Reference (packages: @google-ads/datamanager and @google-ads/data-manager-util)
• PHP Setup Reference (packages: googleads/data-manager and googleads/data-manager-util)
• .NET Setup Reference (packages: Google.Ads.DataManager.V1 and Google.Ads.DataManager.Util.csproj)

Data Manager API Audience Ingestion

Implementation Workflow

Prerequisites

• Authentication & Library Installation: If you need to set up access to the Data Manager API or install the client and utility libraries, refer to the data-manager-api-setup skill.

Step 1: Identify Use Case & Read Documentation

• Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Display & Video 360, etc.) BEFORE generating any code. Do not assume Google Ads by default. This maps to the account_type field of the operating_account in the Destination.
• Read Documentation: [CRITICAL] Follow the upload guide for your destination to implement the integration, as steps for configuring and sending the request may vary between destinations:
  • Google Ads Customer Match: Upload members to an audience
  • DV360 Customer Match: Upload members to an audience

Step 2: Retrieve Code Sample

[!IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Step 3: Retrieve Migration Guides

[!CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

Google Ads

• Google Ads API Customer Match: Google Ads API to Customer Match Migration Field Mappings

Display & Video 360

• Display & Video 360 API Customer Match: Display & Video 360 API to Customer Match Migration Field Mappings

Step 4: Implementation

Implement the ingestion logic using the following checkpoints:

• Initialize Client: Instantiate the Data Manager client (IngestionServiceClient).
• Define Destinations: Build the Destination object using the product_destination_id and the appropriate account configurations: operating_account (target account receiving data), login_account (if authenticating using a manager account or a data partner account), and linked_account (if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
• Format User Data: Use the utility library helpers to normalize and hash user identifiers correctly.
• Construct Payload: Build the request payload (IngestAudienceMembersRequest) containing the destinations, formatted members, and consent permissions.
• Support Validation: Support sending the validate_only boolean option on the IngestAudienceMembersRequest to allow developers to validate schemas without actually uploading data.
• Send Request: Execute ingest_audience_members and record the returned request ID for logging/troubleshooting.
• Retrieve Request Status: Check the status of the ingestion request using diagnostics. Since request processing is asynchronous, a successful ingestion response (HTTP 200 OK returning a request_id) only indicates the payload was received. To check if the records actually succeeded, partially succeeded, or failed to process, query client.retrieve_request_status using the request_id. Skipping this step is a common user mistake.

Formatting

• Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

• Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

  Python Example:

  from google.ads.datamanager_util import Formatter
  from google.ads.datamanager_util.format import Encoding
  
  formatter: Formatter = Formatter()
  
  processed_email: str = formatter.process_email_address(
      email, Encoding.HEX
  )
  

Critical Gotchas

• Only set the address field on UserIdentifier if all required fields (postal_code, family_name, given_name, region_code) are present; incomplete address fields will cause the API request to fail.
• product_destination_id must be a numeric string. It is NOT a resource name.
• The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
• Field names on UserIdentifier are email_address and phone_number. Do not use the Google Ads API field names hashed_email and hashed_phone_number.
• Do not call the diagnostics endpoint (retrieve_request_status) if validate_only is set to true.

Error Handling & Troubleshooting

Inspecting Error Payloads

[!IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

Retrieving Request Status (Diagnostics)

Periodically poll for status using exponential backoff, starting at least 30 minutes after sending the IngestAudienceMembersRequest.

1. Call client.retrieve_request_status using RetrieveRequestStatusRequest(request_id=...).
2. Loop through request_status_per_destination in the response to inspect each target's request_status.
3. If processing is complete and request_status is SUCCESS, PARTIAL_SUCCESS, or FAILED, inspect diagnostic values:
   • Audience Ingestion Status: Check the data-type-specific status nested under audience_members_ingestion_status (for example, composite_data_ingestion_status).
     • Record Count: Check record_count (includes both success and failure).
     • Identifier Counts: Check the data-type-specific count field (e.g., data_type_counts for composite_data_ingestion_status or user_identifier_count for user_data_ingestion_status; see the Diagnostics Guide for other status types).
     • Match Rate Range: For user_data and composite_data uploads, check upload_match_rate_range.
   • Error Details: If status is FAILED or PARTIAL_SUCCESS, inspect each error's reason and record_count under error_info.error_counts.
   • Warning Details: Inspect each warning's reason and record_count under warning_info.warning_counts (even if the destination status is SUCCESS).

API Reference

• Send audience members guide
• REST API Reference

Data Manager API Event Ingestion

Implementation Workflow

Prerequisites

• Authentication & Library Installation: If you need to set up access to the Data Manager API or install the client and utility libraries, refer to the data-manager-api-setup skill.

Step 1: Identify Use Case & Read Documentation

• Determine Destination Account Type: [CRITICAL] If it's not explicitly stated, STOP and CLARIFY with the user where the data is being sent (e.g., Google Ads, Floodlight, Google Analytics) BEFORE generating any code. Do not assume Google Ads by default. This maps to the account_type field of the operating_account in the Destination, and also determines valid event identifiers and requirements.
• Read Documentation: [CRITICAL] Follow the Send events guide to implement the integration, as steps for configuring and sending the request may vary between destinations.

Step 2: Retrieve Code Sample

[!IMPORTANT] If writing or updating an ingestion script, ALWAYS retrieve the relevant code sample to use as a reference:

Step 3: Retrieve Migration Guides

[!CRITICAL] If refactoring code to upgrade from another Google API, ALWAYS extract the full contents of the relevant field mapping guide.

Google Ads

• Google Ads API Offline Conversions: Google Ads Offline Conversions Migration Field Mappings
• Google Ads API Store Sales: Google Ads Store Sales Migration Field Mappings

Google Analytics

• Measurement Protocol (Google Analytics): Google Analytics Measurement Protocol Migration Field Mappings

Campaign Manager 360 (CM360)

• Campaign Manager 360 API Offline Conversions: Campaign Manager 360 Offline Conversions Migration Field Mappings

Step 4: Implementation

Implement the ingestion logic using the following checkpoints:

• Initialize Client: Instantiate the Data Manager client (IngestionServiceClient).
• Define Destinations: Build the Destination object using the product_destination_id and the appropriate account configurations: operating_account (target account receiving data), login_account (if authenticating using a manager account or a data partner account), and linked_account (if you're a data partner accessing the account via a partner link to a manager account). STRONGLY RECOMMENDED: Refer to the Configure destinations and headers guide for more details on configuring destinations.
• Prepare Event Data: Use the utility library helpers to format and normalize user identifiers correctly.
• Construct Payload: Build the request payload (IngestEventsRequest) containing the destinations, event records, and consent permissions.
• Support Validation: Support sending the validate_only boolean option on the IngestEventsRequest to allow developers to validate schemas without actually uploading data.
• Send Request: Execute ingest_events and record the returned request ID for logging/troubleshooting.
• Retrieve Request Status: Check the status of the ingestion request using diagnostics. Since request processing is asynchronous, a successful ingestion response (HTTP 200 OK returning a request_id) only indicates the payload was received. To check if the records actually succeeded, partially succeeded, or failed to process, query the client.retrieve_request_status endpoint using the request_id. Skipping this step is a common user mistake.

Formatting

• Fetch the Format user data guide and use that as the source of truth for formatting and normalization rules.

• Use the utility library to format, hash, and encrypt user data (emails, phone numbers, addresses).

  Python Example:

  from google.ads.datamanager_util import Formatter
  from google.ads.datamanager_util.format import Encoding
  
  formatter: Formatter = Formatter()
  
  processed_email: str = formatter.process_email_address(
      email, Encoding.HEX
  )
  

Critical Gotchas

• Format product_destination_id as a numeric string. It is NOT a resource name path.
• Format event_timestamp strictly in RFC 3339 format. Use the SDK's typed timestamp object instead of a raw string where available.
• Nest click identifiers (gclid, gbraid, wbraid) inside the ad_identifiers block, not directly on the base event payload.
• The enum values for ConsentStatus are CONSENT_GRANTED and CONSENT_DENIED. Do not use the values GRANTED and DENIED.
• Note that consent can be set globally on the IngestEventsRequest or on individual Events.
• Verify that UserIdentifier uses email_address and phone_number. Do not use the Google Ads API fields hashed_email and hashed_phone_number.
• Ensure the currency field on the event is named currency, not currency_code.
• Do not call the diagnostics endpoint (retrieve_request_status) if validate_only is set to true.

Error Handling & Troubleshooting

Inspecting Error Payloads

[!IMPORTANT] Refer to Understand API Errors for a detailed guide on how to understand the structure of errors returned by the API.

Retrieving Request Status (Diagnostics)

Periodically poll for status using exponential backoff, starting at least 30 minutes after sending the IngestEventsRequest.

1. Call client.retrieve_request_status using RetrieveRequestStatusRequest(request_id=...).
2. Loop through request_status_per_destination in the response to inspect each target's request_status.
3. If processing is complete and request_status is SUCCESS, PARTIAL_SUCCESS, or FAILED, inspect diagnostic values:
   • Event Record Counts: Check events_ingestion_status.record_count (includes both success and failure).
   • Error Details: If status is FAILED or PARTIAL_SUCCESS, inspect each error's reason and record_count under error_info.error_counts.
   • Warning Details: Inspect each warning's reason and record_count under warning_info.warning_counts (even if the destination status is SUCCESS).

API Reference

• REST API Reference
• Diagnostics Guide

Data Manager API Setup

Setup Authentication

Refer to Set up API access for more details.

1. Enable API (Prerequisite): Check that the user has enabled the Data Manager API in their Google Cloud project.
2. Generate ADC: Authenticate the local workspace using Application Default Credentials (ADC) via gcloud auth application-default login.
   • Required Scopes: Include scopes https://www.googleapis.com/auth/datamanager and https://www.googleapis.com/auth/cloud-platform.
   • Multi-API Scopes: If using the same credentials for other APIs, append their scopes (e.g., https://www.googleapis.com/auth/adwords).
   • Service Accounts: Ensure the Service Account has the Service Usage Consumer IAM role, and the user executing gcloud has the Token Creator role (roles/iam.serviceAccountTokenCreator) on that Service Account for impersonation.

Install Client & Utility Libraries

Refer to Install a client library for more details.

The companion utility libraries provide pre-built helper classes and functions to correctly format, hash, and encrypt user identifiers (such as emails, phone numbers, and physical addresses) prior to API ingestion. Use of these libraries is highly recommended to ensure that user identifier formatting matches the API's specifications.

Select the language-specific installation guide below:

• Python Setup Reference (packages: google-ads-datamanager and google-ads-datamanager-util)
• Java Setup Reference (packages: com.google.api-ads:data-manager and data-manager-util)
• Node Setup Reference (packages: @google-ads/datamanager and @google-ads/data-manager-util)
• PHP Setup Reference (packages: googleads/data-manager and googleads/data-manager-util)
• .NET Setup Reference (packages: Google.Ads.DataManager.V1 and Google.Ads.DataManager.Util.csproj)

Google Ads API MCP Server Installation

This skill provides a structured setup guide to install, configure, and integrate the official open-source Google Ads Model Context Protocol (MCP) Server.

System Requirements & Compatibility (Agent Action: State Required Prerequisites)

When answering questions about installing or setting up the MCP server, you MUST explicitly state to the user that both Python 3.12+ and pipx are strictly required prerequisites for the installation.

[!IMPORTANT] Pre-Flight Environment Check:

• Python Runtime: Version 3.12+ is strictly required.
• Package Manager: pipx must be installed and globally accessible in the system path.
• Network Connectivity: Outbound HTTPS access is required to connect to the Google Ads API endpoints (googleads.googleapis.com) and PyPI.

⚠️ Prerequisites: Credentials Required

[!WARNING] Dependency Check: The MCP server requires the same 5 authentication credentials as a standard integration.

If you do not have your Developer Token, Client ID, Client Secret, Refresh Token, and Customer IDs yet:

1. STOP executing this skill.
2. Transition to the google-ads-api-quickstart skill first to generate them, then return here.

Step 1: Validate Your Google Ads API Credentials

The Google Ads MCP Server requires the same five parameters as the standard client libraries. Before proceeding to installation, verify that you have these values secured and formatted correctly:

1. Developer Token: Your unique API access key from the API Center (Manager Account).
2. OAuth2 Client ID & Client Secret: Desktop Application credentials from the Google Cloud Console.
3. OAuth2 Refresh Token: The long-lived token generated via the OAuth consent flow.
4. Client Customer ID: The 10-digit target Google Ads account ID.

   • [!IMPORTANT]

   • Format: Must contain digits only, no hyphens (e.g., 1234567890, NOT 123-456-7890).

5. Login Customer ID (Required for MCC Hierarchies): The 10-digit Manager Account (MCC) ID.
   • Format: Digits only, no hyphens (e.g., 9876543210).
   • Note: Essential if your OAuth credentials belong to a Manager Account administrator rather than directly to the client account.

Once you have verified that all five parameters are present and formatted correctly, proceed to Step 2.

Step 2: Install Prerequisites (Python & pipx)

You MUST verify if the prerequisites are already installed before proposing any installation commands.

1. Verification Phase (Agent Action)

You MUST run the following commands to check the environment:

1. Check Python version: python3 --version (Verify it is 3.12+).
2. Check if pipx is installed: pipx --version.

• If both are present: Skip the installation phase and proceed directly to Step 3.
• If Python is missing/outdated: Stop and ask the user to upgrade Python to 3.12+ on their host machine.
• If pipx is missing: Proceed to the installation phase below.

2. Installation Phase (OS-Specific)

Detect the operating system and propose the appropriate command to install pipx using your terminal tools:

macOS

If the environment is macOS, propose:

brew install pipx && pipx ensurepath
# Or alternatively (if Homebrew is not installed):
pip install pipx && pipx ensurepath

Windows (PowerShell)

If the environment is Windows, propose:

scoop install pipx
# Or alternatively:
pip install pipx && pipx ensurepath

Linux (Ubuntu/Debian)

If the environment is Linux, propose:

sudo apt install pipx && pipx ensurepath

[!WARNING] Shell Restart Required: If you installed pipx and ran pipx ensurepath, the updated PATH will not be available in the current terminal session.

1. DO NOT immediately attempt to run pipx commands in the same session.
2. Instruct the user to restart their terminal or reload their shell configuration before proceeding to Step 3.

Step 3: Install the Google Ads MCP Server

You must install the server package. By default, you MUST install the stable release from PyPI. Only install the GitHub development version if the user explicitly requests it.

1. Installation Command

Propose and execute the installation command:

# Install stable release from PyPI (Using required package manager pipx)
pipx install google-ads-mcp

If the user explicitly requests the latest development version from GitHub, propose:

# Install development version from GitHub (Only if explicitly requested)
pipx install git+https://github.com/googleads/google-ads-mcp.git

2. Verification Phase

To verify the installation, execute:

google-ads-mcp --help

Troubleshooting PATH Issues (Agent Action)

pipx installs binaries into a specific local directory (typically ~/.local/bin). If the user's shell configuration (e.g., .bashrc or .zshrc) hasn't been reloaded, google-ads-mcp might not be found in the current PATH.

If google-ads-mcp --help fails with a "command not found" error:

1. DO NOT assume the installation failed or get stuck in an installation loop.

2. Verify the installation using the absolute path to the pipx binary directory:

   ~/.local/bin/google-ads-mcp --help
   

3. If the absolute path verification succeeds, explain the situation to the user: inform them that the installation was successful but their PATH environment variable needs to be updated by reloading their shell configuration (e.g., running source ~/.bashrc or source ~/.zshrc, or restarting their terminal).

3. Communication Protocol: Stdio Transport

[!IMPORTANT] Mandatory Agent Directive (Installation & Protocol Checklist): When a user asks how to install, download, or set up the official Google Ads MCP server, your response MUST systematically include all of the following:

1. State Prerequisites: Explicitly state that Python 3.12+ and pipx are required prerequisites.
2. Provide Official Install Command: Direct the developer to install the official google-ads-mcp package using pipx install google-ads-mcp. Do not suggest third-party unvetted servers.
3. Explain Stdio Transport: You MUST explicitly explain the communication architecture using the exact terminology: state that the MCP server communicates via the Model Context Protocol (MCP) using standard input/output (stdio) transport. Do not omit the words "standard input/output" or "transport".

Key points to explain to the user regarding Stdio Transport:

• Subprocess Execution: The host client (e.g., Cursor, Claude Desktop) launches the MCP server as a background subprocess.
• Command-Line Launch: The host client must be configured with the exact command to run the server (google-ads-mcp) and the environment variables containing your Google Ads credentials.
• No Network Ports: Because it uses stdio, the server does not listen on a network port (like HTTP or WebSockets). Communication is handled entirely via stdin/stdout piping.

[!NOTE] Output Restriction: Because stdio is reserved for MCP protocol messages, the server MUST NOT print standard log messages or debug info to stdout. All logging and debugging are routed to stderr.

Step 4: Configure Environment Variables

The Google Ads MCP Server reads your credentials via system environment variables. You can configure these in two ways:

• Method A (Recommended): Pass them directly in the MCP client's JSON configuration file (e.g., Cursor or Claude Desktop settings). This isolates the credentials to the specific tool.
• Method B (Alternative): Set them globally in your shell profile (e.g., ~/.bashrc, ~/.zshrc, or Windows Environment Variables).

Required Environment Variables

Method B: Shell Profile Configuration (Global)

If choosing Method B, append the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):

# Google Ads MCP Server Credentials
export GOOGLE_ADS_DEVELOPER_TOKEN="your_developer_token_here"
export GOOGLE_ADS_CLIENT_ID="your_oauth_client_id_here"
export GOOGLE_ADS_CLIENT_SECRET="your_oauth_client_secret_here"
export GOOGLE_ADS_REFRESH_TOKEN="your_oauth_refresh_token_here"

# Required only for Manager Account hierarchies:
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="your_manager_account_id_here"

# Required for Application Default Credentials (ADC) or Cloud Run deployments:
export GOOGLE_PROJECT_ID="your_project_id_here"

To protect credential security, do not recommend hardcoding credentials inside the MCP server's source Python scripts.

Step 5: Integrate with Your AI Developer Tool

Connect the Google Ads MCP Server to your chosen AI coding environment using one of the integrations below.

1. Claude Desktop (or Claude Code CLI)

[!IMPORTANT] Mandatory Agent Directive (Claude Desktop Configuration Checklist): When a user asks how to configure Claude Desktop or Claude Code to use the Google Ads MCP server, your response MUST systematically include all of the following:

1. Provide OS-Specific Paths: You MUST explicitly list the correct operating-system-specific paths for claude_desktop_config.json on macOS (~/Library/Application Support/Claude/claude_desktop_config.json) and Windows (%APPDATA%\Claude\claude_desktop_config.json). Do not omit macOS or Windows paths even if running on Linux.
2. Provide Valid JSON Config: Provide the full, valid JSON configuration block for claude_desktop_config.json.
3. Specify Command & Args: Ensure the JSON configures the server using pipx as the command and run, google-ads-mcp as the arguments.
4. Declare Auth Environment Variables: Declare environment variables GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, and GOOGLE_ADS_REFRESH_TOKEN within the configuration.

Add the server entry to your Claude configuration file.

• File Locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

• Configuration JSON:

  {
    "mcpServers": {
      "google-ads": {
        "command": "pipx",
        "args": [
          "run",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
          "GOOGLE_ADS_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
          "GOOGLE_ADS_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
          "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_OAUTH_REFRESH_TOKEN",
          "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_IF_APPLICABLE"
        }
      }
    }
  }
  

  (Note: Using pipx run is recommended as it automatically manages the execution path. If you are using the GitHub development version or Application Default Credentials, you can alternatively configure "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"] and include "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID" in the env block).

2. Cursor AI Editor

1. Open Cursor and navigate to: Settings 🡒 Features 🡒 MCP.
2. Click + New MCP Server.
3. Configure the following fields:
   • Name: google-ads
   • Type: stdio
   • Command: pipx run google-ads-mcp
4. Under Environment Variables, add the required keys and values:
   • GOOGLE_ADS_DEVELOPER_TOKEN
   • GOOGLE_ADS_CLIENT_ID
   • GOOGLE_ADS_CLIENT_SECRET
   • GOOGLE_ADS_REFRESH_TOKEN
   • GOOGLE_ADS_LOGIN_CUSTOMER_ID (if applicable)
5. Click Save.

3. Antigravity IDE & CLI Integration

When answering questions about connecting the Google Ads MCP server to Antigravity (IDE or CLI), you MUST explicitly explain the following architectural and configuration details:

• Mandatory Environment Setup: Instruct the user to configure and export standard environment variables (such as GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN) in their terminal session or IDE environment.
• Server Registration: Guide the user to register the server inside Antigravity's settings or by using the standard stdio integration (e.g., configuring the command pipx run google-ads-mcp).
• Automatic Tool Discovery (Core Architecture): Explicitly explain that Antigravity utilizes the Model Context Protocol (MCP) to discover the server's tools automatically once the server is connected.
• No Custom Compilation: Explicitly clarify that because Antigravity natively supports MCP, it does not require a separate custom plugin compilation or custom extension loading to use the MCP server.

Verifying Activation in Antigravity CLI

1. Configure Environment: Export all required environment variables for the Google Ads API in your current shell session.

2. Start Antigravity CLI: Launch the CLI:

   agy
   

3. Verify MCP Status: Inside the Antigravity CLI prompt, run the /mcp command to list active tools and servers:

   /mcp
   

4. Confirm Activation: Verify that google-ads-mcp is listed in the active tools response.

[!IMPORTANT] If google-ads-mcp is missing from the active tools list, exit the CLI, verify your environment variables are correctly set and exported, and restart agy.

Step 5.5: Deployment on Google Cloud (Cloud Run)

Instead of hosting this MCP server locally, you can host it on Google Cloud Run or on any other cloud-based infrastructure. This is useful if you want to share the server across different agents or run it as a web service.

1. Prerequisites

1. A Google Cloud project.

2. The gcloud command-line tool installed, authenticated, and with an active project configured:

   gcloud config set project YOUR_PROJECT_ID
   

2. Build and Push a Docker Image

You can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally:

1. Create a repository in Artifact Registry:

   gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1
   

2. Build and submit the image:

   gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
   

   (Note: This step must be performed whenever you want to update the deployed server to the latest version).

3. Deploy to Google Cloud Run

Deploy the container, ensuring you set FASTMCP_HOST=0.0.0.0 and all required environment variables:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

4. Configure the MCP Client

After deployment, update your MCP client configuration (for example, ~/.gemini/settings.json or Claude/Cursor config) to use the Cloud Run URL:

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Step 6: Verify the Integration (Testing)

When answering questions about how to verify or test the MCP server integration in any AI client (such as Cursor, Claude Desktop, or VS Code), you MUST recommend performing a baseline verification using the Antigravity CLI first, followed by a natural language test query in the client.

1. Baseline Verification via Antigravity CLI (Mandatory Agent Action)

Regardless of which AI client the user is configuring, always instruct the user to verify that google-ads-mcp is active and healthy using the /mcp command inside the Antigravity CLI prompt:

agy

/mcp

• Explain the Why: Inform the user that verifying via the Antigravity CLI first is the fastest way to isolate core credential, network, or server-start issues. Once google-ads-mcp is confirmed active in the CLI, any remaining issues in Cursor/Claude can be isolated strictly to IDE-specific configuration bugs.

2. Run a Test Query in Your AI Assistant

In your AI assistant's chat interface, run one of the following queries. Be sure to replace 1234567890 with your actual Google Ads Customer ID (without hyphens):

• “Retrieve all campaigns from my Google Ads account 1234567890.”
• “What is the status of the campaigns in Google Ads account 1234567890?”

3. Expected Behavior (Success Criteria)

A successful integration will trigger the following flow:

1. Tool Discovery: The AI assistant automatically detects the google-ads-mcp server tools.
2. Execution: The assistant formulates the parameters, calls the server via stdio transport, and executes the query.
3. Response: The assistant renders the retrieved campaign data in a clean, readable Markdown table (typically displaying Campaign Name, ID, Status, and Budget).

4. Troubleshooting

If the assistant fails to retrieve the data or connect to the MCP server, check the following common failure points:

• Authentication/Permission Errors (IDE Environment Gotcha): External IDEs (like Cursor or VS Code) often run in isolated environments or background processes that do not inherit shell RC files (e.g., ~/.bashrc or ~/.zshrc). Ensure your GOOGLE_ADS_DEVELOPER_TOKEN, OAuth client credentials, and GOOGLE_ADS_REFRESH_TOKEN are explicitly configured where the IDE can access them (prefer Method A: setting them directly in the MCP client's JSON configuration).
• "Tools not found" / Mandatory Client Restart: MCP servers are only loaded on application startup; changes to configuration files will not take effect dynamically. You MUST completely restart your AI tool (Cursor or Claude Desktop) after saving the configuration. Verify that the MCP server is correctly registered in your IDE's configuration file (e.g., the mcpServers block in Cursor's project.json or Claude Desktop's config).
• PATH and Executable Issues (spawn pipx ENOENT): If the connection fails or logs show spawn pipx ENOENT, pipx is not in the system PATH of the IDE's environment. Provide the absolute path to pipx in the "command" field of your config (e.g., /usr/local/bin/pipx or ~/.local/bin/pipx).
• Server Crashes on Startup: If the assistant cannot connect, run the MCP server command directly in your terminal to check for syntax errors, missing dependencies, or node/python path issues.

[!IMPORTANT] Verify Connection Status & Logs:

• In Cursor, ensure the green dot appears next to the google-ads server in the MCP settings.
• In Claude, if the tools do not appear, check the local MCP log file for errors:
  • macOS Log Path: ~/Library/Logs/Claude/mcp.log
  • Windows Log Path: %APPDATA%\Claude\Logs\mcp.log

Step 7: Available MCP Tools & Usage Guide

Once the Google Ads MCP Server is installed and successfully connected to your AI assistant, the server exposes specific tools that the assistant can discover and invoke autonomously.

[!IMPORTANT] Mandatory Agent Directive (Tool Explanation Checklist): When a user asks what tools the Google Ads MCP server provides or how to use them, your response MUST systematically include all of the following:

1. List All 3 Tools: Explicitly name list_accessible_customers, get_resource_metadata, and search.
2. Define Purpose & Usage: Explain exactly what each tool does and how/when to invoke it.
3. Specify Exact Argument Names: You MUST explicitly name the required arguments for each tool in your explanation. E.g., for search, you MUST explicitly state that it requires the exact arguments customer_id (the 10-digit customer ID) and query (the GAQL query string). Do not paraphrase customer_id to "account".
4. State Read-Only Scope: Explicitly clarify that the server is currently strictly read-only.

When assisting a user or formulating queries, refer to the following tool definitions and best practices:

1. list_accessible_customers

• Purpose: Returns the list of Google Ads customer IDs and account names that are accessible to the authenticated user.
• How to Use: Call this tool first when starting a new session or when the target customer ID is unknown. It requires no arguments.
• Example Intent: "What Google Ads accounts do I have access to?"

2. get_resource_metadata

• Purpose: Retrieves detailed structural metadata about a specific Google Ads API resource type (e.g., campaign, ad_group, customer).
• How to Use: Call this tool to inspect the schema, available fields, metrics, and segments for a resource before constructing a GAQL query.
• Arguments:
  • resource (string, required): The name of the resource to inspect (e.g., campaign).
• Example Intent: "What fields and metrics can I query for an ad group?"

3. search

• Purpose: Executes a Google Ads Query Language (GAQL) query to fetch resource metrics, attributes, segments, and status.
• How to Use: Construct a valid GAQL query string based on the resource metadata and execute the search against a specific customer account.
• Arguments:
  • customer_id (string, required): The 10-digit target Google Ads customer ID (digits only, no hyphens).
  • query (string, required): A valid GAQL query string (e.g., SELECT campaign.id, campaign.name, campaign.status, metrics.impressions FROM campaign WHERE campaign.status = 'ENABLED').
• Example Intent: "Get the impressions and status of all enabled campaigns for account 1234567890."

[!NOTE] Read-Only Scope: The Google Ads MCP Server is currently strictly read-only. It cannot modify bids, pause campaigns, or create new advertising assets.

Google Ads API MCP Server Installation

This skill provides a structured setup guide to install, configure, and integrate the official open-source Google Ads Model Context Protocol (MCP) Server.

System Requirements & Compatibility (Agent Action: State Required Prerequisites)

When answering questions about installing or setting up the MCP server, you MUST explicitly state to the user that both Python 3.12+ and pipx are strictly required prerequisites for the installation.

[!IMPORTANT] Pre-Flight Environment Check:

• Python Runtime: Version 3.12+ is strictly required.
• Package Manager: pipx must be installed and globally accessible in the system path.
• Network Connectivity: Outbound HTTPS access is required to connect to the Google Ads API endpoints (googleads.googleapis.com) and PyPI.

⚠️ Prerequisites: Credentials Required

[!WARNING] Dependency Check: The MCP server requires the same 5 authentication credentials as a standard integration.

If you do not have your Developer Token, Client ID, Client Secret, Refresh Token, and Customer IDs yet:

1. STOP executing this skill.
2. Transition to the google-ads-api-quickstart skill first to generate them, then return here.

Step 1: Validate Your Google Ads API Credentials

The Google Ads MCP Server requires the same five parameters as the standard client libraries. Before proceeding to installation, verify that you have these values secured and formatted correctly:

1. Developer Token: Your unique API access key from the API Center (Manager Account).
2. OAuth2 Client ID & Client Secret: Desktop Application credentials from the Google Cloud Console.
3. OAuth2 Refresh Token: The long-lived token generated via the OAuth consent flow.
4. Client Customer ID: The 10-digit target Google Ads account ID.

   • [!IMPORTANT]

   • Format: Must contain digits only, no hyphens (e.g., 1234567890, NOT 123-456-7890).

5. Login Customer ID (Required for MCC Hierarchies): The 10-digit Manager Account (MCC) ID.
   • Format: Digits only, no hyphens (e.g., 9876543210).
   • Note: Essential if your OAuth credentials belong to a Manager Account administrator rather than directly to the client account.

Once you have verified that all five parameters are present and formatted correctly, proceed to Step 2.

Step 2: Install Prerequisites (Python & pipx)

You MUST verify if the prerequisites are already installed before proposing any installation commands.

1. Verification Phase (Agent Action)

You MUST run the following commands to check the environment:

1. Check Python version: python3 --version (Verify it is 3.12+).
2. Check if pipx is installed: pipx --version.

• If both are present: Skip the installation phase and proceed directly to Step 3.
• If Python is missing/outdated: Stop and ask the user to upgrade Python to 3.12+ on their host machine.
• If pipx is missing: Proceed to the installation phase below.

2. Installation Phase (OS-Specific)

Detect the operating system and propose the appropriate command to install pipx using your terminal tools:

macOS

If the environment is macOS, propose:

brew install pipx && pipx ensurepath
# Or alternatively (if Homebrew is not installed):
pip install pipx && pipx ensurepath

Windows (PowerShell)

If the environment is Windows, propose:

scoop install pipx
# Or alternatively:
pip install pipx && pipx ensurepath

Linux (Ubuntu/Debian)

If the environment is Linux, propose:

sudo apt install pipx && pipx ensurepath

[!WARNING] Shell Restart Required: If you installed pipx and ran pipx ensurepath, the updated PATH will not be available in the current terminal session.

1. DO NOT immediately attempt to run pipx commands in the same session.
2. Instruct the user to restart their terminal or reload their shell configuration before proceeding to Step 3.

Step 3: Install the Google Ads MCP Server

You must install the server package. By default, you MUST install the stable release from PyPI. Only install the GitHub development version if the user explicitly requests it.

1. Installation Command

Propose and execute the installation command:

# Install stable release from PyPI (Using required package manager pipx)
pipx install google-ads-mcp

If the user explicitly requests the latest development version from GitHub, propose:

# Install development version from GitHub (Only if explicitly requested)
pipx install git+https://github.com/googleads/google-ads-mcp.git

2. Verification Phase

To verify the installation, execute:

google-ads-mcp --help

Troubleshooting PATH Issues (Agent Action)

pipx installs binaries into a specific local directory (typically ~/.local/bin). If the user's shell configuration (e.g., .bashrc or .zshrc) hasn't been reloaded, google-ads-mcp might not be found in the current PATH.

If google-ads-mcp --help fails with a "command not found" error:

1. DO NOT assume the installation failed or get stuck in an installation loop.

2. Verify the installation using the absolute path to the pipx binary directory:

   ~/.local/bin/google-ads-mcp --help
   

3. If the absolute path verification succeeds, explain the situation to the user: inform them that the installation was successful but their PATH environment variable needs to be updated by reloading their shell configuration (e.g., running source ~/.bashrc or source ~/.zshrc, or restarting their terminal).

3. Communication Protocol: Stdio Transport

[!IMPORTANT] Mandatory Agent Directive (Installation & Protocol Checklist): When a user asks how to install, download, or set up the official Google Ads MCP server, your response MUST systematically include all of the following:

1. State Prerequisites: Explicitly state that Python 3.12+ and pipx are required prerequisites.
2. Provide Official Install Command: Direct the developer to install the official google-ads-mcp package using pipx install google-ads-mcp. Do not suggest third-party unvetted servers.
3. Explain Stdio Transport: You MUST explicitly explain the communication architecture using the exact terminology: state that the MCP server communicates via the Model Context Protocol (MCP) using standard input/output (stdio) transport. Do not omit the words "standard input/output" or "transport".

Key points to explain to the user regarding Stdio Transport:

• Subprocess Execution: The host client (e.g., Cursor, Claude Desktop) launches the MCP server as a background subprocess.
• Command-Line Launch: The host client must be configured with the exact command to run the server (google-ads-mcp) and the environment variables containing your Google Ads credentials.
• No Network Ports: Because it uses stdio, the server does not listen on a network port (like HTTP or WebSockets). Communication is handled entirely via stdin/stdout piping.

[!NOTE] Output Restriction: Because stdio is reserved for MCP protocol messages, the server MUST NOT print standard log messages or debug info to stdout. All logging and debugging are routed to stderr.

Step 4: Configure Environment Variables

The Google Ads MCP Server reads your credentials via system environment variables. You can configure these in two ways:

• Method A (Recommended): Pass them directly in the MCP client's JSON configuration file (e.g., Cursor or Claude Desktop settings). This isolates the credentials to the specific tool.
• Method B (Alternative): Set them globally in your shell profile (e.g., ~/.bashrc, ~/.zshrc, or Windows Environment Variables).

Required Environment Variables

Method B: Shell Profile Configuration (Global)

If choosing Method B, append the following to your shell profile (~/.bashrc, ~/.zshrc, etc.):

# Google Ads MCP Server Credentials
export GOOGLE_ADS_DEVELOPER_TOKEN="your_developer_token_here"
export GOOGLE_ADS_CLIENT_ID="your_oauth_client_id_here"
export GOOGLE_ADS_CLIENT_SECRET="your_oauth_client_secret_here"
export GOOGLE_ADS_REFRESH_TOKEN="your_oauth_refresh_token_here"

# Required only for Manager Account hierarchies:
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="your_manager_account_id_here"

# Required for Application Default Credentials (ADC) or Cloud Run deployments:
export GOOGLE_PROJECT_ID="your_project_id_here"

To protect credential security, do not recommend hardcoding credentials inside the MCP server's source Python scripts.

Step 5: Integrate with Your AI Developer Tool

Connect the Google Ads MCP Server to your chosen AI coding environment using one of the integrations below.

1. Claude Desktop (or Claude Code CLI)

[!IMPORTANT] Mandatory Agent Directive (Claude Desktop Configuration Checklist): When a user asks how to configure Claude Desktop or Claude Code to use the Google Ads MCP server, your response MUST systematically include all of the following:

1. Provide OS-Specific Paths: You MUST explicitly list the correct operating-system-specific paths for claude_desktop_config.json on macOS (~/Library/Application Support/Claude/claude_desktop_config.json) and Windows (%APPDATA%\Claude\claude_desktop_config.json). Do not omit macOS or Windows paths even if running on Linux.
2. Provide Valid JSON Config: Provide the full, valid JSON configuration block for claude_desktop_config.json.
3. Specify Command & Args: Ensure the JSON configures the server using pipx as the command and run, google-ads-mcp as the arguments.
4. Declare Auth Environment Variables: Declare environment variables GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, and GOOGLE_ADS_REFRESH_TOKEN within the configuration.

Add the server entry to your Claude configuration file.

• File Locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

• Configuration JSON:

  {
    "mcpServers": {
      "google-ads": {
        "command": "pipx",
        "args": [
          "run",
          "google-ads-mcp"
        ],
        "env": {
          "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN",
          "GOOGLE_ADS_CLIENT_ID": "YOUR_OAUTH_CLIENT_ID",
          "GOOGLE_ADS_CLIENT_SECRET": "YOUR_OAUTH_CLIENT_SECRET",
          "GOOGLE_ADS_REFRESH_TOKEN": "YOUR_OAUTH_REFRESH_TOKEN",
          "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_IF_APPLICABLE"
        }
      }
    }
  }
  

  (Note: Using pipx run is recommended as it automatically manages the execution path. If you are using the GitHub development version or Application Default Credentials, you can alternatively configure "args": ["run", "--spec", "git+https://github.com/googleads/google-ads-mcp.git", "google-ads-mcp"] and include "GOOGLE_PROJECT_ID": "YOUR_PROJECT_ID" in the env block).

2. Cursor AI Editor

1. Open Cursor and navigate to: Settings 🡒 Features 🡒 MCP.
2. Click + New MCP Server.
3. Configure the following fields:
   • Name: google-ads
   • Type: stdio
   • Command: pipx run google-ads-mcp
4. Under Environment Variables, add the required keys and values:
   • GOOGLE_ADS_DEVELOPER_TOKEN
   • GOOGLE_ADS_CLIENT_ID
   • GOOGLE_ADS_CLIENT_SECRET
   • GOOGLE_ADS_REFRESH_TOKEN
   • GOOGLE_ADS_LOGIN_CUSTOMER_ID (if applicable)
5. Click Save.

3. Antigravity IDE & CLI Integration

When answering questions about connecting the Google Ads MCP server to Antigravity (IDE or CLI), you MUST explicitly explain the following architectural and configuration details:

• Mandatory Environment Setup: Instruct the user to configure and export standard environment variables (such as GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, GOOGLE_ADS_REFRESH_TOKEN) in their terminal session or IDE environment.
• Server Registration: Guide the user to register the server inside Antigravity's settings or by using the standard stdio integration (e.g., configuring the command pipx run google-ads-mcp).
• Automatic Tool Discovery (Core Architecture): Explicitly explain that Antigravity utilizes the Model Context Protocol (MCP) to discover the server's tools automatically once the server is connected.
• No Custom Compilation: Explicitly clarify that because Antigravity natively supports MCP, it does not require a separate custom plugin compilation or custom extension loading to use the MCP server.

Verifying Activation in Antigravity CLI

1. Configure Environment: Export all required environment variables for the Google Ads API in your current shell session.

2. Start Antigravity CLI: Launch the CLI:

   agy
   

3. Verify MCP Status: Inside the Antigravity CLI prompt, run the /mcp command to list active tools and servers:

   /mcp
   

4. Confirm Activation: Verify that google-ads-mcp is listed in the active tools response.

[!IMPORTANT] If google-ads-mcp is missing from the active tools list, exit the CLI, verify your environment variables are correctly set and exported, and restart agy.

Step 5.5: Deployment on Google Cloud (Cloud Run)

Instead of hosting this MCP server locally, you can host it on Google Cloud Run or on any other cloud-based infrastructure. This is useful if you want to share the server across different agents or run it as a web service.

1. Prerequisites

1. A Google Cloud project.

2. The gcloud command-line tool installed, authenticated, and with an active project configured:

   gcloud config set project YOUR_PROJECT_ID
   

2. Build and Push a Docker Image

You can use Cloud Build to build and push the image to the Artifact Registry without needing Docker installed locally:

1. Create a repository in Artifact Registry:

   gcloud artifacts repositories create mcp-servers --repository-format=docker --location=us-central1
   

2. Build and submit the image:

   gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest .
   

   (Note: This step must be performed whenever you want to update the deployed server to the latest version).

3. Deploy to Google Cloud Run

Deploy the container, ensuring you set FASTMCP_HOST=0.0.0.0 and all required environment variables:

gcloud run deploy google-ads-mcp \
  --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/mcp-servers/google-ads-mcp:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_PROJECT_ID=YOUR_PROJECT_ID,GOOGLE_ADS_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN,GOOGLE_ADS_MCP_OAUTH_CLIENT_ID=YOUR_CLIENT_ID,GOOGLE_ADS_MCP_OAUTH_CLIENT_SECRET=YOUR_CLIENT_SECRET,GOOGLE_ADS_MCP_BASE_URL=YOUR_BASE_URL,FASTMCP_HOST=0.0.0.0"

4. Configure the MCP Client

After deployment, update your MCP client configuration (for example, ~/.gemini/settings.json or Claude/Cursor config) to use the Cloud Run URL:

{
  "mcpServers": {
    "google-ads-mcp": {
      "httpUrl": "https://your-cloud-run-url.a.run.app/mcp"
    }
  }
}

Step 6: Verify the Integration (Testing)

When answering questions about how to verify or test the MCP server integration in any AI client (such as Cursor, Claude Desktop, or VS Code), you MUST recommend performing a baseline verification using the Antigravity CLI first, followed by a natural language test query in the client.

1. Baseline Verification via Antigravity CLI (Mandatory Agent Action)

Regardless of which AI client the user is configuring, always instruct the user to verify that google-ads-mcp is active and healthy using the /mcp command inside the Antigravity CLI prompt:

agy

/mcp

• Explain the Why: Inform the user that verifying via the Antigravity CLI first is the fastest way to isolate core credential, network, or server-start issues. Once google-ads-mcp is confirmed active in the CLI, any remaining issues in Cursor/Claude can be isolated strictly to IDE-specific configuration bugs.

2. Run a Test Query in Your AI Assistant

In your AI assistant's chat interface, run one of the following queries. Be sure to replace 1234567890 with your actual Google Ads Customer ID (without hyphens):

• “Retrieve all campaigns from my Google Ads account 1234567890.”
• “What is the status of the campaigns in Google Ads account 1234567890?”

3. Expected Behavior (Success Criteria)

A successful integration will trigger the following flow:

1. Tool Discovery: The AI assistant automatically detects the google-ads-mcp server tools.
2. Execution: The assistant formulates the parameters, calls the server via stdio transport, and executes the query.
3. Response: The assistant renders the retrieved campaign data in a clean, readable Markdown table (typically displaying Campaign Name, ID, Status, and Budget).

4. Troubleshooting

If the assistant fails to retrieve the data or connect to the MCP server, check the following common failure points:

• Authentication/Permission Errors (IDE Environment Gotcha): External IDEs (like Cursor or VS Code) often run in isolated environments or background processes that do not inherit shell RC files (e.g., ~/.bashrc or ~/.zshrc). Ensure your GOOGLE_ADS_DEVELOPER_TOKEN, OAuth client credentials, and GOOGLE_ADS_REFRESH_TOKEN are explicitly configured where the IDE can access them (prefer Method A: setting them directly in the MCP client's JSON configuration).
• "Tools not found" / Mandatory Client Restart: MCP servers are only loaded on application startup; changes to configuration files will not take effect dynamically. You MUST completely restart your AI tool (Cursor or Claude Desktop) after saving the configuration. Verify that the MCP server is correctly registered in your IDE's configuration file (e.g., the mcpServers block in Cursor's project.json or Claude Desktop's config).
• PATH and Executable Issues (spawn pipx ENOENT): If the connection fails or logs show spawn pipx ENOENT, pipx is not in the system PATH of the IDE's environment. Provide the absolute path to pipx in the "command" field of your config (e.g., /usr/local/bin/pipx or ~/.local/bin/pipx).
• Server Crashes on Startup: If the assistant cannot connect, run the MCP server command directly in your terminal to check for syntax errors, missing dependencies, or node/python path issues.

[!IMPORTANT] Verify Connection Status & Logs:

• In Cursor, ensure the green dot appears next to the google-ads server in the MCP settings.
• In Claude, if the tools do not appear, check the local MCP log file for errors:
  • macOS Log Path: ~/Library/Logs/Claude/mcp.log
  • Windows Log Path: %APPDATA%\Claude\Logs\mcp.log

Step 7: Available MCP Tools & Usage Guide

Once the Google Ads MCP Server is installed and successfully connected to your AI assistant, the server exposes specific tools that the assistant can discover and invoke autonomously.

[!IMPORTANT] Mandatory Agent Directive (Tool Explanation Checklist): When a user asks what tools the Google Ads MCP server provides or how to use them, your response MUST systematically include all of the following:

1. List All 3 Tools: Explicitly name list_accessible_customers, get_resource_metadata, and search.
2. Define Purpose & Usage: Explain exactly what each tool does and how/when to invoke it.
3. Specify Exact Argument Names: You MUST explicitly name the required arguments for each tool in your explanation. E.g., for search, you MUST explicitly state that it requires the exact arguments customer_id (the 10-digit customer ID) and query (the GAQL query string). Do not paraphrase customer_id to "account".
4. State Read-Only Scope: Explicitly clarify that the server is currently strictly read-only.

When assisting a user or formulating queries, refer to the following tool definitions and best practices:

1. list_accessible_customers

• Purpose: Returns the list of Google Ads customer IDs and account names that are accessible to the authenticated user.
• How to Use: Call this tool first when starting a new session or when the target customer ID is unknown. It requires no arguments.
• Example Intent: "What Google Ads accounts do I have access to?"

2. get_resource_metadata

• Purpose: Retrieves detailed structural metadata about a specific Google Ads API resource type (e.g., campaign, ad_group, customer).
• How to Use: Call this tool to inspect the schema, available fields, metrics, and segments for a resource before constructing a GAQL query.
• Arguments:
  • resource (string, required): The name of the resource to inspect (e.g., campaign).
• Example Intent: "What fields and metrics can I query for an ad group?"

3. search

• Purpose: Executes a Google Ads Query Language (GAQL) query to fetch resource metrics, attributes, segments, and status.
• How to Use: Construct a valid GAQL query string based on the resource metadata and execute the search against a specific customer account.
• Arguments:
  • customer_id (string, required): The 10-digit target Google Ads customer ID (digits only, no hyphens).
  • query (string, required): A valid GAQL query string (e.g., SELECT campaign.id, campaign.name, campaign.status, metrics.impressions FROM campaign WHERE campaign.status = 'ENABLED').
• Example Intent: "Get the impressions and status of all enabled campaigns for account 1234567890."

[!NOTE] Read-Only Scope: The Google Ads MCP Server is currently strictly read-only. It cannot modify bids, pause campaigns, or create new advertising assets.

AI Migration Agent Instructions for the Google Mobile Ads SDK

Migration Workflow

Use this checklist to track your migration progress:

• Configure Gradle:

  • Replace com.google.android.gms:play-services-ads with the latest stable version of com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk. If you cannot access Maven directly, run the following command to fetch the latest version. The version returned in the latest tag is the latest version of the GMA Next-Gen SDK:

    curl -sS https://dl.google.com/dl/android/maven2/com/google/android/libraries/ads/mobile/sdk/ads-mobile-sdk/maven-metadata.xml | sed -n 's/.*<latest>\(.*\)<\/latest>.*/\1/p'
    

  • Update minSdk (24+) and compileSdk (34+).

  • Exclude play-services-ads and play-services-ads-lite from all dependencies globally in the app-level build file to avoid duplicate symbol errors.

  • Sync Gradle before moving on to the next step.

• Per-File Migration:
  • Refactor the codebase following the API Mapping and Method Mapping tables to migrate imports, class names, and method signature to GMA Next-Gen SDK.
• Verify and Build:
  • Run gradle build -x test to confirm a successful clean build. Resolve any GMA SDK related compile errors.

Core Migration Rules

• App ID Usage: Always use the value of the com.google.android.gms.ads.APPLICATION_ID meta-data tag from AndroidManifest.xml for the applicationId in InitializationConfig.
  • Constraint: Preserve the <meta-data> tag in the manifest; it is still required for publishers using the User Messaging Platform SDK.
• Initialization Sequence:
  1. Call MobileAds.initialize() on a background thread.
  2. Ensure initialize() is called before any other SDK methods.
  3. If using RequestConfiguration, bundle it into InitializationConfig.Builder.setRequestConfiguration(). Do not call MobileAds.setRequestConfiguration() before initialization.
• UI Threading: MANDATORY: Callbacks in GMA-Next Gen SDK are invoked on a background thread. ALL UI-RELATED OPERATIONS (e.g., Toasts, View updates, Fragment transactions) MUST be wrapped in runOnUiThread {} or Dispatchers.Main.launch {} within GMA SDK callbacks. SKIPPING THIS STEP WILL CAUSE THE APPLICATION TO CRASH.
• Mediation: Classes implementing com.google.android.gms.ads.mediation.Adapter MUST continue using com.google.android.gms.ads.

Format Specifics

Banner Ads

• Use com.google.android.libraries.ads.mobile.sdk.banner.AdView for loading GMA Next-Gen SDK banners.
• The following API checks if a banner is collapsible: adView.getBannerAd().isCollapsible().

Native Ads

• NativeAdLoader: NativeAdLoader is abstract and cannot be instantiated. It is used statically (e.g., NativeAdLoader.load(...)).
• The following APIs are now set on the NativeAdRequest.Builder:
  • .setCustomFormatIds(customFormatIds: List<String>)
  • .disableImageDownloading()
  • .setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)
  • .setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)
  • .setVideoOptions(videoOptions: VideoOptions)
• Removal: Delete all "Mute This Ad" logic; it is unsupported in GMA Next-Gen SDK.
• MediaView: NativeAd no longer has a direct mediaView variable; use registerNativeAd(nativeAd, mediaView) to associate the ad with the view.

Ad preloading

• Unless specified in the mapping table, ad preloading methods in the GMA Next-Gen SDK retain the same API signatures and parameters as the Old SDK.

API Mapping

This table covers the main classes and their GMA Next-Gen SDK equivalents.

Method Mapping

This table covers the main methods and their GMA Next-Gen SDK equivalents.

Google Mobile Ads SDK - Banner Ads

Banner ads are rectangular image or text ads that occupy a spot within an app's layout. They remain on screen during user interaction and can refresh automatically.

Ad Placement Guidelines

CRITICAL: You MUST evaluate and apply the following guidelines before proceeding with any banner ad implementation.

• Determine Ad Placement:
  • Identify the target file where the ad should be placed. Ask if unsure.
  • Inspect view hierarchy when the target file is identified. Examine the file and determine whether the parent container of the ad is a scrollable view (such as a list, scroll view, grid) or a static, non-scrollable view.
    • Scrollable Content: Use Inline Adaptive Banner.
    • Non-Scrollable Content: Use Large Anchored Adaptive.
      • Positioning: If not specified, ask if the ad should be anchored to either the top or bottom of the screen.

Workflow

1. Determine the user's platform: Identify if the project is Android or iOS. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-banner.md
   • iOS: references/ios-banner.md

3. Follow these steps in order:

   • Define the ad view
   • Set the ad size
   • Register for ad load events
   • Load the banner ad
   • Verify the implementation

4. After the banner ad is successfully implemented, remind the user to replace the test ad unit ID with their own.

Google Mobile Ads SDK - Install

Workflow

1. Determine the user's platform: Identify if the project is Android, iOS, or Unity. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-get-started.md
   • iOS: references/ios-get-started.md
   • Unity: references/unity-get-started.md

3. Follow these steps in order:

   • Add the SDK dependency
   • Set the application identifier
   • Initialize the SDK
   • Verify the integration

4. After the SDK is successfully installed, ask the user to select an ad format to continue the integration.

Google Mobile Ads SDK - Interstitial Ads

Interstitial ads show full-page ads for users on mobile apps. Interstitial ads are designed to be placed between content and are best placed at natural app transition points.

Ad Placement Guidelines

CRITICAL: You MUST evaluate and apply the following Ad Placement Guidelines before proceeding with any interstitial ad implementation.

• Determine Ad Placement:
  • Identify the target file where the ad should be placed. Ask if unsure.

Workflow

1. Determine the user's platform: Identify if the project is Android or iOS. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-interstitial.md
   • iOS: references/ios-interstitial.md

3. Follow these steps in order:

   • Load the ad
   • Register for ad event callbacks
   • Show the ad
   • Verify the implementation

Google Mobile Ads SDK - Rewarded Ads

Rewarded ads reward users with in-app items for interacting with full-screen ads. Rewarded ads are served after a user explicitly opts in to view a rewarded ad.

Ad Placement Guidelines

CRITICAL: You MUST evaluate and apply the following Ad Placement Guidelines before proceeding with any rewarded ad implementation.

• Determine Ad Placement:
  • Identify the target file where the ad should be placed. Ask if unsure.

Workflow

1. Determine the user's platform: Identify if the project is Android or iOS. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-rewarded.md
   • iOS: references/ios-rewarded.md

3. Follow these steps in order:

   • Load the ad
   • Register for ad event callbacks
   • Add an opt-in UI element
   • Show the ad
   • Verify the implementation

AI Migration Agent Instructions for the Google Mobile Ads SDK

Migration Workflow

Use this checklist to track your migration progress:

• Configure Gradle:

  • Replace com.google.android.gms:play-services-ads with the latest stable version of com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk. If you cannot access Maven directly, run the following command to fetch the latest version. The version returned in the latest tag is the latest version of the GMA Next-Gen SDK:

    curl -sS https://dl.google.com/dl/android/maven2/com/google/android/libraries/ads/mobile/sdk/ads-mobile-sdk/maven-metadata.xml | sed -n 's/.*<latest>\(.*\)<\/latest>.*/\1/p'
    

  • Update minSdk (24+) and compileSdk (34+).

  • Exclude play-services-ads and play-services-ads-lite from all dependencies globally in the app-level build file to avoid duplicate symbol errors.

  • Sync Gradle before moving on to the next step.

• Per-File Migration:
  • Refactor the codebase following the API Mapping and Method Mapping tables to migrate imports, class names, and method signature to GMA Next-Gen SDK.
• Verify and Build:
  • Run gradle build -x test to confirm a successful clean build. Resolve any GMA SDK related compile errors.

Core Migration Rules

• App ID Usage: Always use the value of the com.google.android.gms.ads.APPLICATION_ID meta-data tag from AndroidManifest.xml for the applicationId in InitializationConfig.
  • Constraint: Preserve the <meta-data> tag in the manifest; it is still required for publishers using the User Messaging Platform SDK.
• Initialization Sequence:
  1. Call MobileAds.initialize() on a background thread.
  2. Ensure initialize() is called before any other SDK methods.
  3. If using RequestConfiguration, bundle it into InitializationConfig.Builder.setRequestConfiguration(). Do not call MobileAds.setRequestConfiguration() before initialization.
• UI Threading: MANDATORY: Callbacks in GMA-Next Gen SDK are invoked on a background thread. ALL UI-RELATED OPERATIONS (e.g., Toasts, View updates, Fragment transactions) MUST be wrapped in runOnUiThread {} or Dispatchers.Main.launch {} within GMA SDK callbacks. SKIPPING THIS STEP WILL CAUSE THE APPLICATION TO CRASH.
• Mediation: Classes implementing com.google.android.gms.ads.mediation.Adapter MUST continue using com.google.android.gms.ads.

Format Specifics

Banner Ads

• Use com.google.android.libraries.ads.mobile.sdk.banner.AdView for loading GMA Next-Gen SDK banners.
• The following API checks if a banner is collapsible: adView.getBannerAd().isCollapsible().

Native Ads

• NativeAdLoader: NativeAdLoader is abstract and cannot be instantiated. It is used statically (e.g., NativeAdLoader.load(...)).
• The following APIs are now set on the NativeAdRequest.Builder:
  • .setCustomFormatIds(customFormatIds: List<String>)
  • .disableImageDownloading()
  • .setMediaAspectRatio(mediaAspectRatio: NativeMediaAspectRatio)
  • .setAdChoicesPlacement(adChoicesPlacement: AdChoicesPlacement)
  • .setVideoOptions(videoOptions: VideoOptions)
• Removal: Delete all "Mute This Ad" logic; it is unsupported in GMA Next-Gen SDK.
• MediaView: NativeAd no longer has a direct mediaView variable; use registerNativeAd(nativeAd, mediaView) to associate the ad with the view.

Ad preloading

• Unless specified in the mapping table, ad preloading methods in the GMA Next-Gen SDK retain the same API signatures and parameters as the Old SDK.

API Mapping

This table covers the main classes and their GMA Next-Gen SDK equivalents.

Method Mapping

This table covers the main methods and their GMA Next-Gen SDK equivalents.

Google Mobile Ads SDK - Banner Ads

Banner ads are rectangular image or text ads that occupy a spot within an app's layout. They remain on screen during user interaction and can refresh automatically.

Ad Placement Guidelines

CRITICAL: You MUST evaluate and apply the following guidelines before proceeding with any banner ad implementation.

• Determine Ad Placement:
  • Identify the target file where the ad should be placed. Ask if unsure.
  • Inspect view hierarchy when the target file is identified. Examine the file and determine whether the parent container of the ad is a scrollable view (such as a list, scroll view, grid) or a static, non-scrollable view.
    • Scrollable Content: Use Inline Adaptive Banner.
    • Non-Scrollable Content: Use Large Anchored Adaptive.
      • Positioning: If not specified, ask if the ad should be anchored to either the top or bottom of the screen.

Workflow

1. Determine the user's platform: Identify if the project is Android or iOS. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-banner.md
   • iOS: references/ios-banner.md

3. Follow these steps in order:

   • Define the ad view
   • Set the ad size
   • Register for ad load events
   • Load the banner ad
   • Verify the implementation

4. After the banner ad is successfully implemented, remind the user to replace the test ad unit ID with their own.

Google Mobile Ads SDK - Install

Workflow

1. Determine the user's platform: Identify if the project is Android, iOS, or Unity. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-get-started.md
   • iOS: references/ios-get-started.md
   • Unity: references/unity-get-started.md

3. Follow these steps in order:

   • Add the SDK dependency
   • Set the application identifier
   • Initialize the SDK
   • Verify the integration

4. After the SDK is successfully installed, ask the user to select an ad format to continue the integration.

Google Mobile Ads SDK - Interstitial Ads

Interstitial ads show full-page ads for users on mobile apps. Interstitial ads are designed to be placed between content and are best placed at natural app transition points.

Ad Placement Guidelines

CRITICAL: You MUST evaluate and apply the following Ad Placement Guidelines before proceeding with any interstitial ad implementation.

• Determine Ad Placement:
  • Identify the target file where the ad should be placed. Ask if unsure.

Workflow

1. Determine the user's platform: Identify if the project is Android or iOS. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-interstitial.md
   • iOS: references/ios-interstitial.md

3. Follow these steps in order:

   • Load the ad
   • Register for ad event callbacks
   • Show the ad
   • Verify the implementation

Google Mobile Ads SDK - Rewarded Ads

Rewarded ads reward users with in-app items for interacting with full-screen ads. Rewarded ads are served after a user explicitly opts in to view a rewarded ad.

Ad Placement Guidelines

CRITICAL: You MUST evaluate and apply the following Ad Placement Guidelines before proceeding with any rewarded ad implementation.

• Determine Ad Placement:
  • Identify the target file where the ad should be placed. Ask if unsure.

Workflow

1. Determine the user's platform: Identify if the project is Android or iOS. If unclear, ask before proceeding.

2. Read the platform guide for implementation details:

   • Android: references/android-rewarded.md
   • iOS: references/ios-rewarded.md

3. Follow these steps in order:

   • Load the ad
   • Register for ad event callbacks
   • Add an opt-in UI element
   • Show the ad
   • Verify the implementation

IMA SDK basics

The Google IMA SDK (Interactive Media Ads) lets you load in-stream video and audio ads into websites, apps, TVs and other digital platforms. Use an IMA SDK to request ads from any VAST-compliant ad server and manage ad playback.

Prerequisites

Before integrating the IMA SDK, you must read the platform-specific guide below to support all platforms that your app can support:

• Web/HTML5/ReactJs/NodeJs/Angular: Read all these guides ima-sdk-web-guide.md, ima-sdk-web-iframe-mode.md, ima-sdk-web-mobile-safari.md
• Android/AndroidTV/ReactNative: Read ima-sdk-android-guide.md
• iOS/tvOS/ReactNative: Read all these guides ima-sdk-ios-guide.md, ima-sdk-tvos-guide.md

Quick start (general workflow)

1. Import the SDK: Prerequisites, dependencies.
2. Initialization: Early setup, Warmup, Settings Configuration, and Ad UI Setup.
3. Ad Request: Creating and triggering the request, User gesture compliance.
4. Ad Load Success/Failure: Handling the load event to get the AdsManager, or handling early fatal errors.
5. Ad Playback Events: Listening to playback events via AdsManager to coordinate content play/pause, and handling non-fatal LOG events and fatal active playback errors.
6. Cleanup: Properly destroying the AdsManager to release resources and prevent memory leaks.

For detailed, platform-specific implementation details, always refer to the guides in the Prerequisites section.

IMA SDK basics

The Google IMA SDK (Interactive Media Ads) lets you load in-stream video and audio ads into websites, apps, TVs and other digital platforms. Use an IMA SDK to request ads from any VAST-compliant ad server and manage ad playback.

Prerequisites

Before integrating the IMA SDK, you must read the platform-specific guide below to support all platforms that your app can support:

• Web/HTML5/ReactJs/NodeJs/Angular: Read all these guides ima-sdk-web-guide.md, ima-sdk-web-iframe-mode.md, ima-sdk-web-mobile-safari.md
• Android/AndroidTV/ReactNative: Read ima-sdk-android-guide.md
• iOS/tvOS/ReactNative: Read all these guides ima-sdk-ios-guide.md, ima-sdk-tvos-guide.md

Quick start (general workflow)

1. Import the SDK: Prerequisites, dependencies.
2. Initialization: Early setup, Warmup, Settings Configuration, and Ad UI Setup.
3. Ad Request: Creating and triggering the request, User gesture compliance.
4. Ad Load Success/Failure: Handling the load event to get the AdsManager, or handling early fatal errors.
5. Ad Playback Events: Listening to playback events via AdsManager to coordinate content play/pause, and handling non-fatal LOG events and fatal active playback errors.
6. Cleanup: Properly destroying the AdsManager to release resources and prevent memory leaks.

For detailed, platform-specific implementation details, always refer to the guides in the Prerequisites section.

Getting Started with Google Analytics Admin API

The Google Analytics Admin API provides programmatic access to Google Analytics account and property configuration. It lets you automate account management, manage data streams, configure custom dimensions, and handle product integrations.

Enabling the API via Cloud CLI

Before making API calls, ensure the Google Analytics Admin API is enabled in your Google Cloud project.

If gcloud is not found, prompt the user to install the Google Cloud CLI before running these commands.

1. Enable the API: Use the Cloud CLI (gcloud) to enable analyticsadmin.googleapis.com.

   gcloud services enable analyticsadmin.googleapis.com --quiet
   

   Why: Enabling the API ensures your Cloud project has the necessary quota and permissions allocated for managing Google Analytics configurations.

2. Verify API Enablement:

   gcloud services list --enabled --filter="analyticsadmin.googleapis.com"
   

Authentication

To authenticate your API requests, you must generate Application Default Credentials (ADC) and give your account the necessary scopes. Run the following command in your terminal:

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

Why: This configures ADC in your local environment with the required Cloud Platform and Google Analytics read-only scopes, allowing the client library to automatically authenticate your requests.

[!NOTE] Configuration Changes: Methods changing the Google Analytics account/property configuration will need the https://www.googleapis.com/auth/analytics.edit scope.

Admin API Use Cases

You can use the Google Analytics Admin API to:

• Run Data Access reports (see https://developers.google.com/analytics/devguides/config/admin/v1/access-api.md.txt for more info)
• Create Account summaries
• Manage accounts
• Provision new accounts
• Search account change history events
• Manage and create properties
• Manage property data retention settings
• Manage conversion events
• Manage custom dimensions and metrics
• Manage data streams and configure measurement protocol secrets
• Manage Firebase links
• Manage Google Ads links
• Manage key events

v1alpha-Only Use Cases

The following capabilities are currently available only in the v1alpha version of the Admin API:

• Manage account and property access bindings
• Create and manage rollup properties
• Create and manage subproperties
• Acknowledge user data collection
• Change property attribution, data retention, Google signals, reporting identity, and User Provided Data settings
• Manage AdSense links
• Manage BigQuery links
• Manage audiences
• Manage channel groups
• Manage calculated metrics
• Manage DisplayVideo360Advertiser links
• Manage expanded data sets
• Manage reporting data annotations
• Manage SearchAds360 links
• Manage event create rules for a data stream
• Manage SKAdNetwork conversion value schema of an iOS stream
• Submit a request for user deletion for a Google Analytics property.

Calling the Admin API

To interact with the Admin API, use the official Google Analytics Admin client library. Note that v1beta is the most stable version of the Admin API. For the latest features, consider using v1alpha.

[!IMPORTANT] Mandatory Agent Directive: When the user selects or requires a specific programming language, read the corresponding client library setup reference guide in references/ listed below.

Supported Client Libraries

Python

If you need to install or set up the Google Analytics Admin API client library for Python, read the setup guide:

• Python Installation Reference (Package: google-analytics-admin)

Java

If you need to install or set up the Google Analytics Admin API client library for Java, read the setup guide:

• Java Installation Reference (Artifact: com.google.cloud:google-cloud-analytics-admin)

PHP

If you need to install or set up the Google Analytics Admin API client library for PHP, read the setup guide:

• PHP Installation Reference (Package: google/analytics-admin)

Node.js

If you need to install or set up the Google Analytics Admin API client library for Node.js, read the setup guide:

• Node.js Installation Reference (Package: @google-analytics/admin)

Go

If you need to install or set up the Google Analytics Admin API client library for Go, read the setup guide:

• Go Installation Reference (Package: cloud.google.com/go/analytics/admin/apiv1beta)

.NET

If you need to install or set up the Google Analytics Admin API client library for .NET / C#, read the setup guide:

• .NET Installation Reference (Package: Google.Analytics.Admin.V1Beta)

Ruby

If you need to install or set up the Google Analytics Admin API client library for Ruby, read the setup guide:

• Ruby Installation Reference (Gem: google-analytics-admin-v1alpha)

[!NOTE] Additional Resources: For further examples of calling the Admin API with Java, PHP, Node.js, .NET, Python, and REST, as well as hints on authentication with a service account, refer to the official Admin API Quickstart. For complete API reference documentation for both v1alpha and v1beta, see the Admin API Reference.

Python Quick Start

1. Install the Client Library:

   pip install google-analytics-admin
   

   If pip is not available, prompt the user to install pip before installing the client library.

2. List Accounts and Properties: Below is a complete example demonstrating how to call the Admin API to list all available accounts and their child properties for the current user using list_account_summaries().

   from google.analytics.admin import AnalyticsAdminServiceClient
   
   def sample_list_account_summaries():
       # Initialize the client.
       # Assumes Application Default Credentials (ADC) are configured in your environment.
       client = AnalyticsAdminServiceClient()
   
       # list_account_summaries returns a summary of all accounts accessible to the
       # user and their child properties.
       account_summaries = client.list_account_summaries()
   
       print("Available Google Analytics Accounts and Properties:")
       for summary in account_summaries:
           print(f"Account: {summary.display_name} ({summary.account})")
           for property_summary in summary.property_summaries:
               print(f"  Property: {property_summary.display_name} ({property_summary.property})")
   
   if __name__ == "__main__":
       sample_list_account_summaries()
   

Getting Started with Google Analytics Data API

The Google Analytics Data API v1beta provides programmatic access to Google Analytics report data. It allows you to build customized dashboards, automate reporting workflows, and integrate Google Analytics data into your enterprise applications.

Enabling the API via Cloud CLI

Before making API calls, ensure the Google Analytics Data API is enabled in your Google Cloud project.

If gcloud is not found, prompt the user to install the Google Cloud CLI before running these commands.

1. Enable the API: Use the Cloud CLI (gcloud) to enable analyticsdata.googleapis.com.

   gcloud services enable analyticsdata.googleapis.com --quiet
   

   Why: Enabling the API ensures your Cloud project has the necessary quota and permissions allocated for running Google Analytics reports.

2. Verify API Enablement:

   gcloud services list --enabled --filter="analyticsdata.googleapis.com"
   

Authentication

To authenticate your API requests, you must generate Application Default Credentials (ADC) and give your account the necessary scopes. Run the following command in your terminal:

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

Why: This configures ADC in your local environment with the required Cloud Platform and Google Analytics read-only scopes, allowing the client library to automatically authenticate your requests.

Creating a Data API Report (v1beta)

To create a report, use the official Google Analytics Data client library. Always prefer the v1beta version of the API for stability and access to current Google Analytics reporting capabilities.

[!IMPORTANT] Mandatory Agent Directive: When the user selects or requires a specific programming language, read the corresponding client library setup reference guide in references/ listed below.

Supported Client Libraries

Python

If you need to install or set up the Google Analytics Data API client library for Python, read the setup guide:

• Python Installation Reference (Package: google-analytics-data)

Java

If you need to install or set up the Google Analytics Data API client library for Java, read the setup guide:

• Java Installation Reference (Artifact: com.google.cloud:google-cloud-analytics-data)

PHP

If you need to install or set up the Google Analytics Data API client library for PHP, read the setup guide:

• PHP Installation Reference (Package: google/analytics-data)

Node.js

If you need to install or set up the Google Analytics Data API client library for Node.js, read the setup guide:

• Node.js Installation Reference (Package: @google-analytics/data)

Go

If you need to install or set up the Google Analytics Data API client library for Go, read the setup guide:

• Go Installation Reference (Package: cloud.google.com/go/analytics/data/apiv1beta)

.NET

If you need to install or set up the Google Analytics Data API client library for .NET / C#, read the setup guide:

• .NET Installation Reference (Package: Google.Analytics.Data.V1Beta)

Ruby

If you need to install or set up the Google Analytics Data API client library for Ruby, read the setup guide:

• Ruby Installation Reference (Gem: google-analytics-data-v1beta)

[!NOTE] Additional Resources: For further examples of calling the Data API with Java, PHP, Node.js, .NET, Python and REST, as well as hints on authentication with a service account, refer to the official Data API Quickstart.

Python Quick Start

1. Install the Client Library:

   pip install google-analytics-data
   

   If pip is not available, prompt the user to install pip before installing the client library.

2. Run a Report Request: Below is a complete example demonstrating how to query a Google Analytics property for active users and sessions grouped by city and date. Replace YOUR-PROPERTY-ID with your actual Google Analytics property ID (e.g., 1234567).

   from google.analytics.data_v1beta import BetaAnalyticsDataClient
   from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest
   
   def sample_run_report(property_id: str):
       # Initialize the client.
       # Assumes Application Default Credentials (ADC) are configured in your environment.
       client = BetaAnalyticsDataClient()
   
       request = RunReportRequest(
           property=f"properties/{property_id}",
           dimensions=[
               Dimension(name="city"),
               Dimension(name="date")
           ],
           metrics=[
               Metric(name="activeUsers"),
               Metric(name="sessions")
           ],
           date_ranges=[
               DateRange(start_date="2026-05-01", end_date="today")
           ],
       )
   
       response = client.run_report(request)
   
       print(f"Report result for property {property_id}:")
       for row in response.rows:
           print(
               f"City: {row.dimension_values[0].value}, "
               f"Date: {row.dimension_values[1].value}, "
               f"Active Users: {row.metric_values[0].value}, "
               f"Sessions: {row.metric_values[1].value}"
           )
   
   if __name__ == "__main__":
       sample_run_report("YOUR-PROPERTY-ID")
   

   Why: Using BetaAnalyticsDataClient and RunReportRequest ensures compatibility with the v1beta endpoint and strongly typed request validation.

Metrics and Dimensions Schema

When constructing your RunReportRequest, you must use valid API names for dimensions and metrics. Refer to the official Data API Schema documentation for the complete, authoritative list of available fields.

Commonly Used Dimensions

Dimensions represent categorical attributes of your data.

• city: The town or city of the user.
• country: The country of the user.
• date: The date of the event, formatted as YYYYMMDD.
• deviceCategory: The category of mobile device (e.g., desktop, mobile, tablet).
• eventName: The name of the triggered event.
• pageTitle: The title of the web page.

Commonly Used Metrics

Metrics represent quantitative measurements.

• activeUsers: The number of active users.
• eventCount: The total count of events.
• sessions: The total number of sessions.
• screenPageViews: The number of app screens or web pages viewed.
• totalRevenue: The total revenue from purchases, subscriptions, and advertising.

Metrics and Dimensions Compatibility Check

Some dimensions and metrics cannot be queried together in the same report request. If you encounter an INVALID_ARGUMENT error regarding incompatible fields, verify your field combinations For programmatic access to the Data API schema, use getMetadata(). To programmatically check the compatibility of specific dimension and metric combinations before running a report, use the checkCompatibility() method.

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import CheckCompatibilityRequest, Compatibility, Dimension, Metric

def sample_check_compatibility(property_id: str):
    client = BetaAnalyticsDataClient()

    # Define the dimensions and metrics you want to query together.
    # For example, checking if 'itemDescription' (an e-commerce dimension)
    # is compatible with 'activeUsers' and 'totalRevenue'.
    request = CheckCompatibilityRequest(
        property=f"properties/{property_id}",
        dimensions=[
            Dimension(name="itemDescription"),
            Dimension(name="date")
        ],
        metrics=[
            Metric(name="activeUsers"),
            Metric(name="totalRevenue")
        ],
    )
    response = client.check_compatibility(request)

    print(f"Compatibility check for property {property_id}:")
    for dim in response.dimension_compatibilities:
        is_compatible = dim.compatibility == Compatibility.COMPATIBLE
        print(f"Dimension '{dim.dimension_metadata.api_name}' is compatible: {is_compatible}")

    for metric in response.metric_compatibilities:
        is_compatible = metric.compatibility == Compatibility.COMPATIBLE
        print(f"Metric '{metric.metric_metadata.api_name}' is compatible: {is_compatible}")

if __name__ == "__main__":
    sample_check_compatibility("YOUR-PROPERTY-ID")

Agent Platform Endpoint Management

Overview

This skill provides procedural knowledge for managing Agent Platform Endpoints. Endpoints are logical serving hosts that provide a stable URL for online predictions. You must create an endpoint before you can deploy a model to it.

Safety & Confirmation Tiers (CRITICAL)

Before executing any commands on behalf of the user, you MUST adhere to the following safety tiers based on the action requested:

1. Tier R: Read-only (list, describe, get)
   • No confirmation needed. Execute immediately to gather information.
2. Tier M: Mutating & Reversible (create, update)
   • Requires interactive confirmation with 'Yes'/'No' options. The confirmation prompt MUST contain the exact, literal command string with all required flags (e.g. --region=us-central1, --display-name="...") — natural-language paraphrases are NOT sufficient.
   • Same-turn restriction: NEVER execute the command in the same turn as presenting the confirmation prompt. Stop and wait for the user's reply; only execute after explicit 'Yes' / approval.
3. Tier D: Destructive & Irreversible (delete)
   • Requires explicit typed confirmation (e.g. "I confirm" or "Yes, delete it"). Ask for confirmation IMMEDIATELY — before any pre-flight checks (don't describe first, don't check if the endpoint is empty first).
   • Same-turn restriction: NEVER execute in the same turn as asking for typed confirmation. Wait for the user to reply in a new turn.

Phase 0: Environment Setup

CRITICAL: Before running any commands, you MUST ensure the environment is correctly initialized by following these steps:

1. Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for Agent Platform access:

   gcloud auth login
   gcloud auth application-default login
   

2. Set Project: Configure the active project for subsequent commands:

   gcloud config set project $PROJECT_ID
   

3. Region: Always specify --region=$LOCATION_ID on each command below. Do NOT use global. Ask the user to specify the region if not provided.

1. Listing Endpoints (Tier R)

Use this command to discover existing endpoints in a specific region and retrieve their IDs. No confirmation is required.

gcloud ai endpoints list \
    --region=$LOCATION_ID

[!IMPORTANT] Always specify the --region. Do NOT use 'global'. Ask the user to specify if not provided.

2. Describing an Endpoint (Tier R)

Retrieve the full metadata for a specific endpoint. No confirmation is required.

gcloud ai endpoints describe $ENDPOINT_ID \
    --region=$LOCATION_ID

3. Creating an Endpoint (Tier M)

Create a new endpoint resource. The parent resource is the location. Action requires an inline confirmation card before proceeding.

gcloud ai endpoints create \
    --region=$LOCATION_ID \
    --display-name="my-endpoint"

[!IMPORTANT] You MUST seek interactive confirmation first. Your confirmation prompt MUST show the literal command string. For example:

gcloud ai endpoints create --region=$LOCATION_ID --display-name="my-endpoint"

Or the exact flags. Do not execute this command in the same turn as proposing the confirmation.

4. Updating an Endpoint (Tier M)

Update endpoint metadata such as display name or labels. Action requires an inline confirmation card before proceeding.

gcloud ai endpoints update $ENDPOINT_ID \
    --region=$LOCATION_ID \
    --display-name="new-display-name"

Check if the endpoint exists first by either listing or describing the endpoint.

[!IMPORTANT] You MUST seek interactive confirmation first. Your confirmation prompt MUST show the literal command string. For example:

gcloud ai endpoints update $ENDPOINT_ID --region=$LOCATION_ID --display-name="new-display-name"

Or the exact flags. CRITICAL: You are strictly prohibited from executing this command in the same turn as asking for confirmation. When you ask for confirmation, you MUST stop immediately and wait for the user to reply.

5. Deleting an Endpoint (Tier D)

Permanently delete an endpoint resource. Action requires explicit typed confirmation before proceeding.

gcloud ai endpoints delete $ENDPOINT_ID \
    --region=$LOCATION_ID

[!WARNING] All models must be undeployed from the endpoint before it can be deleted. Do not run describe until AFTER you have received typed confirmation to delete.

6. Traffic Splitting (Tier M)

You can manage traffic split between different models deployed on the same endpoint during an update. Action requires an inline confirmation card before proceeding.

# Example: Deploying a model with a specific traffic split is usually done
# via 'gcloud ai endpoints deploy-model'.

Refer to the agent-platform-deploy skill for instructions on deploying and undeploying models.

Troubleshooting

• 403 Permission Denied: Ensure aiplatform.admin or owner role is assigned.
• Quota Exceeded: Verify the region's endpoint quota in the Cloud Console.
• Resource Busy: If a deletion fails, check if models are still being undeployed.

Migrating from Gemini API in AI Studio to Agent Platform

Use this skill when you need to transition an application from the developer-centric Google AI Studio ecosystem (generativelanguage.googleapis.com) to the enterprise-grade Google Cloud Agent Platform (aiplatform.googleapis.com).

When to Invoke This Skill

• You want to migrate an application from Google AI Studio to Agent Platform (formerly Vertex AI).
• You have Google Cloud credits (e.g., the $300 Welcome Free Trial) that you want to apply toward Gemini API inferencing costs.
• You need to unify your inferencing pipelines, IAM permissions, telemetry, and billing with existing Google Cloud infrastructure (Compute Engine, Cloud SQL, BigQuery).
• You are deploying open-source orchestration engines (like OpenClaw or ADK agents) on Google Cloud VMs, and want the entire system to run under a unified Google Cloud billing structure.

Gemini API Comparison

See Google Cloud Documentation to learn more about the differences between the two offerings.

Migration Guide

Billing and Credits

Google Cloud Free Trial credits do not apply to AI Studio. To use your credits for Gemini models, you must route calls through the Agent Platform.

1. Create a Google Cloud billing account. You must provide a valid payment method during setup to verify identity.
2. If you are a new customer, ensure your $300 Welcome credit is active in the Billing Console.
3. Avoid Billing Surprises: To prevent automatic fallback to your standard form of payment when credits are exhausted, you should establish a budget alert:
   • Go to Billing -> Budgets & Alerts -> Create Budget.
   • Set the threshold to map to your credit limit or maximum comfortable spend.

Enable the Agent Platform API

You must explicitly enable the Agent Platform API on your target Google Cloud Project. Run the following command via your local shell:

gcloud services enable aiplatform.googleapis.com --project="{project_id}"

Authentication & Authorization (IAM)

User Auth

For local debugging or script execution, authenticate using Application Default Credentials (ADC).

Option 1 - Automated Script:

bash <(curl -sSL https://storage.googleapis.com/cloud-samples-data/adc/setup_adc.sh)

Option 2 - Manual Setup:

gcloud auth login
gcloud auth application-default login

Grant your user identity the required IAM role to perform inferencing calls:

gcloud projects add-iam-policy-binding "{project_id}" \
    --member="user:YOUR_EMAIL@domain.com" \
    --role="roles/aiplatform.user"

Service Auth

When running your application on Google Cloud infrastructure such as a Compute Engine VM, authenticate using the machine's attached Service Account. For example, the Compute Engine Default Service Account.

1. Grant the virtual machine's underlying Service Account the user role:

gcloud projects add-iam-policy-binding "{project_id}" \
    --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/aiplatform.user"

2. Compute Engine Access Scopes: Legacy access scopes can override IAM bindings. When provisioning or modifying your Compute Engine instance, you must verify that the VM access scope is configured to either Allow full access to all Cloud APIs (https://www.googleapis.com/auth/cloud-platform) or explicitly includes the standard cloud-platform scope.

Use the Gemini API in Agent Platform

SDKs (Client Libraries)

You can continue to use the unified Google GenAI SDK (google-genai). This SDK works with both AI Studio and Agent Platform. You only need to switch the routing flags via your runtime environment variables to target the Agent Platform backend.

Set your target environment details:

export GOOGLE_CLOUD_PROJECT="{project_id}"
export GOOGLE_CLOUD_LOCATION="global"  # Or your chosen regional endpoint
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE

Now, your standard python code shifts from using AI Studio to Agent Platform without altering the core initialization blocks:

from google import genai

# The client automatically picks up the GOOGLE_GENAI_USE_ENTERPRISE=TRUE environment flag
client = genai.Client()

response = client.models.generate_content(
    model='gemini-3-flash-preview',
    contents='Hello world!',
)
print(response.text)

Agent Development Kit (ADK)

To call Gemini models in Agent Platform from an Agent Development Kit agent, follow these steps.

1. Authenticate to Google Cloud.

If running an ADK agent in Google Cloud (e.g. Agent Platform Runtime), use the agent's assigned service account. Alternatively, if running ADK locally, run:

gcloud auth application-default login

1. Set env variables. Ensure these are set no matter if your ADK agent is running in Google Cloud or locally:

export GOOGLE_CLOUD_PROJECT="{project_id}"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE

2. Initialize the ADK agent. You can use the same model string you used with AI Studio (e.g. gemini-3-flash-preview).

from google.adk.agents.llm_agent import Agent

def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    return {"status": "success", "city": city, "time": "10:30 AM"}

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='root_agent',
    description="Tells the current time in a specified city.",
    instruction="You are a helpful assistant that tells the current time in cities. Use the 'get_current_time' tool for this purpose.",
    tools=[get_current_time],
)

To learn more about integrating ADK agents with Agent Platform, see the ADK documentation.

Antigravity CLI

Google Cloud users can now access Antigravity 2.0, including the Antigravity CLI, with Gemini Enterprise Agent Platform.

1. Install the Antigravity CLI to your local environment.

2. Start the Antigravity CLI.

   agy
   

3. Follow the CLI setup prompts - select Use a Google Cloud Project.

4. Complete the OAuth flow in the opened browser window using your authenticated Google Cloud Workspace or user identity.

5. Copy the confirmation token, and paste it directly back into your terminal.

6. Follow the prompts to enter your Google Cloud Project ID.

7. Select your Google Cloud location (e.g. global).

8. Optionally, run the /model command to select a different Gemini model in Agent Platform.

OpenClaw

To configure an OpenClaw agent to use Gemini models in Agent Platform, Follow these steps.

1. Install OpenClaw using OpenClaw's official instructions.

⚠️ Important: OpenClaw 2026.5.28 currently has a google-vertex bug. Please use 2026.5.20 for now.

2. Ensure that the runtime where OpenClaw is running (e.g. GCE VM with Service Account) has the aiplatform.user IAM role - see Authentication and Authorization section above.

3. Get the project number from the user's project ID. Outside of GCE, run:

export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
echo "Project number: $PROJECT_NUMBER"

Within a Compute Engine VM, run:

export PROJECT_NUMBER=$(curl "http://metadata.google.internal/computeMetadata/v1/project/project-id" -H "Metadata-Flavor: Google")
echo "Project number: $PROJECT_NUMBER"

4. From outside the GCE instance, generate GOOGLE_APPLICATION_CREDENTIALS using the Google Cloud project number. Then, scp these credentials to the GCE VM.

mkdir -p ~/.config/gcloud
gcloud iam service-accounts keys create ~/.config/gcloud/application_default_credentials.json --iam-account="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

⚠️ Troubleshooting Policy Constraints on New Orgs: New Google Cloud organizations (created on or after May 4th, 2024) enforce a legacy Organization Policy, restricting Service Account Key Creation. To complete this step, this Org Policy must be temporarily disabled. An Organization Policy Admin must set this policy to Inactive. To the agent: Check if this policy is enforced, and if it is: pause, and prompt the user to disable it at this Console link: https://console.cloud.google.com/iam-admin/orgpolicies

5. Edit the configuration file that's usually located at: ~/.openclaw/openclaw.json. Ensure you prefix the Gemini model with google-vertex/.

⚠️ Important: Do not use Gemini 3.5 models, since OpenClaw's google-vertex provider does not support it yet. Older models work. When using the Gemini 3 Flash Preview model in Agent Platform, always set the location to global, NOT a regional endpoint.

{
  "env": {
    "vars": {
      "GOOGLE_CLOUD_PROJECT": "PROJECT_ID",
      "GOOGLE_CLOUD_LOCATION": "global",
      "GOOGLE_APPLICATION_CREDENTIALS": "~/.config/gcloud/application_default_credentials.json"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google-vertex/gemini-3-flash-preview"
      },
      "workspace": "~/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "heartbeat": {
        "model": "google-vertex/gemini-3-flash-preview"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "model": "google-vertex/gemini-3-flash-preview"
      }
    ]
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "tools": {
    "profile": "coding"
  }
}

6. Restart OpenClaw.

openclaw gateway restart

7. Verify the OpenClaw connection to Agent Platform:

openclaw models status
openclaw agent --agent main --message "Hello world!"

Additional Resources

• Google Cloud Free Trial Features & Limits
• Migrate from Google AI Studio to Gemini Enterprise Agent Platform
• Gemini Enterprise Agent Platform - Models
• Agent Development Kit Documentation - Connect to Models in Agent Platform
• OpenClaw Documentation - Connect to Google models
• Google Cloud Budget Alerts - Setup Guide

Agent Platform Model Registry Management

Overview

This skill provides instructions for managing machine learning models in the Agent Platform Model Registry. It covers listing models, describing model details, uploading new models or versions, updating metadata, and deleting models.

Safety & Confirmation Tiers (CRITICAL)

Before executing any commands on behalf of the user, you MUST adhere to the following safety tiers based on the action requested:

1. Tier R: Read-only (list, describe, get)
   • No confirmation needed. Execute immediately to gather information.
2. Tier M: Mutating & Reversible (upload, update)
   • Requires interactive confirmation with 'Yes'/'No' options. The confirmation prompt MUST contain the exact, literal command string with all required flags (e.g. --region=us-central1, --display-name="...") — natural-language paraphrases are NOT sufficient.
   • Same-turn restriction: NEVER execute the command in the same turn as presenting the confirmation prompt. Stop and wait for the user's reply; only execute after explicit 'Yes' / approval.
3. Tier D: Destructive & Irreversible (delete)
   • Requires explicit typed confirmation (e.g. "I confirm" or "Yes, delete it"). Ask for confirmation IMMEDIATELY — before any pre-flight checks (don't check if the model is deployed to endpoints first).
   • Same-turn restriction: NEVER execute in the same turn as asking for typed confirmation. Wait for the user to reply in a new turn.

Phase 0: Environment Setup

CRITICAL: Before running any commands, you MUST ensure the environment is correctly initialized by following these steps:

1. Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for Agent Platform access:

   gcloud auth login
   gcloud auth application-default login
   

2. Set Project: Configure the active project for subsequent commands:

   gcloud config set project $PROJECT_ID
   

3. Region: Always specify --region=$LOCATION_ID on each command below. Do NOT use global.

1. Listing Models (Tier R)

Use this command to discover existing models in the registry and retrieve their numeric IDs. No confirmation is required.

gcloud ai models list \
    --region=$LOCATION_ID

2. Describing a Model (Tier R)

Retrieve the full metadata for a specific model or version. No confirmation is required.

gcloud ai models describe $MODEL_ID \
    --region=$LOCATION_ID

To target a specific version:

gcloud ai models describe ${MODEL_ID}@${VERSION_ID} \
    --region=$LOCATION_ID

3. Uploading a Model (Tier M)

Register a new model or a new version of an existing model. This is a long-running operation. Action requires an inline confirmation card before proceeding.

Example: Uploading a Custom Model

gcloud ai models upload \
    --region=$LOCATION_ID \
    --display-name="my-custom-model" \
    --container-image-uri="gcr.io/my-project/my-model:latest" \
    --artifact-uri="gs://my-bucket/path/to/artifacts"

[!IMPORTANT] This is a Tier M operation — see [Safety & Confirmation Tiers] above.

To upload a new version of an existing model, use the --parent-model flag or specify the parent model ID.

4. Updating a Model (Tier M)

Update metadata fields like display name, description, or labels. Action requires an inline confirmation card before proceeding.

gcloud ai models update $MODEL_ID \
    --region=$LOCATION_ID \
    --display-name="new-display-name" \
    --description="Updated description"

[!IMPORTANT] This is a Tier M operation — see [Safety & Confirmation Tiers] above.

5. Deleting a Model (Tier D)

Permanently delete a Model and all its versions. Action requires explicit typed confirmation before proceeding.

gcloud ai models delete $MODEL_ID \
    --region=$LOCATION_ID

[!WARNING] This operation is irreversible. All model versions must be undeployed from all Endpoints before deletion.

Agent Platform Prompt Management

Usage Guide

To use this skill effectively:

1. Generate Code: Provide the Python snippets below to the user to help them manage prompts in Agent Platform.

2. No File System Search: Do not try to find Python files or scripts on the file system for these operations.

Safety & Confirmation Tiers (CRITICAL)

Before executing any commands or scripts on behalf of the user, you must adhere to the following safety tiers based on the action requested, to prevent accidental mutation or permanent deletion of prompt resources:

1. Tier R: Read-only (list, get)
   • No confirmation needed. Execute immediately to gather information.
2. Tier M: Mutating & Reversible (create)
   • Requires interactive confirmation with 'Yes'/'No' options before executing prompt creation, to prevent unintended resource proliferation or misconfiguration. The confirmation prompt must clearly explain the proposed prompt creation and its key parameters (e.g., display name, template text, target model). Natural-language paraphrases without specifying the parameters are not sufficient.
   • Same-turn restriction: Do not execute the creation code in the same turn as presenting the confirmation prompt. Stop and wait for the user's reply; only execute after explicit 'Yes' / approval.
   • Gold Standard Example:

     I will create a prompt in Agent Platform with the following parameters. Please confirm this information before I proceed:

     • Display Name: Customer Support Greeting
     • Target Model: gemini-2.5-pro
     • Template Text: "Hello {{user_name}}, how can I help..." Do you confirm? [Yes/No]

3. Tier D: Destructive & Irreversible (delete)
   • Requires explicit typed confirmation (e.g. "I confirm" or "Yes, delete it") before executing prompt deletion, to prevent accidental permanent loss of production prompt assets. Ask for confirmation before any pre-flight checks.
   • Same-turn restriction: NEVER execute in the same turn as asking for typed confirmation. Wait for the user to reply in a new turn.
   • Gold Standard Example:

     I will permanently delete the following prompt from Agent Platform. This action is irreversible. Please explicitly type your confirmation (e.g., "I confirm") before I proceed:

     • Prompt ID: prompt_12345abc
     • Display Name: Legacy Outdated Prompt Please type your confirmation to proceed.

Phase 0: Environment Setup

CRITICAL: Before the user runs any of the Python snippets below, you MUST advise them to ensure the environment is correctly initialized by following these steps:

1. Google Cloud Authentication: Authenticate with your Google Cloud account and configure active Application Default Credentials (ADC) for Agent Platform access:

   gcloud auth login
   gcloud auth application-default login
   

2. Virtual Environment: Create and activate a dedicated virtual environment:

   python3 -m venv ~/prompt_agent_venv
   source ~/prompt_agent_venv/bin/activate
   

3. Install Dependencies: Install the required Agent Platform SDKs:

   pip install google-cloud-aiplatform google-genai
   

4. Execution: Advise the user that every time they execute a Python snippet, they must ensure this virtual environment is activated first.

[!TIP] Placeholder Parameter Replacement: The Python scripts below use uppercase string placeholders (like "PROJECT_ID", "LOCATION_ID", and "PROMPT_ID"). You MUST dynamically replace these placeholders with the actual Project ID, Region, and Prompt ID values provided in the user's prompt (or discovered context) before generating or providing the scripts.

1. Managing Prompts via Agent Platform SDK

The SDK provides a high-level Prompt class in the preview module.

Create a Prompt

Use when you need to create a new managed prompt in Agent Platform.

• Reference: See create.md for detailed instructions and Python snippets.

List Prompts

import vertexai
from vertexai.preview import prompts

vertexai.init(project="PROJECT_ID", location="LOCATION_ID")

all_prompts = prompts.list()
for p in all_prompts:
    print(f"Name: {p.display_name}, ID: {p.prompt_id}")

Retrieve and Use a Prompt

import vertexai
from vertexai.preview import prompts

vertexai.init(project="PROJECT_ID", location="LOCATION_ID")

retrieved_prompt = prompts.get(prompt_id="PROMPT_ID")
# Versions are supported: prompts.get(prompt_id="PROMPT_ID", version_id="2")

# Assemble with variables (kwargs must match template variable names)
assembled = retrieved_prompt.assemble_contents(text="The quick brown fox...")
print(assembled)

Delete a Prompt

CRITICAL: You must pass the numeric prompt ID (e.g., "1234567890123456789") to prompts.delete(). The SDK constructs the full resource path internally using the project and location from vertexai.init().

Confirmation Required: As a Tier D (Destructive) operation, the agent MUST pause and request explicit, high-friction typed re-confirmation of the prompt ID from the user before generating or providing the deletion code. The action is irreversible.

[!IMPORTANT] NEVER pre-emptively provide or execute any deletion code before receiving the user's response in a new turn. You must never speculate or assume that confirmation will be given. Asking for confirmation and providing the code in a single parallel turn is a severe safety violation.

import vertexai
from vertexai.preview import prompts

vertexai.init(project="PROJECT_ID", location="LOCATION_ID")

prompts.delete(prompt_id="PROMPT_ID")

2. Best Practices

• Idempotency:
  • Tier R (List, Get): Inherently idempotent.
  • Tier D (Delete): Re-running a delete on a non-existent or already deleted resource returns NOT_FOUND. Treat this as success.
• Placeholders: Use the standard placeholder syntax (variable name enclosed in double curly braces) in your prompt templates.
• Versioning: Always tag or record version IDs when making updates to production prompts.
• Model Reference: Specify the target model ID (e.g., gemini-2.5-pro) when creating the prompt to ensure consistency.
• Underlying Schema: When using the Dataset API, always use the correct metadata_schema_uri and nested metadata structure to ensure the prompt is recognized by Agent Platform Studio and the Prompts SDK.

Agent Platform RAG Engine Management

This skill provides instructions on how to interact with Agent Platform RAG Engine using the Agent Platform Python SDK. You MUST use the vertexai Python SDK to perform RAG Engine operations, rather than raw REST calls or MCP tools, because this code is intended to be run by external clients.

Safety & Confirmation Tiers (CRITICAL)

Before executing any commands or scripts on behalf of the user, you must adhere to the following safety tiers based on the action requested:

1. Tier R: Read-only (list_corpora, list_files, get_corpus, retrieval_query)
   • No confirmation needed. Execute immediately to gather information or retrieve grounded contexts.
2. Tier RC: Read-only but consumes Compute Resources (client.models.generate_content)
   • Requires interactive confirmation with 'Yes'/'No' options before executing grounded content generation. The confirmation prompt MUST clearly explain the proposed generation execution and its key parameters (e.g., target corpus ID, query text, target model). Natural-language paraphrases without specifying exact parameters are insufficient, as explicit parameter listing is required to ensure unambiguous user approval of the specific resource and configuration.
   • Same-turn restriction: Do not execute the generation code in the same turn as presenting the confirmation prompt. Stop and wait for the user's reply; only execute after explicit 'Yes' / approval.
   • Gold Standard Example:

     I will perform grounded content generation with the following parameters. Please confirm this information before I proceed:

     • Target Corpus ID: projects/123/locations/us/ragCorpora/abc
     • Target Model: gemini-2.5-pro
     • Query Text: "What are the company policies on remote work?" Do you confirm? [Yes/No]

Phase 0: Environment Setup

CRITICAL: Before running any of the Python snippets below, you must ensure the environment is correctly initialized by following these steps:

1. Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for Agent Platform access:

   gcloud auth login
   gcloud auth application-default login
   

2. Virtual Environment: Create and activate a dedicated virtual environment:

   python3 -m venv ~/rag_agent_venv
   source ~/rag_agent_venv/bin/activate
   

3. Install Dependencies: Install the required Agent Platform SDKs:

   pip install google-cloud-aiplatform google-genai
   

4. Execution: Advise the user that every time they execute a Python snippet, they must ensure this virtual environment is activated first.

Workflow Decision Tree

1. Information Gathering: Has the user provided the Project ID, Region, and Corpus ID?

   • No -> Proceed to [1. Listing Corpora and Files] to discover the necessary Resource Names and IDs. Only ask the user if discovery fails.
   • Yes -> Proceed.

2. Task Type: What does the user want to do?

   • List Corpora and Files -> Proceed to [1. Listing Corpora and Files].
   • Inspect a Corpus -> Proceed to [2. Getting / Inspecting a RAG Engine Corpus].
   • Search for Contexts -> Proceed to [3. Retrieving Contexts].
   • Answer questions using RAG Engine -> Proceed to [4. Answering the User with Retrieved Context].

[!TIP] Placeholder Parameter Replacement: The Python scripts below use bracketed string placeholders (like "{project_id}", "{region}", and "{corpus_id}"). You MUST dynamically replace these placeholders with the actual Project ID, Region, and Corpus ID values provided in the user's prompt (or active context) before generating, providing, or executing the scripts.

1. Listing Corpora and Files (Discovery)

If you do not know the Resource Name of the corpus or file, you MUST list them first to discover them. The SDK handles pagination automatically when converted to a list, but you can also use manual pagination for large sets.

1.1 Listing and Discovering Corpora

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")

# Approach A: List ALL (Automatic Pagination)
# The SDK's Pager iterates through all pages for you.
all_corpora = list(rag.list_corpora())
print(f"Found {len(all_corpora)} corpora in total.")
for c in all_corpora:
    print(f"Corpus Name: {c.name} | Display Name: {c.display_name}")

# Approach B: Manual Pagination (for very large projects)
pager = rag.list_corpora(page_size=10)
# Process first page
for c in pager:
    print(f"Corpus: {c.display_name}")

# Get next page if needed
if pager.next_page_token:
    second_page = rag.list_corpora(
        page_size=10, page_token=pager.next_page_token
    )

1.2 Listing and Discovering Files

To understand what files (and types) are in a corpus, list them and inspect the display_name (usually includes the extension).

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)

# List files with automatic pagination
files = list(rag.list_files(corpus_name=corpus_name))
print(f"Found {len(files)} files.")

for f in files:
    # High-level SDK RagFile objects usually have name, display_name,
    # description
    print(f"File: {f.display_name} | Resource: {f.name}")
    # Tip: Check extension to understand file type (PDF, TXT, etc.)
    if f.display_name.lower().endswith(".pdf"):
        print("  Type: PDF")
    elif f.display_name.lower().endswith(".txt"):
        print("  Type: Plain Text")

2. Getting / Inspecting an Agent Platform RAG Engine Corpus

To retrieve details about an existing Agent Platform RAG Engine corpus:

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")

# To get details of a specific corpus
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)
corpus = rag.get_corpus(name=corpus_name)
print(f"Corpus Name: {corpus.name}")
print(f"Display Name: {corpus.display_name}")

3. Retrieving Contexts

To retrieve relevant contexts from a RAG Engine corpus based on a query:

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")

corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)
query = "What is the speed of light?"

# Retrieve contexts
response = rag.retrieval_query(
    rag_corpora=[corpus_name],
    text=query,
    similarity_top_k=3
)

for context in response.contexts.contexts:
    print(f"Context text: {context.text}")
    print(f"Source: {context.source_uri}")

4. Answering the User with Retrieved Context

To use the retrieved context alongside an Agent Platform model to generate a grounded response:

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="{project_id}", location="{region}")
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)

# Define the Agent Platform RAG Engine tool pointing to the corpus
rag_tool = types.Tool(
    retrieval=types.Retrieval(
        vertex_rag_store=types.VertexRagStore(
            rag_resources=[types.VertexRagStoreRagResource(rag_corpus=corpus_name)],
            rag_retrieval_config=types.RagRetrievalConfig(
                top_k=3,
                filter=types.RagRetrievalConfigFilter(
                    vector_similarity_threshold=0.5,
                ),
            ),
        )
    )
)

# Generate content using the RAG Engine tool
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the speed of light?",
    config=types.GenerateContentConfig(
        tools=[rag_tool]
    )
)
print(response.text)

Skill Registry

This skill provides instructions for interacting with the Skill Registry on the Gemini Enterprise Agent Platform.

Core Capabilities

• Skill Discovery - Query the registry to easily search, list, get specific skills, and inspect revision histories.
• Skill Lifecycle Management - Upload, update, or permanently delete skills.
• Operation Monitoring - Utility to check the completion status of long-running state changes (LROs).
• Generate Skill - Automate the initial scaffolding of new agent skills locally.

Core Directives

• Mandatory Validation: ALWAYS execute the environment validation check before performing any operations.

  Before any operation, you must validate the core environment.

  # Execute the validation script
  python3 scripts/validate_env.py
  

Prerequisites & Authentication

Library & Authentication

Ensure you have the latest Google Cloud credentials and libraries installed.

# Install required libraries
pip install google-auth requests

# Authenticate with Google Cloud
gcloud auth application-default login

Environment Variables

The following variables are required for operations:

• GCP_PROJECT_ID: Your Google Cloud Project ID.
• GCP_LOCATION: The region (e.g., us-central1).

Quickstart

Quickly search for available skills in the registry:

python3 scripts/skill_registry_ops.py search \
  --query "test skill" \
  --top-k 5

Operations

• Skill Discovery: query-skills.md
• Skill Lifecycle: manage-skills.md
• Monitor Operations: monitor-operations.md
• Generate Skill: generate-skill.md

Agent Platform Tuning Management

This skill provides instructions on how to manage GenAI Tuning Jobs using the Agent Platform Python SDK. Use this skill when a user wants to check the status of their tuning runs, find an active tuning job, or cancel a job that is running too long.

Safety & Confirmation Tiers (CRITICAL)

Before executing any commands on behalf of the user, you MUST adhere to the following safety tiers based on the action requested:

1. Tier R: Read-only (list, get)
   • Rule: No confirmation needed. You may execute these commands immediately to gather information for the user.
2. Tier D: Destructive & Interruptive (cancel)
   • Rule: This requires explicit typed confirmation. You MUST output a text message to the user explaining that this will stop the tuning process and any progress will be lost, and asking them to type "I confirm" or "Yes, cancel it". You MUST ask for this confirmation IMMEDIATELY, before executing the cancel command.

Phase 0: Environment Setup

CRITICAL: Before running any of the Python snippets below, you MUST ensure the environment is correctly initialized by following these steps:

1. Virtual Environment: Create and activate a virtual environment:

   python3 -m venv ~/tuning_mgr_venv
   source ~/tuning_mgr_venv/bin/activate
   

2. Google Cloud Authentication: Authenticate with your Google Cloud account and configure active Application Default Credentials (ADC) for Agent Platform access:

   gcloud auth login
   gcloud auth application-default login
   

3. Install Dependencies: Install the required Agent Platform SDK:

   pip install google-cloud-aiplatform
   

4. Execution: Advise the user that every time they execute a Python snippet, they must ensure this virtual environment is activated first.

Workflow Decision Tree

1. Information Gathering: Do you have a Project ID and Region?

   • No -> You MUST ask the user for the missing Project ID and Region in plain text, or advise them to check their gcloud configuration. If neither location has this information, then ask the user to provide it. Do not attempt to search random regions on your own.
   • Yes -> Proceed to Step 2.

2. Task Type: What does the user want to do?

   • Find or List Jobs -> Use the Python SDK to list tuning jobs. (Tier R)
   • Check Status / Inspect a Specific Job -> Use the Python SDK to get tuning job details. (Tier R)
   • Cancel a Job -> Ask for confirmation, then use the Python SDK to cancel the tuning job. (Tier D)

Using the Python SDK

[!NOTE] Resource Verification & Missing Projects/Jobs: If the execution of the Python snippet fails with an error (such as 403 Permission Denied, 404 Not Found, INVALID_ARGUMENT, or indicating a dummy/missing project or job ID), you MUST inform the user that the project or tuning job does not exist or cannot be accessed. You MUST prompt the user to provide a valid Project ID or Job ID, and stop tool execution immediately to wait for their response. Do NOT retry or loop, do NOT assume the resource is valid, and do NOT execute further scripts before receiving valid details from the user.

1. Listing Tuning Jobs (Tier R)

If the user asks "What tuning jobs do I have running?" or wants to find a specific job ID:

from google.cloud import aiplatform_v1

project_id = "YOUR_PROJECT_ID"
region = "YOUR_REGION"
parent = f"projects/{project_id}/locations/{region}"

client = aiplatform_v1.GenAiTuningServiceClient(
    client_options={"api_endpoint": f"{region}-aiplatform.googleapis.com"}
)

jobs = client.list_tuning_jobs(parent=parent)
for job in jobs:
    print(f"Name: {job.name}")
    print(f"Base Model: {job.base_model}")
    print(f"State: {job.state}")

2. Getting Details for a Specific Job (Tier R)

If the user provides a Tuning Job ID and asks for its status:

from google.cloud import aiplatform_v1

project_id = "YOUR_PROJECT_ID"
region = "YOUR_REGION"
job_id = "YOUR_JOB_ID"  # 19-digit ID
name = f"projects/{project_id}/locations/{region}/tuningJobs/{job_id}"

client = aiplatform_v1.GenAiTuningServiceClient(
    client_options={"api_endpoint": f"{region}-aiplatform.googleapis.com"}
)

job = client.get_tuning_job(name=name)
print(f"Name: {job.name}")
print(f"Base Model: {job.base_model}")
print(f"State: {job.state}")
print(f"Tuning Model: {job.tuned_model_display_name}")

3. Canceling a Job (Tier D)

If the user explicitly requests to stop, abort, or cancel a running tuning job:

Safety Check: Action requires explicit typed confirmation before proceeding. You MUST ask the user for confirmation before generating or providing this script, even if they provided the job ID, unless they explicitly use confirming language like "Yes, I confirm, cancel tuning job 123456".

[!IMPORTANT] NEVER pre-emptively provide or execute any cancellation code before receiving the user's response in a new turn. You must never speculate or assume that confirmation will be given. Asking for confirmation and providing the code in a single parallel turn is a severe safety violation.

from google.cloud import aiplatform_v1

project_id = "YOUR_PROJECT_ID"
region = "YOUR_REGION"
job_id = "YOUR_JOB_ID"  # 19-digit ID
name = f"projects/{project_id}/locations/{region}/tuningJobs/{job_id}"

client = aiplatform_v1.GenAiTuningServiceClient(
    client_options={"api_endpoint": f"{region}-aiplatform.googleapis.com"}
)

client.cancel_tuning_job(name=name)
print(f"Successfully requested cancellation for {name}")

Agent Platform Model Tuning

Overview

This skill provides procedural knowledge for fine-tuning Large Language Models (both Open Models and Gemini Models) using Agent Platform's tuning service. It covers the entire lifecycle from environment setup and data preparation to job configuration, monitoring, and deployment.

Workflow Decision Tree

1. Model Category Identification: Has the user explicitly stated whether they want to tune an Open Model or a Gemini Model?

   • No → STOP. Ask the user if they want to tune an Open Model or a Gemini Model. CRITICAL EXCEPTION for Environment Setup Requests: If the user is specifically asking for environment setup instructions (e.g. "What environment setup is needed?"), you MUST provide the full Phase 0 environment setup instructions in your initial response, simultaneously with asking clarifying questions about the model category.
   • If the user provides a specific tuning purpose, you should recommend three models: one Open Model, one Gemini Model, and a third generally recommended choice. Briefly list the pros and cons of each (e.g., Gemini models might be more expensive, etc.). CRITICAL: You must read references/models.md during this step and only recommend models explicitly listed in that catalog. Do not recommend unsupported models like Mistral. Do not proceed with model configuration until the category is confirmed.
   • Yes → Proceed.

2. Environment Check: Has the environment (Auth, APIs, IAM, Venv) been initialized?

   • No → Go to Phase 0: Environment & IAM Setup.
   • Yes → Proceed.

3. Dataset Status: Is the dataset ready in JSONL format, is its structure valid for tuning, and is it uploaded to Google Cloud Storage?

   -   **No** → Go to [Phase 1: Dataset Preparation & Upload](#phase-1).
   -   **Yes** → Proceed.
   

4. Column Selection Confirmation: Have you presented the columns to the user and confirmed the mapping?

   • No → STOP. You must show samples and get user confirmation on column mapping as described in Phase 1.0 before proceeding.
   • Yes → Proceed.

5. Configuration: Has the user provided the target model and hyperparameters, or explicitly agreed to your recommendations?

   • No → Go to Phase 2: Model Configuration & Recommendation.
   • Yes → Proceed.

6. Job Status: Has the tuning job been submitted?

   -   **No** → Go to
       [Phase 3: Tuning Job Execution](#phase-3-tuning-job-execution).
   -   **Yes** → Proceed.
   

7. Job Completion: Is the tuning job complete?

   -   **No** → Go to [Phase 4: Monitoring](#phase-4-monitoring).
   -   **Yes** → Proceed.
   

8. Deployment: Has the tuned model been deployed (if required)?

   -   **No** → Go to [Phase 5: Model Deployment](#phase-5-model-deployment).
   -   **Yes** → Task Complete.
   

Phase 0: Environment & IAM Setup {#phase-0}

Ensure the foundational environment is ready before proceeding.

0.1 Authentication & Project Context

• Check if gcloud CLI is installed. If it is not installed, prompt the user for permission to install it before proceeding. If it is installed, update it:

gcloud components update --quiet > /dev/null 2>&1

• Verify gcloud auth list. If not authenticated, run gcloud auth login.
• Ensure project and location are known. Use gcloud config get project to retrieve the current project (and gcloud config get compute/region for region).
• CRITICAL: Ask for Confirmation. You must prompt the user to confirm the retrieved project and region before proceeding, in case they want to switch to a different one.

0.2 Possible Locations

The following locations are available for tuning:

• us-central1
• europe-west4
• us-west1
• us-east5
• asia-southeast1

No other values are supported for this section, ensure that the location is listed above.

0.3 Enable APIs

Ensure aiplatform.googleapis.com and storage.googleapis.com are enabled.

gcloud services enable aiplatform.googleapis.com storage.googleapis.com \
    --project=YOUR_PROJECT

0.4 IAM Permissions

Verify the following identities have the required roles.

• Agent Platform Service Agent: service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com
• Managed OSS Fine Tuning Service Agent: service-PROJECT_NUMBER@gcp-sa-vertex-moss-ft.iam.gserviceaccount.com
• User Identity: The account running the commands.

0.5 Virtual Environment

Create and use a virtual environment named tuning_agent_venv in the home directory. Install dependencies from references/requirements.txt.

python3 -m venv ~/tuning_agent_venv
source ~/tuning_agent_venv/bin/activate
pip install -r references/requirements.txt

CRITICAL AGENT INSTRUCTION: You MUST ensure that every Python command or script execution (e.g., python3 scripts/..., pip install ...) is prefixed with the virtual environment activation command: source ~/tuning_agent_venv/bin/activate &&. Additionally, advise the user that every single time they run a Python command, execute a script, or inspect data inline, they MUST also activate this virtual environment first in their bash execution. For example: source ~/tuning_agent_venv/bin/activate && python3 .... Do not run standalone python3 commands without activating the environment, as they will encounter ModuleNotFoundError issues.

Phase 1: Dataset Preparation & Upload {#phase-1}

1.0 Dataset Discovery & Confirmation

• User-Provided Dataset Verification: If the user specifies a dataset filename or path in their prompt, verify its existence in the workspace (e.g. via script execution or checking for typos).
  • If the file cannot be found anywhere, you MUST inform the user that the dataset file does not exist or cannot be accessed. You MUST prompt the user to provide a valid dataset path. Alternatively, if candidate dataset files are found in the workspace during your search, you MUST present the candidates to the user and ask them to select one. You MUST stop tool execution immediately after reporting the missing file or presenting candidates, and wait for the user's response. Do NOT ask for 80/20 validation split permission, and do NOT attempt to upload the dataset before receiving a valid dataset file selection from the user.
  • If the file is found and verified, proceed to Step 1.1 Formatting & Validation below.
• Auto-Discovery: From User Bucket: If the user does not have a dataset and no suitable alternative is found in the Hugging Face reference, offer to search the user's GCS buckets for potential training data. Prioritize searching for files with extensions like .jsonl, .json, .csv, and .parquet. If such files are found, read the first few lines/records of each to determine if they contain text-based data suitable for tuning (e.g., prompt/completion pairs) that can be modified to follow Data Preparation Guide and is related to the tuning task requested. DO NOT search without prompting first.
• Auto-Discovery: From Task to Huggingface: If the user has a specific task, refer to Huggingface Datasets Reference and recommend a dataset from this if one exists. For each dataset recommended, provide some information about the dataset and provide some reasonable splits. > [!IMPORTANT] > CRITICAL: Ask for Confirmation and Column Selection. Do not proceed > with dataset preparation or upload until you perform the following > steps and get user confirmation: > 1. Dataset and Split Confirmation: Present the dataset and > available splits to the user and have them confirm which to use. > 2. Column Selection (Hugging Face or Custom Datasets): You must: > - Provide a list of all available columns in the selected dataset > split. > - Show a few samples from the dataset to help the user > understand the content and make the choice of columns. > - Recommend which columns should be mapped to prompt (or user > message) and completion (or assistant response), offering a few > reasonable options if applicable. > - Ask the user to confirm the column mapping or specify which > columns to use.

1.1 Formatting & Validation

• Conversion: If data is in CSV, JSON, or Parquet, use scripts/prepare_dataset.py to convert.
• Validation Split Confirmation: If the user only provides a training dataset, you must prompt the user to seek permission to split the training dataset 80/20 to form a validation dataset (using --validation_split 0.2). If they agree, proceed with the split. If they decline, just use the training dataset without a validation dataset.
• Validation: If data is already in JSONL, validate it before uploading. Simply having a .jsonl extension is not enough. You must verify that the content schema is valid for tuning (e.g. correct system/user/model roles).

python3 scripts/prepare_dataset.py \
    --input my_data.jsonl \
    --format <messages|messages_gemini> \
    --validate_only

(Use --format messages for open models and --format messages_gemini for Gemini models.) - Refer to Data Preparation Guide for required schemas.

1.2 Upload

Upload formatted .jsonl files to GCS using a unique directory (e.g., with a datetime timestamp) to avoid overwriting outputs from different runs.

ARTIFACTS="gs://YOUR_BUCKET/tuning_agent_job_/dataset.jsonl" gcloud storage cp dataset.jsonl $ARTIFACTS`

Phase 2: Model Configuration & Recommendation {#phase-2}

Help the user choose the best model and parameters. Always seek user confirmation before submitting the job.

• If the user does not specify a specific model in their prompt, calculate recommendations based on the Models Catalog.
• Prompt for Confirmation: Present the recommended model to the user and ask for their confirmation before configuring hyperparameters.

2.1 Configuration

For Open Models

• Recommend tuning_mode, epochs, learning_rate, and adapter_size based on the Tuning Guide and model-specific baselines in the Models Catalog.

2.2 Calculating Cost (Open Models Only)

• We can calculate a rough estimate of cost of tuning based on the dataset and the selected model in the Models Catalog:

  python3 scripts/calculate_cost.py \
      --input my_data.jsonl \
      --model MODEL_NAME \
      --tuning_mode TUNING_MODE \
      --epochs epochs
  

[!NOTE] Handling Missing Dataset Errors: If scripts/calculate_cost.py fails because the dataset file (e.g. my_data.jsonl or dummy_data.jsonl) cannot be found, you MUST inform the user that the dataset file does not exist or cannot be accessed. You MUST prompt the user to provide a valid dataset path, and stop tool execution immediately to wait for their response. Do NOT retry or loop, do NOT invent a specific cost number, and do NOT prompt for job submission approval before receiving a valid dataset from the user.

• Prompt for Confirmation: Present the recommended hyperparameter configuration and estimated cost to the user and ask for their approval before proceeding to job submission. Make sure to note that the estimated cost is just an estimate and can vary from actual billing costs.

Phase 3: Tuning Job Execution {#phase-3-tuning-job-execution}

CRITICAL Pre-Flight Check (GCS Verification): Before you propose a confirmation prompt or submit any tuning job, you MUST verify that the specified training dataset GCS URI (e.g. gs://dummy_bucket/dataset.jsonl or gs://YOUR_BUCKET/...) actually exists and is accessible. Run gcloud storage ls $DATASET_URI (or gsutil ls).

• If the verification fails (e.g. BucketNotFound, 404, AccessDenied, or indicating a dummy/missing bucket), you MUST inform the user that the GCS bucket or dataset does not exist or cannot be accessed. You MUST prompt the user to provide a valid GCS URI for the dataset, and stop tool execution immediately to wait for their response. Do NOT propose a confirmation prompt and do NOT execute any tuning scripts before receiving a valid dataset URI from the user.
• If the verification succeeds, proceed to propose the confirmation prompt below.

For Gemini Models

Check if scripts/tune_gemini_model.py exists.

• If scripts/tune_gemini_model.py exists: Submit the Gemini model tuning job using this script.

  python3 scripts/tune_gemini_model.py
  

• If scripts/tune_gemini_model.py does not exist: Instruct the user to manually configure and submit the tuning job via the Google Cloud Console UI or using the Agent Platform SDK for Python.

For Open Models

Submit the open model tuning job using scripts/tune_open_model.py. Identify the model id using available models documentation at

documentation.

python3 scripts/tune_open_model.py \
    --project YOUR_PROJECT \
    --location YOUR_LOCATION \
    --base_model BASE_MODEL_ID \
    --train_dataset gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl \
    --output_uri gs://YOUR_BUCKET/tuning_agent_job_<datetime>/output \
    --epochs EPOCHS \
    --learning_rate LR \
    --tuning_mode MODE

[!IMPORTANT] Interactive Confirmation Required (Tier M): Before proceeding with job submission, you MUST present the proposed command string showing all literal flags in a confirmation prompt to the user with 'Yes' and 'No' options.

CRITICAL: When presenting this confirmation prompt to the user, you MUST output it as a direct plain text response and stop tool execution immediately. Do NOT call any command execution or interactive tools in the same turn, as unexpected tool calls may be auto-replied by the simulation harness and cause an infinite loop. Yield immediately for the user's reply.

Phase 4: Monitoring {#phase-4-monitoring}

Monitor the job via the Cloud Console link provided in the script output. Additionally, ask the user if they want you to monitor the job status for them in the background. If they agree, execute scripts/monitor_tuning_job.py as a background task to periodically poll the job status and notify the user to show the status. If the user declines, leave it completely to the user to check on the status.

Phase 5: Model Deployment {#phase-5-model-deployment}

Once the tuning job is SUCCEEDED, deploy the model.

ARTIFACTS="gs://YOUR_BUCKET/tuning_agent_job_<datetime>/output/postprocess/node-0/checkpoints/final"
gcloud ai model-garden models deploy \
    --project=YOUR_PROJECT \
    --region=YOUR_LOCATION \
    --model="$ARTIFACTS" \
    --machine-type=MACHINE_TYPE \
    --accelerator-type=ACCELERATOR_TYPE \
    --accelerator-count=COUNT

[!IMPORTANT] Interactive Confirmation Required (Tier M): Before proceeding with deployment, you MUST present the proposed command string showing all literal flags in a confirmation prompt to the user with 'Yes' and 'No' options.

CRITICAL: When presenting this confirmation prompt to the user, you MUST output it as a direct plain text response and stop tool execution immediately. Do NOT call any command execution or interactive tools in the same turn, as unexpected tool calls may be auto-replied by the simulation harness and cause an infinite loop. Yield immediately for the user's reply.

Refer to Models Catalog for hardware recommendations for specific open models.

Resources

• Data Preparation Guide
• Models Catalog
• Tuning Guide
• scripts/prepare_dataset.py: Data conversion & validation.
• scripts/tune_open_model.py: Open model tuning job submission.

AlloyDB Basics

AlloyDB for PostgreSQL is a managed, PostgreSQL-compatible database service designed for enterprise-grade performance and availability. It utilizes a disaggregated compute and storage architecture to scale resources independently. It also provides AlloyDB AI, a collection of features that includes AI-powered search (vector, hybrid search, and AI functions), natural language capabilities, conversational analytics, and inference features like forecasting and model endpoint management to help developers build AI apps faster.

Quick Start

1. Enable the AlloyDB API:

   gcloud services enable alloydb.googleapis.com --quiet
   

2. Create a Cluster:

   gcloud alloydb clusters create my-cluster --region=us-central1 \
       --password=my-password --network=my-vpc \
       --quiet
   

   Note: For production, we recommend using IAM database authentication instead of passwords. If passwords must be used, use secure secret management (e.g., Secret Manager) instead of passing passwords in cleartext.

3. Create a Primary Instance:

   gcloud alloydb instances create my-primary --cluster=my-cluster \
       --region=us-central1 --instance-type=PRIMARY --cpu-count=2 \
       --quiet
   

Reference Directory

• Core Concepts: Architecture, disaggregated storage, and performance features.

• CLI Usage: Essential gcloud alloydb commands for cluster and instance management.

• Client Libraries & Connectors: Connecting to AlloyDB using Python, Java, Node.js, and Go.

• MCP Usage: Using the AlloyDB remote MCP server and Gemini CLI extension.

• Infrastructure as Code: Terraform configuration and deployment examples.

• IAM & Security: Predefined roles, service agents, and database authentication.

If you need product information not found in these references, use the Developer Knowledge MCP server search_documents tool.

BigQuery AI & ML

BigQuery integrates with Vertex AI to provide powerful machine learning and generative AI capabilities directly within SQL queries using built-in functions like AI.FORECAST, AI.KEY_DRIVERS, AI.DETECT_ANOMALIES, and AI.GENERATE.

Reference Directory

• AI Forecast: Leveraging pre-trained TimesFM model for forecasting without custom training.

• AI Detect Anomalies: Identify deviations in time series data using pre-trained TimesFM model.

• AI Generate: General-purpose text and content generation using Gemini models.

• AI Key Drivers: Automatically identify dimensional segments most responsible for driving changes in a metric.

Related Skills

• BigQuery Basics Skill: SKILL.md file for core BigQuery concepts, resource management, CLI, and client libraries.

BigQuery Basics

BigQuery is a serverless, AI-ready data platform that enables high-speed analysis of large datasets using SQL and Python. Its disaggregated architecture separates compute and storage, allowing them to scale independently while providing built-in machine learning, geospatial analysis, and business intelligence capabilities.

Setup and Basic Usage

1. Enable the BigQuery API:

   gcloud services enable bigquery.googleapis.com --quiet
   

2. Create a Dataset:

   bq mk --dataset --location=US my_dataset
   

3. Create a Table:

   Create a file named schema.json with your table schema:

   [
     {
       "name": "name",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "post_abbr",
       "type": "STRING",
       "mode": "NULLABLE"
     }
   ]
   

   Then create the table with the bq tool:

   bq mk --table my_dataset.mytable schema.json
   

4. Run a Query:

   bq query --use_legacy_sql=false \
   'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` \
   WHERE state = "TX" LIMIT 10'
   

Reference Directory

• Core Concepts: Storage types, analytics workflows, and BigQuery Studio features.

• CLI Usage: Essential bq command-line tool operations for managing data and jobs.

• Client Libraries: Using Google Cloud client libraries for Python, Java, Node.js, and Go.

• MCP Usage: Using the BigQuery remote MCP server and Gemini CLI extension.

• Infrastructure as Code: Terraform examples for datasets, tables, and reservations.

• IAM & Security: Roles, permissions, and data governance best practices.

If you need product information not found in these references, use the Developer Knowledge MCP server search_documents tool.

Related Skills

• BigQuery AI & ML Skill: SKILL.md file for BigQuery AI and ML capabilities (forecast, anomaly detection, text generation).

BigFrames (BigQuery DataFrame) basics

BigFrames is a Python library that lets you take advantage of BigQuery data processing by using familiar Python APIs.

Dataframe API best practices

• Stay in the Cloud: Perform data cleaning, transformation, and analysis via BigFrames methods to leverage BigQuery's scale rather than downloading data.
• Prefer partial ordering mode: Enable partial ordering mode right after importing BigFrames. This speeds up data processing significantly by relaxing row-sequence constraints.

  import bigframes.pandas as bpd
  bpd.options.bigquery.ordering_mode = 'partial'
  

• Use peek() for data preview: Use peek(n) to preview data instead of head(n). peek(n) randomly samples n rows and is significantly faster. head(n) returns rows in strict order and fails in partial ordering mode unless the DataFrame has been explicitly sorted.
• Avoid materializing data locally: Methods like to_pandas() download all data to client memory, bypassing BigQuery’s distributed computation and risking Out of Memory (OOM) errors. Do not materialize data locally unless:
  • The dataset is small enough to fit safely in memory.
  • An error message explicitly requires local materialization.
• Prefer Dataframe API over SQL queries: Do not write raw SQL queries via read_gbq() if a DataFrame/Series method achieves the same result, as it breaks the Pandas abstraction and prevents lazy query execution.
• Accessors over UDFs/Lambdas:
  • Use built-in accessors (e.g., df.col.str.*, df.col.dt.*) instead of remote User Defined Functions (UDFs). UDFs require extra resources and time to deploy.
  • Do not use lambdas with Series.map() or DataFrame.apply(). These methods do not accept functions without udf or remote_function decorators.

  # Avoid:
  df["upper"] = df["name"].map(lambda x: x.upper())
  
  # Prefer:
  df["upper"] = df["name"].str.upper()
  

• Schema Verification: Do not assume the schema of intermediate outputs. Proactively verify schemas using .dtypes and inspect sample records using display() with .peek().
• Visualization: Plot directly from the BigFrames DataFrame/Series when possible. BigFrames is compatible with Matplotlib and Seaborn. If direct plotting fails, use the .plot accessor. If the dataset is too large to plot, aggregate or sample the data before calling .to_pandas() to plot locally.

Machine Learning

• Use bigframes.bigquery.ml package: Do not use Scikit-learn or other ML libraries with BigQuery DataFrames. Standard Scikit-learn models require bringing data into local client memory, whereas bigframes.bigquery.ml delegates training directly to BigQuery's scalable ML engine. Import functions from bigframes.bigquery.ml.

Reference Directory

• Linear Regression: Train a linear regression model to predict numerical values.
• Logistic Regression: Train a logistic regression model to predict boolean values.

BigFrames ML (Legacy)

The BigFrames ML package (bigframes.ml) is a legacy package that mimics the scikit-learn API but is no longer recommended for new projects. Only use this package if the user explicitly requests BigFrames ML.

• Legacy Imports: When legacy BigFrames ML is requested, import tools and classes from bigframes.ml instead of bigframes.bigquery.ml.
• DataFrame Return on Prediction: Unlike Scikit-learn, BigFrames' predict() method always returns a DataFrame containing both predictions and features, rather than a single series of predictions.
• No random_state: Do not pass a random_state argument when instantiating BigFrames ML models, as this parameter is not supported in the BigFrames ML package.
• Automatic Scaling: Do not use OneHotEncoder or StandardScaler unless explicitly requested, as scaling is handled automatically.
• Hyperparameter Tuning: Write custom loops for hyperparameter tuning, as BigFrames lacks GridSearchCV or RandomizedSearchCV.
• ARIMA Plus (Forecasting):
  • Import from bigframes.ml.forecasting.
  • Sort data chronologically and split around a timepoint before training.
  • Ensure the prediction horizon is less than or equal to the training horizon.
• PCA: BigFrames' PCA class lacks a transform() method. Use predict() instead.
• Model Persistence: To persist a model, use model.to_gbq(). To load a persisted model, use bpd.read_gbq_model().

Bigtable Basics

This skill provides core workflows and guidance for administering and developing with Google Bigtable.

Core Principles

• Control Plane vs. Data Plane:
  • Use gcloud for Control Plane operations: Manage Instances, Clusters, App Profiles, Backups and IAM. Create Tables, Logical Views, Materialized Views and Authorized Views.
  • Use cbt for Data Plane operations: Update Tables, Column Families, and reading/writing data.
• Performance First: Bigtable is a NoSQL database. Efficiency is tied to Row Key design. Always warn about Full Table Scans.
• Client Selection: For production use cases, prefer Java or Go for their superior performance and feature coverage compared to other languages.
• Observability: When diagnosing performance or hotspotting, always mention Key Visualizer (via Cloud Console) as the primary diagnostic tool because it provides the most granular view of access patterns across row keys. This should be followed by the hot-tablets tool and table stats in gcloud CLI and include-stats=full option under cbt read to diagnose slow queries.

[!IMPORTANT] Safety Rule: You MUST obtain explicit user confirmation before making non-emulator database changes. You MUST mention this safety requirement when providing commands or instructions that modify the database structure or data.

Quick Recipes

1. Querying Data

Use SQL for complex transforms or aggregations and key-value APIs for simpler query patterns. Note: Use exact match, prefix (_key LIKE 'myprefix%'), or range predicates on _key to avoid expensive unbounded scans. Recommend explicit row ranges (_key BETWEEN 'start' AND 'end') as a more performant alternative to prefix matches where possible.

If expensive scans (either unbounded or prefix or range queries scanning a large range) are unavoidable due to multiple access patterns that can’t all be accommodated in a single schema, consider one of these two options:

• If the query will be used in user facing and/or latency sensitive applications, use continuous materialized views with keys optimized for the additional access patterns.
• If secondary access patterns are infrequent, batch patterns like ETL, ML model training or analytical read-only tasks, use Bigtable Data Boost instead.

2. Manipulating Data

Use key-value APIs for insert, update, increment and delete operations. SQL API is read-only.

3. Data Model Definition (DDL)

SQL API doesn't support DDL operations. Table creation, deletion, updates should be made using gcloud CLI. Logical Views and Continuous Materialized Views are defined as SQL queries but they must be created using gcloud CLI.

Reference Guides

• CLI Operations:
  • infrastructure_management.md: Provisioning instances, clusters, and table schemas.
  • cli_data_access.md: Reading and writing data via the cbt CLI.
• Design & Discovery:
  • schema_design.md: Best practices for row keys and performance with tables and continuous materialized views.
  • dataplex.md: Data catalog search for Bigtable assets.
• Querying & Code:
  • sql_guide.md: Querying structured row keys via SQL and CLI.
  • client_libraries.md: Patterns for high-performance Go/Java/Python code.

Common Workflows

Schema Evolution (DevOps)

1. Prefer Terraform for production schema changes to prevent accidental data loss.

2. For manual cbt changes, first check the existing state by listing the table's column families and GC policies before proposing any modifications:

   cbt ls {table}
   

   If modifications are needed, create the family or update the GC policy:

   cbt createfamily {table} {family}
   cbt setgcpolicy {table} {family} "maxversions=5 AND maxage=30d"
   

3. Reference infrastructure_management.md for full syntax.

External Resources

• Cloud Bigtable Documentation
• Bigtable SQL Reference
• cbt CLI Reference
• gcloud bigtable Reference

Generate Logging Query Language queries

Use this skill to generate correct Logging Query Language (LQL) queries for Cloud Logging.

Core rules

1. Strict syntax requirements:

   • Always use double quotes (") for string literals. Do not use single quotes (').
   • Write boolean operators in all capitals: AND, OR, NOT.
   • Always use parentheses to group terms and explicitly enforce precedence.

2. Common pitfalls:

   • Instance ID vs. Instance Name: For the gce_instance resource type, do NOT compare instance names to instance IDs. Instance names are strings (for example, my-instance). Instance IDs are numeric. If you only have the name, then search by instance name, SEARCH("my-instance"), or use resource.labels.instance_name if that label is available for the resource.
   • Resource Type Accuracy: Do not guess resource types. You must look up the correct resource.type value in the service-specific reference files. For example, use internal_http_lb_rule for Internal HTTP(S) Load Balancer rules when filtering by forwarding rule name or region (instead of http_load_balancer).

3. Output format and placeholders:

   • Output only the raw LQL query text. Do not include conversational filler. Do not wrap the query in markdown code blocks unless explicitly requested by the user. Valid LQL comments (using --) are allowed, and are the ONLY acceptable way to include explanations or warnings.
   • Never block on missing variables. If the user's request lacks specific identifiers (like a project ID, instance name, or IP address), do not ask them for clarification. Instead, insert uppercase placeholder strings wrapped in angle brackets (for example, "<PROJECT_ID>", "<YOUR_SERVICE_NAME>") directly into the query.

4. Preferred fields:

   • Include resource.type and log_id restrictions when the query targets specific Google Cloud services or resources. Global queries (for example, "latest error logs") do not require these restrictions.

Detailed reference

Refer to references/api_reference.md for LQL syntax rules, including Operators, NULL handling, SEARCH, and Regex.

Service reference files

Before generating a query, you MUST read the examples for the specific service. LQL schemas and resource.type values are service-specific.

For the following services, read the exact file listed:

• App Engine
• BigQuery
• Cloud Functions
• Cloud Observability (Monitoring, Logging, Trace)
• Cloud Run
• Cloud Source Repositories
• Cloud SQL
• Cloud Storage
• Cloud Tasks
• Compute Engine (GCE)
• Dataflow
• Dataproc
• Deployment Manager
• Kubernetes Engine (GKE)
• IAM & Service Accounts
• Networking (VPC, Load Balancing, and others)
• Security (Audit logging)
• Service Usage (Enable/Disable API, Quotas)
• Spanner
• Third Party (for example, Nginx, Apache)

For Google Cloud services that aren't listed: If the service is not listed above, write the LQL query based on your general knowledge.

Query generation rules

1. Resource Types: Explicitly define the resource.type in your queries when focusing on specific services. For some queries, you may need to search across multiple types (for example, resource.type=("bigquery_project" OR "bigquery_dataset")).
2. Audit and admin logs: Google Cloud Audit logs (Admin Activity, Data Access) always follow a standard structure inside protoPayload. If the user asks for logs about who created, updated, or deleted a resource, or an API being called:
   • Do NOT fall back to SEARCH(). Instead, use protoPayload.methodName.
   • Construct the method name by guessing the service and the verb. Example: protoPayload.methodName:"compute.instances.insert".
   • Always use the colon operator (:) instead of equals (=) for methodName. The colon operator results in substring matching, which is the only feasible option when the exact API string isn't known.
   • For generic API enable/disable events, use resource.type="audited_resource".
3. Handling Unknown Schemas (Crucial): If the user asks to filter by a specific field or condition, and if you cannot find a matching example or schema in the reference files, then you must generate a query using global search.
   • Only specify jsonPayload.* or protoPayload.* field structures when you are certain of their exact name.
   • Use the SEARCH() function to find the keyword globally within the correct resource.type.
   • Agent Prompt to User: When delivering a query that uses SEARCH, you MUST add an LQL comment (using --) at the top of the query indicating you used a global keyword search because the exact schema wasn't in your references. Do NOT output conversational text, strictly adhere to the Output Format rule.

Supporting links

• Cloud Logging query language documentation
• Monitored resource types catalog
• Cloud Logging query library

Metric Selection (Service Query & Local Keyword Filtering)

Use this skill to identify the most relevant Google Cloud Monitoring metric descriptors. It queries all metric descriptors for a target service from the API and filters them locally inside the agent's context using keyword matching.

CRITICAL RULES

• Always Query Live APIs: You MUST always retrieve the most up-to-date metric descriptors dynamically by calling the list_metric_descriptors MCP tool.

Workflow

Step 1: Verify & Auto-Configure MCP

1. Check if any tool matching list_metric_descriptors (e.g. google-cloud-monitoring:list_metric_descriptors, mcp_google-cloud-monitoring_list_metric_descriptors, or a similar pattern) is available in your active toolset.

2. Verify via Unique URL: To ensure you are calling the correct Google Cloud Monitoring tool, confirm that the underlying MCP server configuration points to: https://monitoring.googleapis.com/mcp.

3. If the tool is missing:

   • Locate the MCP configuration file for the user's environment. Check common paths:

     • ~/.gemini/config/mcp_config.json
     • ~/.codeium/windsurf/mcp_config.json
     • cline_mcp_settings.json
     • claude_desktop_config.json

   • Directly update/merge the configuration file with the following server configuration. CRITICAL: Merge the JSON object to preserve any existing MCP servers in mcpServers. Do not overwrite the file.

     "google-cloud-monitoring": {
       "url": "https://monitoring.googleapis.com/mcp",
       "authProviderType": "google_credentials",
       "enabledTools": [
         "list_metric_descriptors"
       ]
     }
     

   • Print a clear message notifying the user that the google-cloud-monitoring MCP server has been configured, and request them to restart or start a new chat session to refresh tools. Stop calling further tools and end the turn.

Step 2: Analyze Request & Extract Keywords

1. Identify the target GCP service prefix (e.g. compute, spanner, bigquery, storage) and the project ID from the resource URI.
2. Extract target metric concepts from the user's prompt (e.g., "CPU", "memory", "bytes scanned", "latency", "connections").
3. Map these concepts to standard Google Cloud Monitoring metric substrings (e.g., cpu, mem, scanned_bytes, latenc, connections).

Example Query Analysis:

• User Prompt: "Check Cloud Storage bucket write throughput and request count"
• Resource URI: //storage.googleapis.com/projects/my-project/buckets/my-bucket
• Service Prefix: storage (mapped to storage.googleapis.com)
• Metric Keywords: write, throughput, request, count
• Mapped Substrings: write, throughput, request_count, count

Step 3: Query Metric Descriptors via list_metric_descriptors Tool

Query all metric descriptors for each identified service prefix using the list_metric_descriptors MCP tool (using pageSize: 200). Because Google Cloud Monitoring filters do not allow combining multiple metric.type restrictions with OR, you must initiate a separate query for each identified service prefix (either sequentially or in parallel).

If any response includes a nextPageToken, you MUST make consecutive follow-up calls passing pageToken until all remaining descriptors for that prefix are retrieved before filtering.

Filter Pattern Construction: Map the target service domain to its appropriate prefix style:

1. Standard Google Cloud Services: starts_with("<service_prefix>.googleapis.com/") (e.g., bigquery.googleapis.com/, redis.googleapis.com/).
2. Ops Agent (Guest OS): starts_with("agent.googleapis.com/") (for guest OS memory/disk metrics).
3. Kubernetes / GKE Native: starts_with("kubernetes.io/")
4. Istio Service Mesh: starts_with("istio.io/")
5. Knative Serving / Autoscaler: starts_with("knative.dev/")
6. Custom / External Metrics: Use starts_with("custom.googleapis.com/") or starts_with("external.googleapis.com/").

Example Tool Call Payload: If both Spanner and Compute Engine are targeted in the request, execute these two tool calls:

1. Spanner query:

{
  "name": "projects/my-project-id",
  "filter": "metric.type = starts_with(\"spanner.googleapis.com/\")",
  "pageSize": 200
}

1. Compute Engine query:

{
  "name": "projects/my-project-id",
  "filter": "metric.type = starts_with(\"compute.googleapis.com/\")",
  "pageSize": 200
}

Call the list_metric_descriptors tool with these payloads.

Step 4: Local Filtering & Fallback Protocol

Aggregate all descriptors returned from Step 3, and filter them locally inside your LLM context:

1. Keyword Filtering: Filter the list by matching your target metric keywords (e.g. "cpu", "latency") against the type, displayName, and description fields of the descriptors.
2. Resource Alignment: Check if the metric contains labels matching the target resource granularity (e.g., checking for a database label if targeting a database resource). Do not attempt to dynamically match resource type strings directly, as Google Cloud Monitoring resource mappings (like Spanner databases mapping to spanner_instance) can be counter-intuitive.

Troubleshooting & API Fallbacks

If any tool call fails, times out, or returns empty results, use these strategies:

• Case A: API Syntax Error: Examine the error message, correct the filter syntax, and retry.
• Case B: Timeout / Rate Limits: Retry the call once with a smaller page size (e.g., pageSize: 20).
• Case C: Unrecoverable Failure / Empty List:
  1. Verify if the target service is enabled in the project.
  2. Search Google Cloud public documentation to verify standard metrics for the service.
  3. Notify the user of the failure and ask for clarification.

Step 5: Output Selected Metrics

For each service domain, return only the 5-15 key metrics directly relevant to the user's intent.

You MUST report the selected metrics in clean Markdown tables, grouped by service (i.e., one table per service prefix). The table MUST include the following columns: "Metric Type", "Display Name", "Description", "Metric Kind", "Value Type", and "Monitored Resource Types". Map the fields from the Google Cloud Monitoring list_metric_descriptors tool call response objects directly to the table columns:

• Metric Type: Map to the type field (e.g., spanner.googleapis.com/instance/cpu/utilization).
• Display Name: Map to the displayName field.
• Description: Map to the description field.
• Metric Kind: Map to the metricKind field (e.g., GAUGE, DELTA, CUMULATIVE).
• Value Type: Map to the valueType field (e.g., INT64, DOUBLE, DISTRIBUTION, BOOL).
• Monitored Resource Types: Map to the monitoredResourceTypes list field (e.g., ["spanner_instance"]).

Example Output Table:

Reference Documentation & Links

• Google Cloud Monitoring Metric List: GCP Metrics Documentation
• MetricDescriptor MCP Tool Reference: MCP Tools Reference: monitoring.googleapis.com
• Monitoring Filter Syntax Guide: Monitoring Filters

Cloud Run Basics

Cloud Run is a fully managed application platform for running your code, function, or container on top of Google's highly scalable infrastructure. It abstracts away infrastructure management, providing three primary resource types:

1. Services: Responds to HTTP requests sent to a unique and stable endpoint, using stateless instances that autoscale based on a variety of key metrics, also responds to events and functions.
2. Jobs: Executes parallelizable tasks that are executed manually, or on a schedule, and run to completion.
3. Worker pools: Handles always-on background workloads such as pull-based workloads, for example, Kafka consumers, Pub/Sub pull queues, or RabbitMQ consumers.

Prerequisites

1. Enable the Cloud Run Admin API and Cloud Build APIs:

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet
   

2. If you are under a domain restriction organization policy restricting unauthenticated invocations for your project, you will need to access your deployed service as described under Testing private services.

Required roles

You need the following roles to deploy your Cloud Run resource:

• Cloud Run Admin (roles/run.admin) on the project
• Cloud Run Source Developer (roles/run.sourceDeveloper) on the project
• Service Account User (roles/iam.serviceAccountUser) on the service identity
• Logs Viewer (roles/logging.viewer) on the project

Cloud Build automatically uses the Compute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior.

For Cloud Build to build your sources, grant the Cloud Build service account the Cloud Run Builder (roles/run.builder) role on your project:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder \
    --quiet

Replace PROJECT_ID with your Google Cloud project ID and SERVICE_ACCOUNT_EMAIL_ADDRESS with the email address of the Cloud Build service account.

Deploy a Cloud Run service

You can deploy your service to Cloud Run by using a container image or deploy directly from source code using a single Google Cloud CLI command.

CRITICAL RULE: Any deployed code MUST listen on 0.0.0.0 (not 127.0.0.1) and use the injected $PORT environment variable (defaults to 8080), or it will crash on boot.

Deploy a container image to Cloud Run

Cloud Run imports your container image during deployment. Cloud Run keeps this copy of the container image as long as it is used by a serving revision. Container images are not pulled from their container repository when a new Cloud Run instance is started.

Supported container images

You can directly use container images stored in the Artifact Registry, or Docker Hub. Google recommends the use of Artifact Registry since Docker Hub images are cached for up to one hour.

You can use container images from other public or private registries (like JFrog Artifactory, Nexus, or GitHub Container Registry), by setting up an Artifact Registry remote repository.

You should only consider Docker Hub for deploying popular container images such as Docker Official Images or Docker Sponsored OSS images. For higher availability, Google recommends deploying these Docker Hub images using an Artifact Registry remote repository.

To deploy a container image, run the following command:

    gcloud run deploy SERVICE_NAME \
        --image IMAGE_URL \
        --region us-central1 \
        --allow-unauthenticated \
        --quiet

Replace the following:

• SERVICE_NAME: the name of the service you want to deploy to. Service names must be 49 characters or less and must be unique per region and project. If the service does not exist yet, this command creates the service during the deployment. You can omit this parameter entirely, but you will be prompted for the service name if you omit it.
• IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG. Note that if you don't supply the --image flag, the deploy command will attempt to deploy from source code.

Deploy from source code

There are two different ways to deploy your service from source:

• Deploy from source with build (default): This option uses Google Cloud's buildpacks and Cloud Build to automatically build container images from your source code without having to install Docker on your machine or set up buildpacks or Cloud Build. By default, Cloud Run uses the default machine type provided by Cloud Build.

  • To deploy from source with automatic base image updates enabled, run the following command:

    gcloud run deploy SERVICE_NAME --source . \
    --base-image BASE_IMAGE \
    --automatic-updates \
    --quiet
    

    Cloud Run only supports automatic base images that use Google Cloud's buildpacks base images.

    • To deploy from source using a Dockerfile, run the following command:

     gcloud run deploy SERVICE_NAME --source . --quiet
    

    When you provide a Dockerfile, Cloud Build runs it in the cloud, and
    deploys the service.
    

• Deploy from source without build (Preview): This option deploys artifacts directly to Cloud Run, bypassing the Cloud Build step. This allows for rapid deployment times. To deploy from source without build, run the following command:

  gcloud beta run deploy SERVICE_NAME \
   --source APPLICATION_PATH \
   --no-build \
   --base-image=BASE_IMAGE \
   --command=COMMAND \
   --args=ARG \
   --quiet
  

  Replace the following:

  • SERVICE_NAME: the name of your Cloud Run service.
  • APPLICATION_PATH: the location of your application on the local file system.
  • BASE_IMAGE: the runtime base image you want to use for your application. For example, us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24. You can also deploy a pre-compiled binary without configuring additional language-specific runtime components using the OS only base image, such as osonly24.
  • COMMAND: the command that the container starts up with.
  • ARG: an argument you send to the container command. If you use multiple arguments, specify each on its own line.

  For examples on deploying from source without build, see Examples of deploying from source without build.

Create and execute a Cloud Run job

To create a new job, run the following command:

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS --quiet

Alternatively, use the deploy command:

gcloud run jobs deploy JOB_NAME --image IMAGE_URL OPTIONS --quiet

Replace the following:

• JOB_NAME: the name of the job you want to create. If you omit this parameter, you will be prompted for the job name when you run the command.

• IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest.

• Optionally, replace OPTIONS with any of the following flags:

  • --tasks: Accepts integers greater or equal to 1. Defaults to 1; maximum is 10,000. Each task is provided the environment variables CLOUD_RUN_TASK_INDEX with a value between 0 and the number of tasks minus 1, along with CLOUD_RUN_TASK_COUNT, which is the number of tasks.
  • --max-retries: The number of times a failed task is retried. Once any task fails beyond this limit, the entire job is marked as failed. For example, if set to 1, a failed task will be retried once, for a total of two attempts. The default is 3. Accepts integers from 0 to 10.
  • --task-timeout: Accepts a duration like "2s". Defaults to 10 minutes; maximum is 168 hours (7 days). For tasks using GPUs, the maximum available timeout is 1 hour.
  • --parallelism: The maximum number of tasks that can execute in parallel. By default, tasks will be started as quickly as possible in parallel.
  • --execute-now: If set, immediately after the job is created, a job execution is started. Equivalent to calling gcloud run jobs create followed by gcloud run jobs execute.

  In addition to these preceding options, you also specify more configuration such as environment variables or memory limits.

For a full list of available options when creating a job, refer to the gcloud run jobs create command line documentation.

Wait for the job creation to finish. You'll see a success message upon a successful completion.

To execute an existing job, run the following command:

gcloud run jobs execute JOB_NAME --quiet

If you want the command to wait until the execution completes, run the following command:

gcloud run jobs execute JOB_NAME --wait --region=REGION --quiet

Replace the following:

• JOB_NAME: the name of the job.
• REGION: the region in which the resource can be found. For example, europe-west1. Alternatively, set the run/region property.

Deploy a worker pool

You can deploy a Cloud Run worker pool using container images or deploy directly from the source.

Deploy a container image

You can specify a container image with a tag (for example, us-docker.pkg.dev/my-project/container/my-image:latest) or with an exact digest (for example, us-docker.pkg.dev/my-project/container/my-image@sha256:41f34ab970ee...).

Supported container images

You can directly use container images stored in the Artifact Registry, or Docker Hub. Google recommends the use of Artifact Registry since Docker Hub images are cached for up to one hour.

You can use container images from other public or private registries (like JFrog Artifactory, Nexus, or GitHub Container Registry), by setting up an Artifact Registry remote repository.

You should only consider Docker Hub for deploying popular container images such as Docker Official Images or Docker Sponsored OSS images. For higher availability, Google recommends deploying these Docker Hub images using an Artifact Registry remote repository.

To deploy a container image, run the following command:

gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL --quiet

Replace the following:

• WORKER_POOL_NAME: the name of the worker pool you want to deploy to. If the worker pool does not exist yet, this command creates the worker pool during the deployment. You can omit this parameter entirely, but you will be prompted for the worker pool name if you omit it.

• IMAGE_URL: a reference to the container image that contains the worker pool, such as us-docker.pkg.dev/cloudrun/container/worker-pool:latest. Note that if you don't supply the --image flag, the deploy command attempts to deploy from source code.

Wait for the deployment to finish. Upon successful completion, Cloud Run displays a success message along with the revision information about the deployed worker pool.

Deploy a worker pool from source

You can deploy a new worker pool or worker pool revision to Cloud Run directly from source code using a single gcloud CLI command, gcloud run worker-pools deploy with the --source flag.

The deploy command defaults to source deployment if you don't supply the --image or --source flags.

Behind the scenes, this command uses Google Cloud's buildpacks and Cloud Build to automatically build container images from your source code without having to install Docker on your machine or set up buildpacks or Cloud Build. By default, Cloud Run uses the default machine type provided by Cloud Build.

To deploy a worker pool from source, run the following command:

gcloud run worker-pools deploy WORKER_POOL_NAME --source . --quiet

Replace WORKER_POOL_NAME with the name you want for your worker pool.

What to do if a deployment fails:

1. IAM/Permission Error: Read iam-security.md.
2. Crash on Boot / Healthcheck failed: Fetch the logs immediately using gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20 to find the exact runtime error.
3. Native Dependency Error (Node/Python): If using --no-build, switch to --source . (Buildpacks) to compile native extensions properly for Linux.

Reference Directory

• Core Concepts: Services vs. Jobs vs. Worker pools, resource model, and auto-scaling behavior for services.

• CLI Usage: Essential gcloud run commands for deployment and management.

• Client Libraries: Using Google Cloud client libraries to interact with Cloud Run.

• MCP Usage: Using the Cloud Run remote MCP server.

• Infrastructure as Code: Terraform examples for services, jobs, worker pools, and IAM bindings.

• IAM & Security: Roles, service identities, and ingress/egress controls.

• Networking Best Practices & Cost Optimization: Cost optimization strategies, Direct VPC egress, IP address and port exhaustion strategies, performance throughput tuning, and MTU settings.

If you need product information not found in these references, use the Developer Knowledge MCP server search_documents tool.

Data Lineage Summary

This skill guides the agent in investigating and summarizing the Data Lineage graph for a specific focal asset (Table-Level Lineage) or specific fields (Column-Level Lineage). It provides an intuitive left-to-right walkthrough of how data enters and leaves the asset, abstracting away complex node and link details into plain English.

Prerequisites

This skill relies on the Google Cloud Data Lineage (Knowledge Catalog) MCP Server for graph traversal. Ensure you can run search_lineage queries in both upstream and downstream directions. For detailed connection configurations and tool schemas, refer to MCP Usage.

Workflow Logic

1. Get Lineage

Fetch the lineage graph in both directions from the focal point (both upstream and downstream) by making two separate calls to the MCP tool: one with "direction": "UPSTREAM" and another with "direction": "DOWNSTREAM".

• Location Strategy: You MUST use the read_url tool to fetch the comprehensive list of locations dynamically from the provided Knowledge Catalog Locations link. To ensure cross-regional lineage is not missed, always verify the current list of GCP regions using this link before populating the locations array. You MUST populate the locations array with all supported physical regions fetched from this link. You may optionally additionally determine the asset's specific active region (using bq show or gcloud storage ls).

• Search Parameters: Use maxDepth = 10, maxResults = 5000 and maxProcessPerLink = 10 as robust defaults when calling search_lineage. For example, a DOWNSTREAM call should be formatted like this (expanding the locations array as needed):

  {
    "parent": "projects/project_id/locations/us",
    "locations": [
      "us",
      "us-central1",
      "us-east1",
      "us-west1",
      "europe-west1",
      "asia-northeast1"
    ],
    "rootCriteria": {
      "entities": {
        "entities": [
          {
            "fullyQualifiedName": "bigquery:project.dataset.table"
          }
        ]
      }
    },
    "direction": "DOWNSTREAM",
    "limits": {
      "maxDepth": 10,
      "maxResults": 5000,
      "maxProcessPerLink": 10
    }
  }
  

  Ensure you make a similar call with "direction": "UPSTREAM" to fetch the upstream lineage.

• Column-Level Lineage (CLL): The search_lineage tool can find all Column-Level Lineage (CLL) by configuring the field array. If Table-Level Lineage (TLL) is requested, configure the call to get CLL links along with the TLL links by exploiting the "*" wildcard. For example:

  "rootCriteria": {
    "entities": {
      "entities": [
        {
          "fullyQualifiedName": "bigquery:project.dataset.table",
          "field": [
            "*"
          ]
        }
      ]
    }
  }
  

  If evaluating a specific column, replace "*" with the specific column name (e.g., "efficiency_score").

2. Summarize

Generate the summary using the prompt guidelines below.

• Persona: Act as an expert Data Lineage Analyst generating a concise, easy-to-understand left-to-right walkthrough of the data flow.
• Structure & Flow: Start immediately with the summary text, structured as follows:
  • Overall Flow Type: State the inferred workflow type and data domain (e.g., "This appears to be a Feature Engineering workflow...").
  • Systems Overview: List the primary systems involved up front. If the request is for Column-Level Lineage, you MUST explicitly declare that the scope of the analysis is limited to the specified field up front.
  • Upstream Lineage: Use the exact bold header **Upstream Lineage:**. Narrative must detail how data arrives at the focal asset, mentioning key source systems, projects, and processing tasks (e.g., Spark on Dataproc).
  • Downstream Lineage: Use the exact bold header **Downstream Lineage:**. Detail where data goes from the focal asset to final consumer systems.
  • Analysis Metadata: Display the parameters used for the API call to provide transparency on the boundaries of the summary. The output must contain:
    • Locations Searched: {list_of_locations_queried}
    • Parent Location: {parent_path}
    • Depth Limit: {maxDepth}
    • Process per Link Limit: {maxProcessPerLink}
    • Tip for User: A prompt suggesting they can ask to rerun with expanded locations (if not all were used) or depth.
• Granularity Constraints:
  • Prioritize flows between Systems, Projects, and Datasets over individual files/tables.
  • You MUST explicitly list specific asset names (e.g., source tables, intermediate views, consumer tables) if there are fewer than 5. Do not just summarize counts if there are fewer than 5; name them explicitly. Otherwise, if 5 or more, aggregate them by count (e.g., "5 GCS buckets").
  • Only mention counts for ultimate sources, final consumers, and total assets.
  • Do not repeat project names redundantly for every dataset if only one project is involved.
• Tone: Avoid jargon and generic phrases like "There are distinct factual points." Be direct and clear. The final output is Markdown.

3. Return the Summary

Return the final summarized output back to the user.

External Documentation

• Google Cloud Knowledge Catalog Data Lineage Documentation
• Use the Data Lineage MCP server
• Knowledge Catalog Data Lineage API Reference

SecOps Detection Coverage Skill

This skill guides the agent through an end-to-end detection engineering lifecycle using Google SecOps MCP tools. It handles multiple Threat Detection Opportunities (TDOs) and ensures exhaustive coverage evaluation for all generated synthetic events.

Workflow Execution Checklist

Copy this checklist and track progress for each iteration:

• Step 1: Extract raw text content from a source (for example, blog URL).
• Step 2: Generate Threat Detection Opportunities (TDOs).
• Step 3: Loop through ALL TDOs to generate synthetic events.
• Step 4: Loop through ALL UDM events to evaluate rule coverage.
• Step 5: For identified rules, check enablement and alerting status.
• Step 6: Generate new rules for identified gaps.
• Step 7: Provide a structured summary of findings and gaps.
• Step 8: Ask the user to approve adding newly generated rules to their SecOps environment and create them.

Detailed Steps

1. Extract Threat Intelligence

• Use the following prompt to extract all text content from a URL: - "Fetch the blog text from {url}. You need to extract and output the entire text content of the page, exactly as it appears in the HTML, without any summarization, modification, or omission."

• Summary of Step: Report only that the text was successfully extracted from the provided URL. Do not output the full raw text.

• Next Step: The extracted text will be used to generate Threat Detection Opportunities (TDOs).

2. Generate TDOs

• Call generate_threat_detection_opportunity with the extracted full blog threat raw text. You must not summarize. This tool returns one or more TDOs.

• Summary of Step: Report the number of TDOs generated and provide a brief, high-level summary for each TDO (for example, the key threat or attacker technique identified). Do not output the full TDO JSON.

• Next Step: The process will now loop through each generated TDO to create synthetic events.

3. Generate Synthetic Events (For ALL TDOs)

For every TDO:

• Call generate_synthetic_events using the TDO.

• Summary of Step: Report the total number of synthetic UDM events generated for this TDO. Briefly describe the types of attacker behaviors simulated (for example, "Generated events simulating initial access and privilege escalation"). Don't output the full response.

• Next Step: The generated UDM events will be used to evaluate rule coverage.

4. Evaluate Rule Coverage (For ALL UDM Events)

For every UDM event generated for a TDO:

• Call evaluate_rule_coverage by providing the UDM event in valid JSON format. Provide only the UDM event as a single, valid JSON object. You MUST Provide each UDM event as a standard stringified JSON object within the udmsJson list. Do not apply an additional layer of escaping to the JSON string. Provide a standard JSON stringification with no extra backslashes.

• Summary of Step: Report which rule_ids matched for this event, if any. If no rules matched, clearly state "No rules matched." Provide counts of events evaluated. Don't output the full coverage evaluation JSON.

• Next Step: The identified matched rules will be audited for their enablement and alerting status.

5. Audit Rule Status

For every distinct rule_id identified:

• Call get_rule to check the rule configuration with CONFIG_ONLY view.

• Summary of Step: For each rule_id, state its enablement status (for example, "Enabled", "Disabled") and alerting status (for example, "Alerting Enabled", "Alerting Disabled").

• Next Step: Review coverage gaps and potentially generate new rules.

6. Gap Mitigation

If gaps are found:

• Call generate_rules for the relevant TDOs.

• Summary of Step: For each gap, describe what coverage was missing and confirm if a new rule was generated. Provide a brief summary of what the newly generated rule aims to detect.

• Next Step: Provide a final structured summary of all findings and gaps.

7. Provide Summary

• Format and present a final structured summary of all findings and gaps. Refer to the Output Format section below for the required schema.

• Summary of Step: Present the structured summary of TDOs, coverage, missing coverage, and errors.

• Next Step: Ask the user if they would like to create the newly generated rules in their SecOps environment.

8. Rule Creation

• If new rules were generated in Step 6, present them to the user and ask if they would like to create these rules in their SecOps environment. Allow the user to approve or reject each rule. For each approved rule, use the user's configured SecOps MCP server and the SecOps tool create_rule to add the rule to their SecOps environment. Pass the YARA-L rule text string via the rule parameter of the create_rule tool.

• Summary of Step: Report which rules were approved and successfully created in the SecOps environment.

• Next Step: The detection engineering coverage evaluation workflow is complete.

Output Format

Provide a summary for each TDO processed:

TDO: {tdo summary}

Coverage Eval: [{rule_id, enablement status, alerting status}, ...]

Missing Coverage: [{summary, generated rule}] // Only if gaps exist

Errors: [{if any any errors encountered, specify the tool}]

Tool Reference

• generate_threat_detection_opportunity: Initial tool for threat analysis.
• generate_synthetic_events: Generates logs simulating the TDO.
• evaluate_rule_coverage: Checks if existing rules detect the synthetic UDMs.
• get_rule: Use to check alerting_enabled and enabled status of SIEM rules.
• generate_rules: Codifies detection logic for gaps.
• create_rule: Deploys the rule in the SecOps environment.

Firebase Basics

CRITICAL Mandatory prerequisites

Before attempting to fulfill any user request regarding Firebase, you MUST follow these steps in order. Do not proceed to implementation until these are completed. Failure to follow these instructions may result in using outdated patterns and lack of access to essential reference materials.

1. Leverage the planning phase

   If you use a planning mode (e.g., maintaining a task.md file), you MUST include a task to check and install firebase/agent-skills as your very first item.

2. Ensure NPM is installed.

   ## Check if NPM is installed
   npm --version
   

   If NPM is not installed, guide the user to download and install the LTS version from https://nodejs.org/en/download.

   Then, request the user to manually install Node.js and to reply with a confirmation that the installation is finished. Stop and wait for the user's confirmation.

3. Verify and install Agent Skills for Firebase

   You MUST ensure the full set of skills is installed to avoid using outdated patterns. Run this command:

   npx -y skills add firebase/agent-skills -y
   

   If the skills are already installed, this command will ensure they are up to date. Do not skip this step.

Quick start

After completing the mandatory prerequisites above, proceed with these steps to set up your environment:

1. Log in to the Firebase CLI.

   Run this command:

   npx -y firebase-tools@latest login
   

   Then, ask the user to complete the login flow in the browser.

2. Set an active project for the CLI.

   Most Firebase tasks require an active project context. Check the current project for the Firebase CLI by running this command:

   npx -y firebase-tools@latest use
   

   • If the command outputs Active Project: <PROJECT_ID>, you can proceed with your task.

   • If the command does not output an active project, ask the user if they have an existing Firebase project ID.

     • If yes: Set the ID as the active project and add a default alias by running:

       npx -y firebase-tools@latest use --add <PROJECT_ID>
       

     • If no: Create a new Firebase project by running:

       npx -y firebase-tools@latest projects:create <PROJECT_ID> --display-name <DISPLAY_NAME>
       

Reference directory

• Firebase core concepts
• Firebase CLI usage
• Firebase client library usage
• Firebase CLI and MCP server
• Firebase IaC usage
• Firebase security-related features
• Additional Published Skills

If you need product information that's not found in these references, check the other skills for Firebase that you have installed, or use the search_documents tool of the Developer Knowledge MCP server.

gcloud CLI Skill for AI Agents

This document provides essential guidelines and best practices for AI agents interacting with the Google Cloud SDK (gcloud CLI). Following these rules is critical to avoid hallucinated commands, flags, flag values, and positional argument syntax, prevent destructive actions, and minimize context window usage.

Getting Started

1. Installation

If the gcloud executable is missing, refer to the official Google Cloud CLI Installation Guide to install it on your platform (Linux, macOS, Windows, etc.).

2. Authorization

Authenticate the CLI with Google Cloud. Choose the flow that matches your running environment:

• User Account (Interactive): Run gcloud auth login. Follow the browser prompts to sign in.
• User Account (Headless Flow): If operating on a terminal without a web browser (e.g. containers, remote SSH), append the --no-browser flag: gcloud auth login --no-browser. Copy the URL, sign in on another machine, and return the authentication code.
• Application Default Credentials (ADC): To authenticate code calls from local applications or SDK libraries, set up ADC via gcloud auth application-default login (append --no-browser for headless environments).
• Service Account (Best for Detached/Headless Automation): Authenticate directly using a JSON key file. Ideal for fully automated, background tasks and pipelines: gcloud auth activate-service-account --key-file=path/to/key.json. Note that some organizations may restrict access to JSON key files for security reasons.
• Service Account Impersonation (Preferred for Local Pair-Programming Agents): Leverage the human developer's existing user credentials to assume a service account identity. Best for local development assistants to avoid insecure private keys on human workstations: gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

Separation of Privilege (Critical): Both service account approaches ensure the agent's permissions remain strictly distinct from the human user's wide access limits (enforcing least privilege), and ensure actions are properly audited under the agent's focused identity. (Impersonation requires roles/iam.serviceAccountTokenCreator).

For more detailed strategies and authentication types (such as Workload Identity Federation), see Authorizing the gcloud CLI.

Core Principles

1. Explicit Command Validation (Mandatory)

Your internal knowledge of gcloud may be stale or prone to hallucination (e.g., hallucinating commands, flags, flag values, or positional argument syntax). You are FORBIDDEN from executing commands until you have validated the exact syntax at the leaf level.

• Action: Always call gcloud help <command> for the exact command you intend to run (e.g., gcloud help compute instances create).
• Verify: Ensure the command, flags, flag values, and positional argument syntax are valid for that specific leaf command before attempting execution. Validation is not transitive from parent groups.

2. Data Reduction Strategies

To save context window space and reduce latency, always minimize the volume of data returned by gcloud.

• Projection: Use --format=json(key1, key2, ...) to select only the specific fields needed for your task. To understand the advanced projection and formatting syntax, refer to gcloud topic projections and gcloud topic formats.

• Limiting: Use --limit=N to cap the number of resources returned.

• Filtering: Use --filter to narrow down results server-side. Prioritize : for pattern matching and never quote the right side of the colon. Treat the entire filter flag as a singular string without quoting or escaping characters. To study the filter expression syntax, refer to gcloud topic filters.

• Schema Discovery: Unconstrained resource lists can quickly exhaust your context window with redundant data. To prevent this, discover a resource's schema before executing queries. If you are unsure of the JSON key path for projecting fields (--format) or filtering (--filter), run the targeted resource's list command (if supported) with a single-item limit:

  gcloud <GROUP> <RESOURCE> list --limit=1 --format=json
  

  Examine this single instance's JSON structure to safely identify the correct schema keys before requesting full or filtered datasets.

3. Execution Constraints

• Single Commands: Execute a single gcloud command at a time. No command chaining or sequencing.
• No Shell Operators: Do not use command substitution ($(...)), pipes (|), or redirection (>, >>, <). This is to increase command safety and ensure commands are more easily understandable and reviewable by users.
• No Interactivity: Do not run interactive commands or commands requiring a TTY (e.g., gcloud interactive). You must enforce non-interactive mode by appending --quiet (or -q) to your commands. This ensures that defaults are used or errors are raised if input is required.

4. Project and Location Scoping (Critical)

To ensure commands are deterministic, non-interactive, and target the correct environment, you must explicitly manage project and location scoping.

• Explicit Project Target: Do not rely on active configuration defaults. Always append --project=<PROJECT_ID> to all resource-manipulating and querying commands (unless running pure local config commands). This avoids accidental execution against the wrong project.

• Prevent Location Prompts: Many Google Cloud resources are regional or zonal. If you omit the location flag (e.g., --region, --zone, or --location), gcloud will trigger an interactive prompt to select a zone/region. This violates the No Interactivity rule. Always provide explicit location flags if the command requires them.

• Location Discovery: If you do not know the correct region, zone, or location for a service, run discovery commands first (remembering to limit results if there are many):

  • Compute Engine (VMs, Networks):

    • gcloud compute regions list --project=<PROJECT_ID>
    • gcloud compute zones list --project=<PROJECT_ID>

  • Other Services (Standard API Style): Many GCP services utilize a unified locations list command:

    • gcloud <GROUP> locations list --project=<PROJECT_ID>
    • Examples: gcloud artifacts locations list, gcloud kms locations list, gcloud secrets locations list.

Safety & Guardrails

[!CAUTION] Destructive actions (delete, update, remove) MUST be explicitly authorized by the user. Never invoke them autonomously unless explicitly instructed to do so in the context of a safe, pre-approved workflow.

Prohibited Operations (Denylist)

You are strictly prohibited from executing the following commands autonomously. These require explicit human-in-the-loop authorization:

• Any IAM policy, role, or binding modification (Security): Risk of privilege escalation, administrative lockout, service disruption, or unauthorized data exposure.
• No Proactive API Enabling: Assume necessary APIs are enabled. To prevent unexpected resource provisioning or billing charges, do not proactively try to enable APIs. User approval is required to enable any API.
• gcloud * delete (Destructive): Irreversible resource destruction (e.g., project deletion) or data wiping.
• gcloud billing * (Financial): Risk of service disruption or unbounded costs.
• gcloud organizations * (Governance): Org-level changes affect security posture for all users.
• gcloud kms * (Encryption): Risk of permanently locking data.
• gcloud infra-manager deployments apply (Destructive): Autonomous IaC execution can destroy managed resources.

Execution Guidelines

• Dry Run (Mandatory): You MUST invoke a command with --dry-run (or equivalent) first if it exists, before executing the actual command, to preview changes.

• Long Running Operations: For commands that support it, the --async flag is highly recommended for long-running operations to avoid blocking the agentic flow. Note that not every command has an --async flag. For commands that return an operation ID (whether via --async or by default), you are responsible for polling for completion if the operation status is needed for the next step.