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.yamlconfiguration file with your OAuth 2.0 credentials in your$HOMEdirectory (loaded by default), or at a custom path specified by theGOOGLE_ADS_CONFIGURATION_FILE_PATHenvironment variable. Validation and diagnostic scripts requiregoogle-ads.yamleven when you generate code for another client library. - Familiarity with Google Ads API concepts and authentication.
Software:
- Python 3.10 or later (with
pip) installed and on your systemPATH. Python runs generated read-only scripts and local validation tools. - Host agent platform:
- Google Antigravity command-line tool (
agy), or - Claude Code command-line tool (
claudewith Node.js 18 or later).
- Google Antigravity command-line tool (
- Git installed on your system
PATH.
- Python 3.10 or later (with
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
agyCLI session to load the plugin. - Claude Code: In an active Claude Code session, run the
/reload-pluginscommand or restart theclaudecommand-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
- Claude Code:
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."
- Claude Code:
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, anddelete) to thesaved/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.)
- Claude Code:
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.)
- Claude Code:
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."
- Claude Code:
Project codebase context: To include local helper modules and pipelines, change to your project directory and start the
agyorclaudecommand-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
- GitHub issues: Report bugs, suggest features, or ask for help on the Issues tab in the repository.
- Discord: Join the
#ads-api-ai-toolschannel on the Google Advertising and Measurement Community Discord server. - Feedback: Share your feedback through the Developer Assistant feedback survey.
Contribution guidelines
Contributions are welcome. For contribution steps, see the CONTRIBUTING.md
file in the GitHub repository.
Next steps
- Install Google Ads API AI agent skills
- Connect your AI client to the Google Ads MCP server
- Compare Google Ads AI tools and Developer Assistant architecture