# Google Ads API Agent — Complete Documentation

> 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 to real Google Ads accounts. Built on Claude by Anthropic. Free to use.

**Repository:** https://github.com/itallstartedwithaidea/google-ads-api-agent
**Website:** https://googleadsagent.ai
**Author:** John Williams — Senior Paid Media Specialist at Seer Interactive
**License:** Open Source
**AI Model:** Claude by Anthropic (Opus 4.5 for main agent and most sub-agents, Sonnet 4.5 for Baymax)

---

## Overview

The Google Ads API Agent is a production-ready AI system that gives Claude direct read/write access to Google Ads accounts through 28 custom Python actions. Unlike wrapper tools or simple chatbots, this agent executes real Google Ads API calls — creating campaigns, adjusting bids, adding negative keywords, generating reports, and managing creative assets.

The system is designed around "The Loop" — a reasoning cycle where the agent asks clarifying questions, calls the appropriate tools, analyzes results, and presents findings. Write operations always require explicit user confirmation with a preview of changes and automatic rollback labeling.

---

## Architecture

### The Loop
The agent's core reasoning cycle:
1. User asks a question or requests an action
2. CEP Protocol — agent asks clarifying questions before any API call
3. Top-Down Reporting — starts with account summary, drills down through 6 filter tiers
4. Adapter Layer — loads the action file, injects secrets, filters parameters, executes
5. Google Ads API — real data, real mutations, all costs converted to dollars
6. Claude analyzes results, validates completeness against account totals
7. Write Safety — any mutation requires CONFIRM with preview, current vs. proposed, and rollback labeling
8. Sub-Agent Delegation — heavy tasks are delegated to 6 specialized Disney-named sub-agents

### CEP Protocol (Clarify, Execute, Present)
Before making any API call, the agent asks clarifying questions to narrow scope:
- Which account or MCC?
- ENABLED campaigns only, or all statuses?
- Date range?
- Minimum spend threshold?
This prevents wasted API calls and ensures the agent returns precisely what the user needs.

### Filter-First Architecture
A 6-tier filtering system that narrows data at each level:
1. Account level — which account in the MCC
2. Campaign status — ENABLED, PAUSED, REMOVED
3. Date range — predefined or custom
4. Spend thresholds — minimum spend to include
5. Performance metrics — CPA, ROAS, conversion thresholds
6. Entity-specific — keyword match types, ad group names, etc.

### Top-Down Reporting
Always starts with the account summary and works downward. Never dumps raw data. Summarizes first, then offers to drill into specific areas the user cares about.

### Write Safety Confirmation
Every write operation requires:
- Preview of what will change
- Current values vs. proposed values
- Impact assessment
- Rollback instructions (all changes are labeled with timestamps)
- Explicit "CONFIRM" from the user

### Adapter Layer (tool_executor.py)
Bridges Claude's tool calls to real Python action files:
- **Secret injection:** Injects API credentials into module.__dict__ before exec_module()
- **Parameter filtering:** Uses inspect.signature() to drop unknown parameters Claude sends
- **Subprocess monkey-patching:** Intercepts pip install calls (dependencies are in requirements.txt)

---

## 28 Custom API Actions

Each action is a standalone Python file in actions/main-agent/ with a run() function. They use 4 credential patterns:

**Pattern A (5-key Google Ads) — 12 actions:**
Uses developer_token, client_id, client_secret, refresh_token, and login_customer_id.

**Pattern B (4-key Google Ads) — 13 actions:**
Uses developer_token, client_id, client_secret, and refresh_token.

**Pattern C (3-key Cloudinary) — 1 action:**
Uses cloud_name, api_key, and api_secret.

**Pattern D (No credentials) — 2 actions:**
Standalone utilities requiring no external API keys.

### Complete Action List

1. **Label Manager** (01_label_manager.py) — Pattern A, Category: Organization. Create, apply, and manage labels across campaigns, ad groups, and keywords.
2. **Conversion Tracking Manager** (02_conversion_tracking_manager.py) — Pattern A, Category: Analysis. View and manage conversion actions and tracking configuration.
3. **Audience Manager** (03_audience_manager.py) — Pattern B, Category: Targeting. Create and manage audience segments, remarketing lists, and custom audiences.
4. **Asset Manager** (04_asset_manager.py) — Pattern B, Category: Organization. Upload and manage ad assets including images, videos, and text.
5. **Budget Manager** (05_budget_manager.py) — Pattern B, Category: Campaign. View and adjust campaign budgets, shared budgets, and budget allocation.
6. **RSA Ad Manager** (06_rsa_ad_manager.py) — Pattern B, Category: Campaign. Create and manage Responsive Search Ads with headlines and descriptions.
7. **Bid & Keyword Manager** (07_bid_keyword_manager.py) — Pattern B, Category: Campaign. Adjust keyword bids, manage match types, and optimize bid strategies.
8. **Negative Keywords Manager** (08_negative_keywords_manager.py) — Pattern B, Category: Organization. Create and manage negative keyword lists across campaigns.
9. **Campaign & Ad Group Manager** (09_campaign_adgroup_manager.py) — Pattern B, Category: Campaign. Create, pause, enable, and configure campaigns and ad groups.
10. **Google Ads Mutate** (10_google_ads_mutate.py) — Pattern B, Category: Campaign. Direct mutate operations for advanced campaign modifications.
11. **Account Access Checker** (11_account_access_checker.py) — Pattern B, Category: Infrastructure. Verify API access levels and account permissions.
12. **Scripts Manager** (12_scripts_manager.py) — Pattern A, Category: Infrastructure. Manage Google Ads scripts within accounts.
13. **Experiments Manager** (13_experiments_manager.py) — Pattern A, Category: Optimization. Create and manage campaign experiments and A/B tests.
14. **Package Installer** (14_package_installer.py) — Pattern D, Category: Infrastructure. Install required Python packages for action dependencies.
15. **Check User Access** (15_check_user_access.py) — Pattern B, Category: Infrastructure. Verify user-level access and permissions.
16. **API Gateway** (16_api_gateway.py) — Pattern B, Category: Infrastructure. Route and manage API requests across services.
17. **Session & State Manager** (17_session_state_manager.py) — Pattern D, Category: Infrastructure. Manage conversation state and sub-agent delegation.
18. **Cloudinary Creative Tools** (18_cloudinary_creative_tools.py) — Pattern C, Category: Creative. Image processing, resizing, and optimization via Cloudinary API.
19. **Query Planner** (19_query_planner.py) — Pattern A, Category: Analysis. Dynamic GAQL query builder for flexible account data retrieval.
20. **Recommendations Manager** (20_recommendations_manager.py) — Pattern A, Category: Optimization. View and apply Google Ads optimization recommendations.
21. **Search Term Manager** (21_search_term_manager.py) — Pattern B, Category: Analysis. Analyze search terms, identify wasted spend, suggest negative keywords.
22. **Geo & Location Manager** (22_geo_location_manager.py) — Pattern B, Category: Targeting. Manage geographic targeting and location bid adjustments.
23. **Device Performance Manager** (23_device_performance_manager.py) — Pattern A, Category: Analysis. Analyze performance by device type with bid adjustment recommendations.
24. **Change History Manager** (24_change_history_manager.py) — Pattern A, Category: Analysis. Audit account change history and track modifications.
25. **Campaign Creator** (25_campaign_creator.py) — Pattern A, Category: Campaign. Full campaign creation with targeting, bidding, budget, and ad configuration.
26. **Ad Schedule Manager** (26_ad_schedule_manager.py) — Pattern A, Category: Optimization. Set and manage ad scheduling and dayparting rules.
27. **Bidding Strategy Manager** (27_bidding_strategy_manager.py) — Pattern A, Category: Optimization. Configure and manage portfolio and campaign-level bidding strategies.
28. **PMax Asset Group Manager** (28_pmax_asset_group_manager.py) — Pattern A, Category: PMax. Create and manage Performance Max campaign asset groups.

---

## 6 Specialized Sub-Agents

Heavy tasks are delegated to Disney-named sub-agents, each with their own system prompt and custom actions.

### Simba — Reporting & Analysis
- **Model:** Opus 4.5
- **Actions:** 8 (in actions/sub-agents/reporting/)
- **Principle:** "Summarize, don't dump."
- **Capabilities:** Performance reports, search term analysis, auction insights, PMax reporting, change history audits.
- **System Prompt:** prompts/sub-agents/01_reporting_analysis.md

### Nemo — Research & Intelligence
- **Model:** Opus 4.5
- **Actions:** 4 (in actions/sub-agents/research/)
- **Principle:** "Insight over information."
- **Capabilities:** Keyword planning, Google Trends, Ads Transparency Center, competitive SERP analysis via SearchAPI.io.
- **System Prompt:** prompts/sub-agents/02_research_intelligence.md

### Elsa — Optimization
- **Model:** Opus 4.5
- **Actions:** 0 (contribution opportunity)
- **Principle:** "Preview before execute."
- **Capabilities:** Bulk bid/budget changes, Google recommendations — actions need building.
- **System Prompt:** prompts/sub-agents/03_optimization.md

### Aladdin — Shopping & PMax
- **Model:** Opus 4.5
- **Actions:** 0 (contribution opportunity)
- **Principle:** "E-commerce focused. ROAS is king."
- **Capabilities:** Product feeds, asset groups, PMax optimization — actions need building.
- **System Prompt:** prompts/sub-agents/04_shopping_pmax.md

### Moana — Creative
- **Model:** Opus 4.5
- **Actions:** 2 (in actions/sub-agents/creative/)
- **Principle:** "Visual first."
- **Capabilities:** Responsive display ads, demand gen campaigns across YouTube, Discover, and Gmail.
- **System Prompt:** prompts/sub-agents/05_creative.md

### Baymax — Creative Innovate
- **Model:** Sonnet 4.5
- **Actions:** 2 (in actions/sub-agents/creative-innovate/)
- **Principle:** "Receive → Process → Return ready-to-use."
- **Capabilities:** Cloudinary image processing, Gemini vision AI, platform-specific creative resizing for 20+ formats.
- **System Prompt:** prompts/sub-agents/06_creative_innovate.md

---

## Getting Started

### Prerequisites
- Python 3.10+
- Anthropic API key
- Google Ads API credentials (developer token + OAuth2)

### Installation

```bash
# 1. Clone the repo
git clone https://github.com/itallstartedwithaidea/google-ads-api-agent.git
cd google-ads-api-agent

# 2. Virtual env + dependencies
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 3. Configure credentials
cp .env.example .env
# Edit .env — minimum: ANTHROPIC_API_KEY + GOOGLE_ADS_* keys

# 4. Validate everything works
python scripts/validate.py

# 5. Run the agent
python scripts/cli.py
```

### Required Credentials
- **Anthropic API Key:** Get from https://console.anthropic.com/settings/keys
- **Google Ads API (5 keys):** Developer token, OAuth2 client ID, client secret, refresh token, MCC customer ID. Apply at https://ads.google.com

### Optional Credentials
- **Cloudinary:** Image/video processing. Sign up at https://cloudinary.com/users/register_free
- **SearchAPI.io:** Google search, Trends, Ad Transparency. Sign up at https://www.searchapi.io/signup
- **Google AI / Gemini:** AI image generation. Get key at https://aistudio.google.com/apikey

### Deployment Options
1. **Interactive CLI:** `python scripts/cli.py`
2. **REST API:** `uvicorn deploy.server:app --port 8000`
3. **Docker:** `docker compose up`
4. **Python SDK:** `from deploy import create_agent_system`

---

## Repository Structure

```
google-ads-api-agent/
├── README.md                    # Full implementation guide
├── .env.example                 # Credential template
├── requirements.txt             # Python dependencies
├── Dockerfile                   # Container build
├── docker-compose.yml           # Multi-service orchestration
├── deploy/                      # Orchestrator, executor, schemas, server
│   ├── orchestrator.py
│   ├── tool_executor.py
│   ├── tool_schemas.py
│   └── server.py
├── scripts/                     # CLI + validation suite
│   ├── cli.py
│   └── validate.py
├── actions/
│   ├── main-agent/              # 28 Python action files
│   └── sub-agents/              # 16 sub-agent action files
│       ├── reporting/
│       ├── research/
│       ├── creative/
│       └── creative-innovate/
├── prompts/                     # System prompts — main + 6 sub-agents
│   └── sub-agents/
├── configs/                     # agent_registry.json — metadata
│   └── agent_registry.json
└── docs/
    └── ARCHITECTURE.md          # Full technical architecture
```

---

## Author

**John Williams** — Senior Paid Media Specialist at Seer Interactive with 15+ years managing $48M+ in digital advertising spend across Google Ads, Meta, Microsoft, Amazon, and other platforms.

**Career highlights:**
- NortonLifeLock: 192% year-over-year paid search growth
- Gen Digital, Farmers Insurance
- Conference speaker at Hero Conf on AI applications in advertising

**Built through:** It All Started With A Idea — John's consultancy and product studio building AI-powered marketing tools.

**Connect:**
- Website: https://itallstartedwithaidea.com
- GitHub: https://github.com/itallstartedwithaidea/google-ads-api-agent
- LinkedIn: https://www.linkedin.com/in/johnmichaelwilliams
- X / Twitter: https://x.com/_johnmwilliams
- Instagram: https://www.instagram.com/_johnmwilliams/

**Featured in:**
- LinkedIn: Open Source Announcement — https://www.linkedin.com/posts/johnmichaelwilliams_today-im-releasing-something-ive-been-quietly-activity-7426835945859084289-kUf-
- LinkedIn: Google Ads Free Keywords Guide — https://www.linkedin.com/pulse/google-ads-free-keywords-its-official-john-williams--4b2qc/
- Feedonomics: Tips to Improve Google Ads Performance — https://feedonomics.com/digital-marketing-tips-from-the-pros/tips-to-help-improve-your-google-ads-performance-part-2/
- Hero Conf 2025 San Diego (Speaking) — https://paidsearch.org/event/hero-conf-2025-san-diego/