Ad Trafficking Agent

An intelligent automation system built on Google Cloud Platform that automates the end-to-end ad trafficking workflow.

Overview

The Ad Trafficking Agent monitors a dedicated Gmail inbox for insertion order (IO) emails, validates campaigns against the Boostr Order Management System, generates standardized trafficking sheets, and updates Google Ad Manager automatically.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     AD TRAFFICKING WORKFLOW                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. USER sends email with IO_TAGS or IO_TAGS_FILE subject       │
│     └── Attachment: .xls or .xlsx file                          │
│                                                                  │
│  2. PLANNER AGENT processes the email                           │
│     ├── Tool A: Validates email & extracts attachment           │
│     ├── Tool B: Validates campaign in Boostr OMS                │
│     └── Tool C: Generates Trafficking Sheet                     │
│                                                                  │
│  3. APPROVAL EMAIL sent back to original sender                 │
│     └── "Reply with 'approved' to proceed"                      │
│                                                                  │
│  4. USER replies with "approved"                                │
│                                                                  │
│  5. EXECUTOR AGENT completes workflow                           │
│     └── Tool D: Updates Google Ad Manager                       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Tech Stack

• Orchestration: Google Vertex AI Agent Engine
• Serverless: Google Cloud Functions
• Messaging: Google Pub/Sub
• Storage: Google Cloud Storage
• Secrets: Google Secret Manager
• Email: Gmail API
• Ad Server: Google Ad Manager API
• OMS: Boostr API
• Language: Python 3.13+

Project Structure

├── adk_sequential_agent.py    # Main agent orchestrator
├── cloud_function/
│   ├── main.py                # Cloud Function trigger
│   └── requirements.txt       # Cloud Function dependencies
├── src/
│   ├── services/
│   │   ├── boostr_service.py  # Boostr OMS integration
│   │   ├── email_service.py   # Gmail API integration
│   │   ├── gam_service.py     # Google Ad Manager integration
│   │   └── sheet_service.py   # Trafficking sheet generator
│   └── utils/
│       ├── parser.py          # File parsing utilities
│       └── secret_manager.py  # GCP Secret Manager client
├── requirements.txt           # Python dependencies
└── README.md

Email Subject Rules

Subject	OMS Validation	GAM Validation	Use Case
IO_TAGS	❌ Skipped	❌ Skipped	Quick processing, bypass validation
IO_TAGS_FILE	✅ Required	✅ Required	Full validation against Boostr & GAM

Setup

Prerequisites

• Google Cloud Project with billing enabled
• Python 3.13+
• gcloud CLI installed and authenticated

Required Secrets (Google Secret Manager)

Secret Name	Description
gmail-token	Gmail OAuth token.json content
gmail-credentials	Gmail OAuth credentials.json content
boostr-api-key	Boostr API JWT token
googleads-yaml	GAM credentials YAML
googleads-key	GAM service account JSON key

Installation

1. Clone the repository:

git clone https://github.com/phantomdev0826/Ad-Trafficking-Agent.git
cd Ad-Trafficking-Agent

2. Install dependencies:

pip install -r requirements.txt

3. Configure secrets in Google Secret Manager

4. Deploy the agent:

python deploy_agent.py

Usage

Python SDK

import vertexai
from vertexai.preview import reasoning_engines

# Initialize
vertexai.init(project="your-project", location="us-central1")
agent = reasoning_engines.ReasoningEngine("your-agent-resource-id")

# Full workflow (prototype mode)
response = agent.query()

# Planner only (sends approval email)
response = agent.query(mode="planner")

# Executor only (after approval)
response = agent.query(mode="executor", operative_id="123456")

Email Workflow

1. Send email to the monitored inbox

   • Subject: IO_TAGS or IO_TAGS_FILE
   • Attach: .xls or .xlsx file

2. Wait for approval email

3. Reply with "approved" to complete GAM update

License

MIT License

Author

phantomdev0826