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

ฐานข้อมูลในฐานะเครื่องมือ: RAG แบบเอเจนต์ที่มี ADK, MCP Toolbox และ Cloud SQL

1. บทนำ

เอเจนต์ AI จะมีประโยชน์เพียงใดก็ขึ้นอยู่กับข้อมูลที่เข้าถึงได้ ข้อมูลในโลกแห่งความเป็นจริงส่วนใหญ่อยู่ในฐานข้อมูล และการเชื่อมต่อเอเจนต์กับฐานข้อมูลมักหมายถึงการเขียนการจัดการการเชื่อมต่อ ตรรกะการค้นหา และไปป์ไลน์การฝังภายในโค้ดของเอเจนต์ ตัวแทนทุกรายที่ต้องเข้าถึงฐานข้อมูลจะทำขั้นตอนนี้ซ้ำ และการเปลี่ยนแปลงการค้นหาทุกครั้งจะต้องมีการติดตั้งใช้งานตัวแทนอีกครั้ง

Codelab นี้แสดงแนวทางที่แตกต่างออกไป คุณประกาศเครื่องมือฐานข้อมูลในไฟล์ YAML ซึ่งได้แก่ การค้นหา SQL มาตรฐาน การค้นหาความคล้ายคลึงของเวกเตอร์ หรือแม้แต่การสร้างการฝังอัตโนมัติ และ MCP Toolbox สำหรับฐานข้อมูลจะจัดการการดำเนินการฐานข้อมูลทั้งหมดในฐานะเซิร์ฟเวอร์ MCP โค้ดเอเจนต์ของคุณจะยังคงมีขนาดเล็ก: โหลดเครื่องมือ แล้วปล่อยให้ Gemini ตัดสินใจว่าจะเรียกใช้เครื่องมือใด

สิ่งที่คุณจะสร้าง

ผู้ช่วยร้านอาหารสำหรับ "ร้านอาหารแนะนำ" ซึ่งเป็นเอเจนต์ ADK ที่ขับเคลื่อนโดย Gemini ซึ่งช่วยให้ผู้รับประทานอาหารเรียกดูเมนูของร้านอาหารได้โดยใช้ตัวกรองมาตรฐาน (หมวดหมู่ ประเภทอาหาร) และค้นพบเมนูอาหารผ่านคำอธิบายภาษาธรรมชาติ เช่น "ฉันอยากกินอะไรที่เผ็ดและเป็นมังสวิรัติ" เอเจนต์จะอ่านและเขียนไปยังฐานข้อมูล Cloud SQL PostgreSQL ผ่าน MCP Toolbox สำหรับฐานข้อมูลทั้งหมด ซึ่งจะจัดการการเข้าถึงฐานข้อมูลทั้งหมด รวมถึงการสร้างการฝังอัตโนมัติสำหรับการค้นหาแบบเวกเตอร์ ในท้ายที่สุด ทั้ง Toolbox และเอเจนต์จะทำงานใน Cloud Run

สิ่งที่คุณจะได้เรียนรู้

วิธีที่ MCP (Model Context Protocol) สร้างมาตรฐานการเข้าถึงเครื่องมือสำหรับ Agent AI และวิธีที่ MCP Toolbox สำหรับฐานข้อมูลใช้มาตรฐานนี้กับการดำเนินการฐานข้อมูล
ตั้งค่า MCP Toolbox สำหรับฐานข้อมูลเป็นมิดเดิลแวร์ระหว่าง Agent ADK กับ Cloud SQL PostgreSQL
กำหนดเครื่องมือฐานข้อมูลแบบประกาศใน tools.yaml โดยไม่ต้องมีโค้ดฐานข้อมูลใน Agent
สร้าง ADK Agent ที่โหลดเครื่องมือจากเซิร์ฟเวอร์ Toolbox ที่ทำงานอยู่โดยใช้ ToolboxToolset
สร้าง Vector Embeddings โดยใช้ฟังก์ชัน embedding() ในตัวของ Cloud SQL และเปิดใช้การค้นหาเชิงความหมายด้วย pgvector
ใช้ฟีเจอร์ valueFromParam เพื่อการส่งผ่านข้อมูลเวกเตอร์อัตโนมัติในการดำเนินการเขียน
ติดตั้งใช้งานทั้งเซิร์ฟเวอร์ Toolbox และ Agent ADK ใน Cloud Run

ข้อกำหนดเบื้องต้น

บัญชี Google Cloud ที่มีบัญชีสำหรับการเรียกเก็บเงินช่วงทดลองใช้
มีความรู้พื้นฐานเกี่ยวกับ Python และ SQL
ประสบการณ์การใช้งาน Cloud Database และ ADK มาก่อนจะเป็นประโยชน์

2. ตั้งค่าสภาพแวดล้อม

ขั้นตอนนี้จะเตรียมสภาพแวดล้อม Cloud Shell, กำหนดค่าโปรเจ็กต์ Google Cloud และโคลนที่เก็บข้อมูลอ้างอิง

เปิด Cloud Shell

เปิด Cloud Shell ในเบราว์เซอร์ Cloud Shell มีสภาพแวดล้อมที่กำหนดค่าไว้ล่วงหน้าพร้อมเครื่องมือทั้งหมดที่คุณต้องการสำหรับ Codelab นี้ คลิกให้สิทธิ์เมื่อมีข้อความแจ้งให้ทำ

จากนั้นคลิก "ดู" -> "เทอร์มินัล" เพื่อเปิดเทอร์มินัล อินเทอร์เฟซของคุณควรมีลักษณะคล้ายกับภาพนี้

นี่จะเป็นอินเทอร์เฟซหลักของเรา โดยมี 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

สร้างไฟล์ .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 ที่ลิงก์กับบัญชีสำหรับการเรียกเก็บเงินแบบทดลองใช้(เข้มงวด) อย่างรวดเร็ว หากต้องการใช้โปรเจ็กต์ก่อนหน้านี้ของคุณเอง ให้ข้ามขั้นตอนต่อไปนี้และทำตามขั้นตอนต่อไปนี้แทน

เพิ่มชื่อโปรเจ็กต์ของคุณเองเป็น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

Vertex AI API (aiplatform.googleapis.com) - Agent ของคุณใช้โมเดล 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

สำคัญ รหัสผ่านที่ฮาร์ดโค้ดด้านบนมีไว้เพื่อวัตถุประสงค์ในการสอนเท่านั้น ในสภาพแวดล้อมฮาร์ดแวร์และซอฟต์แวร์ ให้จัดเก็บข้อมูลเข้าสู่ระบบอย่างปลอดภัยโดยใช้บริการอย่าง Secret Manager และอ้างอิงข้อมูลดังกล่าวในขณะรันไทม์ โดยอย่าคอมมิตข้อมูลลับที่เป็นข้อความธรรมดาไปยังการควบคุมแหล่งที่มา

การสร้างสคริปต์ 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 ที่นี่เพื่อเริ่มต้นการเชื่อมต่อที่ปลอดภัยกับอินสแตนซ์ฐานข้อมูลของเรา ซึ่งได้รับการตรวจสอบสิทธิ์โดยใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน

เรียกใช้สคริปต์การตั้งค่า

ตอนนี้เราสามารถเรียกใช้สคริปต์การตั้งค่าในเบื้องหลังและตรวจสอบเอาต์พุตของคอนโซลที่จะเขียนลงในไฟล์ 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 ซึ่งมาพร้อมกับไบนารีที่สร้างไว้ล่วงหน้าซึ่งพร้อมใช้งานในสภาพแวดล้อม 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, RAM 3.75 GB) ในรุ่น 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 2 รายการ

google_ml_integration — มีembedding()ฟังก์ชัน SQL ซึ่งเรียกใช้โมเดลการฝังของ Vertex AI จาก SQL โดยตรง ส่วนขยายนี้เป็นส่วนขยายระดับฐานข้อมูลที่ทำให้ฟังก์ชัน ML พร้อมใช้งานภายใน restaurant_db แฟล็กระดับอินสแตนซ์ (--enable-google-ml-integration) ที่คุณตั้งค่าระหว่างการสร้างอินสแตนซ์จะอนุญาตให้ VM ของ Cloud SQL เข้าถึง Vertex AI ได้ ส่วนส่วนขยายจะทำให้ฟังก์ชัน SQL พร้อมใช้งานภายในฐานข้อมูลที่เฉพาะเจาะจงนี้
vector (pgvector) — เพิ่มประเภทข้อมูล vector และตัวดำเนินการระยะทางสำหรับการจัดเก็บและค้นหาการฝัง

สร้างตาราง โปรดทราบว่าคอลัมน์ description_embedding คือ vector(3072) ซึ่งเป็นคอลัมน์ pgvector ที่จัดเก็บเวกเตอร์ 3072 มิติ
เริ่มต้นใช้งานข้อมูลรายการเมนูเริ่มต้น
สร้างข้อมูลการฝังจากฟิลด์ description และกรอก description_embedding โดยใช้การผสานรวม Vertex ในตัวผ่านฟังก์ชัน embedding()

embedding('gemini-embedding-001', description) — เรียกใช้โมเดลการฝัง Gemini ของ Vertex AI โดยตรงจาก SQL โดยส่งdescriptionข้อความของแต่ละงาน นี่คือส่วนขยาย google_ml_integration ที่คุณติดตั้งในสคริปต์เริ่มต้น
::vector — แปลงอาร์เรย์ของค่าทศนิยมที่ส่งคืนเป็นประเภท vector ของ pgvector เพื่อให้จัดเก็บและค้นหาด้วยโอเปอเรเตอร์ระยะทางได้
UPDATE จะทำงานในทั้ง 15 แถว โดยสร้างการฝังมิติ 3072 จำนวน 1 รายการต่อคำอธิบายงาน

ซึ่งจะเตรียมข้อมูลเริ่มต้นที่ Agent ของเราจะเข้าถึง

5. กำหนดค่า MCP Toolbox สำหรับฐานข้อมูล

ขั้นตอนนี้จะแนะนำ MCP Toolbox สำหรับฐานข้อมูล กำหนดค่าให้เชื่อมต่อกับอินสแตนซ์ Cloud SQL และกำหนดเครื่องมือคำค้นหา SQL มาตรฐาน 2 รายการ

MCP คืออะไรและเหตุใดจึงควรใช้กล่องเครื่องมือ

MCP (Model Context Protocol) เป็นโปรโตคอลแบบเปิดที่กำหนดมาตรฐานวิธีที่ Agent AI ค้นหาและโต้ตอบกับเครื่องมือภายนอก โดยจะกำหนดรูปแบบไคลเอ็นต์-เซิร์ฟเวอร์ ซึ่ง Agent จะโฮสต์ไคลเอ็นต์ MCP และเซิร์ฟเวอร์ MCP จะแสดงเครื่องมือต่างๆ ไคลเอ็นต์ที่เข้ากันได้กับ MCP สามารถใช้เซิร์ฟเวอร์ที่เข้ากันได้กับ MCP ได้โดยไม่ต้องมีโค้ดการผสานรวมที่กำหนดเองสำหรับแต่ละเครื่องมือ

MCP Toolbox สำหรับฐานข้อมูลเป็นเซิร์ฟเวอร์ MCP โอเพนซอร์สที่สร้างขึ้นเพื่อการเข้าถึงฐานข้อมูลโดยเฉพาะ หากไม่มี คุณจะต้องเขียนฟังก์ชัน Python ที่เปิดการเชื่อมต่อฐานข้อมูล จัดการกลุ่มการเชื่อมต่อ สร้างการค้นหาที่มีพารามิเตอร์เพื่อป้องกันการแทรก SQL จัดการข้อผิดพลาด และฝังโค้ดทั้งหมดนั้นไว้ในตัวแทน ตัวแทนทุกคนที่ต้องการเข้าถึงฐานข้อมูลจะต้องทำขั้นตอนนี้ซ้ำ การเปลี่ยนคำค้นหาหมายถึงการติดตั้งใช้งาน Agent อีกครั้ง

เมื่อใช้ Toolbox คุณจะเขียนไฟล์ YAML ได้ โดยแต่ละเครื่องมือจะแมปกับคำสั่ง SQL ที่กำหนดพารามิเตอร์ไว้ Toolbox จะจัดการการจัดกลุ่มการเชื่อมต่อ คำค้นหาที่กำหนดพารามิเตอร์ การตรวจสอบสิทธิ์ และความสามารถในการสังเกต เครื่องมือจะแยกออกจาก Agent คุณสามารถอัปเดตคำค้นหาได้โดยการแก้ไข tools.yaml และรีสตาร์ท Toolbox โดยไม่ต้องแตะต้องโค้ดของ Agent เครื่องมือเดียวกันนี้จะทำงานได้ใน ADK, LangGraph, LlamaIndex หรือเฟรมเวิร์กที่เข้ากันได้กับ MCP

เขียนการกำหนดค่าเครื่องมือ

ตอนนี้เราต้องสร้างไฟล์ชื่อ tools.yaml ใน Cloud Shell Editor เพื่อตั้งค่าเครื่องมือ

cloudshell edit tools.yaml

ไฟล์ใช้ YAML แบบหลายเอกสาร โดยแต่ละบล็อกที่คั่นด้วย --- จะเป็นทรัพยากรแบบสแตนด์อโลน ทรัพยากรทุกรายการมี kind ที่ประกาศว่าทรัพยากรนั้นคืออะไร (sources สำหรับการเชื่อมต่อฐานข้อมูล tools สำหรับการดำเนินการที่เรียกใช้ได้ของเอเจนต์) และ type ที่ระบุแบ็กเอนด์ (cloud-sql-postgres สำหรับแหล่งที่มา postgres-sql สำหรับเครื่องมือที่ใช้ SQL) เครื่องมือจะอ้างอิงแหล่งที่มาด้วย name ซึ่งเป็นวิธีที่กล่องเครื่องมือจะทราบว่าควรใช้ Connection Pool ใด ตัวแปรสภาพแวดล้อมใช้ไวยากรณ์ ${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}

---