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

Datenbank als Tool: Agentic RAG mit ADK, MCP Toolbox und Cloud SQL

1. Einführung

KI-Agents sind nur so nützlich wie die Daten, auf die sie zugreifen können. Die meisten realen Daten befinden sich in Datenbanken. Wenn Sie Agents mit Datenbanken verbinden möchten, müssen Sie in der Regel das Verbindungsmanagement, die Abfragelogik und die Einbettungspipelines in den Agent-Code schreiben. Bei jedem Agent, der Datenbankzugriff benötigt, wird diese Arbeit wiederholt. Bei jeder Abfrageänderung muss der Agent neu bereitgestellt werden.

In diesem Codelab wird ein anderer Ansatz vorgestellt. Sie deklarieren Ihre Datenbanktools in einer YAML-Datei – Standard-SQL-Abfragen, Vektorähnlichkeitssuche und sogar die automatische Einbettungsgenerierung – und die MCP Toolbox for Databases übernimmt alle Datenbankvorgänge als MCP-Server. Ihr Agent-Code bleibt minimal: Laden Sie die Tools und lassen Sie Gemini entscheiden, welches aufgerufen werden soll.

Umfang

Ein Restaurant Concierge für „Foodie Finds“ – ein ADK-Agent, der auf Gemini basiert und Gästen hilft, die Speisekarte eines Restaurants mit Standardfiltern (Kategorie, Art der Küche) zu durchsuchen und Gerichte anhand von Beschreibungen in natürlicher Sprache wie „Ich möchte etwas Scharfes und Vegetarisches“ zu finden. Der Agent liest aus einer Cloud SQL PostgreSQL-Datenbank und schreibt in diese, und zwar ausschließlich über die MCP Toolbox for Databases, die den gesamten Datenbankzugriff übernimmt, einschließlich der automatischen Einbettungsgenerierung für die Vektorsuche. Am Ende werden sowohl die Toolbox als auch der Agent in Cloud Run ausgeführt.

Lerninhalte

Wie das MCP (Model Context Protocol) den Toolzugriff für KI-Agents standardisiert und wie die MCP Toolbox for Databases dies auf Datenbankvorgänge anwendet
MCP Toolbox for Databases als Middleware zwischen einem ADK-Agenten und Cloud SQL for PostgreSQL einrichten
Datenbanktools deklarativ in tools.yaml definieren – kein Datenbankcode in Ihrem Agent
Einen ADK-Agenten erstellen, der Tools von einem laufenden Toolbox-Server mit ToolboxToolset lädt
Vektoreinbettungen mit der integrierten embedding()-Funktion von Cloud SQL generieren und semantische Suche mit pgvector aktivieren
valueFromParam-Funktion für die automatische Vektoreingabe bei Schreibvorgängen verwenden
Toolbox-Server und ADK-Agent in Cloud Run bereitstellen

Voraussetzungen

Ein Google Cloud-Konto mit einem Testabrechnungskonto
Grundkenntnisse in Python und SQL
Vorkenntnisse mit Cloud Database und ADK sind hilfreich.

2. Umgebung einrichten

In diesem Schritt wird Ihre Cloud Shell-Umgebung vorbereitet, Ihr Google Cloud-Projekt konfiguriert und das Referenz-Repository geklont.

Cloud Shell öffnen

Öffnen Sie Cloud Shell in Ihrem Browser. Cloud Shell bietet eine vorkonfigurierte Umgebung mit allen Tools, die Sie für dieses Codelab benötigen. Klicken Sie auf Autorisieren, wenn Sie dazu aufgefordert werden.

Klicken Sie dann auf Ansicht -> Terminal, um das Terminal zu öffnen.Die Benutzeroberfläche sollte so aussehen:

Das ist unsere Hauptoberfläche: oben die IDE, unten das Terminal.

Arbeitsverzeichnis einrichten

Erstellen Sie Ihr Arbeitsverzeichnis. Der gesamte Code, den Sie in diesem Codelab schreiben, befindet sich hier:

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

Danach bereiten wir mehrere Verzeichnisse vor, um Dinge wie Seeding-Skripts und Logs zu verwalten.

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

Google Cloud-Projekt einrichten

Erstellen Sie die Datei .env mit den Standortvariablen:

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

Um die Einrichtung des Projekts in Ihrem Terminal zu vereinfachen, laden Sie dieses Setupscript in Ihr Arbeitsverzeichnis herunter:

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

Führen Sie das Skript aus. Dabei wird Ihr Probeabo-Rechnungskonto überprüft, ein neues Projekt erstellt (oder ein vorhandenes Projekt validiert), Ihre Projekt-ID in einer .env-Datei im aktuellen Verzeichnis gespeichert und das aktive Projekt in gcloud festgelegt.

bash setup_verify_trial_project.sh && source .env

Das Skript führt Folgendes aus:

Prüfen, ob Sie ein aktives Testabrechnungskonto haben
Prüfen Sie, ob in .env ein Projekt vorhanden ist.
Neues Projekt erstellen oder vorhandenes Projekt wiederverwenden
Test-Rechnungskonto mit Ihrem Projekt verknüpfen
Speichern Sie die Projekt-ID in .env.
Projekt als aktives gcloud-Projekt festlegen

Prüfen Sie, ob das Projekt richtig festgelegt ist. Sehen Sie dazu im Cloud Shell-Terminal-Prompt nach dem gelben Text neben Ihrem Arbeitsverzeichnis. Dort sollte Ihre Projekt-ID angezeigt werden.

Erforderliche API aktivieren

Als Nächstes müssen wir mehrere APIs für das Produkt aktivieren, mit dem wir interagieren werden:

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): Ihr Agent verwendet Gemini-Modelle und Toolbox verwendet die Embedding API für die Vektorsuche.
Cloud SQL Admin API (sqladmin.googleapis.com): Sie stellen eine PostgreSQL-Instanz bereit und verwalten sie.
Compute Engine API (compute.googleapis.com): Erforderlich zum Erstellen von Cloud SQL-Instanzen.
Cloud Run, Cloud Build, Artifact Registry: werden im Bereitstellungsschritt weiter unten in diesem Codelab verwendet.

3. Skripts für die Datenbankinitialisierung vorbereiten

In diesem Schritt wird die Cloud SQL-Instanz erstellt und ein automatisiertes Setupscript ausgeführt, das wartet, bis die Instanz bereit ist. Anschließend wird die Datenbank erstellt, mit Stellenangeboten gefüllt und es werden Einbettungen generiert – alles in einem Vorgang.

Fügen Sie zuerst das Datenbankpasswort in die Datei .env ein und laden Sie sie neu:

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

Bash-Skript zum Erstellen von Instanzen und Datenbanken erstellen

Erstellen Sie dann das scripts/setup_database.sh-Skript mit dem folgenden Befehl:

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

Kopieren Sie dann den folgenden Code in die Datei 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-Script für Data Seed erstellen

Erstellen Sie dann mit dem folgenden Befehl die Python-Datei scripts/setup_restaurant_db.py für das Seeding-Skript.

cloudshell edit scripts/setup_restaurant_db.py

Kopieren Sie dann den folgenden Code in die Datei 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()

Kommen wir nun zum nächsten Schritt.

4. Datenbank erstellen und initialisieren

Jetzt können wir unsere Skripts ausführen. Dazu benötigen wir Python.

Python-Projekt einrichten

uv ist ein schneller Python-Paket- und Projektmanager, der in Rust geschrieben wurde ( uv-Dokumentation). In diesem Codelab wird er verwendet, um das Python-Projekt schnell und einfach zu verwalten.

Initialisieren Sie ein Python-Projekt und fügen Sie die erforderlichen Abhängigkeiten hinzu:

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

Wir verwenden hier das cloud-sql-python-connector Python SDK, um eine sichere Verbindung mit unserer Datenbankinstanz zu initialisieren, die mit Standardanmeldedaten für Anwendungen authentifiziert wird.

Setup-Skript ausführen

Jetzt können wir das Einrichtungs-Script im Hintergrund ausführen und die Konsolenausgabe, die in die Datei logs/atabase_setup.log geschrieben wird, mit dem folgenden Befehl prüfen. Sie können mit dem nächsten Abschnitt fortfahren, während Sie darauf warten, dass dieser Vorgang abgeschlossen wird.

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

Toolbox-Binärdatei herunterladen

In dieser Anleitung verwenden wir die MCP Toolbox. Glücklicherweise ist sie mit einem vorgefertigten Binärprogramm ausgestattet, das in der Linux-Umgebung verwendet werden kann. Laden wir es jetzt im Hintergrund herunter, da es eine Weile dauert. Führen Sie den folgenden Befehl aus, um das Binärprogramm herunterzuladen, und sehen Sie sich das Ausgabeprotokoll auf der logs/toolbox_dl.log an. Sie können mit dem nächsten Abschnitt fortfahren, während der Download läuft.

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 &

Das Setup-Skript `scripts/setup_database.sh`

Sehen wir uns nun das Setupskript an, das wir zuvor konfiguriert haben. Es führt die folgenden Schritte aus:

Der erste Befehl, den wir dort ausführen, ist der Befehl gcloud sql instances create mit dem folgenden Flag:

db-custom-1-3840 ist die kleinste Cloud SQL-Stufe mit dedizierten Kernen (1 vCPU, 3,75 GB RAM) in der ENTERPRISE-Version. Weitere Informationen Für die Vertex AI ML-Integration ist ein dedizierter Core erforderlich. Tarife mit gemeinsam genutztem Kern (db-f1-micro, db-g1-small) werden nicht unterstützt.
Mit --root-password wird das Passwort für den Standardnutzer postgres festgelegt.
--enable-google-ml-integration ermöglicht die integrierte Einbindung von Cloud SQL in Vertex AI. So können Sie Einbettungsmodelle mit der Funktion embedding() direkt über SQL aufrufen.

Prüfen Sie, ob die Instanz bereits den Status RUNNABLE hat.
Gewähren Sie dem Dienstkonto der Cloud SQL-Instanz die Berechtigung, Vertex AI mit dem Befehl gcloud projects add-iam-policy-binding aufzurufen. Dies ist für die integrierte embedding()-Funktion erforderlich, die wir beim Seeding der Datenbank verwenden.
Datenbank erstellen
Das Seeding-Skript setup_restaurant_db.py ausführen

Grundlegendes zum Seed-Skript `scripts/setup_restaurant_db.py`

Das Seeding-Script führt folgende Aktionen aus:

Verbindung zur Datenbankinstanz initialisieren
Installiert zwei PostgreSQL-Erweiterungen:

google_ml_integration: Stellt die SQL-Funktion embedding() bereit, mit der Vertex AI-Embedding-Modelle direkt über SQL aufgerufen werden können. Dies ist eine Erweiterung auf Datenbankebene, die ML-Funktionen in restaurant_db verfügbar macht. Das Flag auf Instanzebene (--enable-google-ml-integration), das Sie beim Erstellen der Instanz festlegen, ermöglicht es der Cloud SQL-VM, Vertex AI zu erreichen. Die Erweiterung macht die SQL-Funktionen in dieser bestimmten Datenbank verfügbar.
vector (pgvector): Fügt den Datentyp vector und Distanzoperatoren zum Speichern und Abfragen von Einbettungen hinzu.

Erstellen Sie die Tabelle. Beachten Sie, dass die Spalte description_embedding vector(3072) ist – eine pgvector-Spalte, in der 3.072-dimensionale Vektoren gespeichert werden.
Erste Menüpunkte übertragen
Generieren Sie die Einbettungsdaten aus dem Feld description und füllen Sie das Feld description_embedding mithilfe der integrierten Vertex-Integration über die Funktion embedding() aus.

embedding('gemini-embedding-001', description) – ruft das Gemini-Einbettungsmodell von Vertex AI direkt über SQL auf und übergibt den description-Text jedes Jobs. Das ist die google_ml_integration-Erweiterung, die Sie im Seed-Script installiert haben.
::vector: Wandelt das zurückgegebene Float-Array in den Typ vector von pgvector um, damit es mit Distanzoperatoren gespeichert und abgefragt werden kann.
Die UPDATE wird für alle 15 Zeilen ausgeführt und generiert ein 3.072-dimensionales Embedding pro Stellenbeschreibung.

Dadurch werden die ersten Daten vorbereitet, auf die unser Agent zugreifen kann.

5. MCP Toolbox for Databases konfigurieren

In diesem Schritt wird die MCP Toolbox für Datenbanken eingeführt, so konfiguriert, dass sie eine Verbindung zu Ihrer Cloud SQL-Instanz herstellt, und es werden zwei Standard-SQL-Abfragetools definiert.

Was ist MCP und warum sollte ich die Toolbox verwenden?

MCP (Model Context Protocol) ist ein offenes Protokoll, das die Art und Weise standardisiert, wie KI-Agenten externe Tools erkennen und mit ihnen interagieren. Es wird ein Client-Server-Modell definiert: Der Agent hostet einen MCP-Client und Tools werden von MCP-Servern bereitgestellt. Jeder MCP-kompatible Client kann jeden MCP-kompatiblen Server verwenden. Der Agent benötigt also keinen benutzerdefinierten Integrationscode für jedes Tool.

Die MCP Toolbox for Databases ist ein Open-Source-MCP-Server, der speziell für den Datenbankzugriff entwickelt wurde. Andernfalls müssten Sie Python-Funktionen schreiben, die Datenbankverbindungen öffnen, Verbindungspools verwalten, parametrisierte Abfragen erstellen, um SQL-Injection zu verhindern, Fehler verarbeiten und den gesamten Code in Ihren Agent einbetten. Jeder Agent, der Datenbankzugriff benötigt, wiederholt diese Schritte. Wenn Sie eine Abfrage ändern, müssen Sie den Agenten neu bereitstellen.

Mit Toolbox schreiben Sie eine YAML-Datei. Jedes Tool wird einer parametrisierten SQL-Anweisung zugeordnet. Die Toolbox übernimmt das Verbindungs-Pooling, parametrisierte Abfragen, die Authentifizierung und die Beobachtbarkeit. Tools sind vom Agent entkoppelt – aktualisieren Sie eine Anfrage, indem Sie tools.yaml bearbeiten und die Toolbox neu starten, ohne den Agentencode zu ändern. Die gleichen Tools funktionieren mit dem ADK, LangGraph, LlamaIndex oder einem anderen MCP-kompatiblen Framework.

Tool-Konfiguration schreiben

Jetzt müssen wir im Cloud Shell-Editor eine Datei mit dem Namen tools.yaml erstellen, um die Konfiguration unserer Tools einzurichten.

cloudshell edit tools.yaml

In der Datei wird YAML mit mehreren Dokumenten verwendet. Jeder Block, der durch --- getrennt ist, ist eine eigenständige Ressource. Jede Ressource hat ein kind, das angibt, was sie ist (sources für Datenbankverbindungen, tools für von Agenten aufrufbare Aktionen), und ein type, das das Backend angibt (cloud-sql-postgres für die Quelle, postgres-sql für SQL-basierte Tools). Ein Tool verweist mit name auf seine Quelle. So weiß Toolbox, welcher Verbindungspool verwendet werden soll. Umgebungsvariablen verwenden die ${VAR_NAME}-Syntax und werden beim Start aufgelöst.

Kopieren wir nun die folgenden Skripts zuerst in die Datei 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}

---