Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

‫Google Cloud MCP ל-AlloyDB לסוכני AI

1. מבוא

ב-Codelab הזה נסביר איך להתחיל להשתמש בשרת Google Cloud MCP ל-AlloyDB, להפעיל אותו כחלק מערכת הכלים של סוכן AI ולהשתמש בו כחלק מהאפליקציה.

דרישות מוקדמות

הבנה בסיסית של Google Cloud ושל המסוף
מיומנויות בסיסיות בממשק שורת הפקודה וב-Cloud Shell

מה תלמדו

איך יוצרים אשכול AlloyDB ומייבאים נתונים לדוגמה
איך מפעילים את AlloyDB Data access API
איך מפעילים את Google Cloud MCP ל-AlloyDB NL
איך מוסיפים את Google Cloud MCP for AlloyDB לסוכן ADK
איך משתמשים ב-Google Cloud MCP ל-AlloyDB באפליקציה
איך משתמשים בסוכנים עם AlloyDBMCP לניתוח נתונים

מה תצטרכו

חשבון Google Cloud ופרויקט Google Cloud
דפדפן אינטרנט כמו Chrome שתומך במסוף Google Cloud וב-Cloud Shell

2. הגדרה ודרישות

הגדרת פרויקט

נכנסים ל-מסוף Google Cloud. אם עדיין אין לכם חשבון Gmail או Google Workspace, אתם צריכים ליצור חשבון.

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

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

בחלון Select a project (בחירת פרויקט), לוחצים על הלחצן New Project (פרויקט חדש) כדי לפתוח תיבת דו-שיח לפרויקט החדש.

בתיבת הדו-שיח, מזינים את שם הפרויקט המועדף ובוחרים את המיקום.

שם הפרויקט הוא השם המוצג של הפרויקט הזה למשתתפים. השם של הפרויקט לא משמש את Google APIs, ואפשר לשנות אותו בכל שלב.
מזהה הפרויקט הוא ייחודי לכל הפרויקטים ב-Google Cloud ואי אפשר לשנות אותו אחרי שהוא מוגדר. מסוף Google Cloud יוצר באופן אוטומטי מזהה ייחודי, אבל אפשר להתאים אותו אישית. אם לא אהבתם את המזהה שנוצר, אתם יכולים ליצור מזהה אקראי אחר או לספק מזהה משלכם כדי לבדוק אם הוא זמין. ברוב ה-codelabs, תצטרכו להפנות למזהה הפרויקט שלכם, שבדרך כלל מזוהה באמצעות placeholder בשם PROJECT_ID.
לידיעתכם, יש ערך שלישי, מספר פרויקט, שחלק מממשקי ה-API משתמשים בו. מידע נוסף על שלושת הערכים האלה מופיע במאמרי העזרה.

הפעלת החיוב

הגדרה של חשבון לחיוב לשימוש אישי

אם הגדרתם חיוב באמצעות קרדיטים ב-Google Cloud, אתם יכולים לדלג על השלב הזה.

כדי להגדיר חשבון לחיוב לשימוש אישי, עוברים לכאן כדי להפעיל את החיוב ב-Cloud Console.

הערות:

העלות של השלמת ה-Lab הזה במשאבי Cloud צריכה להיות פחות מ-3 דולר ארה"ב.
כדי למחוק משאבים ולמנוע חיובים נוספים, אפשר לבצע את השלבים בסוף ה-Lab הזה.
משתמשים חדשים זכאים לתקופת ניסיון בחינם בשווי 300$.

מפעילים את Cloud Shell

אפשר להפעיל את Google Cloud מרחוק מהמחשב הנייד, אבל ב-Codelab הזה נשתמש ב-Google Cloud Shell, סביבת שורת פקודה שפועלת בענן.

ב-מסוף Google Cloud, לוחצים על סמל Cloud Shell בסרגל הכלים שבפינה הימנית העליונה:

הפעלת Cloud Shell

אפשר גם ללחוץ על G ואז על S. אם אתם נמצאים במסוף Google Cloud, או אם אתם משתמשים בקישור הזה, רצף הפעולות הזה יפעיל את Cloud Shell.

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

צילום מסך של טרמינל Google Cloud Shell שבו מוצג שהסביבה מחוברת

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

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

הפעלת ה-API

כדי להשתמש ב-AlloyDB, ב-Compute Engine, ב-Networking services וב-Vertex AI, צריך להפעיל את ממשקי ה-API שלהם בפרויקט בענן של Google Cloud.

במסוף Cloud Shell, מוודאים שמזהה הפרויקט מוגדר:

gcloud config get-value project

המזהה של הפרויקט ב-Google אמור להופיע.

מגדירים את משתנה הסביבה PROJECT_ID:

PROJECT_ID=$(gcloud config get-value project)

מפעילים את כל השירותים הנדרשים:

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

הפלט הצפוי

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. פריסת AlloyDB

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

פריסת AlloyDB באמצעות סקריפט אוטומטי

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

בטרמינל של Cloud Shell, מריצים את הפקודה כדי לשכפל את סקריפט הפריסה מהמאגר.

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-ai-mcp"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL

cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

מריצים את סקריפט הפריסה.

./deploy_alloydb.sh

הסקריפט יפעל במשך זמן מה – בדרך כלל כ-5 עד 7 דקות. לאחר מכן, כפלט, הוא צריך לספק מידע על אשכול AlloyDB שנפרס. חשוב לדעת שהסיסמה תהיה שונה – כדאי לרשום את הסיסמה איפשהו לשימוש עתידי.

...
<redacted>
...
Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster)
Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715
Creating instance...done.                                                                                                                                                                                                             
----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (TRIAL)
Instance: alloydb-aip-01-pr
Region:   us-central1
Initial Password: JBBoDTgixzYwYpkF (if new cluster)
----------------------------------------

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

5. הכנת מסד הנתונים

כדי להשתמש בפונקציות ובאופרטורים של AI, צריך להפעיל את השילוב עם Vertex AI, להפעיל את Data access API וליצור מסד נתונים למערך נתונים לדוגמה.

מתן ההרשאות הנדרשות ל-AlloyDB

מוסיפים הרשאות ל-Vertex AI לסוכן השירות של AlloyDB.

פותחים כרטיסייה נוספת ב-Cloud Shell באמצעות הסימן '+' בחלק העליון.

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

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/discoveryengine.viewer"

הפלט הצפוי במסוף:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
... < redacted > 
etag: BwYIEbe_Z3U=
version: 1

הפעלת Data Access API

כדי להשתמש בכלי MCP כמו execute_sql, צריך להפעיל את Data Access API באשכול AlloyDB.

בכרטיסיית המסוף, מריצים את הפקודה.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
 -d '{
   "dataApiAccess": "ENABLED",
 }'

Update Instance Flags

כדי להשתמש בפונקציות מתקדמות של AI ב-AlloyDB, צריך להפעיל כמה דגלים של מסד הנתונים. אחרי שמפעילים את Data Access API, יכול להיות שיעברו כמה דקות עד שהמופע יהיה מוכן לשינויים הבאים. כדי לוודא שהמכונה מסומנת בסימן וי ירוק, צריך לבדוק את הסטטוס שלה במסוף.

בכרטיסיית המסוף, מריצים את הפקודה.

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags=google_ml_integration.enable_model_support=on,google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

הפעלת MCP

השלב הבא הוא להפעיל את שרת ה-MCP של Google Cloud עבור AlloyDB בפרויקט. כברירת מחדל, ה-MCP לא מופעל, והוא אחת מכמה שכבות של הגנה, כולל אימות והרשאה של IAM, API לגישה לנתונים ותפקידים בתוך האשכול.

בכרטיסיית המסוף, מריצים את הפקודה.

PROJECT_ID=$(gcloud config get-value project)
gcloud beta services mcp enable alloydb.googleapis.com \
    --project=$PROJECT_ID

סוגרים את הכרטיסייה באמצעות הפקודה 'exit' בכרטיסייה:

exit

התחברות ל-AlloyDB Studio

בפרקים הבאים אפשר להריץ את כל פקודות ה-SQL שדורשות חיבור למסד הנתונים ב-AlloyDB Studio. T

עוברים אל הדף Clusters (אשכולות) ב-AlloyDB ל-Postgres.

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

אחר כך לוחצים על AlloyDB Studio בצד ימין:

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

אם הסיסמה לא עובדת או ששכחתם לרשום אותה, אתם יכולים לשנות אותה. בתיעוד מוסבר איך עושים את זה.

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

ייפתח ממשק שבו אפשר להריץ פקודות SQL

יצירת מסד נתונים

יצירת מסד נתונים – מדריך למתחילים

בעורך של AlloyDB Studio, מריצים את הפקודה הבאה.

יצירת מסד נתונים:

CREATE DATABASE quickstart_db

הפלט אמור להיראות כך:

Statement executed successfully

התחברות ל-quickstart_db

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

מהרשימה הנפתחת בוחרים את מסד הנתונים החדש quickstart_db ומשתמשים באותו משתמש ובאותה סיסמה כמו קודם.

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

6. נתונים לדוגמה

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

יצירת קטגוריית אחסון

תשתמשו ב-Google SDK‏ (gcloud) כדי לייבא נתונים מהמאגר המשוכפל שלנו למסד הנתונים של AlloyDB, ותצטרכו ליצור קטגוריית אחסון בשביל זה ולתת גישה לחשבון השירות של AlloyDB. לחלופין, תמיד אפשר לנסות לעשות את זה באמצעות מסוף האינטרנט, כפי שמתואר במסמכי התיעוד.

בטרמינל של Google Cloud Shell, מריצים את הפקודה:

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer

טעינת נתונים

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

מעתיקים את קובץ ה-SQL הדחוס לקטגוריית האחסון החדשה:

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz  gs://$PROJECT_ID-import

לאחר מכן טוענים את הנתונים למסד הנתונים quickstart_db:

PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME  --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql

הפקודה תטען את מערך הנתונים לדוגמה למסד הנתונים quickstart_db. אפשר לאמת את הטבלאות והרשומות באמצעות AlloyDB Studio.

7. עבודה עם סוכן הנתונים

נתחיל עם סוכן AI לדוגמה שנוצר באמצעות Google ADK ל-Python, ונדגים איך להגדיר אותו כך שיפעל עם שרת Google Cloud MCP ל-AlloyDB.

בדיקת קוד המקור של הסוכן

מאמתים את קוד הסוכן במאגר המשוכפל באמצעות עורך Google Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/data_agent/agent.py

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

# Google Cloud MCP Server for AlloyDB

MCP_SERVER_URL = "https://alloydb.googleapis.com/mcp"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
    creds.refresh(GoogleAuthRequest())

print(f"Authenticated as project: {project_id}")

# 2. Configure MCP Toolset
# We use StreamableHTTPConnectionParams to pass the auth header
headers = {
    "Authorization": f"Bearer {creds.token}",
    "X-Goog-User-Project": project_id
}
    
connection_params = StreamableHTTPConnectionParams(
    url=MCP_SERVER_URL,
    headers=headers,
    timeout=300.0,
    sse_read_timeout=600.0
)

mcp_toolset = McpToolset(connection_params=connection_params)

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

MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"

# Agent configuration

root_agent = Agent(
    model=MODEL_ID,
    name='root_agent',
    description='A helpful assistant for analyst requests.',
    instruction=f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
    """,
    tools=[mcp_toolset],
)

לשירות Google Cloud MCP ל-AlloyDB יש קבוצה מוגדרת מראש של כלים. כדי לראות רשימה של כל הכלים הזמינים, אפשר להשתמש בפקודה curl ממסוף Cloud Shell באמצעות הפקודה הבאה. תמיד אפשר לבדוק את ההפניה האחרונה לשרת Google Cloud MCP ל-AlloyDB במסמכי העזרה.

curl -s -X POST http://alloydb.googleapis.com/mcp \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r '.result.tools[].name'
{
  "id": "my_id_01",
  "jsonrpc": "2.0",
  "method": "tools/list"
}
EOF

הפעלת הנציג

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

קודם נתקין את כל החבילות הנדרשות ל-Python באמצעות מנהל החבילות uv.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv sync

אחרי שמתקינים את כל החבילות, צריך להוסיף קובץ .env לספריית הסוכן כדי להנחות אותו להשתמש ב-Vertex AI לכל התקשורת עם מודלים של AI.

echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env

אחר כך אפשר להפעיל את הסוכן.

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

אמור להופיע פלט כמו זה שבהמשך, עם נקודת הקצה כמו http://127.0.0.1:8000 .

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

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

8. בדיקת AlloyDB MCP עם סוכן

הסוכן מאפשר לכם לשאול שאלות בפריסה גמישה באמצעות שפה טבעית, והוא ישתמש בשרת Google Cloud MCP עבור AlloyDB ככלי לענות על השאלות. השאלות מוצגות בפינה השמאלית התחתונה, והתשובה עם כל הפניות לכלים תופיע בחלק העליון.

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

בשדה להזנת קלט בצד שמאל למטה, מקלידים את הפקודה הבאה ומקישים על Enter.

Hello, can you tell me how many trips we've done in February this year?

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

בסופו של דבר, הוא יפיק את התוצאה אחרי שיבנה את השאילתה המתאימה ויריץ אותה במסד הנתונים.

לפי הרשומות במסד הנתונים שלנו, הושלמו 108 נסיעות בפברואר 2026.

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

עכשיו נבקש השוואה בין התוצאות לבין החודש הקודם.

How is it in comparison in numbers and mileage with the January?

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

In comparison to January 2026, February saw a slight decrease in both the number of trips and the total mileage:

January 2026: 114 trips with a total mileage of 185,597 km.
February 2026: 108 trips with a total mileage of 177,893 km.
This represents a decrease of 6 trips and 7,704 km in mileage for February compared to January.

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

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

עכשיו אפשר לנסות אפליקציה לדוגמה ולראות איך אפשר להשתמש בה ככלי לניתוח נתונים.

9. אפליקציה לדוגמה

באותו מאגר משוכפל יש לנו אפליקציה לדוגמה עבור חברת הלוגיסטיקה Cymbol. האפליקציה משתמשת ב-framework של Python‏ Mesop של Google .

כדי לנתח את קוד האפליקציה, פותחים את הקובץ app.py בעורך של Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
edit ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic/app.py

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

def run_query_sync(request_text, cluster_name, location, instance_name, database_name, project_id, session_id, summary):
    local_runner = FrontendRunner()
    
    instruction = f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    Use ai schema to use AI functions and models like gemini-3-flash-preview with the functions from the schema.
    """
    ...

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

מריצים את הפקודה ב-Cloud Shell.

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-ai-mcp"
cd ~/$REPO_NAME/$SOURCE_DIR/cymbal_logistic
uv run mesop app.py --port=8080

אחר כך משתמשים בתצוגה מקדימה באינטרנט ב-Google Cloud Shell על ידי לחיצה על http://localhost:8080

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

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

What was the average speed for each driver last month? List top 5 fasters drivers ranking them by the average speed. Show the name, distance and average speed for each of them.

ואז לוחצים על הלחצן Submit Request.

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

כדי לבדוק את הסוכנים ואת היכולות של האפליקציה, אפשר לנסות שאלות אנליטיות שונות.

עד עכשיו יכולתם לבצע ניתוח בסיסי וגילוי באמצעות הסוכן עם MCP. בפרק הבא תנסו להשתמש בתכונות מתקדמות יותר של AlloyDB.

10. פונקציות AI ב-AlloyDB

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

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

Can you analyze the activity for the last 5 months and evaluate drivers for the most positive customer feedbacks. Give me top 5 drivers listing names, distance and years of experience for each driver.

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

SELECT 
    d.first_name || ' ' || d.last_name as driver_name,
    SUM(sr.distance_km) as total_distance,
    d.experience_years,
    COUNT(cf.feedback_id) as positive_feedback_count

FROM drivers d

JOIN truck_trips tt ON d.driver_id = tt.driver_id

JOIN customer_feedback cf ON tt.trip_id = cf.trip_id

JOIN shipping_requests sr ON tt.request_id = sr.request_id

WHERE tt.arrival_time >= '2025-12-01' 
AND tt.arrival_time < '2026-05-01'
  
AND cf.rating >= 4

GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years

ORDER BY positive_feedback_count DESC, total_distance DESC

LIMIT 5;

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

אופרטורים של AI.RANK

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

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

Can you find the top 5 fastest drivers in the last month and rank them by the feedback using the AI.RANK function?  Give me top drivers  names, distance, years of experience and rank for each driver.

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

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

WITH fastest_drivers AS (
    SELECT 
        d.driver_id,
        d.first_name || ' ' || d.last_name as driver_name,
        d.experience_years,
        SUM(sr.distance_km) as total_distance,
        AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH 
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) as avg_speed,
        COALESCE(STRING_AGG(cf.feedback_text, ' | '), 'No feedback') as feedbacks,
        ROW_NUMBER() OVER (
ORDER BY AVG(sr.distance_km / (NULLIF(EXTRACT(EPOCH 
FROM (tt.arrival_time - tt.departure_time)), 0) / 3600)) DESC) - 1 as row_idx
    
FROM drivers d
    
JOIN truck_trips tt ON d.driver_id = tt.driver_id
    
JOIN shipping_requests sr ON tt.request_id = sr.request_id
    LEFT 
JOIN customer_feedback cf ON tt.trip_id = cf.trip_id
    
WHERE tt.arrival_time >= '2026-04-04'
      
AND tt.arrival_time IS NOT NULL 
      
AND tt.departure_time IS NOT NULL
      
AND tt.arrival_time > tt.departure_time
    
GROUP BY d.driver_id, d.first_name, d.last_name, d.experience_years
    
ORDER BY avg_speed DESC
    
LIMIT 5
)
SELECT 
    f.driver_name,
    f.total_distance,
    f.experience_years,
    f.avg_speed,
    f.feedbacks,
    (SELECT r.score 
FROM ai.rank(
        'semantic-ranker-fast-004',
        'excellent customer service, professional, friendly, fast, 
and reliable delivery reviews',
        ARRAY[f.feedbacks],
        1
    ) r 
LIMIT 1) as feedback_score

FROM fastest_drivers f

ORDER BY feedback_score DESC;

אתם יכולים להמשיך לבדוק את האפליקציה ולבחון את השאילתות כדי לראות איך הסוכן מגיע לתוצאות הסופיות.

כאן מסתיים שיעור ה-Lab. מקווה שהצלחת לעבור על כל הדוגמאות וללמוד איך להשתמש בשירות Google Cloud MCP ל-AlloyDB. כדי להפעיל את ה-MCP בארגון, מומלץ לשלב אותו עם התכונות של AlloyDB NL2SQL שמתוארות במאמרי העזרה של AlloyDB. אפשר לנסות את התכונה הזו באמצעות ה-codelab בנושא יצירת הצהרות SQL ל-AlloyDB.

11. ניקוי הסביבה

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

בסיום שיעור ה-Lab, משמידים את המופעים ואת האשכול של AlloyDB.

מחיקת אשכול AlloyDB וכל המכונות

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

האשכול נהרס עם האפשרות force, שמוחקת גם את כל המופעים ששייכים לאשכול.

אם התנתקתם וכל ההגדרות הקודמות אבדו, מגדירים את משתני הפרויקט והסביבה ב-Cloud Shell:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

מחיקת האשכול:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

הפלט הצפוי במסוף:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

מחיקת גיבויים של AlloyDB

מחיקת כל הגיבויים של AlloyDB באשכול:

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

הפלט הצפוי במסוף:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

12. מזל טוב

כל הכבוד, סיימתם את ה-Codelab.

מה למדנו

איך יוצרים אשכול AlloyDB ומייבאים נתונים לדוגמה
איך מפעילים את ממשק ה-API לגישה לנתונים ב-AlloyDB
איך מפעילים את Google Cloud MCP ל-AlloyDB NL
איך מוסיפים את Google Cloud MCP for AlloyDB לסוכן ADK
איך משתמשים ב-Google Cloud MCP ל-AlloyDB באפליקציה
איך משתמשים בסוכנים עם AlloyDBMCP לניתוח נתונים

13. סקר

פלט:

איך תשתמשו במדריך הזה?

רק קוראים את הטקסט

קוראים את הטקסט ומבצעים את התרגילים