Bu sayfa, Cloud Translation API ile çevrilmiştir.

ADK, MCP Aracı Kutusu ve AlloyDB ile Spor Mağazası Temsilcisi Yapay Zeka Asistanı Oluşturma

1. Giriş

Ne oluşturacaksınız?

Bu codelab'de Sports Shop Agent AI asistanı oluşturmayı öğreneceksiniz. ADK, MCP Toolbox ve AlloyDB tarafından desteklenen bu yeni nesil Agent AI uygulaması, kullanıcılara aşağıdakiler dahil çeşitli görevlerde yardımcı olacaktır:

Doğal dil kullanarak ürün arama
Önerilen ürünleri satın almak için yakındaki mağazaları bulma
Yeni sipariş verme
Mevcut sipariş durumlarını kontrol etme
Siparişleri tercih edilen teslimat yöntemleriyle güncelleme

Neler öğreneceksiniz?

AlloyDB for PostgreSQL veritabanı sağlama ve doldurma.
AlloyDB for PostgreSQL örneğinizle Veritabanları için MCP Araç Kutusu'nu ayarlama
Spor mağazası sorgularında yardımcı olması için Agent Development Kit (ADK) kullanarak bir yapay zeka ajanı tasarlama ve geliştirme.
Bulut ortamında veritabanları için aracınızı ve MCP Toolbox'ınızı test etme
Akıllı aracı yanıtları için AlloyDB'nin gelişmiş sorgu özelliklerinden yararlanma.

Gerekenler

Bu codelab'i tamamlamak için şunlara ihtiyacınız olacak:

Chrome web tarayıcısı
Gmail hesabı
Faturalandırmanın etkin olduğu bir Google Cloud projesi.

Bu codelab, yeni başlayanlar da dahil olmak üzere her seviyeden geliştirici için tasarlanmıştır.

2. Başlamadan önce

Bu bölümde, Sports Shop Agent yapay zeka asistanını oluşturmaya başlamadan önce Google Cloud projenizde yapmanız gereken ilk kurulum adımları açıklanmaktadır.

Proje oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmanın projede etkin olup olmadığını kontrol etmeyi öğrenin .
Bu bağlantıyı tıklayarak Cloud Shell'i etkinleştirin. Cloud Shell'deki ilgili düğmeyi tıklayarak Cloud Shell Terminali (bulut komutlarını çalıştırmak için) ile Düzenleyici (projeleri oluşturmak için) arasında geçiş yapabilirsiniz.

Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığını kontrol edin:

gcloud auth list

gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.

gcloud config list project

PROJECT_ID değişkenini ayarlamak için aşağıdaki komutu kullanın:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Aşağıdaki komutları çalıştırarak şu API'leri etkinleştirin:

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

3. AlloyDB örneğini oluşturma

Bu bölümde, AlloyDB veritabanı kümenizi ve örneğinizi ayarlayacak, yapay zeka aracınız için gerekli ağ iletişimi ve izinleri yapılandıracaksınız.

Öncelikle AlloyDB kümesini oluşturmak için Cloud Shell terminalinizde aşağıdaki komutu çalıştırın:

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

AlloyDB, güvenli ve yüksek performanslı erişim için özel IP bağlantısını kullanır. Google'ın, Google tarafından yönetilen hizmet ağı altyapısına hizmet eşleme bağlantısı için kullanması amacıyla VPC'nizde özel bir IP aralığı ayırmanız gerekir. Aşağıdaki komutu çalıştırın:

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

Ardından, VPC Hizmet Eşleme bağlantısını oluşturun. Bu sayede Google Cloud Sanal Özel Bulut (VPC) ağınız, AlloyDB dahil olmak üzere Google'ın yönetilen hizmetleriyle güvenli ve özel bir şekilde iletişim kurabilir. Aşağıdaki komutu çalıştırın:

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

Şimdi AlloyDB kümenizde birincil örneği oluşturun. Bu, uygulamalarınızın bağlanacağı gerçek veritabanı uç noktasıdır. AlloyDB örneği oluşturmak için aşağıdaki komutu çalıştırın:

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

Not: Örnek oluşturma işlemi yaklaşık 10 dakika sürebilir. Lütfen devam etmeden önce bu işlemin tamamlanmasını bekleyin.

Vertex AI entegrasyonunu etkinleştirme

AlloyDB örneğinizin vektör arama sorguları (semantik arama gibi yapay zeka işlevleri için gereklidir) gerçekleştirmesine ve Vertex AI'da dağıtılan modelleri çağırmasına izin vermek için AlloyDB hizmet aracısına Vertex AI izinleri vermeniz gerekir.

Öncelikle IAM bağlaması için gerekli olan Google Cloud proje numaranızı alın.

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

Ardından, Vertex AI'a AlloyDB hizmet aracısı izni verin:

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

Genel IP'yi etkinleştirme

Sonraki adımlara hazırlanmak için AlloyDB örneğimizde herkese açık IP bağlantısını etkinleştireceğiz.

Konsol'da ekranın üst orta kısmındaki arama alanına gidin ve "alloydb" yazın. Ardından, düzenleyin ve genel IP bağlantısı bölümüne gidin. "Genel IP'yi etkinleştir" onay kutusunu işaretleyin ve Cloud Shell makinenizin IP adresini girin.

Cloud Shell makinenizin IP'sini almak için Cloud Shell Terminal'e gidip "ifconfig | grep -A 1 eth0" komutunu girin. Sonuçta, son 2 basamağı "/16" maske boyutuyla 0.0 ile değiştirin. Örneğin, "XX.XX.0.0/16" şeklinde görünür. Burada XX sayılardır.

Bu IP'yi, örnek düzenleme sayfasının Yetkili harici ağlar "Ağlar" metin kutusuna yapıştırın.

Not: Güncelleme işlemi 3 dakika sürebilir.

4. Veritabanını Yükleme

Mağaza veritabanını oluşturma

Şimdi de veritabanınızı oluşturma ve spor mağazanız için ilk verileri yükleme zamanı.

psql'nın Cloud Shell'den özel AlloyDB örneğinize bağlanmasını sağlamak için AlloyDB Auth Proxy'yi kullanırsınız. Bu yardımcı program, veritabanına olan bağlantınızı güvenli bir şekilde tüneller. (AlloyDB Auth Proxy bölümüne bakın.)

Aşağıdaki komutu kullanarak AlloyDB Auth Proxy'yi indirin:

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

Yürütülebilir hale getirin:

chmod +x alloydb-auth-proxy

Bu komutu ilk Cloud Shell terminal pencerenizde çalıştırın. Proxy arka planda çalışır ve bağlantıları yönlendirir.

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

psql kullanarak AlloyDB örneğine bağlanın:

psql -h 127.0.0.1 -U postgres

Not: İstendiğinde, küme oluşturma sırasında postgres kullanıcısı için ayarladığınız şifreyi girin (doğrudan dokümanları takip ediyorsanız şifre alloydb'dır).

Ayrıca uygulamamız için mağaza veritabanını oluşturun (komutları tek tek çalıştırın):

CREATE DATABASE store;
\c store
exit

Kaynak Kodu

Şimdi de codelab'in kaynak kodu deposunu klonlayın. Klonlama işleminden önce ana dizininizde veya uygun bir konumda olduğunuzdan emin olun ve aşağıdaki komutu çalıştırın:

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

Veritabanını doldurma

Veritabanı dökümü dosyasına erişmek için klonlanan projenin data klasörüne gidin.

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

Ardından, depodaki store_backup.sql dosyasını kullanarak örnek veri kümesini store veritabanınıza aktarın.

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

Not: Bu içe aktarma işlemi sırasında bazı UYARI ve HATA mesajları görebilirsiniz. Bu mesajlar, bu codelab için güvenle yoksayılabilir. Bunlar genellikle, döküm tam şema içeriyorsa zaten mevcut olan izinler veya nesnelerle ilgilidir. Bazı UYARI ve HATALAR'ı yoksayabilirsiniz.

5. Yetkilendirme hizmeti kurulumu

Bu bölümde, uygulamanız için yetkilendirme hizmetini ayarlayacaksınız. Bu hizmet, erişimi güvenli hale getirmek ve yapay zeka aracınızdaki istem ekleme güvenlik açıklarına karşı koruma sağlamak için çok önemlidir.

Öncelikle, store veritabanınızdaki users tablosuna örnek bir kullanıcı ekleyeceksiniz. Bu kullanıcı, uygulamanızda kimlik doğrulama için kullanılır.

Konsola gidip AlloyDB'ye gidin, birincil örneği ve ardından AlloyDB Studio'yu seçin:

İstendiğinde, AlloyDB Studio'da oturum açmak için küme kurulumu sırasında oluşturduğunuz kimlik bilgilerini kullanın:

Kullanıcı adı: "postgres"
Veritabanı: "store"
Şifre: "alloydb"

SQL Düzenleyici'de, kullanıcıyı veritabanına eklemek için bir INSERT ifadesi çalıştırın. Adı, soyadı ve e-posta adresini değiştirin.

Önemli:

KONUMU örnekteki gibi tutun.
Google Cloud Console'a kaydolmak için kullandığınız e-posta adresini kullanın.

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

Ardından, projeniz için OAuth kullanıcı rızası ekranını yapılandırmanız gerekir. Bu ekran, uygulamanız Google Hesabı'na erişim isteğinde bulunduğunda kullanıcılara gösterilir ve uygulamanızın markasını tanımlar.

Konsol'da "API'ler ve Hizmetler", "Google OAuth İzni"ne gidin:

Uygulamanızın markasını oluşturmak için aşağıdaki bilgileri sağlayın:

Uygulama adı: "Sports Shopping Agent AI"
Kullanıcı desteği e-posta adresi: "YOUR_EMAIL"
Kitle: "Harici"
İletişim Bilgileri: "YOUR_EMAIL"

Şimdi, ön uç uygulamanızın Google ile kullanıcı kimliğini doğrulamak için kullanacağı OAuth istemci kimliğini oluşturacaksınız.

Öncelikle Google Cloud proje numaranızın olduğundan emin olun. Bu, yönlendirme URI'lerinin doğru şekilde yapılandırılması için gereklidir. Cloud Shell terminalinde aşağıdaki komutu çalıştırın:

PROJECT_ID değişkeniniz bu Cloud Shell Terminal penceresinde ayarlanmamışsa şunu çalıştırın:

export PROJECT_ID=[YOUR_PROJECT_ID]

Ardından, aşağıdaki komutu kullanarak PROJECT_NUMBER değerini alın:

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

Ardından "API'ler ve Hizmetler" -> "Kimlik Bilgileri" -> "Kimlik Bilgileri Oluştur" -> "OAuth İstemci Kimliği"ne gidin.

Kimlik bilgisi oluşturmak için aşağıdaki bilgileri kullanın:

Uygulama türü: "Web Uygulaması"
Ad: "Sports Shopping Agent AI App" (Spor Alışverişi Temsilcisi Yapay Zeka Uygulaması)

Yetkilendirilmiş JavaScript kaynakları:

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

Yetkilendirilmiş yönlendirme URI'leri:

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

Not: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app URL'si, ön uç uygulamanız için beklenen dağıtım URL'sidir. Bu URL, bu codelab'in ilerleyen bölümlerinde ayarlanacaktır. [YOUR_PROJECT_NUMBER] kısmını kopyaladığınız gerçek numarayla değiştirdiğinizden emin olun.

Önemli: Oluşturma işleminden sonra, OAuth istemci kimliğiniz ve bazen de istemci gizli anahtarınız bir pop-up pencerede gösterilir. Ön uçunuzu yapılandırırken daha sonraki bir adımda ihtiyacınız olacağından OAuth istemci kimliğinizi güvenli bir yerde saklayın.

6. Veritabanları için MCP ToolBox Kurulumu

Araç kutusu, uygulamanızın düzenleme çerçevesi ile veritabanınız arasında yer alır ve araçları değiştirmek, dağıtmak veya çağırmak için kullanılan bir kontrol düzlemi sağlar. Araçları depolamak ve güncellemek için merkezi bir konum sağlayarak araçlarınızın yönetimini basitleştirir. Böylece, araçları temsilciler ve uygulamalar arasında paylaşabilir ve uygulamanızı yeniden dağıtmak zorunda kalmadan bu araçları güncelleyebilirsiniz.

MCP Toolbox for Databases tarafından desteklenen veritabanlarından biri AlloyDB olduğundan ve bunu önceki bölümde zaten sağladığımızdan, Toolbox'ı kurmaya devam edelim.

Öncelikle, işlevselliğini doğrulamak için MCP Toolbox sunucusunu Cloud Shell ortamınızda yerel olarak ayarlayacaksınız.

Cloud Shell terminalinizde, klonlanmış proje deponuzda bulunan toolbox klasörüne gidin:

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

Toolbox ikilisini indirmek ve yürütme izinleri vermek için aşağıdaki komutları çalıştırın:

# see releases page for other versions
export VERSION=0.16.0

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

chmod +x toolbox

Not: Burada 0.16.0 sürümü belirtilmiştir. Üretim ortamları için her zaman Araç kutusu sürümleri sayfasındaki en son kararlı sürümü doğrulayın ve kullanın.

Cloud Shell Düzenleyici'ye gidin (Düzenleyici simgesini tıklayarak Terminal'den geçiş yapabilirsiniz).

Aynı sports-agent-adk-mcp-alloydb/src/toolbox dizininde tools.yaml adlı bir dosya bulunur. Bu dosyayı açın ve yer tutucuları önceki adımlarda elde ettiğiniz OAuth istemci kimliğiniz ve Google Cloud projesi kimliğinizle güncelleyin.

tools.yaml dosyasını anlama

Kaynaklar, bir aracın etkileşimde bulunabileceği farklı veri kaynaklarınızı temsil eder. Kaynak, bir aracın etkileşimde bulunabileceği bir veri kaynağını temsil eder. Kaynakları, tools.yaml dosyanızın kaynaklar bölümünde harita olarak tanımlayabilirsiniz. Genellikle bir kaynak yapılandırması, veritabanına bağlanmak ve veritabanıyla etkileşim kurmak için gereken tüm bilgileri içerir.

Araçlar, bir aracının gerçekleştirebileceği işlemleri (ör. bir kaynağa okuma ve yazma) tanımlar. Araç, aracınızın gerçekleştirebileceği bir işlemi (ör. SQL ifadesi çalıştırma) temsil eder. Araçlar'ı tools.yaml dosyanızın araçlar bölümünde harita olarak tanımlayabilirsiniz. Genellikle bir aracın işlem yapması için bir kaynak gerekir.

tools.yaml dosyanızı yapılandırma hakkında daha fazla bilgi için bu belgeye bakın.

Veritabanı Sunucusu için MCP Araç Kutusu'nu çalıştıralım

Sunucuyu başlatmak için aşağıdaki komutu (mcp-toolbox klasöründen) çalıştırın:

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

Artık sunucuyu bulutta web önizleme modunda açarsanız Toolbox sunucusunun uygulamamızdaki tüm araçlarla birlikte çalıştığını görebilirsiniz.

MCP Toolbox Server varsayılan olarak 5000 numaralı bağlantı noktasında çalışır. Bunu test etmek için Cloud Shell'i kullanalım.

Aşağıda gösterildiği gibi Cloud Shell'de Web Önizlemesi'ni tıklayın:

Bağlantı noktasını değiştir'i tıklayın ve bağlantı noktasını aşağıda gösterildiği gibi 5000 olarak ayarlayıp Değiştir ve Önizle'yi tıklayın.

Bu işlem sonucunda şu çıkış elde edilir:

Veritabanları için MCP Araç Seti, araçları doğrulayıp test etmeniz için bir Python SDK'sını açıklar. Bu SDK'nın belgelerini burada bulabilirsiniz. Bu konuyu atlayıp doğrudan bu araçları kullanacak olan bir sonraki bölümdeki Agent Development Kit'e (ADK) geçeceğiz.

Araç kutumuzu Cloud Run'a dağıtma

Araç kutusu sunucunuzu diğer uygulamalar ve yapay zeka aracınızla entegre edilebilen herkese açık bir uç nokta olarak erişilebilir hale getirmek için Cloud Run'a dağıtmanız gerekir. Araç kutusunu Cloud Run'da barındırmayla ilgili ayrıntılı talimatlar burada verilmiştir.

Cloud Shell terminaline dönün ve araç kutusu klasörüne gidin:

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

PROJECT_ID ortam değişkeninizin Google Cloud proje kimliğinize ayarlandığından emin olun.

export PROJECT_ID=$PROJECT_ID

Ardından, projede aşağıdaki Google Cloud hizmetlerinin etkinleştirildiğini doğrulayın.

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

Google Cloud Run'da dağıtacağımız Toolbox hizmetinin kimliği olarak hareket edecek ayrı bir hizmet hesabı oluşturalım. Ayrıca, bu hizmet hesabının doğru rollere (ör. Secret Manager'a erişme ve AlloyDB ile iletişim kurma) sahip olmasını sağlıyoruz.

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=&#39;roles/serviceusage.serviceUsageConsumer'

Ardından, tools.yaml dosyasını gizli olarak yükleyeceksiniz. Araç kutusunu Cloud Run'a yüklememiz gerektiğinden araç kutusu için en son container görüntüsünü kullanıp bunu IMAGE değişkenine ayarlayacağız.

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

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

Son olarak, aşağıdaki komutu kullanarak araç kutusu sunucunuzu Cloud Run'a dağıtın. Bu komut, uygulamanızı kapsar, hizmet hesabını yapılandırır, gizliyi yerleştirir ve herkese açık olarak kullanıma sunar:

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

Bu işlem, yapılandırılmış tools.yaml dosyamızla birlikte Toolbox sunucusunu Cloud Run'a dağıtma sürecini başlatır. Dağıtım başarılı olduğunda aşağıdaki gibi bir mesaj görürsünüz:

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

Artık tarayıcıda yukarıda listelenen hizmet URL'sini ziyaret edebilirsiniz. Daha önce gördüğümüz "Hello World" mesajı görüntülenir. Ayrıca, mevcut araçları görmek için aşağıdaki URL'yi de ziyaret edebilirsiniz:

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

Google Cloud Console'dan Cloud Run'ı da ziyaret edebilirsiniz. Bu durumda, Cloud Run'daki hizmetler listesinde Toolbox hizmetini görürsünüz.

7. ADK'da oluşturulan aracı

Bu bölümde, Agent Development Kit (ADK) kullanılarak oluşturulan yapay zeka aracınızı Cloud Run'a dağıtacaksınız.

Öncelikle, Cloud Run'da aracınızı oluşturup dağıtmak ve Artifact Registry ile Cloud Storage ile etkileşim kurmak için projenizde gerekli API'leri etkinleştirin. Cloud Shell terminalinizde aşağıdaki komutu çalıştırın:

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

Ardından, projemizdeki varsayılan Compute Engine hizmet hesabına gerekli izinleri atayacağız. İlk olarak PROJECT_NUMBER değerini almak için Cloud Shell terminalinizde aşağıdaki komutu çalıştırın:

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

Varsayılan Compute hizmet hesabına izin atama:

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

Müşteri temsilcimizi araçlara bağlama

Aracımızı araçlara bağlayacağız. ADK bağlamında Araç, bir yapay zeka aracısına sağlanan belirli bir özelliği temsil eder. Bu özellik, aracının temel metin oluşturma ve muhakeme yeteneklerinin ötesinde işlemler gerçekleştirmesine ve dünyayla etkileşim kurmasına olanak tanır.

Bu örnekte, aracımızı şimdi MCP Toolbox for Databases'de yapılandırdığımız araçlarla donatacağız.

Cloud Shell Düzenleyici'yi kullanarak sports-agent-adk-mcp-alloydb/src/backend/ dizinine gidin ve "finn_agent.py" dosyasını aşağıdaki kodla düzenleyin. Önceki adımda dağıtılan MCP ToolBox sunucusundan Cloud Run hizmeti URL'sini kullandığımıza dikkat edin:

Aracımızı Cloud Run'a dağıtma

Son olarak, yapılandırdığınız yapay zeka aracınızı Cloud Run'a dağıtarak bir HTTP uç noktası üzerinden erişilebilir hale getireceksiniz.

İlk olarak, Aracınızın kapsayıcı görüntülerini depolamak için Artifact Registry'de bir Docker deposu oluşturun. Cloud Shell'de aşağıdaki komutu çalıştırın:

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

Ardından, Cloud Build'i kullanarak aracınızın Docker görüntüsünü oluşturun. Bu komutu, klonlanan projenizin kök dizininden (sports-agent-adk-mcp-alloydb/) çalıştırın:

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

Şimdi Agent hizmetini dağıtın. Bu komut, bir Cloud Run hizmeti oluşturur, görüntüyü Artifact Registry'den çeker ve ortam değişkenlerini yapılandırır.

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"

Not: GOOGLE_CLOUD_PROJECT dahil olmak üzere ortam değişkenlerini dinamik olarak ayarlıyoruz ($PROJECT_ID kabuk değişkeni kullanılarak).

Aracınızın başarılı bir şekilde dağıtıldığını belirten aşağıdaki gibi bir çıkış alırsınız:

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

Son olarak, Cloud Shell terminalinizden şu curl komutu çalıştırarak temsilcinizi test edin:

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

Şuna benzer bir çıkış alırsınız:

"Merhaba! Ben Finn, yapay zeka temelli spor alışverişi asistanınız. Spor ürünleri, ekipmanları ve malzemeleri bulmanıza yardımcı olabilirim. Bugün size nasıl yardımcı olabilirim?"

Bu noktada, AlloyDB, MCP Toolbox ve ADK kullanılarak oluşturulan aracınızın dağıtımını başarıyla doğruladınız.

8. Ön ucu dağıtma

Bu bölümde, Cloud Run'da yapay zeka asistanınız için etkileşimli kullanıcı arayüzünü dağıtacaksınız. Bu ön uç, React ve JavaScript kullanılarak oluşturulmuştur.

Dağıtımdan önce, ön ucun kaynak kodunu dağıtılan temsilcinizin URL'leri ve OAuth istemci kimliğinizle güncellemeniz gerekir.

Cloud Shell Düzenleyici'yi kullanarak sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ konumuna gidin ve Home.jsx dosyasını açın. Aracı Cloud Run hizmeti URL'nizin yer tutucusunu güncellemeniz gerekir. Ardından, önceki adımdaki aracınızın Cloud Run hizmeti URL'siyle değiştirin (ör. https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Şimdi İleri'yi tıklayın, sports-agent-adk-mcp-alloydb/src/frontend/src/components/ simgesine gidin ve GoogleSignInButton.jsx dosyasını açın. Bu dosyayı, "Yetkilendirme Hizmeti Kurulumu" bölümünde aldığınız OAuth istemci kimliğiyle güncelleyeceksiniz:

Ön ucu Cloud Run'da dağıtma

Ön uç uygulamanız yapılandırıldığına göre artık Cloud Run'a dağıtmaya hazırsınız.

Ön uç resimleriniz için Artifact Registry'de bir Docker deposu oluşturmak üzere kök dizinden (sports-agent-adk-mcp-alloydb/) Cloud Shell terminalinde aşağıdaki komutu çalıştırın.

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

Ardından, Cloud Build'i kullanarak ön uç uygulamanızın Docker görüntüsünü oluşturun. Bu komutu projenizin kök dizininden çalıştırın:

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

Son olarak, aşağıdaki komutu kullanarak ön ucu Cloud Run'a dağıtacağız:

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

Ön uç dağıtımınızın başarılı olduğunu belirten aşağıdaki gibi bir çıkış alırsınız:

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

Web tarayıcınızı açın ve önceki adımda aldığınız hizmet URL'sini kullanarak yapay zeka aracınız tarafından desteklenen yeni dağıtılmış uygulamanızı açın.

9. Temsilcimizi çalıştırma

Spor mağazası temsilcisi yapay zeka asistanınız Finn artık tamamen kullanıma hazır ve satın alma işlemlerinde yardımcı olmaya hazır.

Web tarayıcınızı açın ve önceki adımda oluşturduğunuz ön uç uygulamanızın hizmet URL'sine gidin. URL şu biçimdedir: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Ön uç yüklendikten sonra Google kimlik bilgilerinizi kullanarak kimlik doğrulaması yapmak için sağ üstteki düğmeyi (genellikle "Oturum aç" veya benzer bir istem olarak etiketlenir) tıklayın. Bu işlem, daha önce ayarladığınız OAuth yapılandırmasını kullanır.

Kimlik doğrulama işlemi başarıyla tamamlandıktan sonra Finn ile etkileşime geçebilirsiniz. Etkileşimli alışveriş deneyiminize başlamak için "Şimdi Alışveriş Yap" düğmesini tıklayın.

Yapay zeka aracınızın çeşitli işlevlerini test etmek için aşağıdaki komut dosyasını kullanın. Bu istemleri kopyalayıp sohbet arayüzüne tek tek yapıştırın:

Merhaba Finn!
Ultra maraton için koşu ayakkabısı arıyorum
Ultra Glide hakkında daha fazla bilgi ver
Alışveriş listeme Ultra Glide, 40 numara, Kırmızı/Gri renk ekle
Alışveriş listemi göster
Yakınımdaki mağazaları bulma
Lütfen Sports Diagonal Mar mağazası için alışveriş listemi kullanarak sipariş verin.
Siparişlerimin durumunu kontrol etme
Lütfen Sports Diagonal Mar mağazası için teslimat yöntemlerini listeleyin.
[YOUR_ORDER_NUMBER] numaralı siparişim için teslimat yöntemini Ekspres Teslimat olarak güncelle
Siparişlerimin durumunu kontrol etme
Thanks Finn !

Dağıtılan Finn Temsilcisi ve özelliklerinin görsel tanıtımı için aşağıdaki videoya göz atın:

AlloyDB destekli bir Spor Menajeri Yapay Zeka Asistanı demosu

10. Sonuçlar

Önceki komut dosyasını çalıştırdıktan sonra ADK aracınızın tam entegrasyonunu, AlloyDB'ye bağlantısını ve MCP araç kutusunu kullanımını başarıyla doğrulamış olursunuz. Bu bölümde, uyguladığınız temel özellikler vurgulanır.

Yetkilendirme Hizmeti

Veritabanları için MCP Araç Kutusu, uygulamanızdaki kullanıcıların kimliğini doğrulamak için bir yetkilendirme hizmetini (bu kod laboratuvarında özellikle Google ile Oturum Açma) birleştirme olanağı sunar. MCP Toolbox ile bir araç çağrıldığında kullanıcı kimliğini doğrulamak için OAuth istemci kimliğiniz kullanılır.

Bu güçlü kimlik doğrulama mekanizması, istem ekleme saldırılarına karşı aracılı uygulamanızı korumak için mükemmel bir çözüm sunar. Bu saldırı türünde, kötü amaçlı girişler aracının amaçlanan davranışını atlamaya veya değiştirmeye çalışır. Daha fazla bilgi için istem ekleme ile ilgili Wikipedia makalesini inceleyebilirsiniz.

Bu uygulamada, kullanıcı "siparişlerimizin durumunu kontrol et" veya "alışveriş listemi göster" dediğinde bu teknik kullanılır. Aracı, yalnızca kimliği doğrulanmış kullanıcıya ait siparişleri gösterecek şekilde tasarlanmıştır. Böylece, sipariş bilgilerine yetkisiz erişim önlenir.

Vector Search

Yapay zeka destekli uygulamanız, özellikle vektör araması aracılığıyla gelişmiş sorgu özellikleri sağlamak için AlloyDB for PostgreSQL'den yararlanıyor. AlloyDB, SQL işlevlerini kullanarak doğrudan veritabanında online yerleştirme oluşturmayı destekler.

Bu güçlü özellik, temsilcinin kullanıcının doğal dil girişini sayısal bir yerleştirme gösterimine çevirmesine olanak tanır. Daha sonra, bu yerleştirmelere dayalı olarak ürün kataloğunuzda (veya diğer alakalı verilerde) benzerlik araması yapabilir ve bu sayede alaka düzeyi yüksek arama sonuçları sağlayabilir.

Uygulamanızda, Finn'e "Ultra maraton için koşu ayakkabısı arıyorum" diye sorduğunuzda bu tekniği deneyimlersiniz.

Coğrafi Özellikler (PostGis)

AlloyDB for PostgreSQL, standart PostgreSQL özellikleriyle% 100 uyumluluğu korur. Bu uygulamada, aracıya coğrafi konum özellikleri sağlamak için popüler PostgreSQL uzantısı PostGIS'i kullanıyoruz.

Aracıya "Yakınımdaki mağazaları bul" diye sorduğunuzda, veritabanındaki PostGIS dizinlerinden yararlanarak kullanıcının belirttiği veya çıkarılan konuma en yakın mağazaları verimli bir şekilde bulan bir araç çalıştırılır.

11. (İsteğe bağlı) AlloyDB AI Natural Language to SQL'i test etme

Bu bölümde, PostgreSQL için AlloyDB'nin gelişmiş bir GA öncesi özelliği olan Doğal Dilden SQL'e tanıtılmaktadır. Bu özellik, veritabanınızdaki yapay zekanın gücünden yararlanarak doğrudan doğal dil istemlerinden SQL sorguları oluşturmanıza olanak tanır.

Önemli: Bu özellik, GA öncesi bir özellik olduğundan kaydolmanızı ve Google Cloud projeniz, AlloyDB kümeniz ve veritabanınız için erişimin etkinleştirilmesini gerektirir.

Erişim için kaydolma: Projenize erişim isteğinde bulunmak için lütfen bu formu kullanın.
Belgeler: AlloyDB AI Natural Language to SQL'den yararlanma hakkında daha fazla bilgiyi resmi belgelerde bulabilirsiniz.

Kaydolup projeniz için erişimi onayladıktan sonra AlloyDB Studio'da aşağıdaki adımları uygulayın.

Küme oluştururken oluşturduğunuz kimlik bilgilerini kullanarak AlloyDB'de oturum açın:

Kullanıcı adı: "postgres"
Veritabanı: "store"
Şifre: "alloydb"

1. alloydb_ai_nl uzantısını oluşturun. Bu uzantı, AlloyDB AI Natural Language özelliklerinin çalışması için gereken işlevleri sağlar.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Uygulamanız için bir yapılandırma oluşturun. Yapılandırma, yapay zeka modelinin veritabanınızı anlamak için kullanacağı şema bağlamını tanımlar.

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

3. Şemayı / tabloları yapılandırmaya kaydedin. Uygulamanızın aracısının etkileşimde bulunacağı tabloları ve şemaları yapılandırmaya ekleyin.

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. Şema / tablolar için bağlam oluşturun. Bu adımda, yapay zeka modeli için gerekli bağlamı oluşturmak üzere kayıtlı tablolar işlenir. Bu işlem yaklaşık 2-3 dakika sürebilir.

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

5. Belirli tablolar ve sütunlar için otomatik olarak oluşturulan bağlamı kontrol edin (isteğe bağlı). Yapay zeka modelinin şemanızı nasıl yorumladığını anlamak için oluşturulan bağlamı inceleyebilirsiniz.

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

Aracımızın "tools.yaml" dosyasında "check-inventory-by-store-brand-category" adlı bir araç bulunur. Bu araç, AlloyDB Natural Language to SQL'i kullanır:

Bir web tarayıcısı açın ve uygulamayı açmak için hizmet URL'sini kullanın: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

Ardından, bu yeni özelliği test etmek için sohbet arayüzünde aşağıdaki komut dosyasını kullanın:

Merhaba Finn!
"Sports Diagonal Mar" mağazasında Salomon'un Koşu kategorisindeki ürünlerin toplam stok miktarı nedir?

AlloyDB AI'ın doğal dil girişinizden oluşturduğu gerçek SQL sorgusunu görmek için AlloyDB Studio'ya dönün ve aşağıdaki sorguyu çalıştırın:

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 Ma>>r" store?'
   ) - 'sql';

Bu işlem, AlloyDB AI tarafından oluşturulan SQL ifadesini gösterir.

12. Temizleme

Bu laboratuvarda kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız şu adımları uygulayın:

Google Cloud Console'da Kaynakları yönetin sayfasına gidin.
Proje listesinde silmek istediğiniz projeyi seçin ve Sil'i tıklayın.
İletişim kutusunda proje kimliğini yazın ve projeyi silmek için Kapat'ı tıklayın.

13. Tebrikler

Tebrikler! ADK, MCP Toolbox for Databases ve AlloyDB for PostgreSQL kullanarak veriye dayalı bir yapay zeka uygulaması oluşturdunuz.

Daha fazla bilgi için ürün belgelerine bakın: Agent Development Kit, MCP Toolbox for Databases ve AlloyDB for PostgreSQL