Name: Google Ads API Agent
Author: John Williams

body{background:#08080d;color:#c8bfb0;font-family:Georgia,serif;max-width:860px;margin:0 auto;padding:40px 20px;line-height:1.8}h1,h2,h3{color:#f0a830;margin:32px 0 12px}h1{font-size:48px;letter-spacing:.08em}a{color:#60a5fa}code{font-family:monospace;background:#12110e;padding:2px 6px;border-radius:3px;color:#4ade80;font-size:14px}pre{background:#0e0e16;border:1px solid #1e1e2e;border-radius:8px;padding:20px;overflow-x:auto;margin:16px 0}table{width:100%;border-collapse:collapse;margin:16px 0}th,td{text-align:left;padding:10px 12px;border-bottom:1px solid #1e1e2e}th{color:#887766;font-weight:normal;text-transform:uppercase;font-size:12px;letter-spacing:.1em}hr{border:none;border-top:1px solid #1a1a2a;margin:40px 0}.badge{display:inline-block;padding:2px 8px;border-radius:3px;font-size:11px;margin-left:6px}THE LOOPGoogle Ads API Agent — Open Source28 Tools · 6 Sub-Agents · Live API Access · Built on ClaudeView on GitHub ↗ · llms.txt · llms-full.txtAboutAn 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.Built by John Williams — Senior Paid Media Specialist at Seer Interactive with 15+ years managing $48M+ in digital advertising spend.How The Loop Works

You ask a question

CEP Protocol — agent asks clarifying questions before any API call (Which account? ENABLED only? Date range? Spend threshold?)

Top-Down Reporting — account summary first, then drill down through 6-tier filter system

Adapter Layer — load action → inject secrets → filter params → execute (tool_executor.py)

Google Ads API — real data, real mutations, all costs in dollars

Claude analyzes results, validates completeness against account totals

Write Safety — writes require CONFIRM with preview of current vs. proposed + rollback labeling

Heavy tasks delegated to 6 Disney-named sub-agents

Full architecture documentation ↗28 Custom API ActionsEach action is a standalone Python file in actions/main-agent/ — real Google Ads API calls with read and write access.

Action

File

Category

Credential Pattern

Label Manager

01_label_manager.py

Organization

Conversion Tracking

02_conversion_tracking_manager.py

Analysis

Audience Manager

03_audience_manager.py

Targeting

Asset Manager

04_asset_manager.py

Organization

Budget Manager

05_budget_manager.py

Campaign

RSA Ad Manager

06_rsa_ad_manager.py

Campaign

Bid & Keyword Manager

07_bid_keyword_manager.py

Campaign

Negative Keywords

08_negative_keywords_manager.py

Organization

Campaign & Ad Group Manager

09_campaign_adgroup_manager.py

Campaign

Google Ads Mutate

10_google_ads_mutate.py

Campaign

Account Access Checker

11_account_access_checker.py

Infrastructure

Scripts Manager

12_scripts_manager.py

Infrastructure

Experiments Manager

13_experiments_manager.py

Optimization

Package Installer

14_package_installer.py

Infrastructure

Check User Access

15_check_user_access.py

Infrastructure

API Gateway

16_api_gateway.py

Infrastructure

Session & State Manager

17_session_state_manager.py

Infrastructure

Cloudinary Creative Tools

18_cloudinary_creative_tools.py

Creative

Query Planner

19_query_planner.py

Analysis

Recommendations Manager

20_recommendations_manager.py

Optimization

Search Term Manager

21_search_term_manager.py

Analysis

Geo & Location Manager

22_geo_location_manager.py

Targeting

Device Performance

23_device_performance_manager.py

Analysis

Change History Manager

24_change_history_manager.py

Analysis

Campaign Creator

25_campaign_creator.py

Campaign

Ad Schedule Manager

26_ad_schedule_manager.py

Optimization

Bidding Strategy Manager

27_bidding_strategy_manager.py

Optimization

PMax Asset Group Manager

28_pmax_asset_group_manager.py

PMax

Credential Patterns: A = 5-key Google Ads (12 actions), B = 4-key Google Ads (13 actions), C = 3-key Cloudinary (1 action), D = No credentials (2 actions)6 Specialized Sub-AgentsNamed after Disney characters. System prompts in prompts/sub-agents/, actions in actions/sub-agents/

Agent

Role

Model

Actions

Principle

🦁 Simba

Reporting & Analysis

Opus 4.5

"Summarize, don't dump."

🐠 Nemo

Research & Intelligence

Opus 4.5

"Insight over information."

❄️ Elsa

Optimization

Opus 4.5

0 (needs building)

"Preview before execute."

🧞 Aladdin

Shopping & PMax

Opus 4.5

0 (needs building)

"E-commerce focused. ROAS is king."

🌊 Moana

Creative

Opus 4.5

"Visual first."

🤖 Baymax

Creative Innovate

Sonnet 4.5

"Receive → Process → Return ready-to-use."

Quick Startgit clone https://github.com/itallstartedwithaidea/google-ads-api-agent.git cd google-ads-api-agent python -m venv venv && source venv/bin/activate pip install -r requirements.txt cp .env.example .env python scripts/validate.py python scripts/cli.pyCredentialsRequired: Anthropic API Key + Google Ads API (5 keys)Optional: Cloudinary · SearchAPI.io · Google AI / GeminiDeployment OptionsInteractive CLI: python scripts/cli.py · REST API: uvicorn deploy.server:app --port 8000 · Docker: docker compose up · Python SDK: from deploy import create_agent_systemRepository66 files across 12 directories. View on GitHub ↗AboutBuilt by 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. Former NortonLifeLock (192% YoY paid search growth), Gen Digital, Farmers Insurance. Conference speaker at Hero Conf on AI applications in advertising.Featured In

Open Source Announcement (LinkedIn)

Google Ads Free Keywords — Official Guide

Feedonomics: Tips to Improve Google Ads Performance

Hero Conf 2025 — San Diego (Speaking)

ConnectGitHub · LinkedIn · X / Twitter · Instagram · itallstartedwithaidea.comIt reasons, calls, receives, validates — and loops until it has the truth.OPEN SOURCE · 28 TOOLS · 6 SUB-AGENTS · BUILT ON CLAUDE · googleadsagent.ai