Diese Seite wurde von der Cloud Translation API übersetzt.

KI-Assistent für einen Sportartikel-Shop mit ADK, MCP Toolbox und AlloyDB erstellen

1. Einführung

Umfang

In diesem Codelab erfahren Sie, wie Sie einen KI-Assistenten für einen Sportartikel-Shop erstellen. Diese KI-Anwendung der nächsten Generation für Agenten, die auf ADK, MCP Toolbox und AlloyDB basiert, unterstützt Nutzer bei verschiedenen Aufgaben, darunter:

Produkte anhand natürlicher Sprache suchen
Geschäfte in der Nähe finden, in denen empfohlene Produkte gekauft werden können
Neue Bestellungen aufgeben
Vorhandene Bestellstatus prüfen
Bestellungen mit bevorzugten Versandarten aktualisieren

Lerninhalte

Bereitstellung und Befüllung einer AlloyDB for PostgreSQL-Datenbank.
MCP Toolbox for Databases mit Ihrer AlloyDB for PostgreSQL-Instanz einrichten.
Entwicklung eines KI-Agenten mit dem Agent Development Kit (ADK) zur Unterstützung bei Anfragen zu Sportgeschäften
Testen Sie Ihren Agenten und die MCP Toolbox for Databases in einer Cloud-Umgebung.
Die erweiterten Abfragefunktionen von AlloyDB für intelligente Agent-Antworten nutzen.

Voraussetzungen

Für dieses Codelab benötigen Sie Folgendes:

Sie verwenden den Chrome-Webbrowser.
Ein Gmail-Konto.
Google Cloud-Projekt mit aktivierter Abrechnungsfunktion

Dieses Codelab richtet sich an Entwickler aller Erfahrungsstufen, auch an Anfänger.

2. Hinweis

In diesem Abschnitt wird die Ersteinrichtung beschrieben, die in Ihrem Google Cloud-Projekt erforderlich ist, bevor Sie mit der Entwicklung des KI-Assistenten für den Sportartikel-Shop-Agent beginnen können.

Projekt erstellen

Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist .
Aktivieren Sie Cloud Shell, indem Sie auf diesen Link klicken. Sie können zwischen dem Cloud Shell-Terminal (zum Ausführen von Cloud-Befehlen) und dem Editor (zum Erstellen von Projekten) wechseln, indem Sie in Cloud Shell auf die entsprechende Schaltfläche klicken.

Wenn Sie mit Cloud Shell verbunden sind, können Sie mit dem folgenden Befehl prüfen, ob Sie bereits authentifiziert sind und das Projekt auf Ihre Projekt-ID festgelegt ist:

gcloud auth list

Führen Sie den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass der gcloud-Befehl Ihr Projekt kennt.

gcloud config list project

Legen Sie die Variable PROJECT_ID mit dem folgenden Befehl fest:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Aktivieren Sie die folgenden APIs, indem Sie die folgenden Befehle ausführen:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. AlloyDB-Instanz erstellen

In diesem Abschnitt richten Sie Ihren AlloyDB-Datenbankcluster und Ihre ‑Instanz ein und konfigurieren die erforderlichen Netzwerk- und Berechtigungseinstellungen für Ihren KI-Agenten.

Führen Sie zuerst den folgenden Befehl in Ihrem Cloud Shell-Terminal aus, um den AlloyDB-Cluster zu erstellen:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

AlloyDB nutzt private IP-Verbindungen für sicheren und leistungsstarken Zugriff. Sie müssen in Ihrer VPC einen privaten IP-Bereich zuweisen, den Google für die Dienst-Peering-Verbindung zur von Google verwalteten Dienstnetzwerkinfrastruktur verwendet. Führen Sie dazu diesen Befehl aus:

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

Erstellen Sie als Nächstes die VPC-Dienst-Peering-Verbindung. So kann Ihr Google Cloud-VPC-Netzwerk (Virtual Private Cloud) sicher und privat mit den verwalteten Diensten von Google kommunizieren, einschließlich AlloyDB. Führen Sie dazu diesen Befehl aus:

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

Erstellen Sie nun die primäre Instanz in Ihrem AlloyDB-Cluster. Dies ist der tatsächliche Datenbankendpunkt, mit dem sich Ihre Anwendungen verbinden. Führen Sie den folgenden Befehl aus, um eine AlloyDB-Instanz zu erstellen:

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Hinweis:Das Erstellen der Instanz kann etwa 10 Minuten dauern. Warten Sie, bis dieser Vorgang abgeschlossen ist, bevor Sie fortfahren.

Vertex AI-Einbindung aktivieren

Damit Ihre AlloyDB-Instanz Vektorsuchanfragen ausführen kann, die für KI-Funktionen wie die semantische Suche unerlässlich sind, und in Vertex AI bereitgestellte Modelle aufrufen kann, müssen Sie dem AlloyDB-Dienstkonto Berechtigungen für Vertex AI gewähren.

Rufen Sie zuerst Ihre Google Cloud-Projektnummer ab, da sie für die IAM-Bindung erforderlich ist.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Erteilen Sie dann Vertex AI die Berechtigung für den AlloyDB-Dienst-Agent:

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:service-$PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

Öffentliche IP-Adresse aktivieren

Zur Vorbereitung auf die folgenden Schritte aktivieren wir die öffentliche IP-Konnektivität in unserer AlloyDB-Instanz.

Rufen Sie in der Console das Suchfeld oben in der Mitte des Bildschirms auf, geben Sie „alloydb“ ein und bearbeiten Sie den Abschnitt „Public IP connectivity“ (Verbindung über öffentliche IP-Adresse). Setzen Sie ein Häkchen in das Kästchen „Öffentliche IP-Adresse aktivieren“ und geben Sie die IP-Adresse Ihrer Cloud Shell-Maschine ein.

Wenn Sie die IP-Adresse Ihrer Cloud Shell-Maschine abrufen möchten, rufen Sie das Cloud Shell-Terminal auf und geben Sie den Befehl „ifconfig | grep -A 1 eth0“ ein. Ersetzen Sie im Ergebnis die letzten beiden Ziffern durch 0.0 mit der Maskengröße „/16“. Ein Beispiel dafür ist „XX.XX.0.0/16“, wobei XX für Zahlen steht.

Fügen Sie diese IP-Adresse auf der Seite zum Bearbeiten der Instanz in das Textfeld „Netzwerke“ unter „Autorisierte externe Netzwerke“ ein.

Hinweis:Der Aktualisierungsvorgang kann bis zu 3 Minuten dauern.

4. Datenbank laden

Shop-Datenbank erstellen

Jetzt ist es an der Zeit, die Datenbank zu erstellen und die ersten Daten für Ihren Sportartikelshop zu laden.

Damit psql über Cloud Shell eine Verbindung zu Ihrer privaten AlloyDB-Instanz herstellen kann, verwenden Sie den AlloyDB Auth-Proxy. Dieses Tool stellt einen sicheren Tunnel für Ihre Verbindung zur Datenbank her. (Siehe AlloyDB Auth-Proxy)

Laden Sie den AlloyDB Auth-Proxy mit dem folgenden Befehl herunter:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

Machen Sie es ausführbar:

chmod +x alloydb-auth-proxy

Führen Sie diesen Befehl im ersten Cloud Shell-Terminalfenster aus. Der Proxy wird im Hintergrund ausgeführt und leitet Verbindungen weiter.

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

Wichtig:Lassen Sie dieses Terminalfenster geöffnet und den Proxy laufen. Schließen Sie es nicht.

Öffnen Sie ein neues Terminalfenster in Cloud Shell. Klicken Sie dazu oben neben dem Tab „Cloud Shell-Terminal“ auf das Symbol +.

Stellen Sie mit psql eine Verbindung zur AlloyDB-Instanz her:

psql -h 127.0.0.1 -U postgres

Hinweis:Geben Sie bei Aufforderung das Passwort ein, das Sie beim Erstellen des Clusters für den Nutzer postgres festgelegt haben. Wenn Sie der Dokumentation direkt folgen, lautet das Passwort alloydb.

Erstellen Sie die Speicherdatenbank für unsere Anwendung (führen Sie die Befehle nacheinander aus):

CREATE DATABASE store;
\c store
exit

Quellcode

Klonen Sie nun das Quellcode-Repository des Codelabs. Achten Sie darauf, dass Sie sich in Ihrem Basisverzeichnis oder an einem geeigneten Ort befinden, bevor Sie den Klonvorgang starten, und führen Sie den folgenden Befehl aus:

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

Datenbank füllen

Rufen Sie den Ordner data des geklonten Projekts auf, um auf die Datenbank-Dumpdatei zuzugreifen.

cd sports-agent-adk-mcp-alloydb/data

Importieren Sie dann das Beispieldataset mit der Datei store_backup.sql aus dem Repository in Ihre store-Datenbank.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

Hinweis:Während des Imports werden möglicherweise einige WARNUNGs- und FEHLER-Meldungen angezeigt, die in diesem Codelab ignoriert werden können. Diese beziehen sich häufig auf Berechtigungen oder Objekte, die bereits vorhanden sind, wenn der Dump das vollständige Schema enthält. Sie finden einige WARNUNGEN und FEHLER, die ignoriert werden können.

5. Autorisierungsdienst einrichten

In diesem Abschnitt richten Sie den Autorisierungsdienst für Ihre Anwendung ein. Dieser Dienst ist entscheidend, um den Zugriff zu sichern und vor Prompt-Injection-Schwachstellen in Ihrem KI-Agenten zu schützen.

Zuerst fügen Sie der Tabelle users in Ihrer Datenbank store einen Beispielnutzer hinzu. Dieser Nutzer wird für die Authentifizierung in Ihrer Anwendung verwendet.

Rufen Sie die Console auf, gehen Sie zu AlloyDB, wählen Sie die primäre Instanz und dann AlloyDB Studio aus:

Melden Sie sich bei entsprechender Aufforderung mit den Anmeldedaten in AlloyDB Studio an, die Sie beim Einrichten des Clusters erstellt haben:

Nutzername: „postgres“
Datenbank: „store“
Passwort: „alloydb“

Führen Sie im SQL-Editor eine INSERT-Anweisung aus, um den Nutzer der Datenbank hinzuzufügen. Ändern Sie den Namen, den Nachnamen und die E‑Mail-Adresse.

Wichtig:

Behalten Sie den LOCATION-Wert aus dem Beispiel bei.
Verwenden Sie dieselbe E-Mail-Adresse, mit der Sie sich in der Google Cloud Console registrieren.

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

Als Nächstes müssen Sie den OAuth-Zustimmungsbildschirm für Ihr Projekt konfigurieren. Dieser Bildschirm wird Nutzern angezeigt, wenn Ihre Anwendung Zugriff auf ihr Google-Konto anfordert. Außerdem wird hier die Marke Ihrer Anwendung definiert.

Rufen Sie in der Console „APIs und Dienste“ > „Google OAuth Consent“ auf:

Geben Sie die folgenden Informationen an, um die Marke Ihrer Anwendung zu erstellen:

App-Name: „Sports Shopping Agent AI“
E‑Mail-Adresse für Nutzersupport: „YOUR_EMAIL“
Zielgruppe: „Extern“
Kontaktdaten: „YOUR_EMAIL“

Als Nächstes erstellen Sie die OAuth-Client-ID, die Ihre Frontend-Anwendung verwenden wird, um die Nutzeridentität bei Google zu bestätigen.

Prüfen Sie zuerst, ob Sie Ihre Google Cloud-Projektnummer haben. Dies ist erforderlich, um die Weiterleitungs-URIs richtig zu konfigurieren. Führen Sie den folgenden Befehl in einem Cloud Shell-Terminal aus:

Falls die Variable PROJECT_ID in diesem Cloud Shell-Terminalfenster nicht festgelegt ist, führen Sie folgenden Befehl aus:

export PROJECT_ID=[YOUR_PROJECT_ID]

Rufen Sie dann die PROJECT_NUMBER mit dem folgenden Befehl ab:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Rufen Sie dann „APIs und Dienste“ -> „Anmeldedaten“ -> „Anmeldedaten erstellen“ -> „OAuth-Client-ID“ auf.

Verwenden Sie die folgenden Informationen, um die Anmeldedaten zu erstellen:

Anwendungstyp: „Webanwendung“
Name: „Sports Shopping Agent AI App“

Autorisierte JavaScript-Quellen:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Autorisierte Weiterleitungs-URIs:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Hinweis:Die URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app ist die erwartete Deployment-URL für Ihre Frontend-Anwendung, die später in diesem Codelab eingerichtet wird. Ersetzen Sie [YOUR_PROJECT_NUMBER] durch die tatsächliche Nummer, die Sie kopiert haben.

Wichtig:Nach der Erstellung wird in einem Pop-up-Fenster Ihre OAuth-Client-ID und manchmal ein Clientschlüssel angezeigt. Bewahren Sie Ihre OAuth-Client-ID an einem sicheren Ort auf, da Sie sie in einem späteren Schritt beim Konfigurieren Ihres Front-Ends benötigen.

6. MCP ToolBox for Databases einrichten

Toolbox befindet sich zwischen dem Orchestrierungs-Framework Ihrer Anwendung und Ihrer Datenbank und bietet eine Steuerungsebene, mit der Tools geändert, verteilt oder aufgerufen werden können. Es vereinfacht die Verwaltung Ihrer Tools, da Sie Tools zentral speichern und aktualisieren können. So können Sie Tools zwischen Agents und Anwendungen freigeben und aktualisieren, ohne Ihre Anwendung neu bereitstellen zu müssen.

Da AlloyDB eine der von MCP Toolbox for Databases unterstützten Datenbanken ist und wir sie bereits im vorherigen Abschnitt bereitgestellt haben, können wir jetzt mit der Einrichtung der Toolbox fortfahren.

Zuerst richten Sie den MCP Toolbox-Server lokal in Ihrer Cloud Shell-Umgebung ein, um seine Funktionalität zu überprüfen.

Wechseln Sie im Cloud Shell-Terminal zum Ordner toolbox in Ihrem geklonten Projekt-Repository:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Führen Sie die folgenden Befehle aus, um die Toolbox-Binärdatei herunterzuladen und ihr Ausführungsberechtigungen zu erteilen:

# see releases page for other versions
export VERSION=0.7.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

Hinweis:Hier wird Version 0.7.0 angegeben. Für Produktionsumgebungen sollten Sie immer die neueste stabile Version von der Seite „Toolbox-Releases“ verwenden.

Rufen Sie den Cloud Shell-Editor auf. Sie können vom Terminal aus wechseln, indem Sie auf das Editorsymbol klicken.

Im selben Verzeichnis sports-agent-adk-mcp-alloydb/src/toolbox finden Sie eine Datei namens tools.yaml. Öffnen Sie diese Datei und aktualisieren Sie die Platzhalter mit Ihrer OAuth-Client-ID und Google Cloud-Projekt-ID aus den vorherigen Schritten.

tools.yaml

Quellen sind die verschiedenen Datenquellen, mit denen ein Tool interagieren kann. Eine Quelle ist eine Datenquelle, mit der ein Tool interagieren kann. Sie können Quellen als Map im Abschnitt „sources“ Ihrer tools.yaml-Datei definieren. Normalerweise enthält eine Quellkonfiguration alle Informationen, die für die Verbindung mit der Datenbank und die Interaktion mit ihr erforderlich sind.

Tools definieren Aktionen, die ein Agent ausführen kann, z. B. das Lesen und Schreiben in eine Quelle. Ein Tool stellt eine Aktion dar, die Ihr Agent ausführen kann, z. B. das Ausführen einer SQL-Anweisung. Sie können Tools als Map im Abschnitt „tools“ Ihrer Datei „tools.yaml“ definieren. Normalerweise benötigt ein Tool eine Quelle, auf die es sich beziehen kann.

Weitere Informationen zum Konfigurieren von „tools.yaml“ finden Sie in dieser Dokumentation.

MCP-Toolbox für Datenbanken-Server ausführen

Führen Sie den folgenden Befehl aus dem Ordner „mcp-toolbox“ aus, um den Server zu starten:

./toolbox --tools-file "tools.yaml"

Wenn Sie den Server jetzt in einem Webvorschaumodus in der Cloud öffnen, sollte der Toolbox-Server mit allen Tools unserer Anwendung ausgeführt werden.

Der MCP Toolbox-Server wird standardmäßig auf Port 5000 ausgeführt. Wir verwenden Cloud Shell, um dies zu testen.

Klicken Sie in Cloud Shell auf „Webvorschau“ (siehe unten):

Klicken Sie auf „Port ändern“, legen Sie den Port wie unten dargestellt auf 5000 fest und klicken Sie auf „Ändern und Vorschau“.

Dies sollte die folgende Ausgabe liefern:

Das MCP Toolkit for Databases enthält ein Python SDK, mit dem Sie die Tools validieren und testen können. Die Dokumentation dazu finden Sie hier. Wir überspringen das und gehen im nächsten Abschnitt direkt zum Agent Development Kit (ADK) über, in dem diese Tools verwendet werden.

Toolbox in Cloud Run bereitstellen

Damit Ihr Toolbox-Server als öffentlicher Endpunkt zugänglich ist, der in andere Anwendungen und Ihren KI-Agenten eingebunden werden kann, stellen Sie ihn in Cloud Run bereit. Eine ausführliche Anleitung zum Hosten der Toolbox in Cloud Run finden Sie hier.

Kehren Sie zum Cloud Shell-Terminal zurück und wechseln Sie zum Toolbox-Ordner:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Achten Sie darauf, dass die Umgebungsvariable PROJECT_ID auf Ihre Google Cloud-Projekt-ID eingestellt ist.

export PROJECT_ID=$PROJECT_ID

Prüfen Sie als Nächstes, ob die folgenden Google Cloud-Dienste im Projekt aktiviert sind.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Erstellen wir ein separates Dienstkonto, das als Identität für den Toolbox-Dienst dient, den wir in Google Cloud Run bereitstellen. Wir sorgen auch dafür, dass dieses Dienstkonto die richtigen Rollen hat, d.h. Zugriff auf Secret Manager und die Möglichkeit zur Kommunikation mit AlloyDB.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor


gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

Anschließend laden Sie die Datei „tools.yaml“ als Secret hoch. Da wir die Toolbox in Cloud Run installieren müssen, verwenden wir das aktuelle Container-Image für die Toolbox und legen es in der IMAGE-Variablen fest.

gcloud secrets create tools --data-file=tools.yaml

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

Stellen Sie den Toolbox-Server mit dem folgenden Befehl in Cloud Run bereit. Mit diesem Befehl wird Ihre Anwendung in einen Container gepackt, das Dienstkonto konfiguriert, das Secret eingefügt und öffentlich zugänglich gemacht:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

Dadurch sollte der Prozess zum Bereitstellen des Toolbox-Servers mit unserer konfigurierten „tools.yaml“-Datei in Cloud Run gestartet werden. Bei erfolgreicher Bereitstellung wird eine Meldung ähnlich der folgenden angezeigt:

Deploying container to Cloud Run service [toolbox] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

Sie können jetzt die oben aufgeführte Dienst-URL im Browser aufrufen. Es sollte die Meldung „Hello World“ angezeigt werden, die wir zuvor gesehen haben. Unter der folgenden URL finden Sie eine Übersicht der verfügbaren Tools:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

Sie können auch in der Google Cloud Console Cloud Run aufrufen. Der Toolbox-Dienst wird in der Liste der Dienste in Cloud Run angezeigt.

7. Auf ADK basierender Agent

In diesem Abschnitt stellen Sie Ihren KI-Agenten, der mit dem Agent Development Kit (ADK) erstellt wurde, in Cloud Run bereit.

Aktivieren Sie zuerst die erforderlichen APIs in Ihrem Projekt, um Ihren Agent in Cloud Run zu erstellen und bereitzustellen und mit Artifact Registry und Cloud Storage zu interagieren. Führen Sie im Cloud Shell-Terminal den folgenden Befehl aus:

gcloud services enable artifactregistry.googleapis.com \
                       cloudbuild.googleapis.com \
                       run.googleapis.com \
                       storage.googleapis.com

Anschließend weisen wir dem Standard-Compute-Dienstkonto in unserem Projekt die erforderlichen Berechtigungen zu. Führen Sie zuerst den folgenden Befehl in Ihrem Cloud Shell-Terminal aus, um die PROJECT_NUMBER abzurufen:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Weisen Sie dem Standard-Compute-Dienstkonto Berechtigungen zu:

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

Agent mit Tools verbinden

Wir verbinden unseren Agent mit Tools. Im Kontext des ADK stellt ein Tool eine bestimmte Funktion dar, die einem KI-Agenten zur Verfügung gestellt wird, damit er Aktionen ausführen und mit der Welt interagieren kann, die über seine grundlegenden Fähigkeiten zur Textgenerierung und zum logischen Denken hinausgehen.

In unserem Fall statten wir unseren Agenten jetzt mit den Tools aus, die wir in der MCP Toolbox for Databases konfiguriert haben.

Rufen Sie mit dem Cloud Shell-Editor das Verzeichnis „sports-agent-adk-mcp-alloydb/src/backend/“ auf und bearbeiten Sie die Datei „finn_agent.py“ mit dem folgenden Code. Beachten Sie, dass wir die Cloud Run-Dienst-URL des im vorherigen Schritt bereitgestellten MCP ToolBox-Servers verwenden:

Agent in Cloud Run bereitstellen

Schließlich stellen Sie Ihren konfigurierten KI-Agent in Cloud Run bereit, sodass er über einen HTTP-Endpunkt zugänglich ist.

Erstellen Sie zuerst ein Docker-Repository in Artifact Registry, um die Container-Images Ihres Agent zu speichern. Führen Sie in Cloud Shell den folgenden Befehl aus:

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

Als Nächstes erstellen Sie das Docker-Image für Ihren Agent mit Cloud Build. Führen Sie diesen Befehl im Stammverzeichnis Ihres geklonten Projekts (sports-agent-adk-mcp-alloydb/) aus:

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

Stellen Sie nun den Agent-Dienst bereit. Mit diesem Befehl wird ein Cloud Run-Dienst erstellt, das Image aus Artifact Registry abgerufen und Umgebungsvariablen konfiguriert.

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

Hinweis:Wir legen Umgebungsvariablen dynamisch fest, einschließlich GOOGLE_CLOUD_PROJECT (mit der Shell-Variablen $PROJECT_ID).

Sie sollten eine ähnliche Ausgabe erhalten, die angibt, dass Ihr Agent erfolgreich bereitgestellt wurde:

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

Testen Sie Ihren Agent, indem Sie den folgenden curl-Befehl in Ihrem Cloud Shell-Terminal ausführen:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

Die Ausgabe sollte in etwa so aussehen:

„Hallo! Ich bin Finn, dein KI‑Assistent für Sportartikel. Ich kann dir helfen, Sportprodukte, Ausrüstung und Zubehör zu finden. Was kann ich für Sie tun?

Sie haben die Bereitstellung von AlloyDB, der MCP Toolbox und Ihres mit dem ADK erstellten Agenten validiert.

8. Frontend bereitstellen

In diesem Abschnitt stellen Sie die Konversations-Benutzeroberfläche für Ihren KI-Assistenten in Cloud Run bereit. Dieses Frontend wurde mit React und JavaScript erstellt.

Vor der Bereitstellung müssen Sie den Quellcode des Frontends mit den URLs Ihres bereitgestellten Agents und Ihrer OAuth-Client-ID aktualisieren.

Rufen Sie im Cloud Shell-Editor sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ auf und öffnen Sie die Datei Home.jsx. Sie müssen den Platzhalter für die Cloud Run-Dienst-URL Ihres Agents aktualisieren. Ersetzen Sie sie dann durch die Cloud Run-Dienst-URL Ihres Agenten aus dem vorherigen Schritt (z.B. https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app) verwenden.

Rufen Sie als Nächstes sports-agent-adk-mcp-alloydb/src/frontend/src/components/ auf und öffnen Sie die Datei GoogleSignInButton.jsx. Sie aktualisieren diese Datei mit der OAuth-Client-ID, die Sie im Abschnitt „Autorisierungsdienst einrichten“ erhalten haben:

Frontend in Cloud Run bereitstellen

Nachdem Sie die Frontend-Anwendung konfiguriert haben, können Sie sie in Cloud Run bereitstellen.

Führen Sie den folgenden Befehl in einem Cloud Shell-Terminal aus dem Stammverzeichnis (sports-agent-adk-mcp-alloydb/) aus, um ein Docker-Repository in Artifact Registry für Ihre Frontend-Images zu erstellen.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

Als Nächstes erstellen Sie mit Cloud Build das Docker-Image für Ihre Frontend-Anwendung. Führen Sie diesen Befehl im Stammverzeichnis Ihres Projekts aus:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

Schließlich stellen wir das Frontend mit dem folgenden Befehl in Cloud Run bereit:

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

Sie sollten eine ähnliche Ausgabe erhalten, die die erfolgreiche Bereitstellung Ihres Front-Ends angibt:

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

Öffnen Sie Ihren Webbrowser und verwenden Sie die Dienst-URL aus dem vorherigen Schritt, um Ihre neu bereitgestellte Anwendung zu öffnen, die von Ihrem KI-Agenten unterstützt wird.

9. Agent ausführen

Ihr KI‑Assistent „Sports Store Agent“, Finn, ist jetzt vollständig bereitgestellt und kann Ihnen bei Käufen helfen.

Öffnen Sie Ihren Webbrowser und rufen Sie die Dienst-URL Ihrer Frontend-Anwendung aus dem vorherigen Schritt auf. Die URL hat folgendes Format: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Klicken Sie nach dem Laden des Frontends rechts oben auf die Schaltfläche (in der Regel mit „Anmelden“ oder einem ähnlichen Hinweis), um sich mit Ihren Google-Anmeldedaten zu authentifizieren. Bei dieser Aktion wird die OAuth-Konfiguration verwendet, die Sie zuvor eingerichtet haben.

Nach erfolgreicher Authentifizierung können Sie mit Finn interagieren. Klicken Sie auf die Schaltfläche „Jetzt einkaufen“, um mit dem Conversational Shopping zu beginnen.

Verwenden Sie das folgende Skript, um die verschiedenen Funktionen Ihres KI-Agents zu testen. Kopieren Sie diese Prompts und fügen Sie sie einzeln in die Chatoberfläche ein:

Hallo Finn!
Ich suche Laufschuhe für einen Ultratrail.
Erzähl mir mehr über Ultra Glide.
Setz Ultra Glide, Größe 40, Farbe Rot/Grau auf meine Einkaufsliste
Zeig mir meine Einkaufsliste
Geschäfte in meiner Nähe finden
Bitte gib eine Bestellung für das Geschäft Sports Diagonal Mar über meine Einkaufsliste auf.
Status meiner Bestellungen prüfen
Bitte liste die Liefermethoden für das Geschäft Sports Diagonal Mar auf.
Liefermethode für meine Bestellung [YOUR_ORDER_NUMBER] auf Expressversand umstellen
Status meiner Bestellungen prüfen
Danke, Finn!

Eine visuelle Demonstration des bereitgestellten Finn-Agents und seiner Funktionen finden Sie im folgenden Video:

Demo eines KI-Assistenten für Sportagenten, der auf AlloyDB basiert

10. Ergebnisse

Nachdem Sie das vorherige Skript ausgeführt haben, haben Sie die vollständige Integration Ihres ADK-Agents, seine Verbindung zu AlloyDB und die Verwendung der MCP Toolbox erfolgreich validiert. In diesem Abschnitt werden die von Ihnen implementierten Kernfunktionen hervorgehoben.

Autorisierungsdienst

Die MCP Toolbox for Databases bietet die Möglichkeit, einen Autorisierungsdienst (in diesem Codelab speziell Google Sign-in) zu föderieren, um Nutzer in Ihrer Anwendung zu authentifizieren. In der MCP Toolbox wird Ihre OAuth-Client-ID verwendet, um die Nutzeridentität zu bestätigen, wenn ein Tool aufgerufen wird.

Dieser robuste Authentifizierungsmechanismus bietet eine hervorragende Lösung, um Ihre Agent-Anwendung vor Prompt Injection zu schützen. Bei dieser Art von Angriff wird versucht, das beabsichtigte Verhalten des Agents durch schädliche Eingaben zu umgehen oder zu manipulieren. Weitere Informationen finden Sie im Wikipedia-Artikel Prompt Injection .

In dieser Anwendung wird diese Technik verwendet, wenn ein Nutzer fragt: „Check the status of our orders“ (Prüfe den Status unserer Bestellungen) oder „Show my shopping list“ (Zeige meine Einkaufsliste an). Der Agent ist so konzipiert, dass nur die Bestellungen des authentifizierten Nutzers angezeigt werden. So wird unbefugter Zugriff auf Bestellinformationen verhindert.

Vektorsuche

Ihre agentische Anwendung nutzt AlloyDB for PostgreSQL, um erweiterte Abfragefunktionen bereitzustellen, insbesondere durch die Vektorsuche. AlloyDB unterstützt die Online-Generierung von Einbettungen direkt in der Datenbank mithilfe von SQL-Funktionen.

Mit dieser leistungsstarken Funktion kann der Agent die Eingabe eines Nutzers in natürlicher Sprache in eine numerische Einbettungsdarstellung übersetzen. Anschließend kann eine Ähnlichkeitssuche in Ihrem Produktkatalog (oder anderen relevanten Daten) auf Grundlage dieser Einbettungen durchgeführt werden, um hochrelevante Suchergebnisse zu erzielen.

In Ihrer Anwendung wird diese Technik angewendet, wenn Sie Finn fragen: „Ich suche Laufschuhe für einen Ultra-Trail.“

Geospatiale Funktionen (PostGis)

AlloyDB for PostgreSQL ist zu 100% mit den Standard-PostgreSQL-Funktionen kompatibel. In dieser Anwendung nutzen wir die beliebte PostgreSQL-Erweiterung PostGIS, um dem Agenten Funktionen für die geografische Positionierung zur Verfügung zu stellen.

Wenn Sie den Agenten fragen: „Finde Geschäfte in meiner Nähe“, führt der Agent ein Tool aus, das PostGIS-Indizes in der Datenbank nutzt, um die Geschäfte in der Nähe des angegebenen oder abgeleiteten Standorts des Nutzers effizient zu finden.

11. (Optional) AlloyDB AI Natural Language to SQL testen

In diesem Abschnitt wird ein Pre-GA-Feature von AlloyDB for PostgreSQL vorgestellt: Natural Language to SQL. Mit dieser Funktion können Sie SQL-Abfragen direkt aus Prompts in natürlicher Sprache generieren und so die Leistungsfähigkeit von KI in Ihrer Datenbank nutzen.

Wichtig:Da es sich um eine Pre-GA-Funktion handelt, müssen Sie sich registrieren und den Zugriff für Ihr Google Cloud-Projekt, Ihren AlloyDB-Cluster und Ihre Datenbank aktivieren lassen.

Für Zugriff registrieren:Bitte verwenden Sie dieses Formular, um Zugriff für Ihr Projekt anzufordern.
Dokumentation:Weitere Informationen zur Verwendung von AlloyDB AI Natural Language to SQL finden Sie in der offiziellen Dokumentation.

Nachdem Sie sich registriert und den Zugriff für Ihr Projekt bestätigt haben, fahren Sie mit den folgenden Schritten in AlloyDB Studio fort.

Melden Sie sich mit den Anmeldedaten bei AlloyDB an, die Sie beim Erstellen des Clusters erstellt haben:

Nutzername: „postgres“
Datenbank: „store“
Passwort: „alloydb“

1. Erstellen Sie die Erweiterung „alloydb_ai_nl“. Diese Erweiterung bietet die erforderlichen Funktionen für die AlloyDB AI-Funktionen für natürliche Sprache.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Konfiguration für Ihre Anwendung erstellen Eine Konfiguration definiert den Schemakontext, den das KI-Modell verwendet, um Ihre Datenbank zu verstehen.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3. Registrieren Sie das Schema bzw. die Tabellen mit der Konfiguration. Fügen Sie der Konfiguration die spezifischen Tabellen und Schemas hinzu, mit denen der Agent Ihrer Anwendung interagieren soll.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4. Kontext für das Schema / die Tabellen generieren In diesem Schritt werden die registrierten Tabellen verarbeitet, um den erforderlichen Kontext für das KI-Modell zu generieren. Dieser Vorgang kann etwa 2–3 Minuten dauern.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5. Optional: Überprüfen Sie den automatisch generierten Kontext für bestimmte Tabellen und Spalten. Sie können den generierten Kontext prüfen, um zu sehen, wie das KI-Modell Ihr Schema interpretiert.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

In der Datei „tools.yaml“ unseres Agents finden Sie das Tool „check-inventory-by-store-brand-category“. Für dieses Tool wird AlloyDB Natural Language to SQL verwendet:

Öffnen Sie einen Webbrowser und rufen Sie die Anwendung über die Dienst-URL auf: „https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app“.

Verwenden Sie dann das folgende Script in der Chatoberfläche, um diese neue Funktion zu testen:

Hallo Finn!
Wie hoch ist die Gesamtmenge der Produkte der Kategorie „Laufen“ von Salomon, die im Geschäft „Sports Diagonal Mar“ auf Lager sind?

Wenn Sie die tatsächliche SQL-Abfrage sehen möchten, die von AlloyDB AI aus Ihrer Eingabe in natürlicher Sprache generiert wurde, kehren Sie zu AlloyDB Studio zurück und führen Sie die folgende Abfrage aus:

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

Dadurch wird die SQL-Anweisung angezeigt, die von AlloyDB AI generiert wurde.

12. Bereinigen

So vermeiden Sie, dass Ihrem Google Cloud-Konto die in diesem Lab verwendeten Ressourcen in Rechnung gestellt werden:

Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.
Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf „Löschen“.
Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf „Beenden“, um das Projekt zu löschen.

13. Glückwunsch

Glückwunsch! Sie haben erfolgreich eine datengesteuerte agentische KI-Anwendung mit dem ADK, der MCP Toolbox for Databases und AlloyDB for PostgreSQL erstellt.

Weitere Informationen finden Sie in der Produktdokumentation: Agent Development Kit, MCP Toolbox for Databases und AlloyDB for PostgreSQL.