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

Araç Olarak Veritabanı: ADK, MCP Toolbox ve Cloud SQL ile Agentic RAG

1. Giriş

Yapay zeka temsilcileri, yalnızca erişebildikleri veriler kadar faydalıdır. Gerçek dünyadaki verilerin çoğu veritabanlarında bulunur ve temsilcileri veritabanlarına bağlamak genellikle temsilci kodunuzda bağlantı yönetimi, sorgu mantığı ve yerleştirme işlem hatları yazmak anlamına gelir. Veritabanı erişimi gerektiren her temsilci bu çalışmayı tekrarlar ve her sorgu değişikliği, temsilcinin yeniden dağıtılmasını gerektirir.

Bu codelab'de farklı bir yaklaşım gösterilmektedir. Veritabanı araçlarınızı bir YAML dosyasında (standart SQL sorguları, vektör benzerliği araması ve hatta otomatik yerleştirme oluşturma) tanımlarsınız. Veritabanları için MCP Araç Kutusu, tüm veritabanı işlemlerini bir MCP sunucusu olarak yönetir. Aracı kodunuz en az düzeyde kalır: Araçları yükleyin, hangi aracın çağrılacağına Gemini karar versin.

Ne oluşturacaksınız?

"Yemek Tutkunlarına Özel" için Restoran Concierge: Gemini destekli bir ADK aracısıdır. Yemek yiyenlerin standart filtreleri (kategori, mutfak türü) kullanarak restoranın menüsüne göz atmasına ve "Acı ve vejetaryen bir yemek istiyorum" gibi doğal dil açıklamalarıyla yemekleri keşfetmesine yardımcı olur. Aracı, vektör araması için otomatik yerleştirme oluşturma da dahil olmak üzere tüm veritabanı erişimini işleyen MCP Toolbox for Databases aracılığıyla Cloud SQL PostgreSQL veritabanından okuma ve bu veritabanına yazma işlemleri gerçekleştirir. Sonunda hem Toolbox hem de aracı Cloud Run'da çalışır.

Neler öğreneceksiniz?

MCP (Model Context Protocol) standardının, yapay zeka ajanlarının araç erişimini nasıl standartlaştırdığı ve MCP Toolbox for Databases'in bunu veritabanı işlemlerine nasıl uyguladığı
Veritabanları için MCP Toolbox'ı ADK aracısı ile Cloud SQL PostgreSQL arasında ara katman yazılımı olarak ayarlama
Veritabanı araçlarını tools.yaml içinde bildirimsel olarak tanımlayın. Temsilcinizde veritabanı kodu bulunmaz.
ToolboxToolset kullanarak çalışan bir Araç Kutusu sunucusundan araç yükleyen bir ADK aracısı oluşturma
Cloud SQL'in yerleşik embedding() işlevini kullanarak vektör yerleştirmeleri oluşturma ve pgvector ile semantik aramayı etkinleştirme
Yazma işlemlerinde otomatik vektör alımı için valueFromParam özelliğini kullanma
Toolbox sunucusunu ve ADK aracısını Cloud Run'a dağıtma

Ön koşullar

Deneme faturalandırma hesabına sahip bir Google Cloud hesabı
Python ve SQL ile ilgili temel bilgiler
Cloud Database ve ADK ile ilgili önceki deneyimler yardımcı olacaktır.

2. Ortamınızı ayarlama

Bu adımda Cloud Shell ortamınız hazırlanır, Google Cloud projeniz yapılandırılır ve referans deposu klonlanır.

Cloud Shell'i açma

Tarayıcınızda Cloud Shell'i açın. Cloud Shell, bu codelab için ihtiyacınız olan tüm araçların bulunduğu önceden yapılandırılmış bir ortam sağlar. İstendiğinde Yetkilendir'i tıklayın.

Ardından, terminali açmak için "Görünüm" -> "Terminal"i tıklayın. Arayüzünüz aşağıdaki gibi görünmelidir.

Bu, ana arayüzümüz olacak. Üstte IDE, altta terminal yer alacak.

Çalışma dizininizi ayarlama

Çalışma dizininizi oluşturun. Bu codelab'de yazdığınız tüm kodlar burada bulunur:

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

Ardından, seeding komut dosyaları ve günlükler gibi öğeleri yönetmek için birkaç dizin hazırlayalım.

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

Google Cloud projenizi oluşturun

Konum değişkenlerini içeren .env dosyasını oluşturun:

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

Terminalinizde proje kurulumunu basitleştirmek için bu proje kurulum komut dosyasını çalışma dizininize indirin:

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

Komut dosyasını çalıştırın. Bu komut, deneme faturalandırma hesabınızı doğrular, yeni bir proje oluşturur (veya mevcut bir projeyi doğrular), proje kimliğinizi geçerli dizindeki bir .env dosyasına kaydeder ve gcloud'de etkin projeyi ayarlar.

bash setup_verify_trial_project.sh && source .env

Komut dosyası:

Etkin bir deneme faturalandırma hesabınız olduğunu doğrulayın.
.env içinde mevcut bir proje olup olmadığını kontrol edin (varsa)
Yeni bir proje oluşturun veya mevcut projeyi yeniden kullanın
Deneme faturalandırma hesabını projenize bağlama
Proje kimliğini .env dosyasına kaydedin.
Projeyi etkin gcloud projesi olarak ayarlayın

Cloud Shell terminal isteminde çalışma dizininizin yanındaki sarı metni kontrol ederek projenin doğru şekilde ayarlandığını doğrulayın. Proje kimliğiniz gösterilmelidir.

Gerekli API'yi Etkinleştirme

Ardından, etkileşimde bulunacağımız ürün için birkaç API'yi etkinleştirmemiz gerekir:

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): Aracınız Gemini modellerini kullanır ve Toolbox, vektör araması için yerleştirme API'sini kullanır.
Cloud SQL Admin API (sqladmin.googleapis.com): PostgreSQL örneği sağlarsınız ve yönetirsiniz.
Compute Engine API (compute.googleapis.com): Cloud SQL örnekleri oluşturmak için gereklidir.
Cloud Run, Cloud Build, Artifact Registry: Bu codelab'in ilerleyen bölümlerinde dağıtım adımında kullanılır.

3. Veritabanı başlatma için komut dosyaları hazırlama

Bu adımda Cloud SQL örneği oluşturma işlemi başlatılır ve örneğin hazır olmasını bekleyen, ardından veritabanını oluşturan, iş ilanlarıyla dolduran ve yerleştirmeler oluşturan otomatik bir kurulum komut dosyası çalıştırılır. Tüm bu işlemler tek bir işlemde gerçekleştirilir.

Öncelikle, veritabanı şifresini .env dosyanıza ekleyip yeniden yükleyelim:

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

Örnek ve veritabanı oluşturma için Bash komut dosyası oluşturma

Ardından, aşağıdaki komutla scripts/setup_database.sh komut dosyasını oluşturun.

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

Ardından, aşağıdaki kodu scripts/setup_database.sh dosyasına kopyalayın.

#!/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 ""

Veri başlangıcı için Python komut dosyası oluşturma

Ardından, aşağıdaki komutu kullanarak seeding_script.py adlı Python dosyasını scripts/setup_restaurant_db.py oluşturun.

cloudshell edit scripts/setup_restaurant_db.py

Ardından, aşağıdaki kodu scripts/setup_restaurant_db.py dosyasına kopyalayın.

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

Şimdi bir sonraki adıma geçelim.

4. Veritabanını Oluşturma ve Başlatma

Artık komut dosyalarımız yürütülmeye hazır. Hazırladığımız komut dosyasını yürütmek için Python'a ihtiyacımız olacak. Bu nedenle, önce Python'ı hazırlayalım.

Python projesini oluşturma

uv, Rust ile yazılmış hızlı bir Python paketi ve proje yöneticisidir ( uv belgeleri ). Bu codelab'de, Python projesinin bakımında hız ve basitlik sağlamak için kullanılır.

Bir Python projesi başlatın ve gerekli bağımlılıkları ekleyin:

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

Uygulama Varsayılan Kimlik Bilgileri kullanılarak kimliği doğrulanmış veritabanı örneğimizle güvenli bir bağlantı başlatmak için burada cloud-sql-python-connector Python SDK'sını kullandığımızı unutmayın.

Kurulum komut dosyasını yürütme

Artık kurulum komut dosyasını arka planda çalıştırabilir ve aşağıdaki komutu kullanarak logs/atabase_setup.log dosyasına yazılacak konsol çıkışını inceleyebiliriz. Bu işlemin tamamlanmasını beklerken sonraki bölüme geçebilirsiniz.

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

Araç kutusu ikilisini indirin

Bu eğitimde MCP Toolbox'ı kullanacağız. Neyse ki bu araç, Linux ortamında kullanıma hazır önceden oluşturulmuş bir ikili dosya ile birlikte gelir. Şimdi de arka planda indirelim. Bu işlem biraz zaman alabilir. İkili dosyayı indirmek ve çıkış günlüğünü logs/toolbox_dl.log üzerinde incelemek için aşağıdaki komutu çalıştırın . Bu işlemin tamamlanmasını beklerken sonraki bölüme geçebilirsiniz.

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 &

Kurulum komut dosyasını anlama `scripts/setup_database.sh`

Şimdi de daha önce yapılandırdığımız kurulum komut dosyasını anlamaya çalışalım. Aşağıdaki işlemi yapar:

Burada yürüttüğümüz ilk komut, aşağıdaki işaretle birlikte gcloud sql instances create komutudur.

db-custom-1-3840, ENTERPRISE sürümündeki en küçük ayrılmış çekirdekli Cloud SQL katmanıdır (1 vCPU, 3,75 GB RAM). Daha fazla bilgiyi burada bulabilirsiniz. Vertex AI ML entegrasyonu için özel bir çekirdek gerekir. Paylaşılan çekirdek katmanları (db-f1-micro, db-g1-small) bu entegrasyonu desteklemez.
--root-password, varsayılan postgres kullanıcısının şifresini ayarlar.
--enable-google-ml-integration, Cloud SQL'in Vertex AI ile yerleşik entegrasyonunu etkinleştirir. Bu entegrasyon, embedding() işlevini kullanarak doğrudan SQL'den yerleştirme modellerini çağırmanıza olanak tanır.

Örneğin RUNNABLE durumunda olup olmadığını doğrulayın.
gcloud projects add-iam-policy-binding komutunu kullanarak Cloud SQL örneğinin hizmet hesabına Vertex AI'ı çağırma izni verin. Bu, veritabanını doldururken kullanacağımız yerleşik embedding() işlevi için gereklidir.
Veritabanını oluşturma
İlk veri komut dosyası setup_restaurant_db.py komut dosyasını yürütme

Başlangıç komut dosyasını anlama `scripts/setup_restaurant_db.py`

Şimdi de başlangıç komut dosyasına geçelim. Bu komut dosyası aşağıdaki işlemleri yapar:

Veritabanı örneğiyle bağlantıyı başlatma
İki PostgreSQL uzantısı yükler:

google_ml_integration: Vertex AI yerleştirme modellerini doğrudan SQL'den çağıran embedding() SQL işlevini sağlar. Bu, restaurant_db içinde makine öğrenimi işlevlerini kullanılabilir hale getiren bir veritabanı düzeyinde uzantıdır. Örnek oluşturma sırasında ayarladığınız örnek düzeyindeki işaret (--enable-google-ml-integration), Cloud SQL VM'nin Vertex AI'ye ulaşmasına olanak tanır. Uzantı, SQL işlevlerini bu belirli veritabanında kullanılabilir hale getirir.
vector (pgvector): Yerleştirmeleri depolamak ve sorgulamak için vector veri türünü ve mesafe operatörlerini ekler.

Tabloyu oluşturun. description_embedding sütununun vector(3072) olduğunu unutmayın. Bu, 3072 boyutlu vektörleri depolayan bir pgvector sütunudur.
İlk menü öğeleri verilerini doldurma
description alanından yerleştirme verilerini oluşturun ve embedding() işlevi aracılığıyla yerleşik Vertex entegrasyonunu kullanarak description_embedding alanını doldurun.

embedding('gemini-embedding-001', description): Her işin description metnini ileterek doğrudan SQL'den Vertex AI'ın Gemini yerleştirme modelini çağırır. Bu, başlangıç komut dosyasında yüklediğiniz google_ml_integration uzantısıdır.
::vector: Döndürülen kayan nokta dizisini, pgvector'ın vector türüne yayınlar. Böylece, mesafe operatörleriyle depolanabilir ve sorgulanabilir.
UPDATE, 15 satırın tamamında çalışarak her iş açıklaması için 3072 boyutlu bir yerleştirme oluşturur.

Bu işlem, ajanımız tarafından erişilecek ilk verileri hazırlar.

5. Veritabanları için MCP Araç Kutusu'nu yapılandırma

Bu adımda, MCP Toolbox for Databases tanıtılır, Cloud SQL örneğinize bağlanmak için yapılandırılır ve iki standart SQL sorgu aracı tanımlanır.

ÇMY nedir ve neden Araç Kutusu'nu kullanmalısınız?

MCP (Model Context Protocol), yapay zeka ajanlarının harici araçları keşfetme ve bunlarla etkileşime girme şeklini standartlaştıran açık bir protokoldür. Bu modelde bir istemci-sunucu modeli tanımlanır: Ajan, bir MCP istemcisine ev sahipliği yapar ve araçlar MCP sunucuları tarafından kullanıma sunulur. MCP ile uyumlu tüm istemciler, MCP ile uyumlu tüm sunucuları kullanabilir. Aracının her araç için özel entegrasyon koduna ihtiyacı yoktur.

Veritabanları için MCP Araç Kutusu, özellikle veritabanı erişimi için oluşturulmuş açık kaynaklı bir MCP sunucusudur. Bu olmadan, veritabanı bağlantılarını açan, bağlantı havuzlarını yöneten, SQL eklemeyi önlemek için parametreli sorgular oluşturan, hataları işleyen ve tüm bu kodu aracınıza yerleştiren Python işlevleri yazmanız gerekir. Veritabanı erişimi gereken her temsilci bu çalışmayı tekrarlar. Bir sorguyu değiştirmek, temsilcinin yeniden dağıtılması anlamına gelir.

Toolbox ile bir YAML dosyası yazarsınız. Her araç, parametrelendirilmiş bir SQL ifadesiyle eşlenir. Toolbox, bağlantı havuzunu, parametrelendirilmiş sorguları, kimlik doğrulamayı ve gözlemlenebilirliği yönetir. Araçlar, aracıdan ayrılmıştır. Sorguyu, aracı koduna dokunmadan tools.yaml dosyasını düzenleyip Toolbox'ı yeniden başlatarak güncelleyebilirsiniz. Aynı araçlar ADK, LangGraph, LlamaIndex veya MCP ile uyumlu herhangi bir çerçevede çalışır.

Araç yapılandırmasını yazma

Şimdi araç yapılandırmamızı ayarlamak için Cloud Shell Düzenleyici'de tools.yaml adlı bir dosya oluşturmamız gerekiyor.

cloudshell edit tools.yaml

Dosyada çok dokümanlı YAML kullanılır. --- ile ayrılan her blok bağımsız bir kaynaktır. Her kaynağın, ne olduğunu bildiren bir kind (veritabanı bağlantıları için sources, aracı tarafından çağrılabilir işlemler için tools) ve arka ucu belirten bir type (kaynak için cloud-sql-postgres, SQL tabanlı araçlar için postgres-sql) vardır. Bir araç, kaynağına name ile referans verir. Bu, Araç Kutusu'nun hangi bağlantı havuzuna karşı yürütüleceğini bilmesini sağlar. Ortam değişkenleri ${VAR_NAME} söz dizimini kullanır ve başlatma sırasında çözümlenir.

Şimdi aşağıdaki komut dosyalarını önce tools.yaml dosyasına kopyalayalım.

# 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}

---