יצירת עוזרת 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 Toolbox for Databases בסביבת ענן.
  • שימוש ביכולות המתקדמות של שאילתות ב-AlloyDB כדי ליצור תשובות חכמות של סוכנים.

מה תצטרכו

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

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

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

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

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

יצירת פרויקט

  1. ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-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. כך רשת הענן הווירטואלי הפרטי (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 הרשאה לסוכן השירות של AlloyDB:

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. לאחר מכן, עורכים ועוברים לקטע Public IP connectivity (קישוריות לכתובת 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, צריך להשתמש בשרת proxy ל-AlloyDB Auth. כלי השירות הזה יוצר מנהרה מאובטחת לחיבור למסד הנתונים. (ראו AlloyDB Auth Proxy)

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

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

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

chmod +x alloydb-auth-proxy

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

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

מתחברים למופע 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 של הפרויקט המשוכפל כדי לגשת לקובץ dump של מסד הנתונים.

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 הזה. לרוב, הן קשורות להרשאות או לאובייקטים שכבר קיימים אם ה-dump מכיל סכימה מלאה. יופיעו כמה אזהרות ושגיאות שאפשר להתעלם מהן.

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, מריצים את הפקודה:

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 שלכם, שתוגדר בהמשך ב-codelab הזה. חשוב להחליף את [YOUR_PROJECT_NUMBER] במספר האמיתי שהעתקתם.

1873d292fd27f07c.png

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

6. הגדרה של MCP ToolBox for Databases

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

אחד ממסדי הנתונים שנתמכים על ידי 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.16.0

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

chmod +x toolbox

הערה: כאן מצוינת גרסה 0.16.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 Toolbox for Databases

מריצים את הפקודה הבאה (מהתיקייה 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

כדי שהשרת שלכם ב-Toolbox יהיה נגיש כנקודת קצה ציבורית שאפשר לשלב עם אפליקציות אחרות ועם סוכן ה-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

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

קודם צריך להפעיל בפרויקט את ממשקי ה-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 Toolbox for Databases.

באמצעות 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, כך שאפשר יהיה לגשת אליו דרך נקודת קצה של 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

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

"שלום! אני Finn, עוזר קניות מבוסס-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 Agent והיכולות שלו, אפשר לצפות בסרטון הבא:

הדגמה של עוזר אישי מבוסס-AI לסוכני ספורט שמבוסס על AlloyDB

10. תוצאות

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

  1. Authorization Service

ערכת הכלים של 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. (אופציונלי) בדיקה של שפה טבעית ל-SQL ב-AlloyDB AI

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

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

  • הרשמה לגישה: כדי לבקש גישה לפרויקט, צריך למלא את הטופס הזה.
  • תיעוד: מידע נוסף על שימוש בשפה טבעית ב-AlloyDB AI כדי ליצור 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. הכלי הזה משתמש בתכונה 'שפה טבעית ל-SQL' של AlloyDB:

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. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete (מחיקה).
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

13. מזל טוב

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

מידע נוסף זמין במסמכי המוצר: ערכה לפיתוח סוכנים, MCP Toolbox for Databases ו- AlloyDB ל-PostgreSQL