1. Einführung
Dieses Codelab bietet eine Anleitung für den Einstieg in den Google Cloud MCP-Server für AlloyDB. Außerdem wird beschrieben, wie Sie ihn als Teil des Toolsets für einen KI-Agenten aktivieren und als Teil einer Anwendung verwenden.
Voraussetzungen
- Grundkenntnisse in Google Cloud und der Google Cloud Console
- Grundkenntnisse in der Befehlszeile und Cloud Shell
Lerninhalte
- AlloyDB-Cluster erstellen und Beispieldaten importieren
- AlloyDB Data Access API aktivieren
- Google Cloud MCP für AlloyDB NL aktivieren
- Google Cloud MCP für AlloyDB zu Ihrem ADK-Agenten hinzufügen
- Google Cloud MCP für AlloyDB in einer Anwendung verwenden
- Agents mit AlloyDBMCP für Analysen verwenden
Voraussetzungen
- Ein Google Cloud-Konto und ein Google Cloud-Projekt
- Ein Webbrowser wie Chrome, der die Google Cloud Console und die Cloud Shell unterstützt
2. Einrichtung und Anforderungen
Projekteinrichtung
- Melden Sie sich in der Google Cloud Console an. Wenn Sie noch kein Gmail- oder Google Workspace-Konto haben, müssen Sie eines erstellen.
Verwenden Sie stattdessen ein privates Konto.
- Erstellen Sie ein neues Projekt oder verwenden Sie ein vorhandenes. Klicken Sie zum Erstellen eines neuen Projekts in der Google Cloud Console in der Kopfzeile auf die Schaltfläche „Projekt auswählen“, um ein Pop-up-Fenster zu öffnen.
Klicken Sie im Fenster „Projekt auswählen“ auf die Schaltfläche „Neues Projekt“, um ein Dialogfeld für das neue Projekt zu öffnen.
Geben Sie im Dialogfeld den gewünschten Projektnamen ein und wählen Sie den Speicherort aus.
- Der Projektname ist der Anzeigename für die Teilnehmer dieses Projekts. Der Projektname wird von Google APIs nicht verwendet und kann jederzeit geändert werden.
- Die Projekt-ID ist für alle Google Cloud-Projekte eindeutig und unveränderlich. Sie kann also nicht mehr geändert werden, nachdem sie festgelegt wurde. In der Google Cloud Console wird automatisch eine eindeutige ID generiert, die Sie aber anpassen können. Wenn Ihnen die generierte ID nicht gefällt, können Sie eine andere zufällige ID generieren oder eine eigene ID angeben, um die Verfügbarkeit zu prüfen. In den meisten Codelabs müssen Sie auf Ihre Projekt-ID verweisen, die in der Regel mit dem Platzhalter PROJECT_ID angegeben wird.
- Zur Information: Es gibt einen dritten Wert, die Projektnummer, die von einigen APIs verwendet wird. Weitere Informationen zu diesen drei Werten
Abrechnung aktivieren
Privates Rechnungskonto einrichten
Wenn Sie die Abrechnung mit Google Cloud-Guthaben einrichten, können Sie diesen Schritt überspringen.
Hier können Sie die Abrechnung in der Cloud Console aktivieren, um ein privates Rechnungskonto einzurichten.
Hinweise:
- Die Kosten für Cloud-Ressourcen für dieses Lab sollten weniger als 3 $ betragen.
- Sie können die Schritte am Ende dieses Labs ausführen, um Ressourcen zu löschen und so weitere Kosten zu vermeiden.
- Neue Nutzer haben Anspruch auf den kostenlosen Testzeitraum mit einem Guthaben von 300 $.
Cloud Shell starten
Während Sie Google Cloud von Ihrem Laptop aus per Fernzugriff nutzen können, wird in diesem Codelab Google Cloud Shell verwendet, eine Befehlszeilenumgebung, die in der Cloud ausgeführt wird.
Klicken Sie in der Google Cloud Console rechts oben in der Symbolleiste auf das Cloud Shell-Symbol:
Alternativ können Sie auch die Tasten G und dann S drücken. Dadurch wird Cloud Shell aktiviert, wenn Sie sich in der Google Cloud Console befinden oder diesen Link verwenden.
Die Bereitstellung und Verbindung mit der Umgebung sollte nur wenige Augenblicke dauern. Anschließend sehen Sie in etwa Folgendes:
Diese virtuelle Maschine verfügt über sämtliche Entwicklertools, die Sie benötigen. Sie bietet ein Basisverzeichnis mit 5 GB nichtflüchtigem Speicher und läuft in Google Cloud, was die Netzwerkleistung und Authentifizierung erheblich verbessert. Sie können alle Aufgaben in diesem Codelab in einem Browser erledigen. Sie müssen nichts installieren.
3. Hinweis
API aktivieren
Wenn Sie AlloyDB, Compute Engine, Netzwerkdienste und Vertex AI verwenden möchten, müssen Sie die entsprechenden APIs in Ihrem Google Cloud-Projekt aktivieren.
Prüfen Sie im Cloud Shell-Terminal, ob Ihre Projekt-ID eingerichtet ist:
gcloud config get-value project
Ihre Google-Projekt-ID sollte zurückgegeben werden.
Legen Sie die Umgebungsvariable PROJECT_ID fest:
PROJECT_ID=$(gcloud config get-value project)
Aktivieren Sie alle erforderlichen Dienste:
gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Erwartete Ausgabe
student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
aiplatform.googleapis.com \
discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.
4. AlloyDB bereitstellen
AlloyDB-Cluster und primäre Instanz erstellen Sie können die Lösung entweder mit einem vorbereiteten Skript bereitstellen, mit dem alle erforderlichen Ressourcen bereitgestellt werden, oder sie Schritt für Schritt selbst bereitstellen. Eine Anleitung dazu finden Sie in der Dokumentation.
AlloyDB mit automatisiertem Script bereitstellen
Bei diesem Ansatz wird ein automatisiertes Script verwendet, um den AlloyDB-Cluster bereitzustellen und die erforderlichen Informationen für die Arbeit mit den bereitgestellten Ressourcen bereitzustellen.
Führen Sie im Cloud Shell-Terminal den Befehl aus, um das Bereitstellungsscript aus dem Repository zu klonen.
REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"
git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL
cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR
Führen Sie das Bereitstellungsskript aus.
./deploy_alloydb.sh
Die Ausführung des Skripts dauert einige Zeit, in der Regel etwa 5 bis 7 Minuten. Die Ausgabe sollte dann Informationen zu Ihrem bereitgestellten AlloyDB-Cluster enthalten. Bitte beachten Sie, dass Ihr Passwort anders sein wird. Notieren Sie es sich für die spätere Verwendung.
... <redacted> ... Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster) Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715 Creating instance...done. ---------------------------------------- Deployment Process Completed Cluster: alloydb-aip-01 (TRIAL) Instance: alloydb-aip-01-pr Region: us-central1 Initial Password: JBBoDTgixzYwYpkF (if new cluster) ----------------------------------------
Den neuen Cluster und die primäre Instanz können Sie auch in der Webkonsole sehen.
5. Datenbank vorbereiten
Sie müssen die Vertex AI-Integration aktivieren, um KI-Funktionen und ‑Operatoren zu verwenden, die Data Access API aktivieren und eine Datenbank für das Beispieldataset erstellen.
Erforderliche Berechtigungen für AlloyDB erteilen
Fügen Sie dem AlloyDB-Dienst-Agent Vertex AI-Berechtigungen hinzu.
Öffnen Sie oben über das Pluszeichen (+) einen weiteren Cloud Shell-Tab.
Führen Sie im neuen Cloud Shell-Tab Folgendes aus:
PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/discoveryengine.viewer"
Erwartete Konsolenausgabe:
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project) Your active configuration is: [cloudshell-11039] student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \ --role="roles/aiplatform.user" Updated IAM policy for project [test-project-001-402417]. bindings: - members: - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com role: roles/aiplatform.user - members: ... < redacted > etag: BwYIEbe_Z3U= version: 1
Data Access API aktivieren
Sie müssen die Data Access API für den AlloyDB-Cluster aktivieren, um MCP-Tools wie execute_sql verwenden zu können.
Führen Sie den Befehl im selben Terminaltab aus.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED",
}'
Instanz-Flags aktualisieren
Damit wir erweiterte KI-Funktionen in AlloyDB verwenden können, müssen wir einige Datenbank-Flags aktivieren. Nachdem Sie die Data Access API aktiviert haben, kann es einige Minuten dauern, bis die Instanz für die nächsten Änderungen bereit ist. Sehen Sie sich den Status der Instanz in der Konsole an, um sicherzugehen, dass sie das grüne Häkchen hat.
Führen Sie den Befehl im selben Terminaltab aus.
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
--database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
--region=$REGION \
--cluster=$ADBCLUSTER \
--project=$PROJECT_ID \
--update-mode=FORCE_APPLY
MCP aktivieren
Im nächsten Schritt aktivieren Sie den Google Cloud MCP-Server für AlloyDB in Ihrem Projekt. Der MCP ist standardmäßig nicht aktiviert und ist eine von mehreren Schutzebenen, darunter IAM-Authentifizierung und ‑Autorisierung, Datenzugriff API und Rollen in Ihrem Cluster.
Führen Sie den Befehl im selben Terminaltab aus.
PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable alloydb.googleapis.com \
--project=$PROJECT_ID
Schließen Sie den Tab, indem Sie entweder den Befehl „exit“ auf dem Tab ausführen:
exit
Verbindung zu AlloyDB Studio herstellen
In den folgenden Kapiteln können alle SQL-Befehle, für die eine Verbindung zur Datenbank erforderlich ist, in AlloyDB Studio ausgeführt werden. T
Rufen Sie die Seite „Cluster“ in AlloyDB for Postgres auf.
Öffnen Sie die Webkonsolenoberfläche für Ihren AlloyDB-Cluster, indem Sie auf die primäre Instanz klicken.
Klicken Sie dann links auf „AlloyDB Studio“:
Wählen Sie die Postgres-Datenbank und den Nutzer „postgres“ aus und geben Sie das Passwort an, das beim Erstellen des Clusters angegeben wurde. Klicken Sie dann auf die Schaltfläche „Authentifizieren“.
Wenn das Passwort nicht funktioniert oder Sie es vergessen haben, können Sie es ändern. Weitere Informationen
Die AlloyDB Studio-Benutzeroberfläche wird geöffnet. Wenn Sie die Befehle in der Datenbank ausführen möchten, klicken Sie rechts auf den Tab „Unbenannte Abfrage“.
Dadurch wird eine Schnittstelle geöffnet, in der Sie SQL-Befehle ausführen können.
Datenbank erstellen
Schnellstart zum Erstellen von Datenbanken
Führen Sie im AlloyDB Studio-Editor den folgenden Befehl aus.
Datenbank erstellen:
CREATE DATABASE quickstart_db
Erwartete Ausgabe:
Statement executed successfully
Mit quickstart_db verbinden
Prüfen Sie, ob Ihre Datenbank erstellt wurde, indem Sie eine Verbindung zu ihr herstellen. Stellen Sie über die Schaltfläche zum Wechseln des Nutzers/der Datenbank eine neue Verbindung zum Studio her.
Wählen Sie in der Drop-down-Liste die neue Datenbank „quickstart_db“ aus und verwenden Sie denselben Nutzer und dasselbe Passwort wie zuvor.
Dadurch wird eine neue Verbindung geöffnet, über die Sie mit Objekten aus der Datenbank „quickstart_db“ arbeiten können. Dort können Sie das importierte Schema und die importierten Daten untersuchen.
6. Beispieldaten
Jetzt müssen Sie Objekte in der Datenbank erstellen und Daten laden. Sie verwenden einen fiktiven Datensatz des Unternehmens Cymbal Shipping. Sie enthält fiktive Daten zu Waren, Lkw, Anfragen und Lkw-Fahrten sowie fiktive Fahrer.
Storage-Bucket erstellen
Sie verwenden das Google SDK (gcloud), um Daten aus unserem geklonten Repository in die AlloyDB-Datenbank zu importieren. Dazu müssen Sie einen Speicher-Bucket erstellen und dem AlloyDB-Dienstkonto Zugriff gewähren. Alternativ können Sie es auch immer über die Webkonsole versuchen, wie in der Dokumentation beschrieben.
Führen Sie im Google Cloud Shell-Terminal folgenden Befehl aus:
PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer
Daten laden
Als Nächstes laden Sie die Daten. Unser SQL-Dump befindet sich im Ordner des geklonten Repositorys. Beim folgenden Befehl wird davon ausgegangen, dass Sie Ihr Basisverzeichnis als Ausgangspunkt verwendet haben, als Sie das Repository im vorherigen Schritt beim Erstellen des AlloyDB-Clusters geklont haben.
Kopieren Sie den komprimierten SQL-Dump in den neuen Speicher-Bucket:
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz gs://$PROJECT_ID-import
Laden Sie die Daten dann in die quickstart_db-Datenbank:
PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql
Mit dem Befehl wird das Beispieldataset in die Datenbank „quickstart_db“ geladen. Sie können die Tabellen und Datensätze mit AlloyDB Studio überprüfen.
7. Mit Data Agent arbeiten
Wir beginnen mit einem Beispiel-KI-Agenten, der mit dem Google ADK für Python erstellt wurde, und zeigen, wie Sie ihn für die Verwendung mit dem Google Cloud MCP-Server für AlloyDB konfigurieren.
Quellcode des Agents prüfen
Sehen Sie sich den Agent-Code im geklonten Repository mit dem Google Cloud Shell-Editor an.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py
Im Agent sehen Sie einen Abschnitt für den Google Cloud MCP-Server für AlloyDB. Wir stellen einen Endpunkt als MCP_SERVER_URL, Authentifizierung und Projekt-ID bereit und fügen ihn dem MCP-Toolset hinzu.
# Google Cloud MCP Server for AlloyDB
MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
creds.refresh(GoogleAuthRequest())
print(f"Authenticated as project: {project_id}")
# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
"Authorization": f"Bearer {creds.token}",
"X-Goog-User-Project": project_id
}
connection_params = StreamableHTTPConnectionParams(
url=MCP_SERVER_URL,
headers=headers,
timeout=300.0,
sse_read_timeout=600.0
)
mcp_toolset = McpToolset(connection_params=connection_params)
Im KI-Agentencode ist das MCP-Toolset als tools-Parameter für den KI-Agenten enthalten. Außerdem gibt es Cluster- und Instanznamen, die Region und die Datenbank als Variablen für den Agent-Prompt.
MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"
# Agent configuration
root_agent = Agent(
model=MODEL_ID,
name='root_agent',
description='A helpful assistant for analyst requests.',
instruction=f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
""",
tools=[mcp_toolset],
)
Der Google Cloud MCP-Dienst für AlloyDB umfasst eine vordefinierte Reihe von Tools. Wenn Sie alle verfügbaren Tools auflisten möchten, können Sie den Befehl curl über das Cloud Shell-Konsolenterminal mit dem folgenden Befehl verwenden. Die aktuelle Referenz für den Google Cloud-MCP-Server für AlloyDB finden Sie immer in der Dokumentation.
curl -s -X POST http://alloydb.googleapis.com/mcp \
-H "Content-Type: application/json" \
-d @- <<EOF | jq -r '.result.tools[].name'
{
"id": "my_id_01",
"jsonrpc": "2.0",
"method": "tools/list"
}
EOF
Agent starten
Jetzt können Sie den Agenten im interaktiven Modus über die Google ADK-Weboberfläche starten. Die ADK-Weboberfläche bietet eine praktische Möglichkeit, die Workflows von Agenten zu testen und Fehler zu beheben.
Installieren wir zuerst alle erforderlichen Pakete für Python mit dem Paketmanager „uv“.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync
Wenn alle Pakete installiert sind, müssen Sie dem Agent-Verzeichnis eine .env-Datei hinzufügen, damit der Agent Vertex AI für die gesamte Kommunikation mit den KI-Modellen verwendet.
echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env
Dann können Sie den Agenten starten.
uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
Die Ausgabe sollte in etwa wie im folgenden Beispiel aussehen. Der Endpunkt lautet http://127.0.0.1:8000.
Sie können in der Cloud Shell auf diese URL klicken. Dadurch wird in einem separaten Browsertab ein Vorschaufenster geöffnet, in dem Sie data_agent aus der Drop-down-Liste auf der linken Seite auswählen.
Im ADK-Webinterface können Sie Ihre Fragen unten rechts eingeben und den vollständigen Ausführungsablauf mit den Traces für jeden Schritt auf der rechten Seite sehen.
8. AlloyDB MCP mit Agent testen
Mit dem Agent können Sie Fragen in kostenloser Form in natürlicher Sprache stellen. Der Agent verwendet den Google Cloud MCP-Server für AlloyDB als Tool, um die Fragen zu beantworten. Die Fragen werden unten rechts und die Antwort mit allen Aufrufen der Tools oben angezeigt.
Sie arbeiten mit Betriebsdaten für ein Versandunternehmen, die Informationen zu Versandanträgen, Lkw, Fahrern und Fahrten von Fahrern enthalten. Die erste Frage bezieht sich auf die Anzahl der Fahrten, die im Februar 2026 durchgeführt wurden.
Geben Sie im Eingabefeld unten rechts Folgendes ein und drücken Sie die Eingabetaste.
Hello, can you tell me how many trips we've done in February this year?
Der Agent führt mehrere Tool-Aufrufe aus, um die richtigen Tabellen im Schema und die Tabellenstruktur zu ermitteln, bevor er die richtige SQL-Anweisung ausführt, um die richtigen Daten abzurufen.
Schließlich wird das Ergebnis ausgegeben, nachdem die richtige Abfrage erstellt und in der Datenbank ausgeführt wurde.
Laut den Aufzeichnungen in unserer Datenbank wurden im Februar 2026 108 Fahrten abgeschlossen.
Sie können sehen, was jeder Tool-Aufruf bewirkt, indem Sie auf die Tool-Ausführung klicken. Hier ist beispielsweise die Abfrage, die ausgeführt wurde, um unsere Ergebnisse zu erhalten.
Machen Sie die Anfrage nun komplexer, indem Sie die Ergebnisse mit dem Vormonat vergleichen lassen.
How is it in comparison in numbers and mileage with the January?
Das Ergebnis wird zurückgegeben, indem verschiedene Abfragen ausgeführt werden, um die Ergebnisse zu analysieren und eine Differenz bei der Anzahl der Fahrten und der Kilometerleistung zu ermitteln.
In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage: January 2026: 114 trips with a total mileage of 185,597 km. February 2026: 108 trips with a total mileage of 177,893 km. This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.
Probieren Sie andere einfache Anfragen über die ADK-Weboberfläche aus und sehen Sie sich an, wie verschiedene Anfragen ausgeführt werden, um die Ergebnisse zu erzielen.
Beenden Sie den Agent, indem Sie im Terminal ctrl+c drücken. Sie können den Browsertab mit der ADK-Weboberfläche schließen.
Jetzt können Sie eine Beispielanwendung ausprobieren und sehen, wie sie als Tool für Datenanalysten verwendet werden kann.
9. Beispiel-App
Im selben geklonten Repository befindet sich eine Beispielanwendung für unser Unternehmen Cymbol Logistic. Die Anwendung verwendet das Python-Framework Mesop von Google .
Sie können den Anwendungscode analysieren, indem Sie die Datei app.py im Cloud Shell-Editor öffnen.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py
Im Code verwenden wir eine Funktion, um einen neuen Prompt mit Variablen an unseren Daten-Agent zu übergeben. Der Grund dafür ist, dass wir die Konfiguration in der Benutzeroberfläche vornehmen können, wenn wir eine andere Datenbank oder Instanz aufrufen möchten. Hier sind die Funktionsdefinition und der Prompt.
def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
local_runner = FrontendRunner()
instruction = f"""
Answer user questions to the best of your knowledge using provided tools.
Do not try to generate non-existent data but use the grounded data from the database.
When you answer questions about Cymbal Logistic activity
use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
in the project {project_id} in the database {database_name}
Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
"""
...
Drücken Sie nach der Überprüfung des Codes die Schaltfläche „Terminal“, um die Anwendung zu starten und zu testen. Die Anwendung wird auf Port 8080 gestartet. Wenn Sie den Port ändern möchten, passen Sie den Befehl entsprechend an.
Führen Sie den Befehl in Cloud Shell aus.
REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080
Klicken Sie dann in Google Cloud Shell auf http://localhost:8080, um die Webvorschau zu verwenden.
Daraufhin wird ein neuer Tab im Browser mit der Anwendungsoberfläche geöffnet.
Klicken Sie rechts oben auf das Kästchen „Debug-Ausgabe aktivieren“ und geben Sie eine Frage wie die folgende ein.
What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.
Drücke dann die Taste Submit Request.
Der Agent arbeitet im Hintergrund und gibt die Ausgabe und Debugging-Informationen mit allen Abfragen aus, die von unserem MCP-Toolset ausgeführt werden. Sehen Sie sich die Abfragen an, um den Workflow zu sehen.
Sie können die Agenten und App-Funktionen testen, indem Sie verschiedene analytische Fragen stellen.
Bisher konnten Sie mit dem Agenten mit MCP einige grundlegende Analysen und Ermittlungen durchführen. Im nächsten Kapitel werden Sie versuchen, erweiterte AlloyDB-Funktionen zu verwenden.
10. AlloyDB AI-Funktionen
Mit den AlloyDB AI-Funktionen können Sie Text und multimodale Daten (insbesondere Bilder) auf intelligente Weise filtern und einstufen und die Leistungsfähigkeit von Gemini für Ihre Anfragen nutzen. Insbesondere die AlloyDB AI-Funktionen AI.IF und AI.RANK können in SQL-Anweisungen zusammen mit herkömmlichen SQL-Operatoren (Filter, Joins, Aggregation usw.) verwendet werden.
Bevor wir die KI-Funktionen verwenden, untersuchen wir eine Suche und Aggregationen mit den „klassischen“ Methoden. Probieren Sie den folgenden Prompt aus.
Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.
Sie kann die Spalte „Bewertung“ in der Tabelle mit Kundenfeedback finden und damit die Fahrer mit der besten Bewertung ermitteln. Anschließend wurden die Informationen verwendet, um weitere Informationen zu den Fahrern zu erhalten.
SELECT
d.first_name || ' ' || d.last_name as driver_name,
SUM(sr.distance_km) as total_distance,
d.experience_years,
COUNT(cf.feedback_id) as positive_feedback_count
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
WHERE tt.arrival_time >= '2025-12-01'
AND tt.arrival_time < '2026-05-01'
AND cf.rating >= 4
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY positive_feedback_count DESC, total_distance DESC
LIMIT 5;
Die Bewertung enthält jedoch möglicherweise nicht alle Parameter, die wir auswerten möchten. Dazu können wir AlloyDB AI-Funktionen verwenden.
AI.RANK-Operatoren
Die Funktion „ai.rank()“ bewertet, wie gut ein Dokument eine bestimmte Anfrage beantwortet. Sie kann zum Ranking oder erneuten Ranking von Ergebnissen der Abfrage verwendet werden. Weitere Informationen zu Operatoren finden Sie in der Dokumentation.
Ändern Sie die Anfrage und bitten Sie explizit darum, AI.RANK bei der Analyse zu verwenden, um die Faktoren anhand ihrer Leistung und Professionalität zu bewerten.
Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function? Give me top drivers names, distance, years of experience and rank for each driver.
Die Ausführung des Befehls kann etwas länger dauern, da der Agent herausfinden muss, wie die Funktion „AI.RANK“ verwendet wird, die Daten abrufen und „AI.RANK“ anwenden muss, um die Informationen entsprechend zu sortieren. Am Ende sollten Sie die Liste der Treiber erhalten, die vom Modell gerankt wurden, sowie die Liste der ausgeführten Abfragen.
Die Ausführung dieser Abfrage kann je nach vom Modell gewähltem Pfad einige Zeit dauern. Im Debug-Fenster sehen Sie die genaue Abfrage, die ausgeführt wurde, um die Informationen zu den Treibern zu erhalten.
WITH fastest_drivers AS (
SELECT
d.driver_id,
d.first_name || ' ' || d.last_name as driver_name,
d.experience_years,
SUM(sr.distance_km) as total_distance,
AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
FROM drivers d
JOIN truck_trips tt ON d.driver_id = tt.driver_id
JOIN shipping_requests sr ON tt.request_id = sr.request_id
LEFT
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
WHERE tt.arrival_time >= '2026-04-04'
AND tt.arrival_time IS NOT NULL
AND tt.departure_time IS NOT NULL
AND tt.arrival_time > tt.departure_time
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
ORDER BY avg_speed DESC
LIMIT 5
)
SELECT
f.driver_name,
f.total_distance,
f.experience_years,
f.avg_speed,
f.feedbacks,
(SELECT r.score
FROM ai.rank(
'semantic-ranker-fast-004',
'excellent customer service, professional, friendly, fast,
and reliable delivery reviews',
ARRAY[f.feedbacks],
1
) r
LIMIT 1) as feedback_score
FROM fastest_drivers f
ORDER BY feedback_score DESC;
Sie können die Anwendung weiterhin testen und Abfragen untersuchen, um zu sehen, wie der Agent zu den endgültigen Ergebnissen gelangt.
Damit ist das Lab abgeschlossen. Ich hoffe, Sie konnten sich alle Beispiele ansehen und erfahren, wie Sie den Google Cloud MCP-Dienst für AlloyDB verwenden. Damit Ihr MCP für Unternehmen funktioniert, ist es sinnvoll, ihn mit den in der AlloyDB-Dokumentation beschriebenen NL2SQL-Funktionen von AlloyDB zu kombinieren. Sie können es mit dem Codelab zum Generieren von SQL-Anweisungen für AlloyDB ausprobieren.
11. Umgebung bereinigen
Um unerwartete Kosten zu vermeiden, sollten Sie die temporären Ressourcen bereinigen. Am zuverlässigsten ist es, das Projekt zu löschen, in dem Sie den Workflow getestet haben. Optional können Sie sich jedoch einschränken, indem Sie einzelne Ressourcen wie AlloyDB löschen.
Löschen Sie die AlloyDB-Instanzen und den Cluster, wenn Sie das Lab abgeschlossen haben.
AlloyDB-Cluster und alle Instanzen löschen
Wenn Sie die Testversion von AlloyDB verwendet haben. Löschen Sie den Testcluster nicht, wenn Sie planen, andere Labs und Ressourcen damit zu testen. Sie können keinen weiteren Testcluster im selben Projekt erstellen.
Der Cluster wird mit der Option „force“ zerstört, wodurch auch alle zum Cluster gehörenden Instanzen gelöscht werden.
Definieren Sie in Cloud Shell die Projekt- und Umgebungsvariablen, wenn die Verbindung getrennt wurde und alle vorherigen Einstellungen verloren gegangen sind:
gcloud config set project <your project id>
export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)
Löschen Sie den Cluster:
gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
Erwartete Konsolenausgabe:
student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force All of the cluster data will be lost when the cluster is deleted. Do you want to continue (Y/n)? Y Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f Deleting cluster...done.
AlloyDB-Sicherungen löschen
Löschen Sie alle AlloyDB-Sicherungen für den Cluster:
for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Erwartete Konsolenausgabe:
student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f Deleting backup...done.
12. Glückwunsch
Herzlichen Glückwunsch zum Abschluss des Codelabs.
Behandelte Themen
- AlloyDB-Cluster erstellen und Beispieldaten importieren
- AlloyDB Data Access API aktivieren
- Google Cloud MCP für AlloyDB NL aktivieren
- Google Cloud MCP für AlloyDB zu Ihrem ADK-Agenten hinzufügen
- Google Cloud MCP für AlloyDB in einer Anwendung verwenden
- Agents mit AlloyDBMCP für Analysen verwenden
13. Umfrage
Ausgabe: