Architecture Overview

Architecture Overview

System Design

┌─────────────────────────────────────────────────────────────────────┐
│                    GOOGLE ADS AGENT (Main)                          │
│                    claude-opus-4 · 21 Tools · 47 Reads · 62 Writes │
│                                                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Filter-First │  │    CEP       │  │  Session & State Manager │  │
│  │ Architecture │  │  Protocol    │  │  (Coordination Bus)      │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
└────────────────────────────┬────────────────────────────────────────┘
                             │ Delegates via handoff protocol
          ┌──────────┬───────┼───────┬──────────┬──────────┐
          ▼          ▼       ▼       ▼          ▼          ▼
     ┌────────┐ ┌──────┐ ┌─────┐ ┌───────┐ ┌───────┐ ┌──────────┐
     │Simba   │ │Nemo  │ │Elsa │ │Aladdin│ │Moana  │ │Baymax    │
     │Report  │ │Intel │ │Optim│ │Shop+  │ │Create │ │Creative  │
     │8 acts  │ │5 acts│ │     │ │PMax   │ │2 acts │ │Innovate  │
     └────────┘ └──────┘ └─────┘ └───────┘ └───────┘ └──────────┘

Data Flow

ReAct Loop (Tool-Calling)

User Message
    │
    ▼
┌──────────────────┐
│ Intent Classifier │ → classifies into ~20 intent categories
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Pre-Pull Data    │ → automatically pulls relevant Google Ads data
└────────┬─────────┘   based on classified intent
         │
         ▼
┌──────────────────┐
│ AI Model + Tools │ → Claude/GPT/Gemini with 21 tool schemas
└────────┬─────────┘
         │
    ┌────┴────┐
    │tool_use │ → model requests a tool call
    └────┬────┘
         │
         ▼
┌──────────────────┐
│ executeToolCall  │ → dispatches to appropriate handler
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ tool_result      │ → result sent back to model
└────────┬─────────┘
         │
         ▼
    (loop until no more tool calls)
         │
         ▼
   Final Response → streamed to user

Intent-Based Pre-Pull

When a user asks a question, the system pre-pulls relevant data before the AI model sees the message:

Intent	Pre-Pulled Data
audit_request	account_summary, list_campaigns, wasted_spend, quality_score_report, impression_share, list_recommendations
campaign_analysis	list_campaigns, daily_performance
keyword_analysis	list_keywords, list_search_terms, wasted_spend
build_strategy	account_summary, list_campaigns, list_keywords, impression_share, geo_performance, device_performance
budget_question	list_budgets, list_campaigns
competitor_analysis	auction_insights, impression_share

Key Design Patterns

Filter-First Architecture

Queries use progressively narrower filters to stay within API rate limits:

1. Cost filter (costMin) — exclude zero-spend entities
2. Status filter — typically ENABLED only
3. Date range — default 30 days, narrower for detailed views
4. Limit — cap result sets (default varies by query)

CEP Write Safety Protocol

Confirm → Execute → Post-check

1. Agent previews the change with human-readable description
2. User explicitly confirms
3. Pre-write snapshot captured
4. Mutation executed
5. Post-write state compared for validation

Multi-Provider AI Routing

Provider	ReAct (Tools)	Streaming	Fallback
Anthropic (Claude)	Yes	Yes	—
OpenAI (GPT)	Yes	Yes	—
Google (Gemini)	No	Yes	Primary fallback

Google Ads API Integration

• API Version: v22
• Base URL: https://googleads.googleapis.com/v22
• Auth: OAuth2 refresh token → access token (cached in memory)
• Read: searchStream endpoint with GAQL queries
• Write: Resource-specific :mutate endpoints
• MCC Support: login-customer-id header for manager accounts

Merchant Center Integration

• API Version: Content API v2.1
• Base URL: https://shoppingcontent.googleapis.com/content/v2.1
• Operations: Insert, list, update, delete products + product statuses