Membangun Asisten AI Agen Toko Olahraga dengan ADK, MCP Toolbox, dan AlloyDB

1. Pengantar

Yang akan Anda bangun

Dalam codelab ini, Anda akan mempelajari cara membuat asisten AI Agen Toko Olahraga. Aplikasi AI Agen generasi berikutnya ini, yang didukung oleh ADK, MCP Toolbox, dan AlloyDB, akan membantu pengguna dalam berbagai tugas, termasuk:

  • Menelusuri produk menggunakan bahasa alami.
  • Menemukan toko terdekat untuk membeli produk yang direkomendasikan.
  • Melakukan pesanan baru.
  • Memeriksa status pesanan yang ada.
  • Memperbarui pesanan dengan metode pengiriman pilihan.

7d9b5c1b10d1c654.png

Yang akan Anda pelajari

  • Menyediakan dan mengisi database AlloyDB untuk PostgreSQL.
  • Menyiapkan MCP Toolbox for Databases dengan instance AlloyDB untuk PostgreSQL.
  • Mendesain dan mengembangkan Agen AI menggunakan Agent Development Kit (ADK) untuk membantu menjawab kueri toko olahraga.
  • Menguji Agent dan MCP Toolbox for Databases di lingkungan cloud.
  • Memanfaatkan kemampuan kueri lanjutan AlloyDB untuk respons agen cerdas.

Yang Anda butuhkan

Untuk menyelesaikan codelab ini, Anda memerlukan:

  • Browser web Chrome.
  • Akun Gmail.
  • Project Google Cloud yang mengaktifkan penagihan.

Codelab ini dirancang untuk developer dari semua level, termasuk para pemula.

2. Sebelum memulai

Bagian ini memandu Anda melakukan penyiapan awal yang diperlukan di Project Google Cloud sebelum Anda dapat mulai membangun asisten AI Agen Toko Olahraga.

Membuat project

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project .
  3. Aktifkan Cloud Shell dengan mengklik link ini. Anda dapat beralih antara Terminal Cloud Shell (untuk menjalankan perintah cloud) dan Editor (untuk membangun project) dengan mengklik tombol yang sesuai dari Cloud Shell.

e44cf973ddf8b70f.png

  1. Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:
gcloud auth list
  1. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.
gcloud config list project
  1. Tetapkan variabel PROJECT_ID, gunakan perintah berikut untuk menetapkannya:
export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID
  1. Aktifkan API berikut dengan menjalankan perintah berikut:
gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. Buat Instance AlloyDB

Di bagian ini, Anda akan menyiapkan cluster dan instance database AlloyDB, serta mengonfigurasi jaringan dan izin yang diperlukan untuk Agen AI Anda.

Pertama, jalankan perintah berikut di terminal Cloud Shell untuk membuat Cluster AlloyDB:

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

AlloyDB mengandalkan konektivitas IP pribadi untuk akses yang aman dan berperforma tinggi. Anda perlu mengalokasikan rentang IP pribadi dalam VPC agar Google dapat menggunakannya untuk koneksi peering layanan ke infrastruktur jaringan layanan yang dikelola Google. Jalankan perintah berikut:

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

Selanjutnya, buat koneksi VPC Service Peering. Hal ini memungkinkan jaringan Virtual Private Cloud (VPC) Google Cloud Anda berkomunikasi secara aman dan pribadi dengan layanan terkelola Google, termasuk AlloyDB. Jalankan perintah berikut:

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

Sekarang, buat instance utama dalam cluster AlloyDB Anda. Ini adalah endpoint database sebenarnya yang akan dihubungkan oleh aplikasi Anda. Jalankan perintah berikut untuk membuat Instance AlloyDB:

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

Catatan: Pembuatan instance dapat memerlukan waktu sekitar 10 menit. Harap tunggu hingga operasi ini selesai sebelum melanjutkan.

Mengaktifkan Integrasi Vertex AI

Untuk mengizinkan instance AlloyDB Anda melakukan kueri penelusuran vektor (yang penting untuk fungsi AI seperti penelusuran semantik) dan memanggil model yang di-deploy di Vertex AI, Anda harus memberikan izin Vertex AI ke Agen Layanan AlloyDB.

Pertama, ambil Nomor Project Google Cloud Anda, karena diperlukan untuk binding IAM.

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

Kemudian, berikan izin Vertex AI ke Agen Layanan AlloyDB:

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

Mengaktifkan IP Publik

Sebagai persiapan untuk langkah-langkah berikutnya, kita akan mengaktifkan Konektivitas IP Publik di instance AlloyDB.

Di Konsol, buka kolom penelusuran di bagian tengah atas layar dan masukkan "alloydb", lalu edit dan buka bagian konektivitas IP Publik. Centang kotak "Enable Public IP" dan masukkan alamat IP mesin Cloud Shell Anda.

c200ee8f8b776ed4.png

Untuk mendapatkan IP mesin Cloud Shell Anda, buka Terminal Cloud Shell dan masukkan perintah "ifconfig | grep -A 1 eth0". Dari hasilnya, ganti 2 digit terakhir dengan 0.0 dengan ukuran mask '/16'. Misalnya, akan terlihat seperti "XX.XX.0.0/16" dengan XX adalah angka.

Tempelkan IP ini di kotak teks "Jaringan" pada Jaringan eksternal yang diizinkan di halaman edit instance.

a274101902019848.png

Catatan: Operasi update dapat memerlukan waktu hingga 3 menit

4. Memuat Database

Membuat database toko

Sekarang saatnya membuat database dan memuat data awal untuk Toko Olahraga Anda.

Untuk mengizinkan psql terhubung ke instance AlloyDB pribadi Anda dari Cloud Shell, Anda akan menggunakan Proxy Auth AlloyDB. Utilitas ini membuat tunnel koneksi Anda ke database dengan aman. (Lihat Proxy Auth AlloyDB)

Download Proxy Auth AlloyDB menggunakan perintah berikut:

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

Buat agar dapat dieksekusi:

chmod +x alloydb-auth-proxy

Jalankan perintah ini di jendela terminal Cloud Shell pertama Anda. Proxy akan berjalan di latar belakang dan meneruskan koneksi.

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

Penting: Biarkan jendela terminal ini tetap terbuka dan menjalankan proxy. Jangan tutup.

Buka jendela terminal baru di Cloud Shell (klik ikon + di samping tab "Cloud Shell Terminal" di bagian atas).

4495f22b29cd62e8.png

Hubungkan ke Instance AlloyDB menggunakan psql:

psql -h 127.0.0.1 -U postgres

Catatan: Saat diminta, masukkan sandi yang Anda tetapkan untuk pengguna postgres selama pembuatan cluster (jika Anda mengikuti dokumentasi secara langsung, sandinya adalah alloydb).

Kemudian, buat database penyimpanan untuk aplikasi kita (jalankan perintah satu per satu):

CREATE DATABASE store;
\c store
exit

Kode Sumber

Sekarang, clone repositori kode sumber codelab. Pastikan Anda berada di direktori beranda atau lokasi yang sesuai sebelum meng-clone dan menjalankan perintah berikut:

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

Mengisi database

Buka folder data project yang di-clone untuk mengakses file dump database.

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

Kemudian, impor set data contoh ke dalam database store menggunakan file store_backup.sql dari repositori.

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

Catatan: Anda mungkin melihat beberapa pesan PERINGATAN dan ERROR selama impor ini, yang dapat diabaikan dengan aman untuk codelab ini. Hal ini sering kali terkait dengan izin atau objek yang sudah ada jika dump berisi skema lengkap.Anda akan menemukan beberapa PERINGATAN dan ERROR yang dapat diabaikan

5. Penyiapan Layanan Otorisasi

Di bagian ini, Anda akan menyiapkan Layanan Otorisasi untuk aplikasi Anda. Layanan ini sangat penting untuk mengamankan akses dan memberikan perlindungan terhadap kerentanan injeksi perintah di Agen AI Anda.

Pertama, Anda akan menambahkan pengguna contoh ke tabel users di database store. Pengguna ini akan digunakan untuk autentikasi di aplikasi Anda.

Buka konsol dan buka AlloyDB, pilih instance utama, lalu AlloyDB Studio:

a15964d53b4b15e1.png

Saat diminta, login ke AlloyDB Studio menggunakan kredensial yang Anda buat saat menyiapkan cluster:

  • Nama pengguna: "postgres"
  • Database: "store"
  • Sandi: "alloydb"

Di Editor SQL, jalankan pernyataan INSERT untuk menambahkan pengguna Anda ke database. Ubah nama dan nama belakang serta alamat email.

Penting:

  • Biarkan LOCATION seperti pada contoh
  • Gunakan alamat email yang sama dengan yang Anda gunakan untuk mendaftar di Konsol Google Cloud
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');

Selanjutnya, Anda perlu mengonfigurasi Layar Izin OAuth untuk project Anda. Layar ini ditampilkan kepada pengguna saat aplikasi Anda meminta akses ke Akun Google mereka dan menentukan merek aplikasi Anda.

Di Konsol, buka "APIs and Services", "Google OAuth Consent":

cb4db28df92abcb2.png

Berikan informasi berikut untuk membuat merek aplikasi Anda:

  • Nama Aplikasi: "Sports Shopping Agent AI"
  • Email dukungan pengguna: "YOUR_EMAIL"
  • Audiens: "Eksternal"
  • Informasi Kontak: "EMAIL_ANDA"

Sekarang, Anda akan membuat Client ID OAuth yang akan digunakan aplikasi frontend Anda untuk memvalidasi identitas pengguna dengan Google.

Pertama, pastikan Anda memiliki Nomor Project Google Cloud. Hal ini diperlukan untuk mengonfigurasi URI pengalihan dengan benar. Jalankan perintah berikut di Terminal Cloud Shell:

Jika variabel PROJECT_ID Anda tidak ditetapkan di jendela Terminal Cloud Shell ini, jalankan:

export PROJECT_ID=[YOUR_PROJECT_ID]

Kemudian, dapatkan PROJECT_NUMBER menggunakan perintah berikut:

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

Kemudian, buka "API dan Layanan" -> "Kredensial" -> "Buat Kredensial" -> "ID Klien OAuth"

45623e96d417192d.png

Gunakan informasi berikut untuk membuat kredensial:

  • Jenis aplikasi: "Web Application"
  • Nama: "Sports Shopping Agent AI App"

Asal JavaScript resmi:

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

URI pengalihan yang sah:

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

Catatan: URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app adalah URL deployment yang diharapkan untuk aplikasi frontend Anda, yang akan disiapkan nanti dalam codelab ini. Pastikan Anda mengganti [YOUR_PROJECT_NUMBER] dengan nomor sebenarnya yang Anda salin.

1873d292fd27f07c.png

Penting: Setelah pembuatan, pop-up akan menampilkan Client ID OAuth dan, terkadang, Client Secret Anda. Simpan Client ID OAuth Anda di tempat yang aman, karena Anda akan memerlukannya pada langkah selanjutnya saat mengonfigurasi frontend.

6. Penyiapan MCP ToolBox for Databases

Toolbox berada di antara framework orkestrasi aplikasi dan database Anda, menyediakan bidang kontrol yang digunakan untuk mengubah, mendistribusikan, atau memanggil alat. Hal ini menyederhanakan pengelolaan alat Anda dengan memberi Anda lokasi terpusat untuk menyimpan dan memperbarui alat, sehingga Anda dapat membagikan alat di antara agen dan aplikasi serta memperbarui alat tersebut tanpa perlu men-deploy ulang aplikasi Anda.

Karena salah satu database yang didukung oleh MCP Toolbox for Databases adalah AlloyDB, dan kita telah menyediakannya di bagian sebelumnya, mari kita siapkan Toolbox.

26596138ffc32d98.png

Pertama, Anda akan menyiapkan server MCP Toolbox secara lokal di lingkungan Cloud Shell untuk memverifikasi fungsinya.

  1. Di Terminal Cloud Shell, buka folder toolbox yang ada di repositori project yang di-clone:"
cd sports-agent-adk-mcp-alloydb/src/toolbox
  1. Jalankan perintah berikut untuk mendownload biner Toolbox dan memberikan izin eksekusi:
# 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

Catatan: Versi 0.7.0 ditentukan di sini. Untuk lingkungan produksi, selalu verifikasi dan gunakan rilis stabil terbaru dari halaman rilis Toolbox.

  1. Buka Cloud Shell Editor (Anda dapat beralih dari Terminal dengan mengklik ikon Editor).

4000e21f50fa507e.png

Di direktori sports-agent-adk-mcp-alloydb/src/toolbox yang sama, Anda akan menemukan file bernama tools.yaml. Buka file ini dan perbarui placeholder dengan Client ID OAuth dan Project ID Google Cloud Anda dari langkah sebelumnya.

4c0008d3d0f3bcfb.png

Mari kita pahami tools.yaml

Sumber mewakili berbagai sumber data yang dapat berinteraksi dengan alat. Sumber merepresentasikan sumber data yang dapat berinteraksi dengan alat. Anda dapat menentukan Sumber sebagai peta di bagian sumber file tools.yaml. Biasanya, konfigurasi sumber akan berisi informasi apa pun yang diperlukan untuk terhubung dan berinteraksi dengan database.

Alat menentukan tindakan yang dapat dilakukan agen – seperti membaca dan menulis ke sumber. Alat merepresentasikan tindakan yang dapat dilakukan agen Anda, seperti menjalankan pernyataan SQL. Anda dapat menentukan Alat sebagai peta di bagian alat pada file tools.yaml. Biasanya, alat akan memerlukan sumber untuk ditindaklanjuti.

Untuk mengetahui detail selengkapnya tentang cara mengonfigurasi tools.yaml, lihat dokumentasi ini.

Mari kita jalankan MCP Toolbox for Databases Server

Jalankan perintah berikut (dari folder mcp-toolbox) untuk memulai server:

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

Sekarang, jika Anda membuka server dalam mode pratinjau web di cloud, Anda akan dapat melihat server Toolbox berjalan dengan semua alat aplikasi kami.

Server MCP Toolbox berjalan secara default di port 5000. Mari kita gunakan Cloud Shell untuk mengujinya.

Klik Pratinjau Web di Cloud Shell seperti yang ditunjukkan di bawah:

2a5bc3fb3bc5056e.png

Klik Ubah port dan tetapkan port ke 5000 seperti yang ditunjukkan di bawah, lalu klik Ubah dan Pratinjau.

cec224667bff2293.png

Tindakan ini akan menghasilkan output:

ce4c72e5be0f44c4.png

MCP Toolkit for Databases menjelaskan Python SDK yang dapat Anda gunakan untuk memvalidasi dan menguji alat, yang didokumentasikan di sini. Kita akan melewatinya dan langsung membahas Agent Development Kit (ADK) di bagian berikutnya yang akan menggunakan alat ini.

Deploy Toolbox ke Cloud Run

Agar server Toolbox Anda dapat diakses sebagai endpoint publik yang dapat diintegrasikan dengan aplikasi lain dan Agen AI Anda, Anda akan men-deploy-nya ke Cloud Run. Petunjuk mendetail untuk menghosting Toolbox di Cloud Run diberikan di sini.

Kembali ke terminal Cloud Shell dan buka folder toolbox:

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

Pastikan variabel lingkungan PROJECT_ID Anda ditetapkan ke Project ID Google Cloud Anda.

export PROJECT_ID=$PROJECT_ID

Selanjutnya, pastikan layanan Google Cloud berikut diaktifkan di project.

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

Mari buat akun layanan terpisah yang akan bertindak sebagai identitas untuk layanan Toolbox yang akan kita deploy di Google Cloud Run. Kami juga memastikan bahwa akun layanan ini memiliki peran yang benar, yaitu kemampuan untuk mengakses Secret Manager dan berkomunikasi dengan 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'

Kemudian, Anda akan mengupload file tools.yaml sebagai secret dan karena kita harus menginstal Toolbox di Cloud Run, kita akan menggunakan Image container terbaru untuk toolbox dan menyetelnya dalam variabel IMAGE.

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

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

Terakhir, deploy server Toolbox Anda ke Cloud Run menggunakan perintah berikut. Perintah ini akan membuat aplikasi Anda dalam container, mengonfigurasi akun layanan, menyuntikkan secret, dan mengeksposnya secara publik:

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

Perintah ini akan memulai proses men-deploy Server Toolbox dengan tools.yaml yang dikonfigurasi ke Cloud Run. Setelah deployment berhasil, Anda akan melihat pesan yang mirip dengan berikut ini:

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

Sekarang Anda dapat membuka URL Layanan yang tercantum di atas di browser. Pesan "Hello World" yang kita lihat sebelumnya akan ditampilkan. Selain itu, Anda juga dapat membuka URL berikut untuk melihat alat yang tersedia:

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

Anda juga dapat membuka Cloud Run dari konsol Google Cloud dan Anda akan melihat layanan Toolbox tersedia dalam daftar layanan di Cloud Run.

7. Agen yang dibuat di ADK

Di bagian ini, Anda akan men-deploy Agen AI, yang dibangun menggunakan Agent Development Kit (ADK), ke Cloud Run.

Pertama, aktifkan API yang diperlukan di project Anda untuk membangun dan men-deploy Agen di Cloud Run, serta untuk berinteraksi dengan Artifact Registry dan Cloud Storage. Jalankan perintah berikut di Terminal Cloud Shell:

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

Kemudian, kita akan memberikan izin yang diperlukan ke Akun Layanan Compute Default di project kita. Pertama, jalankan perintah berikut di terminal Cloud Shell Anda untuk mendapatkan PROJECT_NUMBER:

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

Tetapkan izin ke Akun Layanan Compute Default:

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

Menghubungkan Agen kami ke Alat

Kita akan menghubungkan Agen ke Alat. Dalam konteks ADK, Alat merepresentasikan kemampuan spesifik yang diberikan kepada agen AI, sehingga memungkinkannya melakukan tindakan dan berinteraksi dengan dunia di luar kemampuan inti pembuatan teks dan penalaran.

Dalam kasus ini, kita akan melengkapi Agen kita dengan Alat yang telah kita konfigurasi di Toolbox MCP untuk Database.

Menggunakan Cloud Shell Editor, buka sports-agent-adk-mcp-alloydb/src/backend/ dan edit file "finn_agent.py" dengan kode berikut. Perhatikan bahwa kita menggunakan URL Layanan Cloud Run dari Server MCP ToolBox yang di-deploy pada langkah sebelumnya:

14cdb7fdcb9f6176.png

Men-deploy Agen kita di Cloud Run

Terakhir, Anda akan men-deploy Agen AI yang dikonfigurasi ke Cloud Run, sehingga dapat diakses melalui endpoint HTTP.

Pertama, buat repositori Docker di Artifact Registry untuk menyimpan image container Agen Anda. Jalankan perintah berikut di Cloud Shell:

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

Selanjutnya, bangun image Docker untuk Agen Anda menggunakan Cloud Build. Jalankan perintah ini dari direktori root project yang di-clone (sports-agent-adk-mcp-alloydb/):

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

Sekarang, deploy layanan Agen. Perintah ini akan membuat layanan Cloud Run, menarik image dari Artifact Registry, dan mengonfigurasi variabel lingkungan

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"

Catatan: Kita menetapkan variabel lingkungan secara dinamis, termasuk GOOGLE_CLOUD_PROJECT (menggunakan variabel shell $PROJECT_ID)

Anda akan mendapatkan output yang mirip dengan ini, yang menunjukkan keberhasilan deployment Agen Anda:

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

Terakhir, uji agen Anda dengan menjalankan perintah curl ini dari Terminal Cloud Shell:

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

Anda akan mendapatkan output yang mirip dengan ini:

"Halo! Saya Finn, asisten belanja olahraga AI Anda. Kami dapat membantu Anda menemukan produk, perlengkapan, dan peralatan olahraga. Ada yang bisa kami bantu?"

Pada tahap ini, Anda telah berhasil memvalidasi deployment AlloyDB, MCP Toolbox, dan Agen yang dibuat menggunakan ADK.

8. Men-deploy Frontend

Di bagian ini, Anda akan men-deploy antarmuka pengguna percakapan untuk asisten AI Anda di Cloud Run. Frontend ini dibangun menggunakan React dan JavaScript.

Sebelum men-deploy, Anda perlu memperbarui kode sumber frontend dengan URL Agen yang di-deploy dan ID Klien OAuth Anda.

Dengan menggunakan Cloud Shell Editor, buka sports-agent-adk-mcp-alloydb/src/frontend/src/pages/, lalu buka file Home.jsx. Anda harus memperbarui placeholder untuk URL Layanan Cloud Run Agen Anda. Kemudian, ganti dengan URL Layanan Cloud Run Agen Anda dari langkah sebelumnya (misalnya, https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

dac45857844de929.png

Selanjutnya, buka sports-agent-adk-mcp-alloydb/src/frontend/src/components/ dan buka file GoogleSignInButton.jsx. Anda akan memperbarui file ini dengan Client ID OAuth yang Anda peroleh di bagian "Penyiapan Layanan Otorisasi":

82db1e66c439a9cb.png

Men-deploy frontend di Cloud Run

Setelah aplikasi frontend dikonfigurasi, Anda siap men-deploy-nya ke Cloud Run.

Jalankan perintah berikut di Terminal Cloud Shell dari direktori root (sports-agent-adk-mcp-alloydb/) untuk membuat repositori Docker di Artifact Registry untuk image frontend Anda.

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

Selanjutnya, bangun image Docker untuk aplikasi frontend Anda menggunakan Cloud Build. Jalankan perintah ini dari direktori root project Anda:

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

Terakhir, kita akan men-deploy frontend di Cloud Run menggunakan perintah berikut:

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

Anda akan mendapatkan output yang mirip dengan ini, yang menunjukkan keberhasilan deployment frontend Anda:

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

Buka browser web Anda dan gunakan URL Layanan dari langkah sebelumnya untuk membuka aplikasi yang baru di-deploy, yang didukung oleh Agen AI Anda.

15bdc2dfd6e47c69.png

9. Menjalankan Agen kami

Asisten AI Sports Store Agent Anda, Finn, kini telah sepenuhnya di-deploy dan siap membantu pembelian.

Buka browser web Anda dan buka URL Layanan aplikasi frontend Anda dari langkah sebelumnya. URL mengikuti format ini: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Setelah frontend dimuat, klik tombol kanan atas (biasanya berlabel "Login" atau perintah serupa) untuk mengautentikasi menggunakan kredensial Google Anda. Tindakan ini akan memanfaatkan konfigurasi OAuth yang Anda siapkan sebelumnya.

Setelah autentikasi berhasil, Anda siap berinteraksi dengan Finn. Klik tombol "Beli Sekarang" untuk memulai pengalaman belanja percakapan Anda.

2b22ae486cebff1b.png

Gunakan skrip berikut untuk menguji berbagai fungsi Agen AI Anda. Salin dan tempel perintah ini ke antarmuka chat satu per satu:

  1. Halo, Finn!
  2. Saya mencari sepatu lari untuk ultra-trail
  3. Beri tahu saya detail selengkapnya tentang Ultra Glide
  4. Tambahkan Ultra Glide, ukuran 40, warna Merah/Abu-abu ke daftar belanja saya
  5. Tampilkan daftar belanja saya
  6. Menemukan toko di sekitar saya
  7. Lakukan pemesanan menggunakan daftar belanja saya untuk toko Sports Diagonal Mar
  8. Memeriksa status pesanan saya
  9. Cantumkan metode pengiriman untuk toko Sports Diagonal Mar
  10. Perbarui metode pengiriman menjadi Pengiriman Ekspres untuk pesanan saya [YOUR_ORDER_NUMBER]
  11. Memeriksa status pesanan saya
  12. Terima kasih, Finn.

Untuk demonstrasi visual Agen Finn yang di-deploy dan kemampuannya, tonton video di bawah:

Demo Asisten AI Agen Olahraga yang didukung oleh AlloyDB

10. Hasil

Setelah menjalankan skrip sebelumnya, Anda telah berhasil memvalidasi integrasi lengkap Agen ADK, koneksinya ke AlloyDB, dan pemanfaatan MCP Toolbox. Bagian ini menyoroti kemampuan inti yang telah Anda terapkan.

  1. Layanan Otorisasi

MCP Toolbox for Databases menyediakan kemampuan untuk memfederasikan Layanan Otorisasi (khususnya, Login dengan Google dalam codelab ini) untuk mengautentikasi pengguna dalam aplikasi Anda. Dengan MCP Toolbox, Client ID OAuth Anda digunakan untuk memvalidasi identitas pengguna saat alat dipanggil.

Mekanisme autentikasi yang kuat ini menawarkan solusi yang sangat baik untuk melindungi aplikasi berbasis agen Anda dari serangan injeksi perintah, yaitu jenis serangan yang menggunakan input berbahaya untuk mencoba melewati atau memanipulasi perilaku yang diinginkan agen. Untuk mengetahui detail selengkapnya, Anda dapat membaca artikel Wikipedia tentang Serangan Injeksi Perintah

Dalam aplikasi ini, teknik ini digunakan saat pengguna meminta untuk "memeriksa status pesanan kami" atau "menampilkan daftar belanja saya". Agen ini dirancang untuk menampilkan hanya pesanan milik pengguna yang diautentikasi, sehingga mencegah akses tidak sah ke informasi pesanan.

27b03aa215c454a.png

  1. Vector Search

Aplikasi berbasis agen Anda memanfaatkan AlloyDB untuk PostgreSQL guna menyediakan kemampuan kueri lanjutan, terutama melalui penelusuran vektor. AlloyDB mendukung pembuatan embedding online langsung di dalam database menggunakan fungsi SQL.

Fitur canggih ini memungkinkan agen menerjemahkan input bahasa alami pengguna ke dalam representasi sematan numerik. Selanjutnya, model ini dapat menjalankan penelusuran kesamaan terhadap katalog produk Anda (atau data relevan lainnya) berdasarkan penyematan ini, sehingga menghasilkan hasil penelusuran yang sangat relevan.

Di aplikasi Anda, Anda akan mengalami teknik ini saat bertanya kepada Finn: "Saya sedang mencari sepatu lari untuk ultra-trail".

1a9172b827077bde.png

  1. Kemampuan Geospasial (PostGis)

AlloyDB untuk PostgreSQL mempertahankan kompatibilitas 100% dengan fitur PostgreSQL standar. Dalam aplikasi ini, kita menggunakan ekstensi PostgreSQL populer PostGIS untuk memberikan kemampuan lokasi geospasial kepada agen.

Saat Anda bertanya kepada agen: "Cari toko di dekat saya", agen akan menjalankan alat yang memanfaatkan indeks PostGIS dalam database untuk menemukan toko terdekat dengan lokasi pengguna yang ditentukan atau disimpulkan secara efisien.

fa491f214521371.png

11. (Opsional) Menguji Natural Language to SQL AI AlloyDB

Bagian ini memperkenalkan fitur lanjutan Pra-GA AlloyDB untuk PostgreSQL: Natural Language to SQL. Fitur ini memungkinkan Anda membuat kueri SQL langsung dari perintah bahasa alami, dengan memanfaatkan kecanggihan AI dalam database Anda.

Penting: Karena ini adalah fitur Pra-GA, Anda harus mendaftar dan mengaktifkan akses untuk Project Google Cloud, Cluster AlloyDB, dan database Anda.

  • Mendaftar untuk Mendapatkan Akses: Isi formulir ini untuk meminta akses ke project Anda
  • Dokumentasi: Anda dapat mempelajari lebih lanjut cara memanfaatkan Bahasa Natural ke SQL AlloyDB AI dalam dokumentasi resmi

Setelah Anda mendaftar dan mengonfirmasi akses untuk project, lanjutkan dengan langkah-langkah berikut di AlloyDB Studio.

a15964d53b4b15e1.png

Login ke AlloyDB menggunakan kredensial yang kita buat saat Anda membuat cluster:

  • Nama pengguna: "postgres"
  • Database: "store"
  • Sandi: "alloydb"

1- Buat ekstensi alloydb_ai_nl. Ekstensi ini menyediakan fungsi yang diperlukan untuk kemampuan Natural Language AI AlloyDB.

CREATE EXTENSION alloydb_ai_nl cascade;

2- Buat konfigurasi untuk aplikasi Anda. Konfigurasi menentukan konteks skema yang akan digunakan model AI untuk memahami database Anda.

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

3- Daftarkan skema / tabel dengan konfigurasi. Tambahkan tabel dan skema tertentu yang akan berinteraksi dengan agen aplikasi Anda ke konfigurasi.

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- Buat konteks untuk skema / tabel. Langkah ini memproses tabel terdaftar untuk menghasilkan konteks yang diperlukan bagi model AI. Proses ini dapat memerlukan waktu sekitar 2-3 menit.

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

5- Periksa konteks yang dibuat otomatis untuk tabel dan kolom tertentu (opsional). Anda dapat memeriksa konteks yang dihasilkan untuk memahami cara model AI menafsirkan skema Anda.

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

Anda akan menemukan alat bernama "check-inventory-by-store-brand-category" di "tools.yaml" Agen kami. Alat ini menggunakan Natural Language to SQL AlloyDB:

2cd70da8caefe2f5.png

Buka browser Web, lalu gunakan URL layanan untuk membuka aplikasi: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

Kemudian, gunakan skrip berikut di antarmuka chat untuk menguji kemampuan baru ini:

  • Halo, Finn!
  • Berapa jumlah total produk kategori Running dari Salomon yang tersedia di toko "Sports Diagonal Mar"?

Untuk melihat kueri SQL sebenarnya yang dihasilkan AlloyDB AI dari input bahasa natural Anda, kembali ke AlloyDB Studio dan jalankan kueri berikut:

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

Tindakan ini akan menampilkan pernyataan SQL yang dibuat oleh AlloyDB AI.

12. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam lab ini, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud, buka halaman Manage resources.
  2. Dalam daftar project, pilih project yang ingin Anda hapus, lalu klik Hapus.
  3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

13. Selamat

Selamat! Anda telah berhasil membuat aplikasi AI Agentik yang Didorong Data menggunakan ADK, MCP Toolbox for Databases, dan AlloyDB for PostgreSQL

Untuk mengetahui informasi selengkapnya, lihat dokumentasi produk: Agent Development Kit, MCP Toolbox for Databases, dan AlloyDB for PostgreSQL