Install and use the Google Ads API Developer Assistant

The open-source Google Ads API Developer Assistant plugin equips Google Antigravity and Claude Code to inspect schemas, validate Google Ads Query Language (GAQL) queries, generate code, and troubleshoot uploads. See the Developer Assistant overview.

Before you begin

Complete the following prerequisites:

  • Google Ads API access:

    • A Google Cloud project with the Google Ads API enabled. Enabling the API grants Test access for test accounts. Production accounts require Explorer, Basic, or Standard access (see API access levels).
    • A google-ads.yaml configuration file with your OAuth 2.0 credentials in your $HOME directory (loaded by default), or at a custom path specified by the GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable. Validation and diagnostic scripts require google-ads.yaml even when you generate code for another client library.
    • Familiarity with Google Ads API concepts and authentication.
  • Software:

Get started

Follow these steps to clone the repository, install Python dependencies, run the platform installation script, configure your credentials, and activate the plugin.

1. Clone the repository and install Python packages

Clone the repository to your local machine and change to the project directory. Then install the required Python packages (google-ads, ruff, and pytest) in your active environment:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant
pip install -r requirements.txt

2. Run the installation script

Run the installation script for your host platform. The installer clones the Python client library descriptors by default. Pass the --php, --ruby, --java, --dotnet, or --all options to include additional client libraries.

Antigravity

Linux and macOS (Python default):

./install.sh agy

Linux and macOS (with additional client libraries):

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

Windows PowerShell (Python default):

.\install.ps1 -Type agy

Windows PowerShell (with additional client libraries):

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

Claude Code

Linux and macOS (Python default):

./install.sh claude

Linux and macOS (with additional client libraries):

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

Windows PowerShell (Python default):

.\install.ps1 -Type claude

Windows PowerShell (with additional client libraries):

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

3. Configure credentials

Place your google-ads.yaml configuration file in your $HOME directory, where the Python client library loads it by default. To load google-ads.yaml from a custom path instead, set the GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable to that path. Don't commit credential files to version control (for example, add google-ads.yaml to your .gitignore file). If you generate code for other client libraries, also place their configuration files (such as google_ads_php.ini, google_ads_config.rb, or ads.properties) in your $HOME directory.

Optional: In your project working directory, save a default 10-digit customer ID (without hyphens) in the config/customer_id file (for example, 1234567890). You can also inspect or pin your target API version in the config/api_version.txt file in your project directory or installed plugin config/ directory.

4. Activate the plugin

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

5. Interact with the Developer Assistant

Change to your project directory and start the agy or claude command-line tool. Send natural language prompts or slash commands to work with the Google Ads API.

Common workflows and prompts

  • Natural language Q&A and conceptual guidance: Ask questions about Google Ads API features, architectural rules, best practices, or specific resources. The assistant grounds responses in official API definitions rather than general model training alone.

    • "What are the available campaign types?"
    • "How do I filter by date in GAQL?"
    • "Explain the difference between click_view and keyword_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 idiomatic Python code by default, or request Java, PHP, .NET, or Ruby when those client libraries are installed.

    • "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."

    The assistant saves generated code in the saved/code/ directory.

  • Programmatic GAQL query validation: Dry-run and validate 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: Inspect resource structures, nested fields, data types, and enum values for your active API version without remote metadata calls.

    • Claude Code: /inspect-object Campaign
    • Natural language: "Inspect the campaign resource."
  • Ad hoc live reporting and CSV export: Request performance data in natural language. The assistant constructs, validates, and runs GAQL queries against your account, streaming formatted tables to your terminal.

    • "Show top 5 keywords by cost last month for customer 123-456-7890."
    • "Save the results as a CSV file." (Exports to saved/data/ in your working directory.)
  • Direct API execution and mutate safety: Run generated read-only Python, PHP, and Ruby scripts in your active environment. Compile and run Java and .NET code separately.

    • Tell the assistant: "Run the code" or "Execute the script".
    • Mutate safety: The assistant writes mutating operations (create, update, mutate, and delete) to the saved/code/ directory and never executes them directly. Review and run those scripts manually outside the assistant.
  • Advanced diagnostics and conversion troubleshooting: Investigate offline conversion upload failures, validate upload CSV files before sending them, and generate diagnostic reports.

    • Claude Code: /troubleshoot-conversions
    • Natural language: "Troubleshoot conversions for customer 123-456-7890." (The built-in diagnostic script saves reports to ~/saved/data/ in your home directory.)
  • Manager account hierarchy mapping: Retrieve client customer IDs and map account hierarchies under a manager account.

    • Claude Code: /get-cids 1234567890
    • Natural language: "Get all client customer IDs under manager 123-456-7890." (The built-in hierarchy script exports CSV files to ~/saved/data/ in your home directory.)
  • Performance Max listing filters and exclusions: Generate asset group webpage listing group filter trees (WEBPAGE) for URL expansion exclusions.

    • Claude Code: /pmax-filter
    • Natural language: "Create webpage exclusion filters for my PMax campaign."
  • Project codebase context: To include local helper modules and pipelines, change to your project directory and start the agy or claude command-line tool.

Claude Code slash commands reference

In Claude Code, the following built-in slash commands are available. In Google Antigravity, invoke these capabilities by using natural language prompts or skill names such as validate-gaql and inspect-object (see Common workflows and prompts):

Slash command Purpose Example
/validate-gaql Validates GAQL syntax, compatibility, and live dry runs. /validate-gaql
/inspect-object Inspects Protobuf fields, types, and enums. /inspect-object Campaign
/get-cids Resolves manager account hierarchies and client customer IDs. /get-cids 1234567890
/troubleshoot-conversions Runs offline conversion upload diagnostics. /troubleshoot-conversions
/pmax-filter Generates Performance Max webpage listing group filters. /pmax-filter
/explain Delivers a four-part structured concept 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
/sync-client-libs Synchronizes local client libraries with GitHub releases. /sync-client-libs python
/ext-version Displays the plugin version and active API version. /ext-version

Maintenance and updates

From the cloned google-ads-api-developer-assistant repository, run the update script to pull the latest plugin files and refresh the config/api_version.txt file. Then run pip install --upgrade -r requirements.txt in your Python environment so your installed google-ads package matches the updated descriptors:

Antigravity

Linux and macOS (installed client libraries):

./update.sh agy

Linux and macOS (include all client libraries):

./update.sh agy --all

Windows PowerShell (installed client libraries):

.\update.ps1 -Type agy

Windows PowerShell (include all client libraries):

.\update.ps1 -Type agy -All

Claude Code

Linux and macOS (installed client libraries):

./update.sh claude

Linux and macOS (include all client libraries):

./update.sh claude --all

Windows PowerShell (installed client libraries):

.\update.ps1 -Type claude

Windows PowerShell (include all client libraries):

.\update.ps1 -Type claude -All

After updating, reload the plugin in any active session by restarting your agy CLI session, running the /reload-plugins command in Claude Code, or restarting the claude command-line tool.

Uninstallation

To uninstall the Developer Assistant plugin:

Antigravity

Linux and macOS:

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows PowerShell:

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Then restart your agy CLI session.

Claude Code

In an active Claude Code session:

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Or from your terminal:

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

Optional: Remove the local marketplace registry in Claude Code (/plugin marketplace remove google-ads-assistant-local) or from your terminal:

claude plugin marketplace remove google-ads-assistant-local

Community and support

Contribution guidelines

Contributions are welcome. For contribution steps, see the CONTRIBUTING.md file in the GitHub repository.

Next steps