Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie asystenta AI dla agenta w sklepie sportowym za pomocą ADK, MCP Toolbox i AlloyDB

1. Wprowadzenie

Co utworzysz

W tym ćwiczeniu w Codelabs dowiesz się, jak utworzyć asystenta AI dla sklepu sportowego. Ta aplikacja AI nowej generacji, oparta na ADK, MCP Toolbox i AlloyDB, będzie pomagać użytkownikom w różnych zadaniach, w tym:

Wyszukiwanie produktów za pomocą języka naturalnego.
znajdowanie pobliskich sklepów, w których można kupić rekomendowane produkty;
składanie nowych zamówień,
Sprawdzanie stanu istniejących zamówień.
Aktualizowanie zamówień z preferowanymi metodami dostawy.

Czego się nauczysz

inicjowanie i wypełnianie bazy danych AlloyDB for PostgreSQL;
Konfigurowanie MCP Toolbox for Databases w instancji AlloyDB for PostgreSQL.
Projektowanie i tworzenie agenta AI za pomocą pakietu Agent Development Kit (ADK), który będzie pomagać w odpowiadaniu na pytania dotyczące sklepu sportowego.
Testowanie narzędzi Agent i MCP Toolbox for Databases w środowisku chmurowym.
Wykorzystywanie zaawansowanych funkcji zapytań AlloyDB do generowania inteligentnych odpowiedzi agenta.

Czego potrzebujesz

Aby ukończyć to ćwiczenie, potrzebujesz:

przeglądarki Chrome;
konto Gmail,
Projekt Google Cloud z włączonymi płatnościami.

Te warsztaty są przeznaczone dla deweloperów na wszystkich poziomach zaawansowania, w tym dla początkujących.

2. Zanim zaczniesz

W tej sekcji znajdziesz instrukcje dotyczące początkowej konfiguracji wymaganej w projekcie Google Cloud, zanim zaczniesz tworzyć asystenta AI Sports Shop Agent.

Tworzenie projektu

W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud.
Sprawdź, czy w projekcie Cloud włączone są płatności. Dowiedz się, jak sprawdzić, czy w projekcie włączone są płatności .
Aktywuj Cloud Shell, klikając ten link. Możesz przełączać się między terminalem Cloud Shell (do uruchamiania poleceń w chmurze) a edytorem (do tworzenia projektów), klikając odpowiedni przycisk w Cloud Shell.

Po połączeniu z Cloud Shell sprawdź, czy jesteś już uwierzytelniony i czy projekt jest ustawiony na Twój identyfikator projektu, używając tego polecenia:

gcloud auth list

Aby potwierdzić, że polecenie gcloud zna Twój projekt, uruchom w Cloud Shell to polecenie:

gcloud config list project

Ustaw zmienną PROJECT_ID za pomocą tego polecenia:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Włącz te interfejsy API, wykonując te polecenia:

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

3. Tworzenie instancji AlloyDB

W tej sekcji skonfigurujesz klaster i instancję bazy danych AlloyDB oraz niezbędne ustawienia sieci i uprawnienia dla agenta AI.

Najpierw uruchom w terminalu Cloud Shell to polecenie, aby utworzyć klaster AlloyDB:

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

AlloyDB korzysta z połączeń przy użyciu prywatnego adresu IP, aby zapewnić bezpieczny i wydajny dostęp. Musisz przydzielić w swojej sieci VPC prywatny zakres adresów IP, który Google będzie używać na potrzeby połączenia równorzędnego usługi z infrastrukturą sieciową usługi zarządzanej przez Google. Uruchom to polecenie:

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

Następnie utwórz połączenie równorzędne usługi VPC. Dzięki temu sieć VPC w Google Cloud może bezpiecznie i prywatnie komunikować się z usługami zarządzanymi Google, w tym z AlloyDB. Uruchom to polecenie:

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

Teraz utwórz instancję główną w klastrze AlloyDB. Jest to rzeczywisty punkt końcowy bazy danych, z którym będą się łączyć Twoje aplikacje. Aby utworzyć instancję AlloyDB, uruchom to polecenie:

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

Uwaga: utworzenie instancji może potrwać około 10 minut. Zanim przejdziesz dalej, poczekaj na zakończenie tej operacji.

Włącz integrację z Vertex AI

Aby umożliwić instancji AlloyDB wykonywanie zapytań dotyczących wyszukiwania wektorowego (które są niezbędne w przypadku funkcji AI, takich jak wyszukiwanie semantyczne) i wywoływanie modeli wdrożonych w Vertex AI, musisz przyznać agentowi usługi AlloyDB uprawnienia do Vertex AI.

Najpierw pobierz numer projektu Google Cloud, ponieważ jest on wymagany w przypadku powiązania IAM.

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

Następnie przyznaj usłudze Vertex AI uprawnienia do agenta usługi AlloyDB:

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

Włącz publiczny adres IP

Aby przygotować się do wykonania kolejnych kroków, włączymy w instancji AlloyDB łączność z publicznym adresem IP.

W konsoli przejdź do pola wyszukiwania u góry pośrodku ekranu i wpisz „alloydb”, a następnie otwórz sekcję Łączność z publicznym adresem IP. Zaznacz pole wyboru „Włącz publiczny adres IP” i wpisz adres IP maszyny Cloud Shell.

Aby uzyskać adres IP maszyny Cloud Shell, otwórz terminal Cloud Shell i wpisz polecenie „ifconfig | grep -A 1 eth0”. W wyniku zastąp 2 ostatnie cyfry wartością 0.0 z rozmiarem maski „/16”. Na przykład może to być „XX.XX.0.0/16”, gdzie XX to liczby.

Wklej ten adres IP w polu tekstowym „Sieci” w sekcji Autoryzowane sieci zewnętrzne na stronie edycji instancji.

Uwaga: operacja aktualizacji może potrwać do 3 minut.

4. Wczytywanie bazy danych

Tworzenie bazy danych sklepu

Teraz możesz utworzyć bazę danych i wczytać do niej dane początkowe dla sklepu sportowego.

Aby umożliwić psql łączenie się z prywatną instancją AlloyDB z Cloud Shell, użyjesz serwera proxy uwierzytelniania AlloyDB. To narzędzie bezpiecznie tuneluje połączenie z bazą danych. (Patrz serwer proxy uwierzytelniania AlloyDB).

Pobierz serwer proxy uwierzytelniania AlloyDB za pomocą tego polecenia:

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

Ustaw plik jako wykonywalny:

chmod +x alloydb-auth-proxy

Uruchom to polecenie w pierwszym oknie terminala Cloud Shell. Serwer proxy będzie działać w tle i przekazywać połączenia.

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

Ważne: pozostaw to okno terminala otwarte i uruchomione z serwerem proxy. Nie zamykaj go.

Otwórz nowe okno terminala w Cloud Shell (kliknij ikonę + obok karty „Terminal Cloud Shell” u góry).

Połącz się z instancją AlloyDB za pomocą psql:

psql -h 127.0.0.1 -U postgres

Uwaga: gdy pojawi się prośba, wpisz hasło ustawione dla użytkownika postgres podczas tworzenia klastra (jeśli postępujesz zgodnie z dokumentacją, hasło to alloydb).

Utwórz bazę danych sklepu dla naszej aplikacji (uruchamiaj polecenia kolejno):

CREATE DATABASE store;
\c store
exit

Source Code

Teraz sklonuj repozytorium kodu źródłowego codelabu. Przed sklonowaniem repozytorium upewnij się, że jesteś w katalogu głównym lub w odpowiednim miejscu, a następnie uruchom to polecenie:

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

Wypełnianie bazy danych

Przejdź do folderu data w sklonowanym projekcie, aby uzyskać dostęp do pliku zrzutu bazy danych.

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

Następnie zaimportuj przykładowy zbiór danych do bazy danych store, używając pliku store_backup.sql z repozytorium.

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

Uwaga: podczas importowania mogą się pojawić komunikaty OSTRZEŻENIE i BŁĄD, które w tym przypadku można bezpiecznie zignorować. Często dotyczą one uprawnień lub obiektów, które już istnieją, jeśli zrzut zawiera pełny schemat. Znajdziesz w nim ostrzeżenia i błędy, które można zignorować.

5. Konfigurowanie usługi autoryzacji

W tej sekcji skonfigurujesz usługę autoryzacji dla swojej aplikacji. Ta usługa ma kluczowe znaczenie dla zabezpieczenia dostępu i zapewnienia ochrony przed lukami w zabezpieczeniach związanymi z wstrzykiwaniem promptów w agencie AI.

Najpierw dodasz przykładowego użytkownika do tabeli users w bazie danych store. Ten użytkownik będzie używany do uwierzytelniania w Twojej aplikacji.

Otwórz konsolę i przejdź do AlloyDB, wybierz instancję główną, a następnie AlloyDB Studio:

Gdy pojawi się odpowiedni komunikat, zaloguj się w AlloyDB Studio, używając danych logowania, które utworzono podczas konfigurowania klastra:

Nazwa użytkownika: „postgres”
Baza danych: „store”
Hasło: „alloydb”

W edytorze SQL wykonaj instrukcję INSERT, aby dodać użytkownika do bazy danych. Zmień imię i nazwisko oraz adres e-mail.

Ważne:

Zachowaj LOKALIZACJĘ w takiej formie, jak w przykładzie.
Użyj tego samego adresu e-mail, którego używasz do rejestracji w Google Cloud Console.

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');

Następnie musisz skonfigurować ekran zgody OAuth w projekcie. Ten ekran jest wyświetlany użytkownikom, gdy aplikacja prosi o dostęp do ich konta Google. Określa on markę aplikacji.

W konsoli kliknij „Interfejsy API i usługi” oraz „Zgoda użytkownika na dostęp do danych w Google OAuth”:

Aby utworzyć markę aplikacji, podaj te informacje:

Nazwa aplikacji: „Sports Shopping Agent AI”
Adres e-mail dla użytkowników potrzebujących pomocy: „YOUR_EMAIL”
Odbiorcy: „Zewnętrzni”
Informacje kontaktowe: „YOUR_EMAIL”

Teraz utworzysz identyfikator klienta OAuth, którego aplikacja front-end będzie używać do weryfikowania tożsamości użytkownika w Google.

Najpierw sprawdź, czy masz numer projektu Google Cloud. Jest to wymagane do prawidłowego skonfigurowania identyfikatorów URI przekierowania. Uruchom to polecenie w terminalu Cloud Shell:

Jeśli zmienna PROJECT_ID nie jest ustawiona w tym oknie terminala Cloud Shell, wykonaj to polecenie:

export PROJECT_ID=[YOUR_PROJECT_ID]

Następnie uzyskaj PROJECT_NUMBER za pomocą tego polecenia:

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

Następnie wybierz kolejno „Interfejsy API i usługi” –> „Dane logowania” –> „Utwórz dane logowania” –> „Identyfikator klienta OAuth”.

Aby utworzyć dane logowania, użyj tych informacji:

Typ aplikacji: „Aplikacja internetowa”
Nazwa: „Sports Shopping Agent AI App”

Autoryzowane źródła JavaScriptu:

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

Autoryzowane identyfikatory URI przekierowania:

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

Uwaga: adres URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app to oczekiwany adres URL wdrożenia aplikacji front-end, który skonfigurujesz w dalszej części tego samouczka. Pamiętaj, aby zastąpić [YOUR_PROJECT_NUMBER] skopiowanym numerem.

Ważne: po utworzeniu pojawi się wyskakujące okienko z identyfikatorem klienta OAuth, a czasami także z tajnym kluczem klienta. Przechowuj identyfikator klienta OAuth w bezpiecznym miejscu, ponieważ będzie on potrzebny w późniejszym kroku podczas konfigurowania interfejsu.

6. Konfiguracja MCP ToolBox for Databases

Toolbox znajduje się między platformą orkiestracji aplikacji a bazą danych, zapewniając płaszczyznę sterowania, która służy do modyfikowania, rozpowszechniania i wywoływania narzędzi. Upraszcza zarządzanie narzędziami, ponieważ zapewnia centralną lokalizację do przechowywania i aktualizowania narzędzi. Umożliwia też udostępnianie narzędzi agentom i aplikacjom oraz aktualizowanie ich bez konieczności ponownego wdrażania aplikacji.

Jedną z baz danych obsługiwanych przez MCP Toolbox for Databases jest AlloyDB, którą skonfigurowaliśmy w poprzedniej sekcji. Przejdźmy więc do konfiguracji Toolbox.

Najpierw skonfigurujesz serwer MCP Toolbox lokalnie w środowisku Cloud Shell, aby sprawdzić jego działanie.

W terminalu Cloud Shell przejdź do folderu toolbox znajdującego się w sklonowanym repozytorium projektu:

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

Aby pobrać plik binarny Toolbox i przyznać mu uprawnienia do wykonywania, uruchom te polecenia:

# 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

Uwaga: w tym przykładzie określono wersję 0.7.0. W środowiskach produkcyjnych zawsze sprawdzaj i używaj najnowszej stabilnej wersji ze strony z wersjami Zestawu narzędzi.

Otwórz edytor Cloud Shell (możesz przełączać się z terminala, klikając ikonę edytora).

W tym samym katalogu sports-agent-adk-mcp-alloydb/src/toolbox znajdziesz plik o nazwie tools.yaml. Otwórz ten plik i zastąp symbole zastępcze identyfikatorem klienta OAuth i identyfikatorem projektu Google Cloud z poprzednich kroków.

Omówienie pliku tools.yaml

Źródła to różne źródła danych, z którymi narzędzie może wchodzić w interakcje. Źródło to źródło danych, z którym narzędzie może wchodzić w interakcje. Źródła możesz zdefiniować jako mapę w sekcji źródeł w pliku tools.yaml. Zwykle konfiguracja źródła zawiera wszystkie informacje potrzebne do połączenia z bazą danych i korzystania z niej.

Narzędzia określają działania, które może wykonać agent, np. odczytywanie i zapisywanie danych w źródle. Narzędzie reprezentuje działanie, które może wykonać agent, np. uruchomienie instrukcji SQL. Narzędzia możesz zdefiniować jako mapę w sekcji narzędzi w pliku tools.yaml. Zwykle narzędzie wymaga źródła, na którym ma działać.

Więcej informacji o konfigurowaniu pliku tools.yaml znajdziesz w tej dokumentacji.

Uruchamianie Zestawu narzędzi MCP dla serwera baz danych

Aby uruchomić serwer, wykonaj to polecenie (w folderze mcp-toolbox):

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

Jeśli teraz otworzysz serwer w trybie podglądu w chmurze, powinien być on uruchomiony i zawierać wszystkie narzędzia naszej aplikacji.

Serwer MCP Toolbox działa domyślnie na porcie 5000. Aby to przetestować, użyjemy Cloud Shell.

W Cloud Shell kliknij Podgląd w przeglądarce, jak pokazano poniżej:

Kliknij Zmień port i ustaw port na 5000, jak pokazano poniżej, a następnie kliknij Zmień i wyświetl podgląd.

Powinny się pojawić te wyniki:

Zestaw narzędzi MCP do baz danych zawiera opis pakietu SDK w Pythonie, który umożliwia weryfikowanie i testowanie narzędzi. Dokumentację znajdziesz tutaj. Pominiemy to i w następnej sekcji przejdziemy bezpośrednio do zestawu Agent Development Kit (ADK), który wykorzystuje te narzędzia.

Wdrażanie przybornika w Cloud Run

Aby serwer Toolbox był dostępny jako publiczny punkt końcowy, który można zintegrować z innymi aplikacjami i agentem AI, wdrożysz go w Cloud Run. Szczegółowe instrukcje dotyczące hostowania pakietu narzędzi w Cloud Run znajdziesz tutaj.

Wróć do terminala Cloud Shell i przejdź do folderu z narzędziami:

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

Sprawdź, czy zmienna środowiskowa PROJECT_ID jest ustawiona na identyfikator Twojego projektu Google Cloud.

export PROJECT_ID=$PROJECT_ID

Następnie sprawdź, czy w projekcie są włączone te usługi Google Cloud:

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

Utwórzmy osobne konto usługi, które będzie tożsamością usługi Toolbox, którą wdrożymy w Google Cloud Run. Dbamy też o to, aby to konto usługi miało odpowiednie role, czyli możliwość dostępu do Secret Managera i komunikowania się z 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'

Następnie prześlesz plik tools.yaml jako klucz tajny. Ponieważ musimy zainstalować Toolbox w Cloud Run, użyjemy najnowszego obrazu kontenera dla Toolbox i ustawimy go w zmiennej IMAGE.

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

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

Na koniec wdróż serwer Toolbox w Cloud Run za pomocą tego polecenia. To polecenie umieści aplikację w kontenerze, skonfiguruje konto usługi, wstrzyknie klucz tajny i udostępni go publicznie:

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

Powinno to rozpocząć proces wdrażania serwera Toolbox z naszym skonfigurowanym plikiem tools.yaml w Cloud Run. Po pomyślnym wdrożeniu powinien wyświetlić się komunikat podobny do tego:

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

Możesz teraz otworzyć w przeglądarce podany wyżej adres URL usługi. Powinien wyświetlić się komunikat „Hello World”, który widzieliśmy wcześniej. Możesz też otworzyć ten adres URL, aby zobaczyć dostępne narzędzia:

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

Możesz też otworzyć Cloud Run w konsoli Google Cloud. Usługa Toolbox będzie widoczna na liście usług w Cloud Run.

7. Agent utworzony na platformie ADK

W tej sekcji wdrożysz w Cloud Run agenta AI utworzonego za pomocą pakietu Agent Development Kit (ADK).

Najpierw włącz w projekcie niezbędne interfejsy API do tworzenia i wdrażania agenta w Cloud Run oraz do interakcji z Artifact Registry i Cloud Storage. Uruchom to polecenie w terminalu Cloud Shell:

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

Następnie przypiszemy niezbędne uprawnienia do domyślnego konta usługi Compute w naszym projekcie. Najpierw uruchom to polecenie w terminalu Cloud Shell, aby uzyskać PROJECT_NUMBER:

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

Przypisz uprawnienia do domyślnego konta usługi Compute:

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

Łączenie naszego agenta z narzędziami

Połączymy agenta z narzędziami. W kontekście ADK narzędzie reprezentuje konkretną funkcję udostępnianą agentowi AI, która umożliwia mu wykonywanie działań i interakcje ze światem wykraczające poza podstawowe możliwości generowania tekstu i wnioskowania.

W tym przypadku wyposażymy naszego agenta w narzędzia, które skonfigurowaliśmy w MCP Toolbox for Databases.

W edytorze Cloud Shell przejdź do katalogu sports-agent-adk-mcp-alloydb/src/backend/ i zmodyfikuj plik „finn_agent.py”, dodając do niego ten kod: Zwróć uwagę, że używamy adresu URL usługi Cloud Run z serwera MCP ToolBox wdrożonego w poprzednim kroku:

Wdrażanie agenta w Cloud Run

Na koniec wdrożysz skonfigurowanego agenta AI w Cloud Run, dzięki czemu będzie on dostępny przez punkt końcowy HTTP.

Najpierw utwórz repozytorium Dockera w Artifact Registry, w którym będziesz zapisywać obrazy kontenerów agenta. Uruchom to polecenie w Cloud Shell:

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

Następnie za pomocą Cloud Build utwórz obraz Dockera dla agenta. Uruchom to polecenie w katalogu głównym sklonowanego projektu (sports-agent-adk-mcp-alloydb/):

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

Teraz wdróż usługę agenta. To polecenie utworzy usługę Cloud Run, pobierze obraz z Artifact Registry i skonfiguruje zmienne środowiskowe.

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"

Uwaga: dynamicznie ustawiamy zmienne środowiskowe, w tym GOOGLE_CLOUD_PROJECT (za pomocą zmiennej powłoki $PROJECT_ID).

Powinny pojawić się wyniki podobne do tych, które wskazują na pomyślne wdrożenie agenta:

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

Na koniec przetestuj agenta, wykonując to polecenie curl w terminalu Cloud Shell:

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

Wynik będzie podobny do tego:

„Cześć! Jestem Finn, Twój asystent AI do zakupów sportowych. Mogę pomóc Ci znaleźć produkty, sprzęt i wyposażenie sportowe. W czym mogę Ci pomóc?

Na tym etapie udało Ci się zweryfikować wdrożenie AlloyDB, MCP Toolbox i agenta utworzonego za pomocą ADK.

8. Wdrażanie frontendu

W tej sekcji wdrożysz konwersacyjny interfejs użytkownika dla asystenta AI w Cloud Run. Interfejs został utworzony przy użyciu Reacta i JavaScriptu.

Przed wdrożeniem musisz zaktualizować kod źródłowy frontendu, podając w nim adresy URL wdrożonego agenta i identyfikator klienta OAuth.

W edytorze Cloud Shell przejdź do folderu sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ i otwórz plik Home.jsx. Musisz zaktualizować symbol zastępczy adresu URL usługi Cloud Run agenta. Następnie zastąp go adresem URL usługi Cloud Run agenta z poprzedniego kroku (np. https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Następnie przejdź do folderu sports-agent-adk-mcp-alloydb/src/frontend/src/components/ i otwórz plik GoogleSignInButton.jsx. Zaktualizuj ten plik za pomocą identyfikatora klienta OAuth uzyskanego w sekcji „Konfiguracja usługi autoryzacji”:

Wdrażanie frontendu w Cloud Run

Aplikacja frontendowa jest już skonfigurowana, więc możesz ją wdrożyć w Cloud Run.

Aby utworzyć w Artifact Registry repozytorium Dockera na potrzeby obrazów frontendu, uruchom to polecenie w terminalu Cloud Shell z katalogu głównego (sports-agent-adk-mcp-alloydb/).

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

Następnie za pomocą Cloud Build utworzysz obraz Dockera dla aplikacji frontendu. Uruchom to polecenie w katalogu głównym projektu:

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

Na koniec wdrożymy frontend w Cloud Run za pomocą tego polecenia:

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

Powinien pojawić się wynik podobny do tego, który wskazuje, że frontend został wdrożony:

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

Otwórz przeglądarkę i użyj adresu URL usługi z poprzedniego kroku, aby otworzyć nowo wdrożoną aplikację obsługiwaną przez agenta AI.

9. Uruchamianie naszego agenta

Asystent AI Twojego sklepu sportowego, Finn, jest już w pełni wdrożony i gotowy do pomocy przy zakupach.

Otwórz przeglądarkę i przejdź do adresu URL usługi aplikacji front-end z poprzedniego kroku. Adres URL ma format: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Po wczytaniu interfejsu kliknij przycisk w prawym górnym rogu (zwykle oznaczony jako „Zaloguj się” lub podobny), aby uwierzytelnić się za pomocą danych logowania Google. To działanie wykorzysta konfigurację OAuth, którą skonfigurowano wcześniej.

Po pomyślnej autoryzacji możesz zacząć korzystać z usługi Finn. Aby rozpocząć zakupy konwersacyjne, kliknij przycisk „Kup teraz”.

Aby przetestować różne funkcje agenta AI, użyj tego skryptu. Skopiuj i wklej te prompty do interfejsu czatu jeden po drugim:

Cześć Finn!
Szukam butów do biegania w terenie na ultra-trail.
Więcej informacji o Ultra Glide
Dodaj do listy zakupów Ultra Glide w rozmiarze 40 w kolorze czerwono-szarym
Pokaż moją listę zakupów
Znajdowanie sklepów w pobliżu
Złóż zamówienie na podstawie mojej listy zakupów w sklepie Sports Diagonal Mar.
Sprawdzanie stanu zamówień
Podaj metody dostawy dla sklepu Sports Diagonal Mar
Zaktualizuj metodę dostawy na dostawę ekspresową dla zamówienia [YOUR_ORDER_NUMBER]
Sprawdzanie stanu zamówień
Dziękuję, Finn!

Aby zobaczyć wizualną prezentację wdrożonego agenta Finn i jego możliwości, obejrzyj poniższy film:

Prezentacja asystenta AI dla agenta sportowego opartego na AlloyDB

10. Wyniki

Po wykonaniu poprzedniego skryptu udało Ci się zweryfikować pełną integrację agenta ADK, jego połączenie z AlloyDB i korzystanie z MCP Toolbox. W tej sekcji znajdziesz najważniejsze wdrożone funkcje.

Usługa autoryzacji

MCP Toolbox for Databases umożliwia federację usługi autoryzacji (w tym przypadku logowania przez Google) w celu uwierzytelniania użytkowników w aplikacji. W przypadku MCP Toolbox identyfikator klienta OAuth służy do weryfikowania tożsamości użytkownika podczas wywoływania narzędzia.

Ten solidny mechanizm uwierzytelniania to doskonałe rozwiązanie do ochrony aplikacji opartej na agentach przed wstrzykiwaniem promptów, czyli rodzajem ataku, w którym złośliwe dane wejściowe próbują ominąć lub zmanipulować zamierzone działanie agenta. Więcej informacji znajdziesz w artykule w Wikipedii na temat wstrzykiwania promptów .

W tej aplikacji ta technika jest wykorzystywana, gdy użytkownik prosi o „sprawdzenie stanu zamówień” lub „wyświetlenie listy zakupów”. Agent został zaprojektowany tak, aby wyświetlać tylko zamówienia należące do uwierzytelnionego użytkownika, co zapobiega nieautoryzowanemu dostępowi do informacji o zamówieniach.

Wyszukiwanie wektorowe

Aplikacja agentowa korzysta z AlloyDB for PostgreSQL, aby zapewniać zaawansowane możliwości zapytań, zwłaszcza za pomocą wyszukiwania wektorowego. AlloyDB obsługuje generowanie osadzania online bezpośrednio w bazie danych za pomocą funkcji SQL.

Ta zaawansowana funkcja umożliwia agentowi przetłumaczenie danych wejściowych użytkownika w języku naturalnym na reprezentację w postaci osadzenia numerycznego. Następnie może przeprowadzić wyszukiwanie podobieństw w katalogu produktów (lub innych odpowiednich danych) na podstawie tych wektorów, co umożliwia uzyskanie bardzo trafnych wyników wyszukiwania.

W aplikacji możesz wypróbować tę technikę, zadając Finnowi pytanie: „Szukam butów do biegania na ultra-trail”.

Funkcje geoprzestrzenne (PostGIS)

AlloyDB for PostgreSQL zachowuje 100% zgodności ze standardowymi funkcjami PostgreSQL. W tej aplikacji używamy popularnego rozszerzenia PostgreSQL PostGIS, aby zapewnić agentowi funkcje lokalizacji geoprzestrzennej.

Gdy zapytasz agenta: „Znajdź sklepy w pobliżu”, uruchomi on narzędzie, które wykorzystuje indeksy PostGIS w bazie danych, aby skutecznie lokalizować sklepy najbliższe określonej lub wywnioskowanej lokalizacji użytkownika.

11. (Opcjonalnie) Testowanie funkcji AlloyDB AI Natural Language to SQL

W tej sekcji przedstawiamy zaawansowaną funkcję AlloyDB for PostgreSQL w wersji przed GA: Natural Language to SQL. Ta funkcja umożliwia generowanie zapytań SQL bezpośrednio z promptów w języku naturalnym, wykorzystując możliwości AI w bazie danych.

Ważne: ponieważ jest to funkcja w wersji przed GA, musisz się zarejestrować i włączyć dostęp do niej w przypadku projektu w Google Cloud, klastra AlloyDB i bazy danych.

Rejestracja w celu uzyskania dostępu: aby poprosić o dostęp do projektu, wypełnij ten formularz.
Dokumentacja: więcej informacji o korzystaniu z funkcji AlloyDB AI Natural Language to SQL znajdziesz w oficjalnej dokumentacji.

Po zarejestrowaniu się i potwierdzeniu dostępu do projektu wykonaj w AlloyDB Studio te czynności:

Zaloguj się w AlloyDB, używając danych logowania utworzonych podczas tworzenia klastra:

Nazwa użytkownika: „postgres”
Baza danych: „store”
Hasło: „alloydb”

1. Utwórz rozszerzenie alloydb_ai_nl. To rozszerzenie udostępnia funkcje niezbędne do korzystania z funkcji języka naturalnego AlloyDB AI.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Utwórz konfigurację aplikacji. Konfiguracja określa kontekst schematu, którego model AI będzie używać do interpretowania bazy danych.

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

3. Zarejestruj schemat lub tabele w konfiguracji. Dodaj do konfiguracji konkretne tabele i schematy, z którymi będzie wchodzić w interakcję agent aplikacji.

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. Wygeneruj kontekst dla schematu lub tabel. W tym kroku przetwarzane są zarejestrowane tabele, aby wygenerować niezbędny kontekst dla modelu AI. Ten proces może potrwać około 2–3 minut.

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

5. Sprawdź automatycznie wygenerowany kontekst dla poszczególnych tabel i kolumn (opcjonalnie). Możesz sprawdzić wygenerowany kontekst, aby dowiedzieć się, jak model AI interpretuje Twój schemat.

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';

W pliku „tools.yaml” naszego agenta znajdziesz narzędzie o nazwie „check-inventory-by-store-brand-category”. To narzędzie korzysta z funkcji AlloyDB Natural Language to SQL:

Otwórz przeglądarkę i użyj adresu URL usługi, aby otworzyć aplikację: „https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app”.

Następnie użyj tego skryptu w interfejsie czatu, aby przetestować tę nową funkcję:

Cześć Finn!
Jaka jest łączna liczba produktów marki Salomon z kategorii Bieganie dostępnych w sklepie „Sports Diagonal Mar”?

Aby zobaczyć rzeczywiste zapytanie SQL wygenerowane przez AlloyDB AI na podstawie danych wejściowych w języku naturalnym, wróć do AlloyDB Studio i wykonaj to zapytanie:

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';

Wyświetli się instrukcja SQL wygenerowana przez AlloyDB AI.

12. Czyszczenie

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym laboratorium, wykonaj te czynności:

W konsoli Google Cloud otwórz stronę Zarządzanie zasobami.
Na liście projektów wybierz projekt, który chcesz usunąć, a następnie kliknij Usuń.
W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.

13. Gratulacje

Gratulacje! Udało Ci się utworzyć aplikację opartą na danych z agentową AI za pomocą ADK, MCP Toolbox for Databases i AlloyDB for PostgreSQL.

Więcej informacji znajdziesz w dokumentacji produktów: Agent Development Kit, MCP Toolbox for Databases i AlloyDB for PostgreSQL.