टूल के तौर पर डेटाबेस: ADK, MCP टूलबॉक्स, और Cloud SQL के साथ एजेंटिक RAG

1. परिचय

एआई एजेंट, सिर्फ़ उस डेटा का इस्तेमाल कर सकते हैं जिसे ऐक्सेस करने की अनुमति उन्हें मिली है. ज़्यादातर रीयल-वर्ल्ड डेटा, डेटाबेस में मौजूद होता है. एजेंट को डेटाबेस से कनेक्ट करने का मतलब आम तौर पर यह होता है कि आपको एजेंट कोड में कनेक्शन मैनेजमेंट, क्वेरी लॉजिक, और एम्बेडिंग पाइपलाइन लिखनी होंगी. डेटाबेस का ऐक्सेस पाने वाले हर एजेंट को यह काम दोहराना पड़ता है. साथ ही, हर क्वेरी में बदलाव करने के लिए, एजेंट को फिर से डिप्लॉय करना पड़ता है.

इस कोडलैब में, एक अलग तरीका दिखाया गया है. डेटाबेस टूल को YAML फ़ाइल में शामिल किया जाता है. जैसे, स्टैंडर्ड एसक्यूएल क्वेरी, वेक्टर सिमिलैरिटी सर्च, और अपने-आप एंबेडिंग जनरेट करने की सुविधा. इसके बाद, डेटाबेस के लिए एमसीपी टूलबॉक्स, एमसीपी सर्वर के तौर पर डेटाबेस से जुड़ी सभी कार्रवाइयां करता है. आपका एजेंट कोड कम से कम रहता है: टूल लोड करें और Gemini को यह तय करने दें कि किस टूल को कॉल करना है.

आपको क्या बनाने को मिलेगा

"TechJobs" के लिए स्मार्ट जॉब बोर्ड असिस्टेंट — यह ADK एजेंट है, जो Gemini की मदद से काम करता है. यह डेवलपर को स्टैंडर्ड फ़िल्टर (भूमिका, टेक स्टैक) का इस्तेमाल करके, टेक्नोलॉजी से जुड़ी नौकरियों की लिस्ट ब्राउज़ करने में मदद करता है. साथ ही, आम बोलचाल की भाषा में दिए गए ब्यौरे के ज़रिए नौकरियों के बारे में जानने में मदद करता है. जैसे, "मुझे एआई चैटबॉट पर काम करने के लिए रिमोट जॉब चाहिए." एजेंट, Cloud SQL PostgreSQL डेटाबेस से डेटा पढ़ता है और उसमें डेटा लिखता है. यह काम, MCP Toolbox for Databases की मदद से किया जाता है. यह टूल, डेटाबेस के सभी ऐक्सेस को मैनेज करता है. इसमें वेक्टर सर्च के लिए अपने-आप एंबेडिंग जनरेट करने की सुविधा भी शामिल है. आखिर तक, टूलबॉक्स और एजेंट, दोनों Cloud Run पर काम करते हैं.

आपको क्या सीखने को मिलेगा

एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल), एआई एजेंट के लिए टूल ऐक्सेस को कैसे स्टैंडर्ड बनाता है. साथ ही, डेटाबेस के लिए MCP Toolbox, इसे डेटाबेस ऑपरेशन्स पर कैसे लागू करता है
एडीके एजेंट और Cloud SQL PostgreSQL के बीच, MCP Toolbox for Databases को मिडलवेयर के तौर पर सेट अप करना
tools.yaml में डेटाबेस टूल के बारे में जानकारी दें. आपके एजेंट में कोई डेटाबेस कोड नहीं होना चाहिए
ToolboxToolset का इस्तेमाल करके, चालू टूलबॉक्स सर्वर से टूल लोड करने वाला ADK एजेंट बनाना
Cloud SQL के पहले से मौजूद embedding() फ़ंक्शन का इस्तेमाल करके वेक्टर एम्बेडिंग जनरेट करना और pgvector की मदद से सेमैंटिक सर्च की सुविधा चालू करना
लिखने की कार्रवाइयों के दौरान, वेक्टर अपने-आप शामिल करने के लिए valueFromParam सुविधा का इस्तेमाल करना
Toolbox सर्वर और ADK एजेंट, दोनों को Cloud Run पर डिप्लॉय करना

ज़रूरी शर्तें

ट्रायल बिलिंग खाते वाला Google Cloud खाता
Python और एसक्यूएल की बुनियादी जानकारी
Cloud Database और ADK का इस्तेमाल करने का अनुभव होना ज़रूरी है

2. अपना एनवायरमेंट सेट अप करना

इस चरण में, Cloud Shell एनवायरमेंट तैयार किया जाता है. साथ ही, आपके Google Cloud प्रोजेक्ट को कॉन्फ़िगर किया जाता है और रेफ़रंस रिपॉज़िटरी को क्लोन किया जाता है.

Cloud Shell खोलें

अपने ब्राउज़र में Cloud Shell खोलें. Cloud Shell में, पहले से कॉन्फ़िगर किया गया एनवायरमेंट मिलता है. इसमें इस कोडलैब के लिए ज़रूरी सभी टूल मौजूद होते हैं. जब कहा जाए, तब अनुमति दें पर क्लिक करें

इसके बाद, टर्मिनल खोलने के लिए "देखें" -> "टर्मिनल" पर क्लिक करें.आपका इंटरफ़ेस कुछ ऐसा दिखना चाहिए

यह हमारा मुख्य इंटरफ़ेस होगा, जिसमें आईडीई सबसे ऊपर और टर्मिनल सबसे नीचे होगा

अपनी वर्किंग डायरेक्ट्री सेट अप करना

अपनी वर्किंग डायरेक्ट्री बनाएं. इस कोडलैब में लिखा गया सारा कोड यहां मौजूद होता है:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

इसके बाद, हम कई डायरेक्ट्री तैयार करेंगे, ताकि सीडिंग स्क्रिप्ट और लॉग जैसी चीज़ों को मैनेज किया जा सके

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs

Google Cloud प्रोजेक्ट सेट अप करना

जगह की जानकारी वाले वैरिएबल के साथ .env फ़ाइल बनाएं:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

अहम जानकारी! यहां दिया गया तरीका, Google Cloud प्रोजेक्ट को तुरंत सेटअप करने में आपकी मदद करेगा. यह प्रोजेक्ट, बिना किसी शुल्क के आज़माने के लिए उपलब्ध बिलिंग खाते (सख्त) से लिंक होता है. अगर आपको अपने पिछले प्रोजेक्ट का इस्तेमाल करना है, तो यहां दिया गया तरीका छोड़ें और इसके बजाय यह तरीका अपनाएं:

अपनी .env फ़ाइल में, अपने प्रोजेक्ट का नाम GOOGLE_CLOUD_PROJECT वैरिएबल के तौर पर जोड़ें
gcloud config set project your-project-id का इस्तेमाल करके, टर्मिनल में अपना प्रोजेक्ट चालू करें

इसके बाद, सीधे एपीआई चालू करने वाले सेक्शन पर जाएं.

अगर आपको इस बारे में पक्के तौर पर नहीं पता है, तो नीचे दिया गया सेक्शन देखें

अपने टर्मिनल में प्रोजेक्ट को आसानी से सेट अप करने के लिए, इस प्रोजेक्ट सेटअप स्क्रिप्ट को अपनी वर्किंग डायरेक्ट्री में डाउनलोड करें:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

स्क्रिप्ट चलाएं. यह आपके मुफ़्त में आज़माने वाले बिलिंग खाते की पुष्टि करता है, एक नया प्रोजेक्ट बनाता है या मौजूदा प्रोजेक्ट की पुष्टि करता है, आपके प्रोजेक्ट आईडी को मौजूदा डायरेक्ट्री में मौजूद .env फ़ाइल में सेव करता है, और gcloud में चालू प्रोजेक्ट सेट करता है.

bash setup_verify_trial_project.sh && source .env

स्क्रिप्ट में ये काम किए जाएंगे:

पुष्टि करें कि आपके पास मुफ़्त में आज़माने की सुविधा वाला चालू बिलिंग खाता हो
.env में कोई मौजूदा प्रोजेक्ट है या नहीं, यह देखें
कोई नया प्रोजेक्ट बनाएं या मौजूदा प्रोजेक्ट का फिर से इस्तेमाल करें
मुफ़्त में आज़माने की सुविधा वाले बिलिंग खाते को अपने प्रोजेक्ट से लिंक करना
प्रोजेक्ट आईडी को .env में सेव करें
प्रोजेक्ट को चालू gcloud प्रोजेक्ट के तौर पर सेट करें

पुष्टि करें कि प्रोजेक्ट सही तरीके से सेट किया गया है. इसके लिए, Cloud Shell टर्मिनल प्रॉम्प्ट में अपनी वर्किंग डायरेक्ट्री के बगल में मौजूद पीले रंग का टेक्स्ट देखें. इसमें आपका प्रोजेक्ट आईडी दिखना चाहिए.

ज़रूरी एपीआई चालू करना

इसके बाद, हमें उस प्रॉडक्ट के लिए कई एपीआई चालू करने होंगे जिसके साथ हमें इंटरैक्ट करना है:

gcloud services enable \
  aiplatform.googleapis.com \
  sqladmin.googleapis.com \
  compute.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

Vertex AI API (aiplatform.googleapis.com) — आपका एजेंट Gemini मॉडल का इस्तेमाल करता है. साथ ही, टूलबॉक्स, वेक्टर सर्च के लिए Embedding API का इस्तेमाल करता है.
Cloud SQL एडमिन एपीआई (sqladmin.googleapis.com) — इससे PostgreSQL इंस्टेंस को मैनेज किया जाता है.
Compute Engine API (compute.googleapis.com) — Cloud SQL इंस्टेंस बनाने के लिए ज़रूरी है.
Cloud Run, Cloud Build, Artifact Registry — इनका इस्तेमाल इस कोडलैब में बाद में डिप्लॉयमेंट के चरण में किया जाता है

3. डेटाबेस शुरू करने के लिए स्क्रिप्ट तैयार करना

इस चरण में, Cloud SQL इंस्टेंस बनाना शुरू किया जाता है. साथ ही, एक ऑटोमेटेड सेटअप स्क्रिप्ट चलाई जाती है. यह स्क्रिप्ट, इंस्टेंस के तैयार होने का इंतज़ार करती है. इसके बाद, डेटाबेस बनाती है, उसमें नौकरी की लिस्टिंग जोड़ती है, और एम्बेडिंग जनरेट करती है. ये सभी काम एक ही ऑपरेशन में होते हैं.

सबसे पहले, डेटाबेस का पासवर्ड अपनी .env फ़ाइल में जोड़ें और उसे फिर से लोड करें:

echo "DB_PASSWORD=techjobs-pwd" >> .env
echo "DB_INSTANCE=jobs-instance" >> .env
echo "DB_NAME=jobs_db" >> .env
source .env

इंस्टेंस और डेटाबेस बनाने के लिए बैश स्क्रिप्ट बनाना

इसके बाद, इस कमांड का इस्तेमाल करके scripts/setup_database.sh स्क्रिप्ट बनाएं

mkdir -p ~/build-agent-adk-toolbox-cloudsql/scripts
cloudshell edit scripts/setup_database.sh

इसके बाद, यहां दिए गए कोड को scripts/setup_database.sh फ़ाइल में कॉपी करें

#!/bin/bash
set -e
source .env

echo "================================================"
echo "Database Setup"
echo "================================================"
echo ""

# Step 1: Create Cloud SQL instance
echo "[1/5] Creating Cloud SQL instance..."

# Check if instance already exists
if gcloud sql instances describe "$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Instance already exists"
else
    echo "      Creating instance (takes 5-10 minutes)..."
    gcloud sql instances create "$DB_INSTANCE" \
        --database-version=POSTGRES_17 \
        --tier=db-custom-1-3840 \
        --edition=ENTERPRISE \
        --region="$REGION" \
        --root-password="$DB_PASSWORD" \
        --enable-google-ml-integration \
        --database-flags cloudsql.enable_google_ml_integration=on \
        --quiet
fi
echo "      ✓ Instance ready"
echo ""

# Step 2: Verify instance is ready
echo "[2/5] Verifying instance state..."

STATE=$(gcloud sql instances describe "$DB_INSTANCE" --format='value(state)')

if [ "$STATE" != "RUNNABLE" ]; then
    echo "ERROR: Instance not ready (state: $STATE)"
    exit 1
fi
echo "      ✓ Instance is RUNNABLE"
echo ""

# Step 3: Grant IAM permissions
echo "[3/5] Granting Vertex AI permissions..."

SERVICE_ACCOUNT=$(gcloud sql instances describe "$DB_INSTANCE" \
    --format='value(serviceAccountEmailAddress)')

if [ -z "$SERVICE_ACCOUNT" ]; then
    echo "ERROR: Could not retrieve service account"
    exit 1
fi

gcloud projects add-iam-policy-binding "$GOOGLE_CLOUD_PROJECT" \
    --member="serviceAccount:$SERVICE_ACCOUNT" \
    --role="roles/aiplatform.user" \
    --quiet

echo "      ✓ Permissions granted"
echo ""

# Step 4: Create database
echo "[4/5] Creating database..."

# Check if database already exists
if gcloud sql databases describe "$DB_NAME" \
    --instance="$DB_INSTANCE" --quiet >/dev/null 2>&1; then
    echo "      Database already exists"
else
    gcloud sql databases create "$DB_NAME" \
        --instance="$DB_INSTANCE" \
        --quiet
fi

echo "      ✓ Database '$DB_NAME' ready"
echo ""

# Step 5: Seed database and generate embeddings
echo "[5/5] Seeding database and generating embeddings..."

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SETUP_SCRIPT="${SCRIPT_DIR}/setup_jobs_db.py"

if [ ! -f "$SETUP_SCRIPT" ]; then
    echo "ERROR: Setup script not found: $SETUP_SCRIPT"
    exit 1
fi

uv run "$SETUP_SCRIPT"

echo ""
echo "================================================"
echo "Setup complete!"
echo "================================================"
echo ""

डेटा सीड के लिए Python स्क्रिप्ट बनाना

इसके बाद, नीचे दिए गए कमांड का इस्तेमाल करके, सीडिंग स्क्रिप्ट की Python फ़ाइल scripts/setup_jobs_db.py बनाएं

cloudshell edit scripts/setup_jobs_db.py

इसके बाद, इस कोड को scripts/setup_jobs_db.py फ़ाइल में कॉपी करें

import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from google.cloud.sql.connector import Connector
import pg8000
import time

# Load environment variables from .env file
env_path = Path(__file__).parent.parent / '.env'
load_dotenv(env_path)
EMBEDDING_MODEL='gemini-embedding-001'

# Verify required environment variables
required_vars = ['GOOGLE_CLOUD_PROJECT', 'REGION', 'DB_PASSWORD']
missing_vars = [var for var in required_vars if not os.environ.get(var)]

if missing_vars:
    print(f"ERROR: Missing required environment variables: {', '.join(missing_vars)}", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Expected .env file location: {env_path}", file=sys.stderr)
    if not env_path.exists():
        print(f"✗ File not found at that location", file=sys.stderr)
    else:
        print(f"✓ File exists but is missing the variables above", file=sys.stderr)
    print(f"", file=sys.stderr)
    print(f"Make sure your .env file contains:", file=sys.stderr)
    for var in missing_vars:
        print(f"  {var}=<value>", file=sys.stderr)
    sys.exit(1)

# Job listings data (fictional, for tutorial purposes only)
JOBS = [
    ("Senior Backend Engineer", "Stripe", "Backend", "Go, PostgreSQL, gRPC, Kubernetes", "$180-250K/year", "San Francisco, Hybrid", 3,
     "Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls."),
    ("Machine Learning Engineer", "Spotify", "Data/AI", "Python, TensorFlow, BigQuery, Vertex AI", "$170-230K/year", "Stockholm, Remote", 2,
     "Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second."),
    ("Frontend Engineer", "Vercel", "Frontend", "React, TypeScript, Next.js", "$140-190K/year", "Remote", 4,
     "Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience."),
    ("DevOps Engineer", "Datadog", "DevOps", "Terraform, GCP, Docker, Kubernetes, ArgoCD", "$160-220K/year", "New York, Hybrid", 2,
     "Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments."),
    ("Mobile Engineer (Android)", "Grab", "Mobile", "Kotlin, Jetpack Compose, GraphQL", "$120-170K/year", "Singapore, Hybrid", 3,
     "Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions."),
    ("Data Engineer", "Airbnb", "Data", "Python, Apache Spark, Airflow, BigQuery", "$160-210K/year", "San Francisco, Hybrid", 2,
     "Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams."),
    ("Full Stack Engineer", "Revolut", "Full Stack", "TypeScript, Node.js, React, PostgreSQL", "$130-180K/year", "London, Remote", 5,
     "Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions."),
    ("Site Reliability Engineer", "Cloudflare", "SRE", "Go, Prometheus, Grafana, GCP, Terraform", "$170-230K/year", "Austin, Hybrid", 2,
     "Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide."),
    ("Cloud Architect", "Google Cloud", "Cloud", "GCP, Terraform, Kubernetes, Python", "$200-280K/year", "Seattle, Hybrid", 1,
     "Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit."),
    ("Backend Engineer (Payments)", "Square", "Backend", "Java, Spring Boot, PostgreSQL, Kafka", "$160-220K/year", "San Francisco, Hybrid", 3,
     "Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services."),
    ("AI Engineer", "Hugging Face", "Data/AI", "Python, LangChain, Vertex AI, FastAPI, PostgreSQL", "$150-210K/year", "Paris, Remote", 2,
     "Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure."),
    ("Platform Engineer", "Coinbase", "Platform", "Rust, Kubernetes, AWS, Terraform", "$180-250K/year", "Remote", 0,
     "Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime."),
    ("QA Automation Engineer", "Shopify", "QA", "Python, Selenium, Cypress, Jenkins", "$110-160K/year", "Toronto, Hybrid", 3,
     "Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows."),
    ("Security Engineer", "CrowdStrike", "Security", "Python, SIEM, Kubernetes, Penetration Testing", "$170-240K/year", "Austin, On-site", 1,
     "Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events."),
    ("Product Engineer", "GitLab", "Full Stack", "Go, React, PostgreSQL, Redis, GCP", "$140-200K/year", "Remote", 4,
     "Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development."),
]


def get_connection():
    """Create a connection to Cloud SQL using the connector."""
    project = os.environ['GOOGLE_CLOUD_PROJECT']
    region = os.environ['REGION']
    password = os.environ['DB_PASSWORD']
    instance = os.environ['DB_INSTANCE']
    database = os.environ['DB_NAME']

    connector = Connector()
    conn = connector.connect(
        f"{project}:{region}:{instance}",
        "pg8000",
        user="postgres",
        password=password,
        db=database
    )
    return conn, connector


def create_schema(cursor):
    """Create extensions and jobs table."""
    cursor.execute("CREATE EXTENSION IF NOT EXISTS google_ml_integration")
    cursor.execute("CREATE EXTENSION IF NOT EXISTS vector")
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS jobs (
            id SERIAL PRIMARY KEY,
            title VARCHAR NOT NULL,
            company VARCHAR NOT NULL,
            role VARCHAR NOT NULL,
            tech_stack VARCHAR NOT NULL,
            salary_range VARCHAR NOT NULL,
            location VARCHAR NOT NULL,
            openings INTEGER NOT NULL,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_jobs(cursor, conn):
    """Insert job listings."""
    cursor.execute("SELECT COUNT(*) FROM jobs")
    existing_count = cursor.fetchone()[0]

    if existing_count > 0:
        print(f"      {existing_count} jobs already exist, skipping seed")
        return 0

    cursor.executemany("""
        INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, JOBS)
    conn.commit()
    return len(JOBS)


def generate_embeddings(cursor, conn):
    """Generate embeddings using Cloud SQL's embedding() function."""
    cursor.execute("SELECT COUNT(*) FROM jobs WHERE description_embedding IS NULL")
    null_count = cursor.fetchone()[0]

    if null_count == 0:
        print("      All jobs already have embeddings")
        return 0

    cursor.execute(f"""
        UPDATE jobs
        SET description_embedding = embedding('{EMBEDDING_MODEL}', description)::vector
        WHERE description_embedding IS NULL
    """)
    rows_updated = cursor.rowcount
    conn.commit()
    return rows_updated


def main():
    conn, connector = get_connection()
    cursor = conn.cursor()

    try:
        create_schema(cursor)
        conn.commit()

        seeded = seed_jobs(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} jobs")

        # Waiting for vertex role propagation
        time.sleep(60)
        embedded = generate_embeddings(cursor, conn)
        if embedded > 0:
            print(f"      ✓ Generated {embedded} embeddings")

    except Exception as e:
        print(f"ERROR: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        cursor.close()
        conn.close()
        connector.close()


if __name__ == "__main__":
    main()

अब अगले चरण पर जाएं

4. डेटाबेस बनाना और उसे शुरू करना

अब हमारी स्क्रिप्ट को लागू किया जा सकता है. तैयार की गई स्क्रिप्ट को चलाने के लिए, हमें Python की ज़रूरत होगी. इसलिए, आइए इसे पहले तैयार कर लें

Python प्रोजेक्ट सेट अप करना

uv, Python पैकेज और प्रोजेक्ट मैनेजर है. इसे Rust में लिखा गया है ( uv के दस्तावेज़ ). इस कोडलैब में, Python प्रोजेक्ट को तेज़ी से और आसानी से मैनेज करने के लिए इसका इस्तेमाल किया जाता है

Python प्रोजेक्ट शुरू करें और ज़रूरी डिपेंडेंसी जोड़ें:

uv init
uv add cloud-sql-python-connector --extra pg8000
uv add python-dotenv

ध्यान दें कि हम यहां cloud-sql-python-connector Python SDK का इस्तेमाल कर रहे हैं, ताकि हमारे डेटाबेस इंस्टेंस के साथ सुरक्षित कनेक्शन शुरू किया जा सके. इस कनेक्शन की पुष्टि, ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल करके की जाती है.

सेटअप स्क्रिप्ट को लागू करना

अब हम सेटअप स्क्रिप्ट को बैकग्राउंड में चला सकते हैं. साथ ही, कंसोल आउटपुट की जांच कर सकते हैं. इसे logs/atabase_setup.log फ़ाइल में लिखा जाएगा. इसके लिए, यहां दिए गए निर्देश का इस्तेमाल करें. इस प्रोसेस के पूरा होने तक, अगले सेक्शन पर जाएं

mkdir -p ~/build-agent-adk-toolbox-cloudsql/logs
bash scripts/setup_database.sh > logs/database_setup.log 2>&1 &

Toolbox बाइनरी डाउनलोड करना

इस ट्यूटोरियल में, हम MCP टूलबॉक्स का इस्तेमाल करेंगे. अच्छी बात यह है कि यह पहले से बने बाइनरी के साथ आता है, जिसे Linux एनवायरमेंट में इस्तेमाल किया जा सकता है. अब इसे बैकग्राउंड में डाउनलोड होने दें, क्योंकि इसमें काफ़ी समय लगता है. बाइनरी डाउनलोड करने और logs/toolbox_dl.log पर आउटपुट लॉग की जांच करने के लिए, यह कमांड चलाएं . इस प्रोसेस के पूरा होने तक, अगले सेक्शन पर जाएं

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/linux/amd64/toolbox > logs/toolbox_dl.log 2>&1 &

सेटअप स्क्रिप्ट को समझना `scripts/setup_database.sh`

अब हम उस सेटअप स्क्रिप्ट को समझने की कोशिश करते हैं जिसे हमने पहले कॉन्फ़िगर किया था. यह प्रोसेस पूरी होती है

हम सबसे पहले gcloud sql instances create कमांड को इस फ़्लैग के साथ एक्ज़ीक्यूट करते हैं

db-custom-1-3840, ENTERPRISE वर्शन में सबसे छोटा डेडीकेटेड-कोर Cloud SQL टियर है. इसमें 1 vCPU और 3.75 जीबी रैम होती है. ज़्यादा जानकारी के लिए, यहां जाएं. Vertex AI ML के इंटिग्रेशन के लिए, एक डेडीकेटेड कोर की ज़रूरत होती है. शेयर किए गए कोर टियर (db-f1-micro, db-g1-small) इसे सपोर्ट नहीं करते.
--root-password डिफ़ॉल्ट postgres उपयोगकर्ता के लिए पासवर्ड सेट करता है.
--enable-google-ml-integration की मदद से, Cloud SQL को Vertex AI के साथ इंटिग्रेट किया जा सकता है. इससे, embedding() फ़ंक्शन का इस्तेमाल करके, SQL से सीधे तौर पर एंबेडिंग मॉडल को कॉल किया जा सकता है.

पुष्टि करें कि इंस्टेंस पहले से ही RUNNABLE स्टेटस में है या नहीं
gcloud projects add-iam-policy-binding कमांड का इस्तेमाल करके, Cloud SQL इंस्टेंस के सेवा खाते को Vertex AI को कॉल करने की अनुमति दें. यह बिल्ट-इन embedding() फ़ंक्शन के लिए ज़रूरी है. इसका इस्तेमाल हम डेटाबेस को सीड करते समय करेंगे
डेटाबेस बनाना
सीडिंग स्क्रिप्ट setup_jobs_db.py स्क्रिप्ट को लागू करना

सीड स्क्रिप्ट को समझना `scripts/setup_jobs_db.py`

अब सीडिंग स्क्रिप्ट के बारे में जानते हैं. यह स्क्रिप्ट ये काम करती है:

डेटाबेस इंस्टेंस से कनेक्शन शुरू करना
यह दो PostgreSQL एक्सटेंशन इंस्टॉल करता है:

google_ml_integration — यह embedding() SQL फ़ंक्शन उपलब्ध कराता है. यह SQL से सीधे तौर पर Vertex AI एम्बेडिंग मॉडल को कॉल करता है. यह डेटाबेस-लेवल का एक्सटेंशन है. इससे jobs_db में एमएल फ़ंक्शन उपलब्ध होते हैं. इंस्टेंस बनाते समय सेट किया गया इंस्टेंस-लेवल का फ़्लैग (--enable-google-ml-integration), Cloud SQL VM को Vertex AI तक पहुंचने की अनुमति देता है. एक्सटेंशन, SQL फ़ंक्शन को इस खास डेटाबेस में उपलब्ध कराता है.
vector (pgvector) — यह vector डेटा टाइप और दूरी के ऑपरेटर जोड़ता है, ताकि एम्बेडिंग को सेव किया जा सके और उनसे क्वेरी की जा सके.

टेबल बनाता है. इसमें बताया गया है कि description_embedding कॉलम, vector(3072) है. यह pgvector कॉलम है, जो 3072 डाइमेंशन वाले वेक्टर सेव करता है.
शुरुआती नौकरियों का डेटा जोड़ना
description फ़ील्ड से एम्बेडिंग डेटा जनरेट करें और embedding() फ़ंक्शन के ज़रिए, Vertex के इंटिग्रेशन की सुविधा का इस्तेमाल करके description_embedding भरें

embedding('gemini-embedding-001', description) — यह SQL से सीधे तौर पर Vertex AI के Gemini एम्बेडिंग मॉडल को कॉल करता है. साथ ही, हर नौकरी के description टेक्स्ट को पास करता है. यह google_ml_integration एक्सटेंशन है, जिसे आपने सीड स्क्रिप्ट में इंस्टॉल किया है.
::vector — यह फ़ंक्शन, फ़्लोट के तौर पर मिले ऐरे को pgvector के vector टाइप में बदलता है, ताकि इसे सेव किया जा सके और दूरी के ऑपरेटर के साथ क्वेरी की जा सके.
UPDATE, सभी 15 लाइनों में चलता है. इससे नौकरी के हर ब्यौरे के लिए, 3072 डाइमेंशन वाली एक एम्बेडिंग जनरेट होती है.

इससे शुरुआती डेटा तैयार होगा, जिसे हमारा एजेंट ऐक्सेस करेगा

5. डेटाबेस के लिए एमसीपी टूलबॉक्स को कॉन्फ़िगर करना

इस चरण में, MCP Toolbox for Databases के बारे में बताया गया है. साथ ही, इसे आपके Cloud SQL इंस्टेंस से कनेक्ट करने के लिए कॉन्फ़िगर करने का तरीका बताया गया है. इसमें, दो स्टैंडर्ड एसक्यूएल क्वेरी टूल के बारे में भी बताया गया है.

एमसीपी क्या है और टूलबॉक्स का इस्तेमाल क्यों किया जाता है?

एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) एक ओपन प्रोटोकॉल है. यह एआई एजेंट के लिए, बाहरी टूल खोजने और उनसे इंटरैक्ट करने के तरीके को व्यवस्थित और आसान बनाता है. यह क्लाइंट-सर्वर मॉडल तय करता है: एजेंट, एमसीपी क्लाइंट को होस्ट करता है. साथ ही, टूल एमसीपी सर्वर से दिखाए जाते हैं. एमसीपी के साथ काम करने वाला कोई भी क्लाइंट, एमसीपी के साथ काम करने वाले किसी भी सर्वर का इस्तेमाल कर सकता है. एजेंट को हर टूल के लिए, कस्टम इंटिग्रेशन कोड की ज़रूरत नहीं होती.

डेटाबेस के लिए एमसीपी टूलबॉक्स, एक ओपन-सोर्स एमसीपी सर्वर है. इसे खास तौर पर डेटाबेस ऐक्सेस करने के लिए बनाया गया है. इसके बिना, आपको Python फ़ंक्शन लिखने होंगे. ये फ़ंक्शन, डेटाबेस कनेक्शन खोलते हैं, कनेक्शन पूल मैनेज करते हैं, एसक्यूएल इंजेक्शन को रोकने के लिए पैरामीटर वाली क्वेरी बनाते हैं, गड़बड़ियों को ठीक करते हैं, और उस पूरे कोड को अपने एजेंट में एम्बेड करते हैं. डेटाबेस का ऐक्सेस पाने के लिए, हर एजेंट को यह काम दोहराना पड़ता है. क्वेरी बदलने का मतलब है कि एजेंट को फिर से डिप्लॉय करना होगा.

टूलबॉक्स की मदद से, YAML फ़ाइल लिखी जाती है. हर टूल, पैरामीटर वाले एसक्यूएल स्टेटमेंट पर मैप करता है. टूलबॉक्स, कनेक्शन पूलिंग, पैरामीटर वाली क्वेरी, पुष्टि करने की प्रोसेस, और निगरानी करने की सुविधा को मैनेज करता है. टूल, एजेंट से अलग किए जाते हैं. एजेंट के कोड में बदलाव किए बिना, tools.yaml में बदलाव करके और टूलबॉक्स को फिर से चालू करके क्वेरी अपडेट करें. ये टूल, एडीके, LangGraph, LlamaIndex या एमसीपी के साथ काम करने वाले किसी भी फ़्रेमवर्क पर काम करते हैं.

टूल का कॉन्फ़िगरेशन लिखना

अब हमें Cloud Shell Editor में tools.yaml नाम की एक फ़ाइल बनानी होगी, ताकि हम अपने टूल का कॉन्फ़िगरेशन सेट अप कर सकें

cloudshell edit tools.yaml

इस फ़ाइल में मल्टी-डॉक्युमेंट YAML का इस्तेमाल किया गया है. हर ब्लॉक को --- से अलग किया गया है. यह एक स्टैंडअलोन रिसॉर्स है. हर संसाधन में एक kind होता है, जो यह बताता है कि वह क्या है (डेटाबेस कनेक्शन के लिए sources, एजेंट की मदद से की जा सकने वाली कार्रवाइयों के लिए tools). साथ ही, इसमें एक type होता है, जो बैकएंड के बारे में बताता है (सोर्स के लिए cloud-sql-postgres, SQL पर आधारित टूल के लिए postgres-sql). टूल अपने सोर्स का रेफ़रंस name के ज़रिए देता है. इससे टूलबॉक्स को पता चलता है कि किस कनेक्शन पूल को एक्ज़ीक्यूट करना है. एनवायरमेंट वैरिएबल, ${VAR_NAME} सिंटैक्स का इस्तेमाल करते हैं और स्टार्टअप के समय हल किए जाते हैं.

अब, यहां दी गई स्क्रिप्ट को सबसे पहले tools.yaml फ़ाइल में कॉपी करें

# tools.yaml

# --- Data Source ---
kind: source
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: ${DB_INSTANCE}
database: ${DB_NAME}
user: postgres
password: ${DB_PASSWORD}

---