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

1. Einführung

KI-Agenten sind nur so nützlich wie die Daten, auf die sie zugreifen können. Die meisten Daten aus der realen Welt befinden sich in Datenbanken. Wenn Sie Agenten mit Datenbanken verbinden, müssen Sie in der Regel das Verbindungsmanagement, die Abfragelogik und die Einbettungspipelines in Ihren Agentencode schreiben. Jeder KI-Agent, der Datenbankzugriff benötigt, muss diese Arbeit wiederholen. Jede Abfrageänderung erfordert eine erneute Bereitstellung des KI-Agenten.

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 Smart Job Board Assistant für „TechJobs“ – ein ADK-Agent, der auf Gemini basiert und Entwicklern hilft, Stellenangebote für technische Berufe mithilfe von Standardfiltern (Rolle, Tech-Stack) zu durchsuchen und Stellen anhand von Beschreibungen in natürlicher Sprache wie „Ich suche einen Remote-Job, bei dem ich an KI-Chatbots arbeiten kann“ zu finden. Der Agent liest Daten aus einer Cloud SQL for PostgreSQL-Datenbank und schreibt Daten in diese Datenbank. Dies geschieht 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 der MCP-Standard (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 Vektorerfassung 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 Hauptschnittstelle. Die IDE befindet sich oben und das Terminal unten.

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 Skript zur Einrichtung des Projekts 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 eingestellt 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 Einrichtungsskript 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=techjobs-pwd" >> .env
echo "DB_INSTANCE=jobs-instance" >> .env
echo "DB_NAME=jobs_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_jobs_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_jobs_db.py für das Seeding-Skript.

cloudshell edit scripts/setup_jobs_db.py

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

# Job listings data (fictional, for tutorial purposes only)
JOBS = [
    ("Senior Backend Engineer", "Stripe", "Backend", "Go, PostgreSQL, gRPC, Kubernetes", "$180-250K/year", "San Francisco, Hybrid", 3,
     "Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls."),
    ("Machine Learning Engineer", "Spotify", "Data/AI", "Python, TensorFlow, BigQuery, Vertex AI", "$170-230K/year", "Stockholm, Remote", 2,
     "Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second."),
    ("Frontend Engineer", "Vercel", "Frontend", "React, TypeScript, Next.js", "$140-190K/year", "Remote", 4,
     "Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience."),
    ("DevOps Engineer", "Datadog", "DevOps", "Terraform, GCP, Docker, Kubernetes, ArgoCD", "$160-220K/year", "New York, Hybrid", 2,
     "Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments."),
    ("Mobile Engineer (Android)", "Grab", "Mobile", "Kotlin, Jetpack Compose, GraphQL", "$120-170K/year", "Singapore, Hybrid", 3,
     "Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions."),
    ("Data Engineer", "Airbnb", "Data", "Python, Apache Spark, Airflow, BigQuery", "$160-210K/year", "San Francisco, Hybrid", 2,
     "Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams."),
    ("Full Stack Engineer", "Revolut", "Full Stack", "TypeScript, Node.js, React, PostgreSQL", "$130-180K/year", "London, Remote", 5,
     "Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions."),
    ("Site Reliability Engineer", "Cloudflare", "SRE", "Go, Prometheus, Grafana, GCP, Terraform", "$170-230K/year", "Austin, Hybrid", 2,
     "Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide."),
    ("Cloud Architect", "Google Cloud", "Cloud", "GCP, Terraform, Kubernetes, Python", "$200-280K/year", "Seattle, Hybrid", 1,
     "Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit."),
    ("Backend Engineer (Payments)", "Square", "Backend", "Java, Spring Boot, PostgreSQL, Kafka", "$160-220K/year", "San Francisco, Hybrid", 3,
     "Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services."),
    ("AI Engineer", "Hugging Face", "Data/AI", "Python, LangChain, Vertex AI, FastAPI, PostgreSQL", "$150-210K/year", "Paris, Remote", 2,
     "Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure."),
    ("Platform Engineer", "Coinbase", "Platform", "Rust, Kubernetes, AWS, Terraform", "$180-250K/year", "Remote", 0,
     "Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime."),
    ("QA Automation Engineer", "Shopify", "QA", "Python, Selenium, Cypress, Jenkins", "$110-160K/year", "Toronto, Hybrid", 3,
     "Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows."),
    ("Security Engineer", "CrowdStrike", "Security", "Python, SIEM, Kubernetes, Penetration Testing", "$170-240K/year", "Austin, On-site", 1,
     "Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events."),
    ("Product Engineer", "GitLab", "Full Stack", "Go, React, PostgreSQL, Redis, GCP", "$140-200K/year", "Remote", 4,
     "Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development."),
]


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 jobs 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 jobs (
            id SERIAL PRIMARY KEY,
            title VARCHAR NOT NULL,
            company VARCHAR NOT NULL,
            role VARCHAR NOT NULL,
            tech_stack VARCHAR NOT NULL,
            salary_range VARCHAR NOT NULL,
            location VARCHAR NOT NULL,
            openings INTEGER NOT NULL,
            description TEXT NOT NULL,
            description_embedding vector(3072)
        )
    """)


def seed_jobs(cursor, conn):
    """Insert job listings."""
    cursor.execute("SELECT COUNT(*) FROM jobs")
    existing_count = cursor.fetchone()[0]

    if existing_count > 0:
        print(f"      {existing_count} jobs already exist, skipping seed")
        return 0

    cursor.executemany("""
        INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description)
        VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
    """, JOBS)
    conn.commit()
    return len(JOBS)


def generate_embeddings(cursor, conn):
    """Generate embeddings using Cloud SQL's embedding() function."""
    cursor.execute("SELECT COUNT(*) FROM jobs WHERE description_embedding IS NULL")
    null_count = cursor.fetchone()[0]

    if null_count == 0:
        print("      All jobs already have embeddings")
        return 0

    cursor.execute(f"""
        UPDATE jobs
        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_jobs(cursor, conn)
        if seeded > 0:
            print(f"      ✓ Inserted {seeded} jobs")

        # 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 unsere Skripts ausgeführt werden. Wir benötigen Python, um unser vorbereitetes Skript auszuführen. Bereiten wir es also zuerst vor.

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 eine vorkompilierte Binärdatei enthalten, die 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 die Binärdatei herunterzuladen und das Ausgabeprotokoll auf dem logs/toolbox_dl.log zu prüfen . Sie können mit dem nächsten Abschnitt fortfahren, während Sie darauf warten, dass dieser Vorgang abgeschlossen wird.

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/v1.0.0/linux/amd64/toolbox > logs/toolbox_dl.log 2>&1 &

Das Einrichtungsskript `scripts/setup_database.sh`

Sehen wir uns nun das Setup-Skript an, das wir zuvor konfiguriert haben. Dabei wird folgender Prozess durchlaufen:

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. Shared-Core-Tarife (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 aktiviert 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_jobs_db.py ausführen

Grundlegendes zum Seed-Skript `scripts/setup_jobs_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-Einbettungsmodelle direkt über SQL aufgerufen werden. Dies ist eine Erweiterung auf Datenbankebene, die ML-Funktionen in jobs_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 Jobdaten übertragen
Generieren Sie die Einbettungsdaten aus dem Feld description und füllen Sie 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 vector-Typ 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 erste Daten vorbereitet, auf die unser Agent zugreifen kann.

5. MCP-Toolbox für Datenbanken konfigurieren

In diesem Schritt wird die MCP Toolbox for Databases eingeführt, für die Verbindung zu Ihrer Cloud SQL-Instanz konfiguriert und zwei Standard-SQL-Abfragetools definiert.

Was ist das MCP und warum sollte ich die Toolbox verwenden?

MCP (Model Context Protocol) ist ein offenes Protokoll, das standardisiert, wie KI-Agents 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 für Datenbanken 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 – Sie können eine Anfrage aktualisieren, indem Sie tools.yaml bearbeiten und die Toolbox neu starten, ohne den Agent-Code zu ändern. Die gleichen Tools funktionieren mit dem ADK, LangGraph, LlamaIndex oder einem anderen MCP-kompatiblen Framework.

Toolkonfiguration schreiben

Als Nächstes 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

Die Datei verwendet YAML mit mehreren Dokumenten. Jeder Block, der durch --- getrennt ist, ist eine eigenständige Ressource. Jede Ressource hat einen kind, der angibt, was sie ist (sources für Datenbankverbindungen, tools für von Agenten aufrufbare Aktionen) und einen type, der 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: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: ${DB_INSTANCE}
database: ${DB_NAME}
user: postgres
password: ${DB_PASSWORD}

---