Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

1. परिचय

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

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

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

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

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

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

ज़रूरी शर्तें

मुफ़्त में आज़माने की सुविधा वाला Google Cloud बिलिंग खाता
Python और SQL की बुनियादी जानकारी
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 Admin API (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=restaurant-pwd" >> .env
echo "DB_INSTANCE=restaurant-instance" >> .env
echo "DB_NAME=restaurant_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_restaurant_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_restaurant_db.py बनाएं

cloudshell edit scripts/setup_restaurant_db.py

इसके बाद, इस कोड को scripts/setup_restaurant_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)

# Menu items data
MENU_ITEMS = [
    ("Truffle Mushroom Risotto", "Italian", "Main Course",
     "Arborio rice, truffle oil, porcini mushrooms, parmesan, white wine",
     "$28", "Vegetarian, Gluten-Free", True,
     "A creamy, luxurious risotto made with arborio rice slow-cooked in white wine and mushroom broth, finished with shaved black truffle and aged parmesan. The porcini mushrooms add a deep, earthy flavor that pairs beautifully with the delicate truffle oil drizzled on top."),
    ("Spicy Tuna Tartare", "Japanese", "Appetizer",
     "Ahi tuna, sriracha, sesame oil, avocado, crispy wonton",
     "$22", "Gluten-Free, Dairy-Free", True,
     "Fresh ahi tuna diced and tossed with sriracha aioli, toasted sesame oil, and lime juice, served atop creamy avocado slices with crispy wonton chips. A perfect balance of heat, richness, and crunch inspired by modern Japanese fusion cuisine."),
    ("Lamb Kofta Kebab", "Middle Eastern", "Main Course",
     "Ground lamb, cumin, coriander, yogurt sauce, flatbread",
     "$24", "Halal", True,
     "Hand-formed spiced lamb kebabs grilled over charcoal, seasoned with cumin, coriander, and sumac. Served with warm flatbread, tangy yogurt-cucumber sauce, and a fresh herb salad. A classic Middle Eastern street food elevated with premium ingredients."),
    ("Pad Thai", "Thai", "Main Course",
     "Rice noodles, shrimp, tamarind, peanuts, bean sprouts, lime",
     "$19", "Gluten-Free, Dairy-Free", True,
     "Stir-fried rice noodles with tiger shrimp, scrambled egg, and a sweet-sour tamarind sauce, topped with crushed peanuts, fresh bean sprouts, and a squeeze of lime. This classic Thai street food dish balances sweet, sour, salty, and umami in every bite."),
    ("Margherita Pizza", "Italian", "Main Course",
     "San Marzano tomatoes, fresh mozzarella, basil, olive oil",
     "$18", "Vegetarian", True,
     "A Neapolitan-style pizza with a thin, charred crust topped with crushed San Marzano tomatoes, creamy buffalo mozzarella, fresh basil leaves, and a drizzle of extra virgin olive oil. Simple, classic, and made with imported Italian ingredients."),
    ("Miso Glazed Black Cod", "Japanese", "Main Course",
     "Black cod, white miso, mirin, sake, pickled ginger",
     "$36", "Gluten-Free, Dairy-Free", True,
     "Buttery black cod marinated for 72 hours in a sweet white miso glaze with mirin and sake, then broiled until caramelized. Served with pickled ginger and steamed bok choy. A signature dish inspired by Nobu's iconic preparation."),
    ("Caesar Salad", "American", "Appetizer",
     "Romaine lettuce, parmesan, croutons, anchovy dressing",
     "$14", "Contains Gluten", True,
     "Crisp romaine hearts tossed with a house-made anchovy-garlic dressing, shaved parmesan, and golden sourdough croutons. A timeless salad that serves as the perfect light starter or side dish with grilled proteins."),
    ("Chicken Tikka Masala", "Indian", "Main Course",
     "Chicken thigh, tomato cream sauce, garam masala, basmati rice",
     "$21", "Gluten-Free", True,
     "Tender chunks of tandoori-marinated chicken simmered in a rich, creamy tomato sauce spiced with garam masala, cumin, and fenugreek. Served over fragrant basmati rice with warm garlic naan on the side."),
    ("Chocolate Lava Cake", "French", "Dessert",
     "Dark chocolate, butter, eggs, vanilla, powdered sugar",
     "$15", "Vegetarian", True,
     "A warm, individual-sized chocolate cake with a molten dark chocolate center that flows when you break through the delicate outer shell. Made with 70% Belgian dark chocolate and served with a scoop of vanilla bean ice cream."),
    ("Pho Bo", "Vietnamese", "Main Course",
     "Rice noodles, beef brisket, star anise, cinnamon, bean sprouts, Thai basil",
     "$17", "Gluten-Free, Dairy-Free", True,
     "A deeply aromatic beef broth simmered for 12 hours with star anise, cinnamon, and charred ginger, ladled over rice noodles and thinly sliced beef brisket. Served with fresh Thai basil, bean sprouts, jalapeño, and lime for the table to customize."),
    ("Lobster Bisque", "French", "Appetizer",
     "Lobster, heavy cream, cognac, tarragon, cayenne",
     "$19", "Gluten-Free", True,
     "A velvety smooth soup made from roasted lobster shells, finished with heavy cream, a splash of cognac, and fresh tarragon. Each bowl is garnished with tender lobster meat and a pinch of cayenne for subtle warmth."),
    ("Falafel Plate", "Middle Eastern", "Main Course",
     "Chickpeas, herbs, tahini, pickled vegetables, hummus",
     "$16", "Vegan, Gluten-Free", True,
     "Crispy-on-the-outside, fluffy-on-the-inside chickpea fritters seasoned with fresh parsley, cilantro, and cumin. Served with creamy tahini sauce, house-made hummus, pickled turnips, and warm pita bread."),
    ("Crème Brûlée", "French", "Dessert",
     "Heavy cream, vanilla bean, egg yolks, caramelized sugar",
     "$13", "Vegetarian, Gluten-Free", True,
     "A classic French custard made with Madagascar vanilla bean and farm-fresh egg yolks, topped with a perfectly torched layer of caramelized sugar that cracks with a satisfying snap. Rich, creamy, and elegantly simple."),
    ("Korean BBQ Short Ribs", "Korean", "Main Course",
     "Beef short ribs, soy sauce, sesame, garlic, pear marinade",
     "$32", "Dairy-Free", False,
     "Premium beef short ribs marinated overnight in a sweet and savory blend of soy sauce, Asian pear, garlic, and toasted sesame. Grilled tableside over charcoal and served with lettuce wraps, pickled daikon, and gochujang dipping sauce."),
    ("Tiramisu", "Italian", "Dessert",
     "Mascarpone, espresso, ladyfingers, cocoa, Marsala wine",
     "$14", "Vegetarian, Contains Gluten", True,
     "Layers of espresso-soaked ladyfingers and whipped mascarpone cream flavored with Marsala wine, dusted with premium Dutch cocoa powder. Made fresh daily and chilled for 24 hours to develop rich, complex flavors."),
]


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 menu_items 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 menu_items (
            id SERIAL PRIMARY KEY,
            name VARCHAR NOT NULL,
            cuisine_type VARCHAR NOT NULL,
            category VARCHAR NOT NULL,
            ingredients VARCHAR NOT NULL,
            price VARCHAR NOT NULL,
            dietary_tags VARCHAR NOT NULL,
            available BOOLEAN NOT NULL DEFAULT TRUE,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_menu_items(cursor, conn):
    """Insert menu items."""
    cursor.execute("SELECT COUNT(*) FROM menu_items")
    existing_count = cursor.fetchone()[0]

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

    cursor.executemany("""
        INSERT INTO menu_items (name, cuisine_type, category, ingredients, price, dietary_tags, available, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, MENU_ITEMS)
    conn.commit()
    return len(MENU_ITEMS)


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

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

    cursor.execute(f"""
        UPDATE menu_items
        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_menu_items(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} menu items")

        # 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 बाइनरी डाउनलोड करना

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

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.1.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_restaurant_db.py स्क्रिप्ट को लागू करना

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

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

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

google_ml_integration — यह embedding() SQL फ़ंक्शन उपलब्ध कराता है. यह SQL से सीधे तौर पर Vertex AI एम्बेडिंग मॉडल को कॉल करता है. यह डेटाबेस-लेवल का एक्सटेंशन है. इससे restaurant_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 फ़ंक्शन लिखने होंगे. ये फ़ंक्शन, डेटाबेस कनेक्शन खोलते हैं, कनेक्शन पूल मैनेज करते हैं, SQL इंजेक्शन को रोकने के लिए पैरामीटर वाली क्वेरी बनाते हैं, गड़बड़ियों को ठीक करते हैं, और उस पूरे कोड को अपने एजेंट में एम्बेड करते हैं. डेटाबेस का ऐक्सेस पाने के लिए, हर एजेंट को यह काम दोहराना पड़ता है. क्वेरी बदलने का मतलब है कि एजेंट को फिर से डिप्लॉय करना होगा.

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

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

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

cloudshell edit tools.yaml

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

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

# tools.yaml

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

---