Skip to content

README.md

Latest commit

 

History

History
229 lines (160 loc) · 5.43 KB

README.md

File metadata and controls

229 lines (160 loc) · 5.43 KB

Introduction

The application uses ADK, Gemini, LangChain tools to power an SQL Agent with built-in multi-layer authorization and safety controls.

Architecture

Frontend: Streamlit app (streamlit_ui.py)
Backend: FastAPI service (main.py)

Security-First Pipeline:

  1. Safety Check Agent - Determines if request is secure/not secure
  2. Security Router Agent - Routes: exits immediately if not secure, continues if secure
  3. Refinement Loop - Processes query (only if secure)

Agents:

  • Coordinator: sql_agent (sql_agent.py)
  • Security Agents:
    • Safety Check agent (agent.py) - Binary security decision
    • Security Router agent (agent.py) - Routes based on security
  • Processing Subagents (in Refinement Loop):
    • Rephraser agent (rewrite_prompt.py) - Includes security passthrough
    • Generator agent (generator.py)
    • Analyzer agent (analyzer.py)
    • Reflexion agent (reflexion.py)
    • Routing agent (routing.py)

Function Tools:

  • get_schema tool (db_tools.py)
  • run_sql_query tool (db_tools.py) - Includes SQL-level validation

Models:

  • Gemini 2.5 pro

Security & Authorization

The system uses a clean three-step security pipeline:

Step 1: Safety Check

  • Analyzes user request intent
  • Binary decision: SECURE or NOT SECURE
  • Fast, focused security validation

Step 2: Security Router

  • If NOT SECURE: Outputs rejection message and exits immediately
  • If SECURE: Outputs "proceeding" and continues to processing

Step 3: Refinement Loop (only if secure)

  • Rewrites query
  • Generates SQL
  • Analyzes results
  • Iterative refinement

Multi-Layer Defense:

  • Layer 1: LLM-based intent analysis (Safety Check)
  • Layer 2: Routing decision (Security Router)
  • Layer 3: SQL-level validation (db_tools)

Only read-only SELECT queries are permitted. Dangerous operations (DROP, DELETE, TRUNCATE, etc.) are blocked immediately.

See ARCHITECTURE_CLEAN.md for detailed documentation.

Getting started

Clone the repo

git clone https://github.com/gabrielpreda/adk-sql-agent.git
cd adk-sql-agent

Create an .env file

The file should contain the following:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT
GOOGLE_CLOUD_LOCATION=YOUR_REGION

Install dependencies

Run:

pip install -r requirements.txt

Start the backend

Run:

uvicorn main:app --reload

Start the frontend

Run:

streamlit run streamlit_ui.py

Testing

From the root folder run:

adk web

Then select the sql_agent folder. ADK web will discover in agent.py the root_agent and you will be able to test, monitor, debug the application.

The Agentic workflow is shown in the following figure (current step: Generator agent receives the result from run_sql_query tool).

The next figure shows the result of Generator Agent.

The next figure shows:

  • Result of Analyzer Agent.
  • Resolution of the Reflection Agent, based on previous agent analysis.
  • The rationale for Routing Agent to route to Rewrite Query Agent.
  • The reasoning of Rewrite Query Agent and the new query generated.

Deployment

Option 1: Deploy to Agent Engine (Recommended)

Agent Engine is Google Cloud's managed service for deploying ADK agents.

Prerequisites

  • Google Cloud Project with billing enabled
  • gcloud CLI installed and configured
  • ADK CLI version 1.3.0+

Deploy

  1. Set your project ID and region:
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1
  1. Run the deployment script:
./deploy.sh
  1. Test your deployed agent:
adk run --project=$GOOGLE_CLOUD_PROJECT --region=$GOOGLE_CLOUD_LOCATION --agent=adk-sql-agent

Option 2: Deploy to Cloud Run

Alternative deployment using Google Cloud Run for broader region availability.

Deploy

  1. Set your project ID and region:
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1
  1. Run the Cloud Run deployment script:
./deploy_cloudrun.sh
  1. The script will output your service URL. Test it:
# Check status
curl https://your-service-url/status

# Send a query
curl -X POST https://your-service-url/query \
  -H 'Content-Type: application/json' \
  -d '{"query": "Show me the top 10 customers"}'

Manual Deployment

If you prefer manual deployment:

# Build container
gcloud builds submit --tag gcr.io/$GOOGLE_CLOUD_PROJECT/adk-sql-agent

# Deploy to Cloud Run
gcloud run deploy adk-sql-agent \
  --image gcr.io/$GOOGLE_CLOUD_PROJECT/adk-sql-agent \
  --platform managed \
  --region $GOOGLE_CLOUD_LOCATION \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE \
  --set-env-vars GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT \
  --set-env-vars GOOGLE_CLOUD_LOCATION=$GOOGLE_CLOUD_LOCATION \
  --memory 4Gi \
  --cpu 2

Demo

We show here the sequence of operations for one query.

Rewrite prompt

Generator results

Analyzer + Reflection

Reflection resolution

Results