יצירת עוזרת AI לסוכן בחנות ספורט באמצעות ADK, ‏ MCP Toolbox ו-AlloyDB

1. מבוא

מה תפַתחו

ב-codelab הזה נסביר איך ליצור עוזר AI לסדנת ספורט. אפליקציית ה-AI של הסוכן מהדור הבא, שמבוססת על ADK,‏ MCP Toolbox ו-AlloyDB, תעזור למשתמשים במגוון משימות, כולל:

  • חיפוש מוצרים באמצעות שפה טבעית.
  • מציאת חנויות בסביבה שבהן אפשר לרכוש מוצרים מומלצים.
  • ביצוע הזמנות חדשות.
  • בדיקת סטטוסים של הזמנות קיימות.
  • עדכון הזמנות עם שיטות משלוח מועדפות.

7d9b5c1b10d1c654.png

מה תלמדו

  • הקצאה ואכלוס של מסד נתונים של AlloyDB ל-PostgreSQL.
  • הגדרת MCP Toolbox for Databases עם מכונת AlloyDB ל-PostgreSQL.
  • תכנון ופיתוח של סוכן AI באמצעות ערכת פיתוח הסוכנים (ADK) כדי לסייע בשאילתות בחנות ספורט.
  • בדיקת הסוכן וערכת הכלים MCP למסדי נתונים בסביבת ענן.
  • שימוש ביכולות המתקדמות של שאילתות ב-AlloyDB כדי ליצור תגובות חכמות של סוכנים.

מה צריך להכין

כדי להשלים את ה-codelab הזה, תצטרכו:

  • דפדפן האינטרנט Chrome.
  • חשבון Gmail.
  • פרויקט ב-Google Cloud עם חיוב מופעל.

ה-codelab הזה מיועד למפתחים בכל הרמות, כולל מתחילים.

2. לפני שמתחילים

בקטע הזה מוסבר איך לבצע את ההגדרה הראשונית שנדרשת בפרויקט Google Cloud לפני שמתחילים לבנות את העוזר הדיגיטלי מבוסס-AI של חנות הספורט.

יצירת פרויקט

  1. ב-Google Cloud Console, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
  2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
  3. לוחצים על הקישור כדי להפעיל את Cloud Shell. אפשר לעבור בין Cloud Shell Terminal (להפעלת פקודות בענן) לבין Editor (לבניית פרויקטים) בלחיצה על הלחצן המתאים ב-Cloud Shell.

e44cf973ddf8b70f.png

  1. אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהפרויקט מוגדר למזהה הפרויקט באמצעות הפקודה הבאה:
gcloud auth list
  1. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט שלכם.
gcloud config list project
  1. כדי להגדיר את המשתנה PROJECT_ID, משתמשים בפקודה הבאה:
export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID
  1. מריצים את הפקודות הבאות כדי להפעיל את ממשקי ה-API הבאים:
gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. יצירת מכונת AlloyDB

בקטע הזה תגדירו את אשכול מסד הנתונים ואת המופע של AlloyDB, ותקבעו את ההגדרות הנדרשות של הרשת וההרשאות לסוכן ה-AI.

קודם מריצים את הפקודה הבאה במסוף Cloud Shell כדי ליצור את אשכול AlloyDB:

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

‫AlloyDB מסתמך על קישוריות של כתובות IP פרטיות כדי לספק גישה מאובטחת עם ביצועים גבוהים. אתם צריכים להקצות טווח של כתובות IP פרטיות ב-VPC שלכם כדי ש-Google תוכל להשתמש בו לחיבור ה-peering של השירות לתשתית של Service Networking שמנוהלת על ידי Google. מריצים את הפקודה הבאה:

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

לאחר מכן, יוצרים את הקישור בין רשתות VPC שכנות (peering) של השירות. כך רשת הענן הווירטואלי הפרטי (VPC) שלכם ב-Google Cloud יכולה לתקשר בצורה מאובטחת ופרטית עם השירותים המנוהלים של Google, כולל AlloyDB. מריצים את הפקודה הבאה:

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

עכשיו יוצרים את המופע הראשי באשכול AlloyDB. זוהי נקודת הקצה (endpoint) של מסד הנתונים שאליה האפליקציות יתחברו. מריצים את הפקודה הבאה כדי ליצור מופע 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

הערה: תהליך יצירת המכונה יכול להימשך כ-10 דקות. צריך להמתין עד שהפעולה הזו תסתיים לפני שממשיכים.

הפעלת השילוב עם Vertex AI

כדי לאפשר למופע AlloyDB שלכם לבצע שאילתות של חיפוש וקטורי (שחיוניות לפונקציות AI כמו חיפוש סמנטי) ולהפעיל מודלים שנפרסו ב-Vertex AI, אתם צריכים להעניק הרשאות Vertex AI לסוכן השירות של AlloyDB.

קודם כל, צריך לאחזר את מספר הפרויקט ב-Google Cloud, כי הוא נדרש לקישור IAM.

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

לאחר מכן, נותנים לסוכן השירות של Vertex AI הרשאה:

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

הפעלת כתובת IP ציבורית

כדי להתכונן לשלבים הבאים, נפעיל את הקישוריות של כתובת ה-IP הציבורית במופע AlloyDB שלנו.

במסוף, עוברים לשדה החיפוש בחלק העליון של המסך ומקלידים 'alloydb'. לאחר מכן, עורכים ועוברים לקטע 'קישוריות לכתובת IP ציבורית'. מסמנים את התיבה 'הפעלת כתובת IP ציבורית' ומזינים את כתובת ה-IP של מכונת Cloud Shell.

c200ee8f8b776ed4.png

כדי לקבל את כתובת ה-IP של מכונת Cloud Shell, עוברים לטרמינל של Cloud Shell ומזינים את הפקודה ifconfig | grep -A 1 eth0. מהתוצאה, מחליפים את 2 הספרות האחרונות ב-0.0 עם גודל מסכה '/16'. לדוגמה, זה ייראה כך: XX.XX.0.0/16, כאשר XX הם מספרים.

מדביקים את כתובת ה-IP הזו בתיבת הטקסט 'רשתות' בקטע 'רשתות חיצוניות מורשות' בדף של עריכת המופע.

a274101902019848.png

הערה: פעולת העדכון יכולה להימשך עד 3 דקות

4. טעינת מסד הנתונים

יצירת מסד נתונים של החנות

עכשיו הגיע הזמן ליצור את מסד הנתונים ולהטעין את הנתונים הראשוניים של חנות הספורט.

כדי לאפשר ל-psql להתחבר למכונת AlloyDB הפרטית שלכם מ-Cloud Shell, תשתמשו ב-AlloyDB Auth Proxy. הכלי הזה יוצר מנהור מאובטח לחיבור למסד הנתונים. (מידע נוסף זמין במאמר בנושא AlloyDB Auth Proxy)

מורידים את AlloyDB Auth Proxy באמצעות הפקודה הבאה:

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

הופכים אותו לקובץ הפעלה:

chmod +x alloydb-auth-proxy

מריצים את הפקודה הזו בחלון הראשון של מסוף Cloud Shell. הפרוקסי יפעל ברקע ויעביר את החיבורים.

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

חשוב: צריך להשאיר את חלון הטרמינל הזה פתוח ולהפעיל את ה-proxy. אל תסגרו אותו.

פותחים חלון טרמינל חדש ב-Cloud Shell (לוחצים על הסמל + לצד הכרטיסייה Cloud Shell Terminal בחלק העליון).

4495f22b29cd62e8.png

מתחברים למופע AlloyDB באמצעות psql:

psql -h 127.0.0.1 -U postgres

הערה: כשתתבקשו, הזינו את הסיסמה שהגדרתם למשתמש postgres במהלך יצירת האשכול (אם אתם פועלים לפי התיעוד ישירות, הסיסמה היא alloydb).

יוצרים את מסד הנתונים של החנות עבור האפליקציה (מריצים את הפקודות אחת אחרי השנייה):

CREATE DATABASE store;
\c store
exit

קוד מקור

עכשיו משכפלים את מאגר קוד המקור של ה-codelab. לפני שמשכפלים, מוודאים שאתם בספריית הבית או במיקום מתאים ומריצים את הפקודה הבאה:

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

איכלוס מסד הנתונים

עוברים לתיקייה data של הפרויקט המשוכפל כדי לגשת לקובץ הגיבוי של מסד הנתונים.

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

לאחר מכן, מייבאים את מערך הנתונים לדוגמה למסד הנתונים store באמצעות קובץ store_backup.sql מהמאגר.

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

הערה: יכול להיות שיוצגו הודעות אזהרה ושגיאה במהלך הייבוא, אבל אפשר להתעלם מהן ב-codelab הזה. לרוב, ההודעות האלה קשורות להרשאות או לאובייקטים שכבר קיימים אם הקובץ מכיל סכימה מלאה. יופיעו כמה הודעות WARNING ו-ERRORS שאפשר להתעלם מהן.

5. הגדרת שירות ההרשאות

בקטע הזה נסביר איך להגדיר את שירות ההרשאות לאפליקציה. השירות הזה חיוני כדי לאבטח את הגישה ולספק הגנה מפני נקודות חולשה של החדרת הנחיות בסוכן ה-AI.

קודם מוסיפים משתמש לדוגמה לטבלה users במסד הנתונים store. המשתמש הזה ישמש לאימות באפליקציה שלכם.

עוברים למסוף, מנווטים אל AlloyDB, בוחרים את המופע הראשי ואז בוחרים באפשרות AlloyDB Studio:

a15964d53b4b15e1.png

כשמוצגת בקשה, נכנסים ל-AlloyDB Studio באמצעות פרטי הכניסה שיצרתם כשמגדירים את האשכול:

  • שם משתמש: postgres
  • מסד נתונים: store
  • סיסמה: alloydb

בעורך ה-SQL, מריצים הצהרת INSERT כדי להוסיף את המשתמש למסד הנתונים. משנים את השם הפרטי, שם המשפחה וכתובת האימייל.

חשוב:

  • משאירים את המיקום כמו שהוא בדוגמה
  • צריך להשתמש באותה כתובת אימייל שבה נרשמתם במסוף 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');

בשלב הבא, צריך להגדיר את מסך ההסכמה של OAuth לפרויקט. המסך הזה מוצג למשתמשים כשהאפליקציה שלכם מבקשת גישה לחשבון Google שלהם, והוא מגדיר את המותג של האפליקציה.

במסוף, עוברים אל 'ממשקי API ושירותים', 'הסכמה ל-OAuth של Google':

cb4db28df92abcb2.png

כדי ליצור את המותג של האפליקציה, צריך לספק את הפרטים הבאים:

  • שם האפליקציה: Sports Shopping Agent AI
  • כתובת האימייל לתמיכה במשתמשים: YOUR_EMAIL
  • קהל: 'חיצוני'
  • פרטי קשר: "YOUR_EMAIL"

עכשיו תיצרו את מזהה הלקוח ב-OAuth שהאפליקציה שלכם בצד הלקוח תשתמש בו כדי לאמת את זהות המשתמש באמצעות Google.

קודם כל, מוודאים שיש לכם את מספר הפרויקט ב-Google Cloud. הפעולה הזו נדרשת כדי להגדיר נכון את כתובות ה-URI להפניה אוטומטית. מריצים את הפקודה הבאה במסוף Cloud Shell:

אם המשתנה PROJECT_ID לא מוגדר בחלון הזה של Cloud Shell Terminal, מריצים את הפקודה:

export PROJECT_ID=[YOUR_PROJECT_ID]

לאחר מכן, מקבלים את PROJECT_NUMBER באמצעות הפקודה הבאה:

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

לאחר מכן, עוברים אל 'ממשקי API ושירותים' -> 'פרטי כניסה' -> 'יצירת פרטי כניסה' -> 'מזהה לקוח OAuth'.

45623e96d417192d.png

כדי ליצור את פרטי הכניסה, משתמשים במידע הבא:

  • סוג האפליקציה: Web Application
  • שם: "Sports Shopping Agent AI App"

מקורות מורשים של JavaScript:

  • כתובת URL1: ‏ https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

כתובות URI מורשות להפניה אוטומטית:

  • כתובת URL1: ‏ https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

הערה: כתובת ה-URL ‏https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app היא כתובת ה-URL הצפויה לפריסה של אפליקציית ה-frontend שלכם, שתוגדר בהמשך במעבדת התכנות הזו. חשוב להחליף את [YOUR_PROJECT_NUMBER] במספר האמיתי שהעתקתם.

1873d292fd27f07c.png

חשוב: אחרי היצירה, יופיע חלון קופץ עם מזהה לקוח OAuth ולפעמים גם עם סוד לקוח. שומרים את מזהה הלקוח ב-OAuth במקום בטוח, כי תצטרכו אותו בשלב מאוחר יותר כשמגדירים את חזית האתר.

6. ארגז הכלים של MCP להגדרת מסדי נתונים

ערכת הכלים נמצאת בין מסגרת התזמור של האפליקציה לבין מסד הנתונים, ומספקת מישור בקרה שמשמש לשינוי, להפצה או להפעלת כלים. הוא מפשט את ניהול הכלים על ידי מתן מיקום מרכזי לאחסון ולעדכון כלים, ומאפשר לכם לשתף כלים בין סוכנים ואפליקציות ולעדכן את הכלים האלה בלי לפרוס מחדש את האפליקציה.

אחד ממסדי הנתונים שנתמכים על ידי MCP Toolbox for Databases הוא AlloyDB, וכבר הקצנו אותו בקטע הקודם, אז נמשיך להגדרת Toolbox.

26596138ffc32d98.png

קודם כל, מגדירים את השרת של MCP Toolbox באופן מקומי בסביבת Cloud Shell כדי לוודא שהוא פועל.

  1. בטרמינל של Cloud Shell, עוברים לתיקייה toolbox שנמצאת במאגר הפרויקט המשוכפל:
cd sports-agent-adk-mcp-alloydb/src/toolbox
  1. מריצים את הפקודות הבאות כדי להוריד את קובץ ההפעלה של Toolbox ולתת לו הרשאות הפעלה:
# 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

הערה: כאן מצוינת גרסה 0.7.0. בסביבות ייצור, תמיד צריך לבדוק את הגרסה היציבה האחרונה מדף הגרסאות של ארגז הכלים ולהשתמש בה.

  1. עוברים אל Cloud Shell Editor (אפשר לעבור מהטרמינל על ידי לחיצה על סמל העורך).

4000e21f50fa507e.png

באותה ספרייה sports-agent-adk-mcp-alloydb/src/toolbox, יופיע קובץ בשם tools.yaml. פותחים את הקובץ הזה ומעדכנים את ה-placeholder עם מזהה לקוח OAuth ומזהה פרויקט Google Cloud מהשלבים הקודמים.

4c0008d3d0f3bcfb.png

הסבר על tools.yaml

מקורות מייצגים את מקורות הנתונים השונים שאיתם הכלי יכול ליצור אינטראקציה. מקור מייצג מקור נתונים שכלי יכול ליצור איתו אינטראקציה. אפשר להגדיר את המקורות כמפה בקטע sources בקובץ tools.yaml. בדרך כלל, הגדרת מקור תכיל את כל המידע שנדרש כדי להתחבר למסד הנתונים ולקיים איתו אינטראקציה.

כלים מגדירים פעולות שהסוכן יכול לבצע – כמו קריאה וכתיבה במקור. כלי מייצג פעולה שהסוכן יכול לבצע, כמו הפעלת הצהרת SQL. אפשר להגדיר כלי כמפה בקטע Tools בקובץ tools.yaml. בדרך כלל, כלי יצטרך מקור כדי לפעול.

לפרטים נוספים על הגדרת הקובץ tools.yaml, אפשר לעיין במסמכי התיעוד.

הפעלת ארגז הכלים של MCP לשרת מסדי נתונים

מריצים את הפקודה הבאה (מהתיקייה mcp-toolbox) כדי להפעיל את השרת:

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

עכשיו, אם תפתחו את השרת במצב תצוגה מקדימה באינטרנט בענן, תוכלו לראות את שרת Toolbox פועל עם כל הכלים של האפליקציה שלנו.

שרת MCP Toolbox פועל כברירת מחדל ביציאה 5000. נשתמש ב-Cloud Shell כדי לבדוק את זה.

לוחצים על Web Preview (תצוגה מקדימה של אתר) ב-Cloud Shell כמו שמוצג למטה:

2a5bc3fb3bc5056e.png

לוחצים על 'שינוי יציאה' ומגדירים את היציאה ל-5000 כמו שמוצג למטה. לוחצים על 'שינוי ותצוגה מקדימה'.

cec224667bff2293.png

הפלט הבא אמור להתקבל:

ce4c72e5be0f44c4.png

ב-MCP Toolkit for Databases מתואר Python SDK שבעזרתו אפשר לאמת ולבדוק את הכלים. התיעוד שלו זמין כאן. בקטע הבא נדלג על זה ונעבור ישירות לערכת פיתוח הסוכן (ADK) שבה נשתמש בכלים האלה.

פריסת ארגז הכלים ב-Cloud Run

כדי שהשרת של ערכת הכלים יהיה נגיש כנקודת קצה ציבורית שאפשר לשלב עם אפליקציות אחרות ועם סוכן ה-AI שלכם, תצטרכו לפרוס אותו ב-Cloud Run. כאן אפשר למצוא הוראות מפורטות לאירוח של כלי תיבת הכלים ב-Cloud Run.

חוזרים לטרמינל של Cloud Shell ועוברים לתיקיית ארגז הכלים:

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

מוודאים שמשתנה הסביבה PROJECT_ID מוגדר למזהה הפרויקט ב-Google Cloud.

export PROJECT_ID=$PROJECT_ID

לאחר מכן, מוודאים שהשירותים הבאים של Google Cloud מופעלים בפרויקט.

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

ניצור חשבון שירות נפרד שישמש כזהות של שירות Toolbox שנפרוס ב-Google Cloud Run. אנחנו גם מוודאים שלחשבון השירות הזה יש את התפקידים הנכונים, כלומר אפשרות לגשת ל-Secret Manager ולתקשר עם 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'

לאחר מכן, תעלו את הקובץ tools.yaml כסוד. מכיוון שאנחנו צריכים להתקין את ארגז הכלים ב-Cloud Run, נשתמש בקובץ האימג' העדכני של ארגז הכלים ונגדיר אותו במשתנה IMAGE.

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

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

לבסוף, פורסים את שרת Toolbox ב-Cloud Run באמצעות הפקודה הבאה. הפקודה הזו תכניס את האפליקציה למאגר, תגדיר את חשבון השירות, תזריק את הסוד ותחשוף אותו לציבור:

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

הפעולה הזו אמורה להתחיל את תהליך הפריסה של שרת Toolbox עם הקובץ tools.yaml שהגדרנו ב-Cloud Run. אם הפריסה בוצעה בהצלחה, תוצג הודעה שדומה לזו:

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

עכשיו אפשר להיכנס לכתובת ה-URL של השירות שמופיעה למעלה בדפדפן. ההודעה 'Hello World' שראינו קודם אמורה להופיע. אפשר גם להיכנס לכתובת ה-URL הבאה כדי לראות את הכלים שזמינים:

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

אפשר גם להיכנס אל Cloud Run מתוך Google Cloud Console, ושירות Toolbox יופיע ברשימת השירותים ב-Cloud Run.

7. נציג שנוצר באמצעות ADK

בקטע הזה תפרסו את סוכן ה-AI שלכם, שנבנה באמצעות ערכת פיתוח הסוכנים (ADK), ב-Cloud Run.

קודם צריך להפעיל בפרויקט את ממשקי ה-API הנדרשים כדי לבנות ולפרוס את הסוכן ב-Cloud Run, וכדי ליצור אינטראקציה עם Artifact Registry ו-Cloud Storage. מריצים את הפקודה הבאה במסוף Cloud Shell:

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

לאחר מכן, נשייך את ההרשאות הנדרשות לחשבון השירות שמשמש כברירת מחדל ב-Compute Engine בפרויקט שלנו. קודם מריצים את הפקודה הבאה בטרמינל של Cloud Shell כדי לקבל את PROJECT_NUMBER:

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

הקצאת הרשאות לחשבון השירות שמוגדר כברירת מחדל ב-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"

חיבור הנציג שלנו לכלי

אנחנו הולכים לחבר את הסוכן שלנו לכלים. במסגרת ADK, כלי מייצג יכולת ספציפית שסופקה לסוכן AI, ומאפשרת לו לבצע פעולות ולקיים אינטראקציה עם העולם מעבר ליכולות הליבה שלו של יצירת טקסט וניתוח מידע.

במקרה שלנו, נצייד את הסוכן בכלים שהגדרנו בארגז הכלים של MCP למסדי נתונים.

באמצעות Cloud Shell Editor, עוברים אל sports-agent-adk-mcp-alloydb/src/backend/ ‎ ועורכים את הקובץ finn_agent.py עם הקוד הבא. שימו לב שאנחנו משתמשים בכתובת ה-URL של שירות Cloud Run מהשרת של MCP ToolBox שנפרס בשלב הקודם:

14cdb7fdcb9f6176.png

פריסת הסוכן ב-Cloud Run

לבסוף, תפרסו את סוכן ה-AI שהגדרתם ב-Cloud Run, כך שאפשר יהיה לגשת אליו דרך נקודת קצה (endpoint) של HTTP.

קודם צריך ליצור מאגר Docker ב-Artifact Registry כדי לאחסן את קובצי האימג' של הקונטיינרים של הסוכן. מריצים את הפקודה הבאה ב-Cloud Shell:

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

בשלב הבא, יוצרים את קובץ האימג' של Docker לסוכן באמצעות Cloud Build. מריצים את הפקודה הבאה מספריית הבסיס של הפרויקט המשוכפל (sports-agent-adk-mcp-alloydb/):

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

עכשיו פורסים את שירות הסוכן. הפקודה הזו תיצור שירות Cloud Run, תמשוך את קובץ האימג' מ-Artifact Registry ותגדיר משתני סביבה

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"

הערה: אנחנו מגדירים באופן דינמי משתני סביבה, כולל GOOGLE_CLOUD_PROJECT (באמצעות משתנה ה-Shell‏ $PROJECT_ID)

הפלט שמתקבל אמור להיות דומה לזה, ולציין שהפריסה של הסוכן בוצעה בהצלחה:

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

לבסוף, בודקים את הנציג על ידי הפעלת הפקודה curl מהטרמינל של Cloud Shell:

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

יוצג פלט שדומה לזה:

"שלום! אני פין, עוזר קניות מבוסס-AI בתחום הספורט. אני יכול לעזור לך למצוא מוצרי ספורט, ציוד ואביזרים. איך אוכל לעזור לך היום?"

בשלב הזה, אימתתם בהצלחה את הפריסה של AlloyDB, של MCP Toolbox ושל הסוכן שנבנה באמצעות ADK.

8. פריסת הקצה הקדמי

בקטע הזה נסביר איך פורסים את ממשק המשתמש לשיחה של העוזר הדיגיטלי מבוסס-AI ב-Cloud Run. החלק הזה של האתר בנוי באמצעות React ו-JavaScript.

לפני הפריסה, צריך לעדכן את קוד המקור של חזית האתר עם כתובות ה-URL של הנציג שפרסתם ועם מזהה הלקוח של OAuth.

בעזרת Cloud Shell Editor, עוברים אל sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ ופותחים את הקובץ Home.jsx. תצטרכו לעדכן את ה-placeholder של כתובת ה-URL של שירות Cloud Run של הנציג. לאחר מכן, מחליפים אותו בכתובת ה-URL של שירות Cloud Run של הסוכן מהשלב הקודם (לדוגמה, https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

dac45857844de929.png

עכשיו, עוברים אל sports-agent-adk-mcp-alloydb/src/frontend/src/components/ ופותחים את הקובץ GoogleSignInButton.jsx. תעדכנו את הקובץ הזה עם מזהה הלקוח של OAuth שקיבלתם בקטע 'הגדרת שירות ההרשאות':

82db1e66c439a9cb.png

פריסת חזית האתר ב-Cloud Run

אחרי שמגדירים את אפליקציית ה-Frontend, אפשר לפרוס אותה ב-Cloud Run.

מריצים את הפקודה הבאה במסוף Cloud Shell מהספרייה הראשית (sports-agent-adk-mcp-alloydb/) כדי ליצור מאגר Docker ב-Artifact Registry לתמונות של חזית האתר.

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

בשלב הבא, יוצרים את קובץ האימג' של Docker לאפליקציית ה-Frontend באמצעות Cloud Build. מריצים את הפקודה הבאה מספריית הבסיס של הפרויקט:

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

לבסוף, נפעיל את חזית האתר ב-Cloud Run באמצעות הפקודה הבאה:

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

הפלט שיתקבל אמור להיות דומה לזה, ולציין שהפריסה של חזית האתר בוצעה בהצלחה:

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

פותחים את דפדפן האינטרנט ומשתמשים בכתובת ה-URL של השירות מהשלב הקודם כדי לפתוח את האפליקציה החדשה שהופעלה על ידי סוכן ה-AI.

15bdc2dfd6e47c69.png

9. הפעלת הנציג שלנו

העוזר הדיגיטלי מבוסס-ה-AI שלך, פין, מוכן עכשיו לעזור לך ברכישות!

פותחים את דפדפן האינטרנט ומנווטים לכתובת ה-URL של השירות של אפליקציית הקצה הקדמי מהשלב הקודם. כתובת ה-URL היא בפורמט הבא: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

אחרי שהחלק הקדמי של האתר נטען, לוחצים על הלחצן בפינה השמאלית העליונה (בדרך כלל הוא מסומן בתווית 'כניסה' או בהנחיה דומה) כדי לבצע אימות באמצעות פרטי הכניסה שלכם לחשבון Google. הפעולה הזו תשתמש בהגדרות OAuth שהגדרתם קודם.

אחרי שתהליך האימות יסתיים בהצלחה, תוכלו לתקשר עם Finn. כדי להתחיל את חוויית הקנייה השיחתית, לוחצים על הלחצן 'קנייה עכשיו'.

2b22ae486cebff1b.png

אפשר להשתמש בסקריפט הבא כדי לבדוק את הפונקציות השונות של סוכן ה-AI. מעתיקים ומדביקים את ההנחיות האלה בממשק הצ'אט, אחת אחרי השנייה:

  1. שלום, פין!
  2. אני מחפש נעלי ריצה למסלול אולטרה
  3. תספק לי פרטים נוספים על Ultra Glide
  4. תוסיף לרשימת הקניות שלי את Ultra Glide, מידה 40, צבע אדום/אפור
  5. Show my shopping list
  6. חיפוש חנויות בסביבה
  7. תבצע בבקשה הזמנה באמצעות רשימת הקניות שלי בחנות Sports Diagonal Mar
  8. בדיקת הסטטוס של ההזמנות שלי
  9. תפרט את שיטות המשלוח בחנות Sports Diagonal Mar
  10. עדכון שיטת המשלוח למשלוח אקספרס להזמנה מספר [YOUR_ORDER_NUMBER]
  11. בדיקת הסטטוס של ההזמנות שלי
  12. תודה, Finn!

כדי לראות הדגמה ויזואלית של סוכן Finn שנפרס ושל היכולות שלו, אפשר לצפות בסרטון הבא:

הדגמה של עוזר AI לסוכן ספורט שמבוסס על AlloyDB

10. תוצאות

אחרי שמריצים את הסקריפט הקודם, מאמתים בהצלחה את השילוב המלא של סוכן ADK, את החיבור שלו ל-AlloyDB ואת השימוש שלו ב-MCP Toolbox. בקטע הזה מפורטות היכולות העיקריות שהטמעתם.

  1. שירות ההרשאות

ערכת הכלים של MCP למסדי נתונים מאפשרת לאחד שירות הרשאות (במקרה הזה, כניסה באמצעות חשבון Google במעבדת התכנות הזו) כדי לאמת משתמשים באפליקציה. ב-MCP Toolbox, מזהה הלקוח ב-OAuth משמש לאימות זהות המשתמש כשמפעילים כלי.

מנגנון האימות החזק הזה הוא פתרון מצוין להגנה על אפליקציות מבוססות-סוכן מפני החדרת הנחיות, סוג של התקפה שבה קלט זדוני מנסה לעקוף את ההתנהגות המיועדת של הסוכן או לתמרן אותה. פרטים נוספים זמינים במאמר בנושא החדרת הנחיות ב-Wikipedia.

באפליקציה הזו, הטכניקה הזו מופעלת כשמשתמש מבקש לבדוק את סטטוס ההזמנות שלו או להציג את רשימת הקניות שלו. הסוכן נועד להציג רק את ההזמנות ששייכות למשתמש המאומת, כדי למנוע גישה לא מורשית לפרטי ההזמנה.

27b03aa215c454a.png

  1. חיפוש תחום או ענף

האפליקציה שלכם שמבוססת על סוכן משתמשת ב-AlloyDB ל-PostgreSQL כדי לספק יכולות מתקדמות של שאילתות, במיוחד באמצעות חיפוש וקטורי. ‫AlloyDB תומך ביצירת הטמעה אונליין ישירות בתוך מסד הנתונים באמצעות פונקציות SQL.

התכונה המתקדמת הזו מאפשרת לסוכן לתרגם קלט של שפה טבעית של משתמש לייצוג מספרי של הטמעה. לאחר מכן, הוא יכול לבצע חיפוש דמיון בקטלוג המוצרים שלכם (או בנתונים רלוונטיים אחרים) על סמך ההטמעות האלה, וכך להציג תוצאות חיפוש רלוונטיות מאוד.

באפליקציה שלכם, אתם יכולים לנסות את הטכניקה הזו כשאתם שואלים את Finn: "I'm looking for running shoes for an ultra-trail" (אני מחפש נעלי ריצה למסלול אולטרה).

1a9172b827077bde.png

  1. יכולות גיאו-מרחביות (PostGis)

‫AlloyDB ל-PostgreSQL שומר על תאימות מלאה לתכונות הסטנדרטיות של PostgreSQL. באפליקציה הזו, אנחנו משתמשים בתוסף הפופולרי PostGIS של PostgreSQL כדי לספק לאגנט יכולות של מיקום גיאוגרפי.

כשמבקשים מהסוכן: "תמצא חנויות בקרבת מקום", הסוכן מפעיל כלי שממנף אינדקסים של PostGIS במסד הנתונים כדי לאתר ביעילות את החנויות הקרובות ביותר למיקום שצוין או שנרמז על ידי המשתמש.

fa491f214521371.png

11. (אופציונלי) בדיקה של AlloyDB AI Natural Language to SQL

בקטע הזה מוצגת תכונה מתקדמת של AlloyDB ל-PostgreSQL שנמצאת בשלב לפני השקת הזמינות הכללית: שפה טבעית ל-SQL. התכונה הזו מאפשרת לכם ליצור שאילתות SQL ישירות מהנחיות בשפה טבעית, תוך ניצול היכולות של AI במסד הנתונים.

חשוב: זו תכונה בשלב שלפני זמינות כללית (Pre-GA), ולכן צריך להירשם כדי לקבל גישה לפרויקט Google Cloud, לאשכול AlloyDB ולמסד הנתונים.

  • הרשמה לגישה: כדי לבקש גישה לפרויקט, צריך למלא את הטופס הזה.
  • תיעוד: מידע נוסף על השימוש ב-AlloyDB AI Natural Language to SQL זמין בתיעוד הרשמי.

אחרי שנרשמים ומאשרים את הגישה לפרויקט, ממשיכים לשלבים הבאים ב-AlloyDB Studio.

a15964d53b4b15e1.png

נכנסים ל-AlloyDB באמצעות פרטי הכניסה שנוצרו כשיוצרים את האשכול:

  • שם משתמש: postgres
  • מסד נתונים: store
  • סיסמה: alloydb

‫1. יוצרים את התוסף alloydb_ai_nl. התוסף הזה מספק את הפונקציות הדרושות ליכולות של שפה טבעית ב-AlloyDB AI.

CREATE EXTENSION alloydb_ai_nl cascade;

‫2. יוצרים הגדרה לאפליקציה. ההגדרה מגדירה את הקשר של הסכימה שבו מודל ה-AI ישתמש כדי להבין את מסד הנתונים.

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

‫3 – רושמים את הסכימה או הטבלאות בהגדרה. מוסיפים להגדרה את הטבלאות והסכימות הספציפיות שהסוכן של האפליקציה יקיים איתן אינטראקציה.

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. יצירת ההקשר לסכימה או לטבלאות. בשלב הזה, המערכת מעבדת את הטבלאות הרשומות כדי ליצור את ההקשר הנדרש למודל ה-AI. התהליך הזה יכול להימשך כ-2-3 דקות.

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

‫5 – בודקים את ההקשר שנוצר באופן אוטומטי לטבלאות ולעמודות ספציפיות (אופציונלי). אתם יכולים לבדוק את ההקשר שנוצר כדי להבין איך מודל ה-AI מפרש את הסכימה שלכם.

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

ב-tools.yaml של הסוכן שלנו תמצאו כלי בשם check-inventory-by-store-brand-category. הכלי הזה משתמש ב-AlloyDB Natural Language to SQL:

2cd70da8caefe2f5.png

פותחים דפדפן אינטרנט ומשתמשים בכתובת ה-URL של השירות כדי לפתוח את האפליקציה: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

לאחר מכן, משתמשים בסקריפט הבא בממשק הצ'אט כדי לבדוק את היכולת החדשה הזו:

  • שלום, פין!
  • מהי הכמות הכוללת של מוצרים בקטגוריה Running של Salomon שנמצאים במלאי בחנות Sports Diagonal Mar?

כדי לראות את שאילתת ה-SQL בפועל שנוצרה על ידי AlloyDB AI מהקלט בשפה טבעית, חוזרים אל AlloyDB Studio ומריצים את השאילתה הבאה:

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

יוצג משפט ה-SQL שנוצר על ידי AlloyDB AI.

12. הסרת המשאבים

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם במעבדה הזו:

  1. במסוף Google Cloud, עוברים לדף Manage resources.
  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על סמל המחיקה.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

13. מזל טוב

מעולה! יצרתם בהצלחה אפליקציית AI מבוססת-סוכן ומבוססת-נתונים באמצעות ADK, ‏ MCP Toolbox for Databases ו-AlloyDB for PostgreSQL

מידע נוסף זמין במסמכי המוצר: Agent Development Kit,‏ MCP Toolbox for Databases ו- AlloyDB for PostgreSQL