Install and use the Google Ads API Developer Assistant

The Google Ads API Developer Assistant brings deep Google Ads API domain expertise directly into your AI coding environment. Use natural language prompts and built-in slash commands to construct queries, generate client library code, execute read-only API calls, stream ad hoc reports, and troubleshoot integrations.

The Assistant is built for the Google Antigravity and Claude Code agent frameworks (v4.0.0) as a modular plugin. It uses AGENTS.md and CLAUDE.md contracts, built-in slash commands, and specialized domain skills to maintain persistent context, robust safety boundaries, and automated validation pipelines.

Prerequisites

Before you begin, make sure you have the following:

  1. Google Ads API Access:

  2. Software:

Get started

Follow these steps to clone the repository, run the platform-specific installation script, configure your credentials, and activate the plugin.

1. Clone the repository

Clone the repository to your local machine and navigate to the project directory:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Run the installation script

Run the installation script for your target platform. By default, the Python client library is included. You can optionally include additional client libraries (--php, --ruby, --java, --dotnet, or --all).

Antigravity

Linux / macOS: ```bash ./install.sh agy

Or include additional client libraries:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

Or include additional client libraries:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS: ```bash ./install.sh claude

Or include additional client libraries:

./install.sh claude --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

Or include additional client libraries:

.\install.ps1 -Type claude -Php -Dotnet ```

3. Configure credentials

Make sure your API configuration file (for example, google-ads.yaml, google_ads_php.ini, or google_ads_config.rb) is placed in your $HOME directory.

(Optional) To configure a default customer ID, enter your customer ID number directly into config/customer_id.txt (for example, 1234567890). You can also inspect or pin your active API version in config/api_version.txt.

4. Activate the plugin

  • Antigravity: Restart your Antigravity / agy host session to load the plugin.
  • Claude Code: In an active Claude Code session, run /reload-plugins or restart claude.

5. Interact with the Assistant

You can interact with the Assistant using natural language prompts or dedicated slash commands directly in your terminal.

Key features

  • Natural language Q&A and conceptual guidance: Ask questions about Google Ads API features, architectural rules, or specific resources. The Assistant grounds responses in official API definitions rather than relying solely on general LLM training.

    • "What are the available campaign types?"
    • "How do I filter by date in GAQL?"
    • "Explain the difference between click_view and impression_view."
    • "What is a shared set and how do I use it?"
    • Claude Code slash commands: /explain, /step-by-step, /assistant-tutorial

  • Grounded client library code generation: Generate tested, idiomatic code using official Google Ads client libraries (Python, Java, PHP, .NET, and Ruby).

    • "Show me campaigns with the most conversions in the last 30 days."
    • "Get all enabled ad group names for customer 123-456-7890."
    • "Write code to create a Performance Max campaign." Generated code is saved in the saved/code/ directory.

  • Programmatic GAQL query validation: Automatically dry-run and validate complex queries against API metadata, field compatibility, zero-impression rules, and date segmentation before execution.

    • Claude Code: /validate-gaql
    • Natural Language: validate: SELECT campaign.id FROM campaign

  • Object and Protobuf schema inspection: Dynamically inspect resource structures, nested fields, data types, and enum values for any active API version without remote metadata overhead.

    • Claude Code: /inspect-object <resource_or_enum>
    • Natural Language: "Inspect campaign resource"

  • Ad hoc live reporting and CSV export: Ask for performance data in plain English. The Assistant constructs, validates, and runs GAQL queries directly against your account, streaming live formatted tables into the terminal.

    • "Show top 5 keywords by cost last month for customer 123-456-7890."
    • "Save the results as a CSV file." (Exports to saved/csv/).

  • Direct API execution and mutate safety: Execute generated read-only scripts directly within a managed virtual environment.

    • Simply tell the Assistant: "Run the code" or "Execute the script".
    • Mutate Safety: For safety, mutating operations (create, update, delete) are generated to saved/code/ but never executed directly by the assistant. Review and execute them manually outside the assistant.

  • Advanced diagnostics and conversion troubleshooting: Investigate offline conversion upload failures, pre-validate upload files, and generate detailed diagnostic reports.

    • Claude Code: /troubleshoot-conversions
    • Natural Language: "Troubleshoot conversions for customer 123-456-7890." (Reports saved to saved/data/).

  • MCC account hierarchy mapping: Retrieve sub-account customer IDs and map account hierarchies under a manager account.

    • Claude Code: /get-cids <manager_cid>
    • Natural Language: "Get all client customer IDs under manager 123-456-7890"

  • Performance Max listing filters and exclusions: Generate product partition trees and webpage URL exclusions for asset groups.

    • Claude Code: /pmax-filter
    • Natural Language: "Create webpage exclusion filters for my PMax campaign"

  • Additional codebase context: Register your application logic and custom architecture into the Assistant's reasoning.

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Claude Code slash commands reference

When using Claude Code, the following built-in slash commands are available. In Google Antigravity, invoke these same capabilities using natural language prompts or skill tool names like validate_gaql and inspect_object, as described in Key features:

Slash command Purpose Example
/validate-gaql Validates GAQL syntax, compatibility, and rules. /validate-gaql
/inspect-object Inspects Protobuf fields, types, and enums. /inspect-object Campaign
/get-cids Resolves MCC hierarchies and client CIDs. /get-cids 1234567890
/troubleshoot-conversions Runs offline conversion upload diagnostics. /troubleshoot-conversions
/pmax-filter Generates PMax listing filters and exclusions. /pmax-filter
/explain Delivers a 4-part structured explanation. /explain shared set
/step-by-step Formulates a multi-phase task execution plan. /step-by-step upload conversions
/assistant-tutorial Runs an interactive 11-step walkthrough. /assistant-tutorial

Maintenance and updates

To update the repository, plugin installation, and client libraries:

Antigravity

Linux / macOS: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

Uninstallation

To uninstall the assistant plugin:

Antigravity

Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Then restart your Antigravity host session.

Claude Code

In an active Claude Code session: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Or from your terminal: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Optional) Remove the local marketplace registry: bash claude plugin marketplace remove google-ads-assistant-local

Community and support

Contribution guidelines

Contributions are welcome! See the CONTRIBUTING.md file in the GitHub repository for guidelines.

Previous
What is the Google Ads API Developer Assistant?