این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پایگاه داده به عنوان یک ابزار: Agentic RAG با ADK، جعبه ابزار MCP و Cloud SQL

۱. مقدمه

عامل‌های هوش مصنوعی فقط به اندازه داده‌هایی که می‌توانند به آنها دسترسی داشته باشند، مفید هستند. بیشتر داده‌های دنیای واقعی در پایگاه‌های داده قرار دارند - و اتصال عامل‌ها به پایگاه‌های داده معمولاً به معنای نوشتن مدیریت اتصال، منطق پرس‌وجو و تعبیه خطوط لوله در داخل کد عامل شماست. هر عاملی که به دسترسی به پایگاه داده نیاز دارد، این کار را تکرار می‌کند و هر تغییر پرس‌وجو نیاز به استقرار مجدد عامل دارد.

این آزمایشگاه کد رویکرد متفاوتی را نشان می‌دهد. شما ابزارهای پایگاه داده خود را در یک فایل YAML تعریف می‌کنید - کوئری‌های استاندارد SQL، جستجوی شباهت برداری، حتی تولید خودکار جاسازی - و MCP Toolbox for Databases تمام عملیات پایگاه داده را به عنوان یک سرور MCP مدیریت می‌کند. کد عامل شما مینیمال باقی می‌ماند: ابزارها را بارگذاری کنید، بگذارید Gemini تصمیم بگیرد کدام یک را فراخوانی کند.

آنچه خواهید ساخت

یک متصدی رستوران برای «Foodie Finds» - یک عامل ADK که توسط Gemini پشتیبانی می‌شود و به مشتریان کمک می‌کند تا با استفاده از فیلترهای استاندارد (دسته‌بندی، نوع غذا) منوی رستوران را مرور کنند و غذاها را از طریق توضیحات زبان طبیعی مانند «من چیزی تند و گیاهی می‌خواهم» کشف کنند. این عامل از طریق MCP Toolbox for Databases، که تمام دسترسی به پایگاه داده - از جمله تولید خودکار جاسازی برای جستجوی برداری - را مدیریت می‌کند، از یک پایگاه داده Cloud SQL PostgreSQL می‌خواند و در آن می‌نویسد. در نهایت، هم Toolbox و هم عامل روی Cloud Run اجرا می‌شوند.

آنچه یاد خواهید گرفت

چگونه MCP (پروتکل زمینه مدل) دسترسی به ابزار را برای عوامل هوش مصنوعی استاندارد می‌کند، و چگونه MCP Toolbox for Databases این را در عملیات پایگاه داده اعمال می‌کند
جعبه ابزار MCP برای پایگاه‌های داده را به عنوان میان‌افزار بین یک عامل ADK و Cloud SQL PostgreSQL تنظیم کنید.
ابزارهای پایگاه داده را به صورت اعلانی در tools.yaml تعریف کنید - هیچ کد پایگاه داده‌ای در عامل شما وجود ندارد
با استفاده از ToolboxToolset یک عامل ADK بسازید که ابزارها را از یک سرور Toolbox در حال اجرا بارگیری کند.
با استفاده از embedding() داخلی Cloud SQL، جاسازی‌های برداری ایجاد کنید و جستجوی معنایی را با pgvector فعال کنید.
از ویژگی valueFromParam برای دریافت خودکار بردار در عملیات نوشتن استفاده کنید
سرور Toolbox و ADK agent را روی Cloud Run مستقر کنید.

پیش‌نیازها

یک حساب Google Cloud با یک حساب پرداخت آزمایشی
آشنایی اولیه با پایتون و SQL
تجربه قبلی با Cloud Database و ADK مفید خواهد بود.

۲. محیط خود را آماده کنید

این مرحله محیط Cloud Shell شما را آماده می‌کند، پروژه Google Cloud شما را پیکربندی می‌کند و مخزن مرجع را کلون می‌کند.

پوسته ابری را باز کنید

Cloud Shell را در مرورگر خود باز کنید. Cloud Shell یک محیط از پیش پیکربندی شده با تمام ابزارهای مورد نیاز برای این آزمایشگاه کد را فراهم می‌کند. در صورت درخواست، روی تأیید (Authorize) کلیک کنید.

سپس روی « مشاهده » -> « ترمینال » کلیک کنید تا ترمینال باز شود. رابط کاربری شما باید شبیه به این باشد.

۸۶۳۰۷fac5da2f077.png

این رابط اصلی ما خواهد بود، IDE در بالا، ترمینال در پایین

دایرکتوری کاری خود را تنظیم کنید

دایرکتوری کاری خود را ایجاد کنید. تمام کدهایی که در این آزمایشگاه کد می‌نویسید، در اینجا قرار دارند:

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

پروژه گوگل کلود خود را راه‌اندازی کنید

فایل .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 که به یک حساب Trial Billing (strict) متصل است، ارائه شده است. اگر ترجیح می‌دهید از پروژه قبلی خود استفاده کنید، می‌توانید مرحله زیر را نادیده بگیرید و به جای آن مرحله زیر را انجام دهید:

نام پروژه خود را به عنوان متغیر GOOGLE_CLOUD_PROJECT در فایل .env اضافه کنید.
پروژه خود را در ترمینال با استفاده از gcloud config set project your-project-id فعال کنید.

پس از آن، می‌توانید مستقیماً به بخش فعال‌سازی API بروید.

اگر در این مورد مطمئن نیستید، بخش زیر را ادامه دهید

برای ساده‌سازی راه‌اندازی پروژه در ترمینال خود، این اسکریپت راه‌اندازی پروژه را در دایرکتوری کاری خود دانلود کنید:

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

رابط برنامه‌نویسی کاربردی هوش مصنوعی ورتکس ( aiplatform.googleapis.com ) — عامل شما از مدل‌های Gemini استفاده می‌کند و تول‌باکس از رابط برنامه‌نویسی کاربردی جاسازی برای جستجوی برداری استفاده می‌کند.
رابط برنامه‌نویسی کاربردی مدیریت SQL ابری ( sqladmin.googleapis.com ) - شما یک نمونه PostgreSQL را تهیه و مدیریت می‌کنید.
رابط برنامه‌نویسی کاربردی موتور محاسبات (compute Engine API ) ( compute.googleapis.com ) — برای ایجاد نمونه‌های Cloud SQL مورد نیاز است.
Cloud Run، Cloud Build، Artifact Registry - که در مرحله استقرار بعداً در این آزمایشگاه کد استفاده می‌شود

۳. آماده‌سازی اسکریپت‌ها برای مقداردهی اولیه پایگاه داده

این مرحله ایجاد نمونه 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 ""

ایجاد اسکریپت پایتون برای ایجاد پایگاه داده

پس از آن، با استفاده از دستور زیر، فایل پایتون scripts/setup_restaurant_db.py مربوط به اسکریپت seeding را ایجاد کنید.

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()

حالا بریم مرحله بعدی

۴. ایجاد و مقداردهی اولیه پایگاه داده

اکنون اسکریپت‌های ما آماده اجرا هستند. برای اجرای اسکریپت آماده شده به پایتون نیاز داریم، بنابراین ابتدا آن را آماده می‌کنیم.

پروژه پایتون را تنظیم کنید

uv یک پکیج سریع پایتون و مدیر پروژه است که با زبان Rust نوشته شده است ( مستندات uv ). این codelab از آن برای سرعت و سادگی در نگهداری پروژه پایتون استفاده می‌کند.

یک پروژه پایتون را راه‌اندازی کنید و وابستگی‌های مورد نیاز را اضافه کنید:

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 &

دانلود فایل باینری جعبه ابزار

ما در این آموزش از MCP Toolbox استفاده خواهیم کرد، خوشبختانه این ابزار با یک فایل باینری از پیش ساخته شده ارائه می‌شود که آماده استفاده در محیط لینوکس است. اکنون، بیایید آن را در پس‌زمینه دانلود کنیم، زیرا زمان زیادی طول می‌کشد. دستور زیر را برای دانلود فایل باینری و بررسی گزارش خروجی در 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 اجازه دهید تا با استفاده از دستور gcloud projects add-iam-policy-binding Vertex AI را فراخوانی کند. این مجوز برای تابع داخلی embedding() که هنگام seeding پایگاه داده از آن استفاده خواهیم کرد، لازم است.
ایجاد پایگاه داده
اجرای اسکریپت seeding اسکریپت setup_restaurant_db.py

آشنایی با `scripts/setup_restaurant_db.py`

حالا، به سراغ اسکریپت seeding می‌رویم، این اسکریپت کارهای زیر را انجام می‌دهد:

مقداردهی اولیه اتصال به نمونه پایگاه داده
دو افزونه PostgreSQL را نصب می‌کند:

google_ml_integration — تابع embedding() SQL را فراهم می‌کند که مدل‌های تعبیه هوش مصنوعی Vertex را مستقیماً از SQL فراخوانی می‌کند. این یک افزونه در سطح پایگاه داده است که توابع یادگیری ماشین را در داخل restaurant_db در دسترس قرار می‌دهد. پرچم سطح نمونه ( --enable-google-ml-integration ) که هنگام ایجاد نمونه تنظیم می‌کنید، به ماشین مجازی Cloud SQL اجازه می‌دهد تا به Vertex AI دسترسی پیدا کند — این افزونه توابع SQL را در این پایگاه داده خاص در دسترس قرار می‌دهد.
vector ( pgvector ) - نوع داده vector و عملگرهای فاصله را برای ذخیره و جستجوی جاسازی‌ها اضافه می‌کند.

جدول را ایجاد کنید، توجه داشته باشید که ستون description_embedding vector(3072) است - یک ستون pgvector که بردارهای 3072 بعدی را ذخیره می‌کند.
داده‌های اولیه‌ی آیتم‌های منو را بارگذاری کنید
داده‌های جاسازی را از فیلد description تولید کنید و description_embedding با استفاده از ادغام رأس داخلی از طریق تابع embedding() پر کنید.

embedding('gemini-embedding-001', description) — مدل embedding Gemini مربوط به Vertex AI را مستقیماً از SQL فراخوانی می‌کند و متن description هر کار را ارسال می‌کند. این افزونه google_ml_integration است که شما در اسکریپت seed نصب کرده‌اید.
::vector — آرایه اعشاری برگشتی را به نوع vector pgvector تبدیل می‌کند تا بتوان آن را ذخیره و با عملگرهای فاصله پرس‌وجو کرد.
UPDATE در هر ۱۵ ردیف اجرا می‌شود و به ازای هر شرح شغل، یک جاسازی ۳۰۷۲ بعدی ایجاد می‌کند.

این داده‌های اولیه‌ای را که توسط نماینده ما قابل دسترسی خواهد بود، آماده می‌کند.

۵. پیکربندی جعبه ابزار MCP برای پایگاه‌های داده

این مرحله جعبه ابزار MCP برای پایگاه‌های داده را معرفی می‌کند، آن را برای اتصال به نمونه Cloud SQL شما پیکربندی می‌کند و دو ابزار استاندارد پرس‌وجوی SQL را تعریف می‌کند.

MCP چیست و چرا از جعبه ابزار استفاده کنیم؟

MCP (پروتکل زمینه مدل) یک پروتکل باز است که نحوه کشف و تعامل عامل‌های هوش مصنوعی با ابزارهای خارجی را استاندارد می‌کند. این پروتکل یک مدل کلاینت-سرور را تعریف می‌کند: عامل میزبان یک کلاینت MCP است و ابزارها توسط سرورهای MCP در معرض دید قرار می‌گیرند. هر کلاینت سازگار با MCP می‌تواند از هر سرور سازگار با MCP استفاده کند - عامل برای هر ابزار به کد یکپارچه‌سازی سفارشی نیاز ندارد.

جعبه ابزار MCP برای پایگاه‌های داده، یک سرور MCP متن‌باز است که به‌طور خاص برای دسترسی به پایگاه داده ساخته شده است. بدون آن، شما باید توابع پایتونی بنویسید که اتصالات پایگاه داده را باز می‌کنند، مجموعه‌های اتصال را مدیریت می‌کنند، کوئری‌های پارامتری برای جلوگیری از تزریق SQL می‌سازند، خطاها را مدیریت می‌کنند و تمام آن کد را درون عامل خود جاسازی می‌کنند. هر عاملی که به دسترسی به پایگاه داده نیاز دارد، این کار را تکرار می‌کند. تغییر یک کوئری به معنای استقرار مجدد عامل است.

با Toolbox، شما یک فایل YAML می‌نویسید. هر ابزار به یک دستور SQL پارامتری نگاشت می‌شود. Toolbox ادغام اتصال، پرس‌وجوهای پارامتری، احراز هویت و مشاهده‌پذیری را مدیریت می‌کند. ابزارها از عامل جدا شده‌اند - یک پرس‌وجو را با ویرایش tools.yaml و راه‌اندازی مجدد Toolbox، بدون دست زدن به کد عامل، به‌روزرسانی کنید. همین ابزارها در ADK، LangGraph، LlamaIndex یا هر چارچوب سازگار با MCP کار می‌کنند.

پیکربندی ابزارها را بنویسید

حالا، باید فایلی به نام tools.yaml در ویرایشگر Cloud Shell ایجاد کنیم تا پیکربندی ابزارهایمان را تنظیم کنیم.

cloudshell edit tools.yaml

این فایل از YAML چند سندی استفاده می‌کند - هر بلوک جدا شده با --- یک منبع مستقل است. هر منبع یک kind دارد که ماهیت آن را اعلام می‌کند ( sources برای اتصالات پایگاه داده، tools برای اقدامات قابل فراخوانی توسط عامل) و یک type که backend را مشخص می‌کند ( cloud-sql-postgres برای منبع، postgres-sql برای ابزارهای مبتنی بر 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}

---