Agent - Search Term Analyzer Workflow

An agentic Google Ads workflow built with Gemini and Google ADK that evaluates search terms using persistent client context and delivers explainable recommendations for human approval.

Comment

Inspiration and problem

A Google Ads account manager often manages eight customers at the same time. Search terms should be reviewed for every customer at least once every two weeks, and an individual account can produce 250 terms or more. That can mean thousands of recurring decisions.

Each decision requires current knowledge of the customer’s products, landing pages, brands, competitors, campaign structure, and performance. Keeping that context current across multiple customers is almost impossible. Manual reviews consume time and money, delayed optimizations waste advertising budget, and inconsistent decisions lead to weaker performance and unhappy customers. Search Term Autopilot turns this recurring audit into a persistent agent workflow. It builds the required customer knowledge once, versions it, refreshes it when needed, and gives every specialized agent only the context required for its task.

This makes Search Term Autopilot a perfect fit for the All Things Agentic Hackathon. It is not a chatbot or a simple text-generation demo, but an autonomous, multi-stage workflow that performs real operational work. Gemini 3.6 Flash handles semantic reasoning, Google ADK orchestrates the specialized agents and tools, Cloud Run hosts the deployed application, and Firestore provides persistent customer memory and run state. The project therefore fulfills all three mandatory technical requirements while directly addressing the Taskmaster track’s goal of automating a complex, repetitive, and high-value business process.

I am especially proud of the agents that build and maintain their own persistent, customer-specific knowledge base. Instead of reconstructing the customer context for every audit, they continuously create a reusable understanding of products, brands, competitors, landing pages, and company-specific details. This foundation makes the project much more than a single search-term workflow: additional Google Ads audit cases can be added later and immediately benefit from the same trusted customer knowledge.

What it does

The demonstrated run starts with a synthetic Google Ads search-term CSV and a customer identifier. The system then completes the following workflow:

  1. A Google ADK Supervisor Agent creates the run, manages shared state, and delegates every stage.
  2. Data Intake validates, normalizes, fingerprints, and deduplicates the incoming records.
  3. Landing-page RAG retrieves the exact content of every destination page. When a current snapshot exists, it is reused. When it does not, the run does not stop: a Coding Scraper Agent inspects the page and writes a site-specific configuration, then a deterministic scraper extracts the text word for word, stores a versioned snapshot, and rejoins the main workflow.
  4. After Landing-page RAG, the Product Agent creates a structured product catalog. The Company Profile Agent adds brands, aliases, spelling variants, competitors, and company-specific context. Firestore stores and versions these artifacts separately for each customer.
  5. The Batch Planner creates restartable work units. The Context Router builds a strict allowlist-based input package for every criterion.
  6. Eight focused evaluation agents assess business relevance, landing-page fit, triggered-keyword fit, campaign and ad-group fit, search intent, competitor detection, KPI performance, and search-term-to-product fit.
  7. Semantic agents never receive performance metrics. Only K7 receives KPI data, and its agent invokes a deterministic, versioned rules engine. This limits anchoring and reduces unnecessary context.
  8. The Result Aggregator validates K1–K8 and applies a deterministic decision matrix. It can recommend keeping or monitoring a term, adding an exact- or phrase-match negative, moving it to another ad group, splitting campaign structure, adjusting a keyword, improving a landing page, or escalating an unclear case.
  9. Every recommendation enters a human review queue as awaiting_approval. The account manager can approve, edit, reject, or defer it. Approved decisions become idempotent change instructions with an audit log.

Every criterion result contains a fixed label, confidence score, short explanation, and evidence references. The account manager can therefore inspect not only the final recommendation, but also the exact product, company, page, or performance evidence behind it.

Technologies used

  • Gemini 3.6 Flash through Google GenAI for semantic reasoning; the verified submission run used Vertex AI
  • Google Agent Development Kit (ADK) for the root agent, specialized sub-agents, tools, and orchestration
  • Google Cloud Run in europe-west3 for the Next.js UI, FastAPI backend, REST API, and MCP endpoint
  • Cloud Firestore in Native mode for runs, profiles, catalogs, landing-page snapshots, and version archives
  • FastAPI, Next.js 14, React, TypeScript, and shadcn/ui
  • Model Context Protocol for workflow access and the prepared server-side Google Ads adapter
  • Scrapling for deterministic landing-page extraction
  • Python 3.11, Pydantic, and pytest

Data sources

  • A 30-row synthetic English Google Ads search-term export for the More Nutrition demo account. The queries and all performance metrics are fictional and contain no customer data; Claude helped generate the dataset.
  • Public product landing pages from morenutrition.co.uk, captured as exact, versioned snapshots for page-grounded analysis.
  • Public Google Search results used by the Company Profile web-research agent for source-backed competitor discovery.

Production-minded safeguards

  • Least-privilege context: semantic judgments cannot anchor on cost or conversion data, and the KPI path cannot see semantic fields.
  • Deterministic boundaries: scraping, KPI evaluation, output validation, and final aggregation use deterministic tools rather than free-form model decisions.
  • Persistent customer isolation: Firestore separates and versions every customer's profiles, catalogs, snapshots, and runs.
  • Restartable processing: batches, checkpoints, retries, and idempotent instructions prevent a partial failure from corrupting the workflow.
  • Human control: no recommendation bypasses review, and live Google Ads mutation is deliberately disabled for this safe demonstration.
  • Credential isolation: Google Ads MCP settings and credentials remain server-side and are never returned to the browser.

Current integration status

The complete CSV-to-K1–K8-to-review workflow is live. The application also exposes its runs, records, profiles, and review decisions through its own streamable HTTP MCP endpoint.

The Settings page contains the prepared server-side Google Ads MCP connection and tool-list test. Direct Google Ads intake is not yet wired into the production demo run. The Schedules page is explicitly labeled as a UI mockup and does not create real cron jobs. These boundaries are shown transparently in both the UI and architecture diagram.

Findings and learnings

  • Persistent context changes the economics of the task. Building and versioning customer knowledge once is far more efficient than reconstructing it for every term and every run.
  • Least-privilege routing improves quality and cost. Strict input allowlists reduce token usage and prevent semantic criteria from being biased by KPIs they should not see.
  • Agent-written scraper configuration scales better than hand-written selectors. New page structures can be analyzed once, converted into a deterministic configuration, and then reused.
  • Deterministic aggregation is easier to trust. The same eight criterion outputs always produce the same action, and every rule can be tested independently.
  • Agents and tools need different jobs. Gemini handles contextual interpretation; deterministic code handles exact extraction, validation, thresholds, persistence, and final action selection.
  • Human review is a feature, not a failure of autonomy. The system removes the expensive research work while preserving accountability for campaign changes.

The repository currently passes 350 automated tests with 1 skipped test, and the production Next.js build completes successfully.

Demonstrated result

The latest verified cloud run, run_20260830_195501_002, processed all 30 synthetic search terms. Every record contains all eight criterion outputs and a final recommendation. All 28 Gemini batch-agent calls completed without an error. The final distribution was:

  • 14 keep
  • 10 manual_review
  • 5 add_negative_phrase
  • 1 adjust_keyword

The run is directly inspectable at: https://suchbegriffe-ui-239331834763.europe-west3.run.app/results?run=run_20260830_195501_002

Disclosure

The project-specific workflow, UI, prompts, tools, and architecture were built for the hackathon. Open-source dependencies are declared in pyproject.toml and ui/package.json. The More Nutrition search-term dataset is synthetic and was created with assistance from Claude. Public advertiser landing pages are used only to demonstrate page-grounded analysis. No real Google Ads account is modified by the demo.

Built With

Share this project:

Updates

Submission history