Buddy — AI Google Ads Agent

Buddy is a free AI-powered Google Ads agent that connects directly to your account via the Google Ads API (v22). Through natural conversation, Buddy audits campaigns, identifies wasted spend, builds optimized account structures, creates ads and keywords, manages bids and budgets, sets up targeting and extensions, researches competitors via Google Trends and the Ads Transparency Center, and provides actionable recommendations backed by live data. Over 30 write operations are available — from creating campaigns to setting up conversion tracking.

Buddy is live now. Connect your Google Ads account, pick an AI model (Claude, GPT, or Gemini), and start managing your campaigns through conversation. Launch Buddy →

Quick Start

Open Buddy
Click Settings (gear icon) and add your AI API key (Anthropic, OpenAI, or Google)
Connect your Google Ads account (OAuth or manual credentials)
Start chatting — ask "audit my account", "show wasted spend", or "build me a campaign structure"

No AI key? Buddy still works for landing page scans and general advertising advice — just paste a URL and ask.

Connect Google Ads

LIVE Two methods to connect your account:

Method 1: OAuth (recommended)

Open Settings and click Connect with Google
Sign in with the Google account that has access to your Google Ads
Authorize the app — Buddy receives a refresh token stored server-side in encrypted KV
Your Customer ID auto-populates

Method 2: Manual credentials

In Settings, enter your Developer Token, Client ID, Client Secret, Refresh Token, and Customer ID
Click Test Connection to verify

MCC accounts: If you connect an MCC (Manager account), Buddy auto-detects this and discovers all client accounts underneath. You can switch between them with the account picker.

AI API Keys

Buddy supports three AI providers. Pick the one you prefer:

Provider	Models	Get a Key
Anthropic (Claude)	claude-sonnet-4-6, claude-opus-4-6	console.anthropic.com
OpenAI (GPT)	gpt-5.4, gpt-5.4-pro, gpt-5.3-codex	platform.openai.com
Google (Gemini)	gemini-3-flash-preview, gemini-3-pro-preview	aistudio.google.com

Keys are stored in sessionStorage only — cleared when you close the tab. They're sent to the Brain server for API calls but never persisted.

Security & Privacy

🔒 Key security measures:

API keys stored in sessionStorage only — cleared on tab close
Google Ads OAuth tokens use Authorization headers (never URL params)
All API endpoints restrict CORS to googleadsagent.ai origins only
Write operations require explicit CONFIRM before execution
Rate limiting on all endpoints (20-60 req/min depending on endpoint)
SSRF protection blocks private/internal IP addresses on URL fetch

Chat Interface

Buddy's chat works like talking to a senior Google Ads strategist who has live access to your account. Key capabilities:

Natural language queries — "How are my campaigns doing?" pulls live data and analyzes it
Auto-intent detection — Buddy recognizes what you want and pulls the right data automatically
Streaming responses — See Buddy's analysis build in real-time
Action buttons — Quick-action buttons appear contextually (Pull campaigns, Scan page, etc.)
File attachments — Attach images, CSVs, or HAR files for analysis
Export — Say "export" to download any data as CSV

Account Audits

LIVE Say "audit my account" and Buddy pulls live data across multiple dimensions, then applies a 6-layer analysis framework:

Data — WoW/MoM metric changes with specific numbers
Benchmarks — Industry comparison ranges
Seasonality — Time-of-year context that may explain patterns
Platform best practices — Google Ads specific guidance
Cross-channel — Portfolio and platform dependency risks
Business impact — Dollar translation of every finding

Campaign Management

Buddy can create complete campaign structures from scratch or modify existing ones:

Create campaigns with budget, bidding strategy, and network settings
7 bidding strategies: Maximize Conversions, Maximize Clicks, Maximize Conversion Value, Manual CPC, Target CPA, Target ROAS, Target Impression Share
4 channel types: Search, Performance Max, Display, Video
Pause/enable/update any campaign status or budget

Keyword Management

Add keywords to ad groups (exact, phrase, or broad match)
Add negative keywords at campaign level (bulk support)
Pause/enable keywords individually
Update bids on specific keywords
Remove keywords that aren't working
Wasted spend analysis — "Show wasted spend" identifies zero-conversion search terms

Ad Creation & Editing

Create RSA ads with 3-15 headlines and 2-4 descriptions, pinning support
Update existing RSAs (replaces the ad — Buddy warns about history loss)
Pause/enable/remove ads

Landing Page Scanner

LIVE Paste any URL and Buddy scans the landing page for:

Tracking tags (GA4, GTM, Google Ads, Meta Pixel, TikTok, LinkedIn, Pinterest, Snap, X, Microsoft UET)
SEO issues (title, meta description, viewport, heading structure)
Page performance signals
Conversion tracking gaps

Works without any API keys or Google Ads connection.

Web Search, Google Trends & Ad Library

Add a SearchAPI.io key in Settings to unlock 4 search engines:

Google Web Search — Competitive intelligence, industry benchmarks, market research. Returns organic results, related searches, and People Also Ask.
Google Trends — Interest over time, rising/top queries, related topics, regional breakdown. Identify keyword seasonality and emerging trends for campaign timing.
Google Ads Transparency Center — See any advertiser’s live ads, ad formats, regions, and creative. Great for competitive ad copy research.
Trending Now — What’s trending in any country right now. Spot real-time opportunities for responsive ad campaigns.

Use the Web Search, Google Trends, and Ad Library buttons in the toolbar, or ask Buddy directly (e.g., “What are the trending searches for HVAC in Texas?”).

Write Safety & CONFIRM Flow

Every write operation follows a strict safety protocol:

PROPOSE — Buddy presents the plan with specific details (what will change, current vs. proposed)
CONFIRM — You type CONFIRM to approve, or CANCEL to abort
EXECUTE — Buddy makes the actual Google Ads API call
REPORT — Real results from the API are shown (success/failure per operation)

Nothing changes until you type CONFIRM. If Buddy describes operations in its response, those are proposals only. The system shows a warning if Buddy uses execution language without an actual API call.

All 30+ Write Operations

Campaign & Budget Operations

Action	What It Does	Required Params
`create_campaign`	New campaign with budget + bidding strategy (SEARCH, PMAX, DISPLAY, VIDEO)	name, budgetAmountDollars
`update_campaign_status`	Pause, enable, or remove a campaign	campaignId, status
`remove_campaign`	Permanently remove a campaign	campaignId
`update_budget`	Change daily budget amount	budgetId, budgetAmount

Ad Group Operations

Action	What It Does	Required Params
`create_ad_group`	New ad group in a campaign	campaignId, name
`update_ad_group`	Update ad group name, status, or CPC bid	adGroupId + fields to update
`remove_ad_group`	Remove an ad group	adGroupId

Ad Operations

Action	What It Does	Required Params
`create_ad`	New RSA ad (3-15 headlines, 2-4 descriptions)	adGroupId, headlines, descriptions, finalUrl
`update_rsa`	Replace existing RSA (deletes + recreates — loses history)	adGroupId, adId, headlines, descriptions, finalUrl
`update_ad_status`	Pause or enable an ad	adGroupId, adId, status
`remove_ad`	Delete an ad	adGroupId, adId

Keyword Operations

Action	What It Does	Required Params
`create_keyword`	Add keywords to an ad group (bulk)	adGroupId, keyword(s), matchType
`remove_keyword`	Delete a keyword	adGroupId, criterionId
`update_keyword_status`	Pause or enable a keyword	adGroupId, criterionId, status
`update_keyword_bid`	Change keyword CPC bid	adGroupId, criterionId, bid
`create_negative_keyword`	Add campaign negative keywords (bulk)	campaignId, keyword(s)
`customer_negative_criterion`	Add account-level negative keywords or placements	keyword or placement

Targeting & Criteria

Action	What It Does	Required Params
`create_campaign_criterion`	Location, language, device, audience, age, gender, topic, placement, proximity targeting	campaignId + targeting type
`create_ad_group_criterion`	Ad group-level targeting (keyword, placement, topic, audience, demographics)	adGroupId + targeting type
`create_ad_schedule`	Ad schedule (day-parting) with optional bid modifier	campaignId, dayOfWeek, startHour, endHour

Assets (Extensions)

Action	What It Does	Required Params
`create_asset`	Create sitelink, callout, structured snippet, call, or text asset	type + type-specific params
`link_asset_to_campaign`	Link an asset to a campaign	campaignId, assetId, fieldType

Labels

Action	What It Does	Required Params
`create_label`	Create a label for organizing entities	name
`apply_label`	Apply label to campaign or ad group	labelId, entityType, entityId

Conversions & Bidding

Action	What It Does	Required Params
`create_conversion_action`	Set up conversion tracking (webpage, phone, upload)	name, type
`create_bidding_strategy`	Portfolio bidding strategy (tCPA, tROAS, Max Conversions, etc.)	name, type

Shared Sets & Audiences

Action	What It Does	Required Params
`create_shared_set`	Shared negative keyword or placement list	name
`add_shared_set_to_campaign`	Link shared set to a campaign	campaignId, sharedSetId
`create_user_list`	Customer match or rule-based audience list	name

Performance Max

Action	What It Does	Required Params
`create_asset_group`	Asset group for PMax campaigns	campaignId, name, finalUrls

Experiments & Recommendations

Action	What It Does	Required Params
`create_experiment`	Set up a campaign experiment (A/B test)	name, campaignId
`apply_recommendation`	Accept a Google-generated recommendation	recommendationId
`dismiss_recommendation`	Dismiss a recommendation	recommendationId

Raw API Access

Action	What It Does	Required Params
`mutate_operation`	Direct access to `googleAds:mutate` endpoint — supports ALL Google Ads API v22 operations including campaignBudgetOperation, assetGroupSignalOperation, assetGroupListingGroupFilterOperation, biddingDataExclusionOperation, biddingSeasonalityAdjustmentOperation, conversionValueRuleOperation, customizerAttributeOperation, keywordPlanOperation, remarketingActionOperation, etc.	operations (array)

Batch Operations

The execute_google_ads_batch tool lets Buddy execute multiple operations in sequence — for example, creating 4 ad groups, then adding keywords to each, then creating ads, then setting up targeting. Supports all 30+ mutation types. Batch operations execute phase by phase (ad groups → keywords → ads → negatives → everything else) with real results reported per phase.

Brain (Server-Side AI)

DEFAULT The Brain is a Cloudflare Worker that orchestrates AI interactions with tool calling. When enabled, the AI can:

Call 30+ tools (pull data, execute 30+ mutation types, search Google/Trends/Ad Library, scan URLs) in a ReAct loop
Chain multiple tool calls in one turn (e.g., pull campaigns, then pull keywords, then analyze)
Maintain session state across turns (history, entity cache, goals, write history)
Stream responses in real-time via SSE

Direct Mode (Client-Side AI)

Toggle off the Brain in Settings to use Direct Mode. The AI call goes from your browser directly to the provider's API. Useful for:

General advertising advice without Google Ads data
Landing page analysis
When you want to use your API key without the Brain server

Direct mode doesn't support tool calling, so it can't pull live Google Ads data or execute mutations.

Supported Models

Provider	Models	Streaming	Tool Calling (Brain)
Anthropic	claude-sonnet-4-6, claude-opus-4-6	✓	✓
OpenAI	gpt-5.4, gpt-5.4-pro, gpt-5.3-codex	✓	✓
Google	gemini-3-flash-preview, gemini-3-pro-preview	✓	✓

Data Flow

Your Browser
  → Brain (Cloudflare Worker)
    → AI Provider (Claude/GPT/Gemini)
    ← AI response with tool calls
    → Google Ads API v22
    ← Live account data
  ← Streamed response to browser

Read Actions (25+)

Buddy can pull these data types from your Google Ads account:

Action	What You Get
Account Summary	Spend, clicks, impressions, conversions, CPA, CTR, ROAS
Campaigns	All campaigns with metrics, status, budget, bidding strategy
Ad Groups	Ad groups with metrics per campaign
Keywords	All keywords with match type, bid, quality score, metrics
Search Terms	What users actually searched + performance
Wasted Spend	Zero-conversion search terms with cost
RSA Ads	Ad copy, headlines/descriptions, performance ratings
Budgets	Campaign budgets with spend pacing
Geo Performance	Performance by country/region/city
Device Performance	Mobile vs. desktop vs. tablet breakdown
Change History	Recent account changes with who/what/when
Recommendations	Google's optimization suggestions
Conversions	Conversion actions with type and value
Quality Scores	Keyword quality scores with components
Impression Share	Search impression share and lost IS (budget/rank)
Landing Pages	Landing page performance metrics
Negative Keywords	Existing negatives across campaigns
Audiences	Audience segments and performance
Labels	Account labels and labelled entities
Bidding Strategies	Portfolio and standard bidding strategy details
Account Discovery	All accessible accounts under an MCC

Settings Panel

Access via the gear icon. Sections:

AI Provider & Model — Choose Claude, GPT, or Gemini and the specific model
API Keys — Anthropic, OpenAI, and/or Gemini keys
Google Ads Connection — OAuth or manual credentials, Customer ID
SearchAPI Key — Optional, enables Web Search, Google Trends, and Ads Transparency Center
Brain Toggle — Enable/disable server-side AI orchestration

Known Issues

update_rsa loses ad history

The Google Ads API doesn't support in-place RSA edits. update_rsa deletes the old ad and creates a new one, meaning quality score, performance history, and the old ad ID are lost. Buddy warns about this before execution.

MCC metrics query fails

Querying metrics on an MCC (Manager) account returns REQUESTED_METRICS_FOR_MANAGER. Buddy auto-detects this and triggers account discovery so you can switch to a client account.

SPA landing pages may not scan fully

The landing page scanner fetches initial HTML. Single Page Applications that inject content via JavaScript may show incomplete results. For these, use browser DevTools to copy the rendered HTML and paste it into the chat.

Built by John Williams.
Part of the Google Ads Agent ecosystem.