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

מסד נתונים ככלי: RAG מבוסס-סוכן עם ADK, ערכת הכלים MCP ו-Cloud SQL

1. מבוא

התועלת של סוכני AI תלויה בנתונים שהם יכולים לגשת אליהם. רוב הנתונים בעולם האמיתי נמצאים במסדי נתונים – ובדרך כלל, כדי לקשר סוכנים למסדי נתונים צריך לכתוב ניהול חיבורים, לוגיקה של שאילתות וצינורות הטמעה בתוך קוד הסוכן. כל נציג שזקוק לגישה למסד הנתונים צריך לחזור על הפעולה הזו, וכל שינוי בשאילתה מחייב פריסה מחדש של הנציג.

ב-Codelab הזה נציג גישה שונה. אתם מגדירים את כלי מסד הנתונים בקובץ YAML – שאילתות SQL סטנדרטיות, חיפוש דמיון וקטורי ואפילו יצירה אוטומטית של הטמעה – ו-MCP Toolbox for Databases מטפל בכל פעולות מסד הנתונים כשרת MCP. קוד הסוכן נשאר מינימלי: טוענים את הכלים ומאפשרים ל-Gemini להחליט לאיזה כלי להתקשר.

מה תפַתחו

מלצר וירטואלי למסעדה בשם "Foodie Finds" – סוכן ADK שמבוסס על Gemini ועוזר לסועדים לעיין בתפריט של המסעדה באמצעות מסננים רגילים (קטגוריה, סוג מטבח) ולגלות מנות באמצעות תיאורים בשפה טבעית כמו "אני רוצה משהו חריף וצמחוני". הסוכן קורא מתוך מסד נתונים של Cloud SQL PostgreSQL וכותב לתוכו אך ורק דרך MCP Toolbox for Databases, שמטפל בכל הגישה למסד הנתונים – כולל יצירה אוטומטית של הטמעה לחיפוש וקטורי. בסוף התהליך, גם ה-Toolbox וגם הסוכן יפעלו ב-Cloud Run.

מה תלמדו

איך תקן MCP‏ (Model Context Protocol) מאפשר גישה סטנדרטית לכלים לסוכני AI, ואיך MCP Toolbox for Databases מיישם את זה בפעולות שקשורות למסדי נתונים
הגדרת MCP Toolbox for Databases כתוכנת ביניים בין סוכן ADK לבין Cloud SQL PostgreSQL
הגדרת כלי מסד נתונים באופן הצהרתי ב-tools.yaml – אין קוד מסד נתונים בסוכן
יצירת סוכן ADK שמעמיס כלים משרת Toolbox פעיל באמצעות ToolboxToolset
יצירת הטמעות וקטורים באמצעות הפונקציה המובנית embedding() של Cloud SQL והפעלת חיפוש סמנטי באמצעות pgvector
שימוש בתכונה valueFromParam להוספה אוטומטית של וקטורים בפעולות כתיבה
פריסה של השרת Toolbox וסוכן ה-ADK ב-Cloud Run

דרישות מוקדמות

חשבון Google Cloud עם חשבון לחיוב בתקופת ניסיון
היכרות בסיסית עם Python ו-SQL
ניסיון קודם עם Cloud Database ו-ADK יעזור לכם

2. הגדרת הסביבה

בשלב הזה מכינים את סביבת Cloud Shell, מגדירים את הפרויקט ב-Google Cloud ומשכפלים את מאגר ההפניות.

פתיחת Cloud Shell

פותחים את Cloud Shell בדפדפן. ‫Cloud Shell מספקת סביבה שהוגדרה מראש עם כל הכלים שדרושים ל-Codelab הזה. כשמופיעה בקשה, לוחצים על Authorize.

אחר כך לוחצים על View (תצוגה) -> Terminal (טרמינל) כדי לפתוח את הטרמינל.הממשק אמור להיראות בערך כך:

זה יהיה הממשק הראשי שלנו, סביבת הפיתוח המשולבת (IDE) בחלק העליון והטרמינל בחלק התחתון

הגדרת ספריית העבודה

יוצרים את ספריית העבודה. כל הקוד שכותבים ב-Codelab הזה נמצא כאן:

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

כדי לפשט את הגדרת הפרויקט במסוף, מורידים את סקריפט הגדרת הפרויקט הזה לספריית העבודה:

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. מזהה הפרויקט צריך להופיע בו.

הפעלת API נדרש

לאחר מכן, צריך להפעיל כמה ממשקי API למוצר שאיתו תהיה אינטראקציה:

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 – השירותים האלה ישמשו בשלב הפריסה בהמשך שיעור ה-Codelab הזה

3. הכנת סקריפטים לאתחול מסד נתונים

בשלב הזה מתחילה יצירה של מופע Cloud SQL ומופעל סקריפט הגדרה אוטומטי שממתין עד שהמופע יהיה מוכן, ואז יוצר את מסד הנתונים, מאכלס אותו בפרטי משרות ויוצר הטבעות – והכול בפעולה אחת.

קודם צריך להוסיף את הסיסמה של מסד הנתונים לקובץ .env ולטעון אותו מחדש:

echo "DB_PASSWORD=restaurant-pwd" >> .env
echo "DB_INSTANCE=restaurant-instance" >> .env
echo "DB_NAME=restaurant_db" >> .env
source .env

יצירת סקריפט Bash ליצירת מכונה ומסד נתונים

לאחר מכן, יוצרים את הסקריפט 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 ). אנחנו משתמשים בו בשיעור Codelab הזה כדי לשמור על מהירות ופשטות בתחזוקת פרויקט Python

מאתחלים פרויקט Python ומוסיפים את התלות הנדרשת:

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

שימו לב: אנחנו משתמשים כאן ב-cloud-sql-python-connector Python SDK כדי להפעיל חיבור מאובטח למופע מסד הנתונים שלנו, שמאומת באמצעות Application Default Credentials.

הפעלת סקריפט ההגדרה

עכשיו אפשר להריץ את סקריפט ההגדרה ברקע ולבדוק את הפלט של המסוף שייכתב לקובץ 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 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 היא הרמה הקטנה ביותר של Cloud SQL עם ליבה ייעודית (‎1 vCPU, ‏ ‎3.75 GB RAM) במהדורת ENTERPRISE. פרטים נוספים זמינים כאן. נדרשת ליבה ייעודית לשילוב של Vertex AI ML – שכבות של ליבת מעבד משותפת (db-f1-micro, db-g1-small) לא תומכות בה.
‫--root-password מגדיר את הסיסמה למשתמש ברירת המחדל postgres.
‫--enable-google-ml-integration מאפשרת את השילוב המובנה של Cloud SQL עם Vertex AI, שמאפשר לכם להפעיל מודלים של הטמעות ישירות מ-SQL באמצעות הפונקציה embedding().

בודקים אם המופע כבר בסטטוס RUNNABLE
נותנים לחשבון השירות של מכונת Cloud SQL הרשאה לקרוא ל-Vertex AI באמצעות הפקודה gcloud projects add-iam-policy-binding. הפעולה הזו נדרשת עבור הפונקציה המובנית embedding() שבה נשתמש כשנזרע את מסד הנתונים
יצירת מסד הנתונים
הרצת סקריפט ההרצה הראשונית setup_restaurant_db.py

הסבר על סקריפט הזרע `scripts/setup_restaurant_db.py`

עכשיו נעבור לסקריפט ההגדרה הראשונית. הסקריפט הזה מבצע את הפעולות הבאות:

הפעלת החיבור למופע של מסד הנתונים
הכלי מתקין שני תוספים ל-PostgreSQL:

‫google_ml_integration — מספק את פונקציית ה-SQL‏ embedding(), שקוראת למודלים של הטמעה ב-Vertex AI ישירות מ-SQL. זהו תוסף ברמת מסד הנתונים שמאפשר להשתמש בפונקציות של למידת מכונה בתוך restaurant_db. הדגל ברמת המופע (--enable-google-ml-integration) שאתם מגדירים במהלך יצירת המופע מאפשר למכונה הווירטואלית של Cloud SQL להגיע אל Vertex AI – התוסף מאפשר להשתמש בפונקציות ה-SQL במסד הנתונים הספציפי הזה.
‫vector (pgvector) – מוסיף את סוג הנתונים vector ואת אופרטורי המרחק לאחסון ולשאילתת הטמעה.

יוצרים את הטבלה, ומציינים שהעמודה description_embedding היא vector(3072) – עמודה מסוג pgvector שמאחסנת וקטורים תלת-ממדיים של 3,072.
הזנת נתונים ראשוניים של פריטים בתפריט
יצירת נתוני ההטמעה מהשדה description ומילוי השדה description_embedding באמצעות השילוב המובנה של Vertex דרך הפונקציה embedding()

‫embedding('gemini-embedding-001', description) — קורא למודל ההטמעה של Gemini ב-Vertex AI ישירות מ-SQL, ומעביר את description הטקסט של כל משרה. זהו התוסף google_ml_integration שהתקנתם בסקריפט ה-seed.
‫::vector — מבצע המרה של מערך המספרים הממשיים שמוחזר לסוג vector של pgvector, כדי שאפשר יהיה לאחסן אותו ולשאול עליו שאילתות באמצעות אופרטורים של מרחק.
המודל UPDATE פועל על כל 15 השורות, ויוצר הטמעה אחת בת 3,072 ממדים לכל תיאור משרה.

הפעולה הזו תכין נתונים ראשוניים שהסוכן שלנו יוכל לגשת אליהם

5. הגדרת MCP Toolbox for Databases

בשלב הזה נציג את MCP Toolbox for Databases, נגדיר אותו לחיבור למופע Cloud SQL ונגדיר שני כלים לשאילתות SQL סטנדרטי.

מה זה MCP ולמה כדאי להשתמש ב-Toolbox?

‫MCP (Model Context Protocol) הוא פרוטוקול פתוח שקובע תקן לאופן שבו סוכני AI מגלים כלים חיצוניים ומקיימים איתם אינטראקציות. הוא מגדיר מודל לקוח-שרת: הסוכן מארח לקוח MCP, והכלים נחשפים על ידי שרתי MCP. כל לקוח שתואם ל-MCP יכול להשתמש בכל שרת שתואם ל-MCP – לא צריך קוד שילוב מותאם אישית לסוכן עבור כל כלי.

‫MCP Toolbox for Databases הוא שרת MCP בקוד פתוח שנבנה במיוחד לגישה למסדי נתונים. בלי זה, תצטרכו לכתוב פונקציות Python שפותחות חיבורים למסד נתונים, מנהלות מאגרי חיבורים, בונות שאילתות עם פרמטרים כדי למנוע הזרקת SQL, מטפלות בשגיאות ומשבצות את כל הקוד הזה בתוך הסוכן. כל נציג שזקוק לגישה למסד הנתונים חוזר על הפעולה הזו. שינוי שאילתה מחייב פריסה מחדש של הסוכן.

כדי להשתמש ב-Toolbox, צריך לכתוב קובץ YAML. כל כלי ממופה להצהרת SQL עם פרמטרים. Toolbox מטפל בניהול חיבורים, בשאילתות עם פרמטרים, באימות ובניטור. הכלים מופרדים מהסוכן – כדי לעדכן שאילתה, צריך לערוך את tools.yaml ולהפעיל מחדש את Toolbox, בלי לגעת בקוד של הסוכן. אותם כלים פועלים ב-ADK, ב-LangGraph, ב-LlamaIndex או בכל מסגרת תואמת ל-MCP.

כתיבת ההגדרה של כלי

עכשיו צריך ליצור קובץ בשם tools.yaml ב-Cloud Shell Editor כדי להגדיר את כלי ההגדרה

cloudshell edit tools.yaml

הקובץ משתמש ב-YAML עם כמה מסמכים – כל בלוק שמופרד על ידי --- הוא משאב עצמאי. לכל משאב יש מאפיין kind שמצהיר מהו (sources לחיבורי מסד נתונים, tools לפעולות שאפשר להפעיל באמצעות סוכן) ומאפיין type שמציין את ה-Backend (cloud-sql-postgres למקור, postgres-sql לכלים מבוססי SQL). כלי מפנה למקור שלו באמצעות name, וכך ארגז הכלים יודע מול איזה מאגר חיבורים לבצע את הפעולה. משתני הסביבה משתמשים בתחביר ${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}

---