# Google Ads API Agent

> An open-source, enterprise-grade AI agent that manages Google Ads accounts through the API. 28 custom Python actions, 6 specialized sub-agents, live read/write access. Built on Claude by Anthropic. Free to use.

## About

- [Homepage](https://googleadsagent.ai): Project overview, animated demo of The Loop, architecture diagrams, and getting started guide.
- [GitHub Repository](https://github.com/itallstartedwithaidea/google-ads-api-agent): Full source code — 66 files across 12 directories.
- [Architecture Documentation](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/docs/ARCHITECTURE.md): CEP Protocol, Filter-First architecture, Top-Down Reporting, adapter layer, and write safety confirmation system.
- [README](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/README.md): Complete implementation guide with credential setup, deployment options, and usage examples.

## Key Concepts

- [The Loop](https://googleadsagent.ai): The agent's core reasoning cycle — ask, clarify, call tools, analyze, confirm writes, execute, label for rollback.
- [CEP Protocol](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/docs/ARCHITECTURE.md): Clarify, Execute, Present — the agent always asks clarifying questions before making any API call.
- [Filter-First Architecture](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/docs/ARCHITECTURE.md): 6-tier filtering system that narrows data at each level to avoid overwhelming responses.
- [Write Safety Confirmation](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/docs/ARCHITECTURE.md): All write operations require explicit CONFIRM with preview of current vs. proposed changes and rollback labeling.
- [Adapter Layer](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/deploy/tool_executor.py): Bridges Claude's tool calls to real Google Ads API actions — handles secret injection, parameter filtering, and subprocess monkey-patching.

## 28 API Actions

- [actions/main-agent/](https://github.com/itallstartedwithaidea/google-ads-api-agent/tree/main/actions/main-agent): All 28 standalone Python action files with real Google Ads API read/write access.
- [Query Planner](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/actions/main-agent/19_query_planner.py): Dynamic GAQL query builder for account data retrieval.
- [Campaign Creator](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/actions/main-agent/25_campaign_creator.py): Full campaign creation with targeting, bidding, and budget configuration.
- [RSA Ad Manager](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/actions/main-agent/06_rsa_ad_manager.py): Responsive Search Ad creation and management.
- [PMax Asset Group Manager](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/actions/main-agent/28_pmax_asset_group_manager.py): Performance Max asset group operations.
- [Negative Keywords Manager](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/actions/main-agent/08_negative_keywords_manager.py): Negative keyword list management across campaigns.

## 6 Sub-Agents

- [prompts/sub-agents/](https://github.com/itallstartedwithaidea/google-ads-api-agent/tree/main/prompts/sub-agents): System prompts for all 6 Disney-named sub-agents.
- [Simba — Reporting & Analysis](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/prompts/sub-agents/01_reporting_analysis.md): Performance reports, search term analysis, auction insights, PMax reporting, change history audits. 8 actions.
- [Nemo — Research & Intelligence](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/prompts/sub-agents/02_research_intelligence.md): Keyword planning, Google Trends, Ads Transparency Center, competitive SERP analysis. 4 actions.
- [Elsa — Optimization](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/prompts/sub-agents/03_optimization.md): Bulk bid/budget changes, Google recommendations. Actions need building — contribution opportunity.
- [Aladdin — Shopping & PMax](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/prompts/sub-agents/04_shopping_pmax.md): Product feeds, asset groups, PMax optimization. Actions need building — contribution opportunity.
- [Moana — Creative](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/prompts/sub-agents/05_creative.md): Responsive display ads, demand gen campaigns across YouTube, Discover, and Gmail. 2 actions.
- [Baymax — Creative Innovate](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/prompts/sub-agents/06_creative_innovate.md): Cloudinary image processing, Gemini vision AI, platform-specific creative resizing. 2 actions.

## Deployment

- [deploy/](https://github.com/itallstartedwithaidea/google-ads-api-agent/tree/main/deploy): Orchestrator, tool executor, tool schemas, and server files.
- [Interactive CLI](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/scripts/cli.py): `python scripts/cli.py`
- [REST API](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/deploy/server.py): `uvicorn deploy.server:app --port 8000`
- [Docker](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/docker-compose.yml): `docker compose up`
- [Python SDK](https://github.com/itallstartedwithaidea/google-ads-api-agent/blob/main/deploy/__init__.py): `from deploy import create_agent_system`

## Credentials

- Anthropic API Key (required): Powers the Claude agent backbone.
- Google Ads API — 5 keys (required): Developer token, OAuth2 client ID, client secret, refresh token, and MCC ID.
- Cloudinary (optional): Image and video processing for creative sub-agents.
- SearchAPI.io (optional): Google search, Trends, and Ad Transparency data.
- Google AI / Gemini (optional): AI image generation via Baymax sub-agent.

## Author

- [John Williams](https://itallstartedwithaidea.com): Senior Paid Media Specialist at Seer Interactive. 15+ years managing $48M+ in digital advertising. Former NortonLifeLock (192% YoY growth), Gen Digital, Farmers Insurance. Conference speaker at Hero Conf on AI in advertising.
- [It All Started With A Idea](https://itallstartedwithaidea.com): John's consultancy and product studio building AI-powered marketing tools.
- [GitHub](https://github.com/itallstartedwithaidea/google-ads-api-agent)
- [LinkedIn](https://www.linkedin.com/in/johnmichaelwilliams)
- [X / Twitter](https://x.com/_johnmwilliams)