3CX BigQuery SQL Agent

A Python CLI agent powered by Google Gemini & Google ADK that queries BigQuery data using natural language.

Features

• 🗣️ Natural Language Queries - Ask questions in plain English, get SQL results
• 🤖 Powered by Gemini 3 Pro - Uses Google's latest LLM for intelligent query generation
• 🔧 Google ADK Integration - Built with Google's Agent Development Kit
• 🎨 Colored CLI Output - Easy-to-read responses with syntax highlighting
• ⏳ Progress Indicator - Spinner shows when queries are processing
• 📊 Usage Stats - See duration and token usage for each query

Architecture

flowchart LR
    User[User CLI] <--> Runner[ADK Runner]
    Runner <--> Agent[LlmAgent]
    Agent <--> Gemini[Google Gemini]
    Agent <--> BQToolset[BigQueryToolset]
    BQToolset <--> BQ[(BigQuery)]
    
    subgraph tools [Available Tools]
        list_datasets[list_dataset_ids]
        get_dataset[get_dataset_info]
        list_tables[list_table_ids]
        get_table[get_table_info]
        execute_sql[execute_sql]
    end
    
    BQToolset --> tools

Loading

How It Works

1. User CLI → Sends question to ADK Runner
2. ADK Runner → Wraps message and sends to LlmAgent
3. LlmAgent → Sends question + tool definitions to Gemini
4. Google Gemini → Analyzes question, returns tool call (e.g., SQL query)
5. LlmAgent → Passes tool call to BigQueryToolset
6. BigQueryToolset → Executes query against BigQuery
7. BigQuery → Returns query results
8. Gemini → Formats results into human-readable response
9. CLI → Displays the answer with stats

Installation

Prerequisites

• Python 3.10+
• Google Cloud account with BigQuery access
• Gemini API key

Setup

1. Clone the repository

   git clone https://github.com/yourusername/GoogleBigQueryAgent.git
   cd GoogleBigQueryAgent

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Authenticate with Google Cloud

   gcloud auth application-default login

5. Configure environment variables

   cp .env.example .env
   # Edit .env with your settings

Configuration

Create a .env file with:

# Required
GOOGLE_API_KEY=your-gemini-api-key

# Optional - override defaults
GOOGLE_CLOUD_PROJECT=your-project-id
BIGQUERY_DEFAULT_DATASET=your-dataset-name

Usage

python main.py

Or if installed as a package:

bigquery-agent

Example Session

============================================================
BigQuery SQL Agent
============================================================
Google Cloud Project ID: **********568
Default BigQuery Dataset: 3cx_call_data
------------------------------------------------------------
Ask questions about your BigQuery data.
Type 'quit' or 'exit' to stop.

You: What datasets are available?

Agent: I found the following datasets in your project:
- 3cx_call_data
- analytics
- logs

────────────────────────────────────────
Duration: 2.34s | Tokens: 150 in / 89 out
────────────────────────────────────────

Example Questions

Discovery & Schema

• "What Datasets are available?"
• "Show me the schema of the cdroutput table"

Data Queries

• "Show me all calls that happened yesterday"
• "Print all the information about this call"
• "Is there a recording associated with this call?"

Investigation

• "I had a complaint in the last 30 days. All I know is that the customer name is John and recipient was Sarah"
• "Can you show me all calls in the last 30 days that were abusive or spam related?"

Performance Analysis

• "How many calls did Sarah answer in the last 30 days? Which ones were with a duration of more than 1 minute?"
• "Based on these calls, how can I help my colleague to do her job better?"

Project Structure

GoogleBigQueryAgent/
├── bigquery_agent/
│   ├── __init__.py       # Package exports
│   ├── agent.py          # LlmAgent configuration
│   └── cli.py            # CLI interface with colors/spinner
├── .env.example          # Environment template
├── .gitignore            # Git ignore rules
├── LICENSE               # MIT License
├── main.py               # Entry point
├── pyproject.toml        # Package configuration
├── README.md             # This file
└── requirements.txt      # Dependencies

Development

Running locally

python main.py

Installing as editable package

pip install -e .

License

MIT License - see LICENSE for details.

Acknowledgments

• Google ADK - Agent Development Kit
• Google Gemini - Large Language Model
• Google BigQuery - Data Warehouse