Skip to main content

​
Quickstart Guide

Get the MABQ BigQuery Agent running locally and test natural language SQL queries with BigQuery.

​
Prerequisites

Before you begin, ensure you have:

Python 3.11+

Required for the backend agent

Node.js 20+

Required for the Next.js frontend

Google Cloud Account

With BigQuery and Vertex AI enabled

Azure AD Tenant

For authentication (optional for local testing)

​
Setup Steps

1

Clone the Repository

Clone the MABQ repository to your local machine:
git clone https://github.com/Fbozou/pruebas-adk.git
cd pruebas-adk
2

Configure Backend

Navigate to the backend directory and install dependencies:
cd POC_ADK
pip install -r requirements.txt
The key dependencies include:
  • google-adk>=0.7.0 - Google Agent Development Kit
  • google-cloud-aiplatform[adk]>=1.125.0 - Vertex AI integration
  • fastapi - Web framework
  • uvicorn - ASGI server
  • PyJWT[crypto]>=2.8.0 - JWT authentication
3

Set Backend Environment Variables

Create a .env file in the POC_ADK directory:
.env
# Google Cloud Configuration
PROJECT_ID=your-gcp-project-id
BIGQUERY_DATASET=your_dataset_name
GOOGLE_CLOUD_LOCATION=us-east4

# Model Configuration
ANALYTICS_AGENT_MODEL=gemini-2.5-pro
LLM_1_NAME=bigquery_agent_stg_activos
LLM_1_MODELO=gemini-2.5-pro

# Company Name (for agent responses)
NOMBRE_EMPRESA=Your Company Name

# Azure AD Configuration (optional for local testing)
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id

# Frontend URL for CORS
FRONTEND_URL=http://localhost:3000
For local development without Azure AD, you can bypass authentication by commenting out the middleware in main.py.
4

Authenticate with Google Cloud

Set up Google Cloud credentials for local development:
gcloud auth application-default login
gcloud config set project your-gcp-project-id
Ensure your account has the following permissions:
  • BigQuery Data Viewer
  • BigQuery Job User
  • Vertex AI User
5

Start the Backend Server

Run the FastAPI backend with uvicorn:
uvicorn main:app --reload --host 0.0.0.0 --port 8000
You should see output like:
INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.
The backend will be available at http://localhost:8000. The ADK agent endpoint is mounted at /.
6

Configure Frontend

In a new terminal, navigate to the frontend directory:
cd frontend-agente
npm install
Key dependencies installed:
  • [email protected] - Next.js framework
  • @copilotkit/react-core@^1.51.3 - Chat UI framework
  • @ag-ui/client@^0.0.44 - ADK HTTP agent
  • @microsoft/teams-js@^2.48.1 - Teams integration
7

Set Frontend Environment Variables

Create a .env.local file in the frontend-agente directory:
.env.local
NEXT_PUBLIC_API_URL=http://localhost:8000
8

Start the Frontend

Run the Next.js development server:
npm run dev
The frontend will start at http://localhost:3000.
By default, the frontend requires Microsoft Teams context. For local testing outside Teams, you’ll need to modify the Teams check in app/page.tsx.

​
Test Your Setup

1

Access the Application

For local testing without Teams, modify app/page.tsx to bypass the Teams check:
app/page.tsx
// Comment out the Teams restriction for local testing
if (isTeams === false) {
  // return (
  //   <div className="flex h-screen items-center justify-center...">
  //      Acceso Restringido...
  //   </div>
  // );
}
2

Ask a Question

Open http://localhost:3000 in your browser and try these example queries:
  • “Show me all tables in the dataset”
  • “What columns are in the [table_name] table?”
  • “Count the total number of records in [table_name]”
  • “Show me the top 10 records from [table_name]”
3

View the Response

The agent will:
  1. Translate your question to SQL
  2. Execute the query against BigQuery
  3. Return the SQL code and results
Example interaction:You: “How many assets are in the database?”Agent:
SELECT COUNT(*) as total_assets
FROM `your-project.your_dataset.assets_table`

​
Troubleshooting

If you see JWT validation errors, either:
  • Set valid AZURE_TENANT_ID and AZURE_CLIENT_ID in your .env
  • Or comment out the authentication middleware in main.py:32-108 for local testing
The app is configured for Microsoft Teams by default. To test locally:
  1. Open frontend-agente/app/page.tsx
  2. Comment out the Teams restriction check (lines 41-47)
  3. Set a mock auth token or modify the backend to allow unauthenticated requests
Verify:
  • gcloud auth application-default login was run
  • PROJECT_ID and BIGQUERY_DATASET are correct in .env
  • Your GCP account has BigQuery permissions
  • The dataset exists and contains tables
Ensure:
  • FRONTEND_URL=http://localhost:3000 is set in backend .env
  • The backend CORS middleware is properly configured
  • Both services are running on the expected ports

​
Next Steps

Understand the Architecture

Learn how the components interact

Configure the Agent

Customize behavior and security settings

Deploy to Cloud Run

Deploy to production on GCP

Set Up Teams Integration

Deploy as a Microsoft Teams app

Build docs developers (and LLMs) love

Get started for freeTalk to us