Customer Audience Agent: The Definitive Guide

Purpose


This document is the definitive guide for the Customer Audience Agent, which uses Gemini AI and BigQuery to convert natural language goals into validated audience attributes.

Learning Objectives

After reading this guide, you will be able to:

  • Construct Behavioral Segments: Turn plain English goals into complex technical filters, such as identifying "users who added to cart" within specific timeframes.

  • Verify Logic and Lineage: Click Inspect (or the eye icon) to open the Traceability & Logic sidebar, allowing you to audit step-by-step reasoning logs, raw SQL code, and the specific schema columns used.

  • Operationalize Audience Insights: Pin segments to dashboards, and Share results via internal links or external CSV/Image downloads.

Home & Navigation

Audience: Marketing Teams & Business Users

The landing page provides a streamlined entry point for audience creation:

  • Quick Start Cards: One-click cards for common audiences like "High Value Users" (> 1000$ purchase), "Cart Abandoners," and "Loyal High-End Brand Browsers".

      

  • Navigation: Access Collections, Saved Chats, and the Business Context workspace via the sidebar

      

  • Accessibility: Use the Dark Mode Toggle in the bottom-left profile section to adjust visual contrast for late-night analysis

Conversational Intelligence: Building Your Audience

The agent translates "business lingo" into database rules through an advanced input layer.

Once a query is processed, the UI bifurcates the view to separate factual data from AI-driven analysis.

  • Processing Log: Shows the step by step reasoning chain (Understanding data, Building audience, Counting matching users).

      

  • Deterministic Data: Displays the Total Audience Size and Raw Data rows.

  • AI Interpretation: Provides Key Characteristics and Recommended Actions based on the segment.

      

  • Action Footer:

    • 📌 Pin: Saves the insight to a Dashboard or pins the conversation to the top of the sidebar for weekly meetings.

  • <> Inspect: Opens the Traceability & Logic sidebar to provide full transparency into the reasoning steps, raw SQL code, and data lineage

      

  • 📤 Share: Supports Internal links for existing users and External downloads (Image or CSV).

Explainable Trust: Traceability & Logic

Audience: Analysts & IT Teams

The Traceability & Logic sidebar (accessible via the Inspect footer button or the top right Eye Icon) provides transparency for every insight generated.

Components of the Sidebar

  • Reasoning Log: A human-readable, step-by-step log of every logic gate the AI passed through, including execution times for each step.

  • SQL Inspector: A read-only block containing the Executable Query. This allows analysts to audit the raw code or copy it for use in other systems.

      

  • Data Lineage: Lists exactly which Schema Columns (e.g., is_purchase, amount) the audience definition relies on.

Governance & Feedback

Audience: Admins & Developers

Feedback Loops (RLHF)

The agent captures granular feedback to fine-tune future responses:

  • Positive Feedback: Confirms the logic is correct and reinforces the pattern.

  • Negative Feedback: Users can flag specific errors like Hallucination, Wrong Data, or Too Slow, providing a description for system improvement.\

Safety Guardrails

The system is built with "Circuit Breakers" to protect data and costs:

  • Read-Only Execution: Strict backend enforcement blocks any command other than SELECT (preventing DROP or DELETE).

  • Cost Alerts: The system halts and warns users before executing queries that require expensive, massive data scans.

Advanced Capabilities & Prompting

Audience: Power Users & Data Analysts

Business Context

This feature allows organizations to define custom rules and business lingo so the AI doesn't have to guess.

  • Standardized Filtering: Define mandatory columns for date/time filtering (e.g., Event_Partition).
  • Default Logic: Set default time ranges (e.g., "Analyze the last 7 days if not specified").
  • Custom Definitions: Define business-specific metrics, such as "High-Value Customer = purchase amount > $1000".
  • Ranking Rules: Set default sorting and result limits (e.g., "Top 10 unless specified").

Technical Overview

The Workflow Pipeline

The agent executes the following steps to ensure accuracy and performance:

  1. Context Dictionary Load: Loads schema metadata from a GCS-hosted JSON file.
  2. Schema Formatting: Converts column dictionaries into an AI-readable format.
  3. Sample Data Fetch: Queries BigQuery for a small data sample, casting all columns to STRING to ensure Gemini interprets values correctly.
  4. Prompt Generation: Constructs a rich Gemini prompt containing the schema, sample data, and user goal.
  5. AI Response Parsing: Extracts filter logic, names, and descriptions from the response.
  6. Filter Validation: Runs the generated SQL against BigQuery to calculate the "Matching User" count.