1. מבוא
בשיעור Codelab הזה נסביר איך ליצור סוכן באמצעות הערכה לפיתוח סוכנים (ADK) שמשתמש ב-MCP Toolbox for Databases.
במהלך ה-codelab, תשתמשו בגישה שלב אחר שלב באופן הבא:
- הקצאת מסד נתונים של Cloud SQL ל-PostgreSQL שיכלול את מסד הנתונים של המלונות ונתונים לדוגמה.
- מגדירים את MCP Toolbox for Databases, שמאפשר גישה לנתונים.
- תכנון ופיתוח של סוכן באמצעות הערכה לפיתוח סוכנים (ADK) שישתמש ב-MCP Toolbox כדי לענות על שאילתות מהמשתמש.
- הכרת האפשרויות לבדיקת הסוכן ו-MCP Toolbox for Databases באופן מקומי וב-Google Cloud באמצעות שירות Cloud Run.
מה עושים
- תכנון, בנייה ופריסה של סוכן שיענה על שאילתות משתמשים לגבי מלונות במיקום מסוים או יחפש מלונות לפי שם.
מה תלמדו
- הקצאת מסד נתונים של Cloud SQL ל-PostgreSQL ואכלוס שלו בנתונים לדוגמה.
- מגדירים את MCP Toolbox for Databases עבור מופע מסד הנתונים של Cloud SQL ל-PostgreSQL.
- תכנון ופיתוח של סוכן באמצעות Agent Development Kit (ADK) כדי לענות על שאילתות של משתמשים.
- בודקים את הסוכן ואת MCP Toolbox for Databases בסביבה המקומית.
- (אופציונלי) פריסת הסוכן ו-MCP Toolbox for Databases ב-Google Cloud.
מה תצטרכו
- דפדפן האינטרנט Chrome
- חשבון Gmail
- פרויקט ב-Cloud עם חיוב מופעל
בשיעור Codelab הזה, שמיועד למפתחים בכל הרמות (כולל מתחילים), נעשה שימוש ב-Python באפליקציה לדוגמה. עם זאת, לא נדרש ידע ב-Python, ויכולת בסיסית של קריאת קוד תספיק כדי להבין את המושגים שמוצגים.
2. לפני שמתחילים
יצירת פרויקט
- ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
- הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
- תשתמשו ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud ומגיעה עם bq שנטען מראש. לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud.
- אחרי שמתחברים ל-Cloud Shell, אפשר לבדוק שכבר בוצע אימות ושהפרויקט מוגדר לפי מזהה הפרויקט באמצעות הפקודה הבאה:
gcloud auth list
- מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט.
gcloud config list project
- אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:
gcloud config set project <YOUR_PROJECT_ID>
- מפעילים את ממשקי ה-API הנדרשים באמצעות הפקודה שמוצגת למטה. זה יימשך כמה דקות, אז כדאי לחכות בסבלנות.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
אם הפקודה תפעל בהצלחה, תוצג הודעה שדומה לזו שמופיעה בהמשך:
Operation "operations/..." finished successfully.
אפשר גם לחפש כל מוצר במסוף או להשתמש בקישור הזה במקום בפקודת gcloud.
אם פספסתם API כלשהו, תמיד תוכלו להפעיל אותו במהלך ההטמעה.
אפשר לעיין במאמרי העזרה בנושא פקודות gcloud ושימוש בהן.
3. יצירת מכונה של Cloud SQL
נשתמש במופע של Google Cloud SQL ל-PostgreSQL כדי לאחסן את נתוני המלונות. Cloud SQL ל-PostgreSQL הוא שירות מנוהל של מסד נתונים שעוזר לכם להגדיר, לתחזק ולנהל את מסדי הנתונים הרלציוניים של PostgreSQL ב-Google Cloud Platform.
מריצים את הפקודה הבאה ב-Cloud Shell כדי ליצור את המכונה:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
ביצוע הפקודה הזו נמשך כ-3 עד 5 דקות. אחרי שהפקודה תופעל בהצלחה, יופיע פלט שמציין שהפקודה הסתיימה, יחד עם פרטי מכונת Cloud SQL כמו NAME, DATABASE_VERSION, LOCATION וכו'.
4. הכנת מסד הנתונים של המלונות
עכשיו ניצור נתוני דוגמה לסוכן המלונות שלנו.
נכנסים אל הדף של Cloud SQL במסוף Cloud.אמור להופיע המופע hoteldb-instance מוכן ונוצר. לוחצים על שם המכונה (hoteldb-instance) כמו שמוצג בהמשך:
בתפריט הימני של Cloud SQL, בוחרים באפשרות Cloud SQL Studio כמו שמוצג בהמשך:
תתבקשו להיכנס ל-Cloud SQL Studio, שדרכו נציג כמה פקודות SQL. בוחרים באפשרות postgres עבור מסד הנתונים, וגם עבור המשתמש והסיסמה. הערך שבו צריך להשתמש הוא postgres. לוחצים על AUTHENTICATE.
קודם ניצור את טבלת המלונות לפי הסכימה שמופיעה בהמשך. באחת מחלוניות העריכה ב-Cloud SQL Studio, מריצים את ה-SQL הבא:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
עכשיו נאכלס את טבלת המלונות בנתונים לדוגמה. מריצים את ה-SQL הבא:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
כדי לאמת את הנתונים, מריצים שאילתת SELECT SQL כמו בדוגמה הבאה:
SELECT * FROM hotels;
בטבלת המלונות אמור להופיע מספר רשומות, כמו שמוצג בהמשך:
סיימנו את תהליך ההגדרה של מכונת Cloud SQL ויצרנו את הנתונים לדוגמה. בקטע הבא נגדיר את MCP Toolbox for Databases.
5. הגדרת MCP Toolbox for Databases
MCP Toolbox for Databases הוא שרת MCP בקוד פתוח למסדי נתונים. הוא תוכנן במיוחד לשימוש ברמת הארגון ולסביבות ייצור. הוא מאפשר לכם לפתח כלים בקלות, במהירות ובאופן מאובטח יותר, כי הוא מטפל במורכבויות כמו איגום חיבורים, אימות ועוד.
ה-Toolbox עוזר לכם ליצור כלי AI גנרטיבי שמאפשרים לסוכנים שלכם לגשת לנתונים במסד הנתונים. ארגז הכלים מספק:
- פיתוח פשוט יותר: אפשר לשלב כלים בסוכן בפחות מ-10 שורות קוד, לעשות שימוש חוזר בכלים בין כמה סוכנים או מסגרות, ולפרוס גרסאות חדשות של כלים בקלות רבה יותר.
- ביצועים טובים יותר: שיטות מומלצות כמו איגום חיבורים, אימות ועוד.
- אבטחה משופרת: אימות משולב לגישה מאובטחת יותר לנתונים
- ניראות מקצה לקצה: מדדים ומעקב מוכנים לשימוש עם תמיכה מובנית ב-OpenTelemetry.
ערכת הכלים נמצאת בין מסגרת התזמור של האפליקציה לבין מסד הנתונים, ומספקת מישור בקרה שמשמש לשינוי, להפצה או להפעלה של כלים. הוא מפשט את ניהול הכלים על ידי מתן מיקום מרכזי לאחסון ולעדכון כלים, ומאפשר לכם לשתף כלים בין סוכנים ואפליקציות ולעדכן את הכלים האלה בלי לפרוס מחדש את האפליקציה.
אפשר לראות שאחד ממסדי הנתונים שנתמכים על ידי MCP Toolbox for Databases הוא Cloud SQL, והקצאנו אותו בקטע הקודם.
התקנת ארגז הכלים
פותחים את הטרמינל של Cloud Shell ויוצרים תיקייה בשם mcp-toolbox.
mkdir mcp-toolbox
עוברים לתיקייה mcp-toolbox באמצעות הפקודה שמוצגת למטה:
cd mcp-toolbox
מתקינים את הגרסה הבינארית של MCP Toolbox for Databases באמצעות הסקריפט שמופיע בהמשך. הפקודה שמופיעה בהמשך היא ל-Linux, אבל אם אתם משתמשים ב-Mac או ב-Windows, חשוב לוודא שאתם מורידים את הקובץ הבינארי הנכון. כדאי לעיין בדף הגרסאות של מערכת ההפעלה והארכיטקטורה ולהוריד את הקובץ הבינארי הנכון.
export VERSION=1.1.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
עכשיו יש לנו את הגרסה הבינארית של ארגז הכלים, והיא מוכנה לשימוש. בואו נוודא שהגדרנו את קובץ ההפעלה הבינארי של ארגז הכלים בצורה נכונה ושהוא מציין את הגרסה הנכונה.
מריצים את הפקודה הבאה כדי לקבוע את הגרסה של כלי הניהול:
./toolbox -v
הפלט שיתקבל אמור להיראות כך:
toolbox version 1.1.0+binary.linux.amd64.466aef0
בשלב הבא מגדירים את ארגז הכלים עם מקורות הנתונים והגדרות אחרות.
הגדרת הקובץ tools.yaml
הדרך העיקרית להגדיר את Toolbox היא באמצעות הקובץ tools.yaml. יוצרים קובץ בשם tools.yaml באותה תיקייה, כלומר mcp-toolbox. התוכן של הקובץ מוצג בהמשך.
אפשר להשתמש בעורך nano שזמין ב-Cloud Shell. הפקודה nano היא: "nano tools.yaml".
חשוב להחליף את הערך YOUR_PROJECT_ID במזהה הפרויקט ב-Google Cloud.
kind: source
name: my-cloud-sql-source
type: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: postgres
---
kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
---
kind: tool
name: search-hotels-by-location
type: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
---
kind: toolset
name: my_first_toolset
tools:
- search-hotels-by-name
- search-hotels-by-location
כדי שנוכל להבין את הקובץ, נבקש ממך לספר לנו עליו בקצרה:
-
Sourcesמייצג את מקורות הנתונים השונים שהכלי יכול ליצור איתם אינטראקציה. מקור מייצג מקור נתונים שכלי יכול ליצור איתו אינטראקציה. אפשר להגדיר אתSourcesכמפה בקטע sources בקובץ tools.yaml. בדרך כלל, הגדרת מקור תכיל את כל המידע שנדרש כדי להתחבר למסד הנתונים ולבצע בו פעולות. במקרה שלנו, הגדרנו מקור יחיד שמפנה למכונת Cloud SQL ל-PostgreSQL עם פרטי הכניסה. מידע נוסף זמין במאמר בנושא מקורות. Toolsמגדירות פעולות שאפשר לבצע באמצעות סוכן – כמו קריאה וכתיבה במקור. כלי מייצג פעולה שהסוכן יכול לבצע, כמו הפעלת הצהרת SQL. אפשר להגדיר אתToolsכמפה בקטע tools בקובץ tools.yaml. בדרך כלל, כלי יצטרך מקור כדי לפעול. בדוגמה שלנו, אנחנו מגדירים שני כלים:search-hotels-by-nameו-search-hotels-by-location, ומציינים את המקור שהם פועלים עליו, יחד עם ה-SQL והפרמטרים. מידע נוסף זמין במאמר בנושא כלים.- לבסוף, יש לנו את
Toolset, שמאפשרת לכם להגדיר קבוצות של כלים שאתם רוצים שייטענו יחד. האפשרות הזו יכולה להיות שימושית להגדרת קבוצות שונות על סמך סוכן או אפליקציה. במקרה שלנו, יש לנו ערכת כלים אחת בשםmy_first_toolset, שמכילה את שני הכלים שהגדרנו.
כדי לשמור את הקובץ tools.yaml בעורך nano:
- לוחצים על
Ctrl + O(הפקודה 'כתיבה'). - תתבקשו לאשר את 'שם הקובץ לכתיבה'. פשוט לוחצים על
Enter. - עכשיו לוחצים על
Ctrl + Xכדי לצאת.
הפעלת השרת של MCP Toolbox for Databases
מריצים את הפקודה הבאה (מהתיקייה mcp-toolbox) כדי להפעיל את השרת:
./toolbox --config "tools.yaml"
הפלט שיוצג צריך להראות שהשרת הצליח להתחבר למקורות הנתונים שלנו ושהוא טען את ערכת הכלים והכלים. דוגמה לפלט:
2026-04-25T09:08:00.738271-07:00 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-04-25T09:08:00.738397-07:00 INFO "Initialized 0 authServices: "
2026-04-25T09:08:00.738405-07:00 INFO "Initialized 0 embeddingModels: "
2026-04-25T09:08:00.738453-07:00 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-04-25T09:08:00.738497-07:00 INFO "Initialized 2 toolsets: my_first_toolset, default"
2026-04-25T09:08:00.738504-07:00 INFO "Initialized 0 prompts: "
2026-04-25T09:08:00.738517-07:00 INFO "Initialized 1 promptsets: default"
2026-04-25T09:08:00.738566-07:00 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag"
2026-04-25T09:08:00.738625-07:00 WARN "wildcard (`*`) allows all hosts to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-hosts` flag to prevent DNS rebinding attacks"
2026-04-25T09:08:00.738909-07:00 INFO "Server ready to serve!"
שרת ה-MCP Toolbox פועל כברירת מחדל ביציאה 5000. אם אתם מגלים שהיציאה 5000 כבר בשימוש, אתם יכולים להשתמש ביציאה אחרת (למשל 7000) בהתאם לפקודה שמוצגת למטה. במקום היציאה 5000 בפקודות הבאות, צריך להשתמש ב-7000.
./toolbox --config "tools.yaml" --port 7000
נשתמש ב-Cloud Shell כדי לבדוק את זה.
לוחצים על Web Preview ב-Cloud Shell כמו שמוצג למטה:
לוחצים על שינוי היציאה ומגדירים את היציאה ל-5000 כמו שמוצג למטה. לוחצים על 'שינוי ותצוגה מקדימה'.
הפלט הבא אמור להתקבל:
בדיקת הכלים באמצעות ממשק המשתמש של MCP Toolbox for Databases
ארגז הכלים מספק ממשק חזותי (ממשק המשתמש של ארגז הכלים) לאינטראקציה ישירה עם כלים באמצעות שינוי פרמטרים, ניהול כותרות והפעלת שיחות, והכול בממשק משתמש פשוט באינטרנט.
כדי לבדוק את זה, אפשר להריץ את הפקודה הקודמת שבה השתמשנו כדי להפעיל את Toolbox Server עם האפשרות --ui.
כדי לעשות את זה, צריך להשבית את המופע הקודם של MCP Toolbox for Databases Server שאולי פועל, ולהריץ את הפקודה הבאה:
./toolbox --config "tools.yaml" --ui
הפלט שיוצג צריך להראות שהשרת הצליח להתחבר למקורות הנתונים שלנו ושהוא טען את ערכת הכלים והכלים. בהמשך מופיע פלט לדוגמה, שבו מצוין שממשק המשתמש של כלי העריכה פועל.
2026-04-25T09:17:45.54415-07:00 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-04-25T09:17:45.544225-07:00 INFO "Initialized 0 authServices: "
2026-04-25T09:17:45.544239-07:00 INFO "Initialized 0 embeddingModels: "
2026-04-25T09:17:45.544298-07:00 INFO "Initialized 2 tools: search-hotels-by-location, search-hotels-by-name"
2026-04-25T09:17:45.544345-07:00 INFO "Initialized 2 toolsets: default, my_first_toolset"
2026-04-25T09:17:45.544365-07:00 INFO "Initialized 0 prompts: "
2026-04-25T09:17:45.544393-07:00 INFO "Initialized 1 promptsets: default"
2026-04-25T09:17:45.544439-07:00 WARN "wildcard (`*`) allows all origin to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-origins` flag"
2026-04-25T09:17:45.54448-07:00 WARN "wildcard (`*`) allows all hosts to access the resource and is not secure. Use it with cautious for public, non-sensitive data, or during local development. Recommended to use `--allowed-hosts` flag to prevent DNS rebinding attacks"
2026-04-25T09:17:45.544887-07:00 INFO "Server ready to serve!"
2026-04-25T09:17:45.544908-07:00 INFO "Toolbox UI is up and running at: http://127.0.0.1:5000/ui"
לוחצים על כתובת ה-URL של ממשק המשתמש ומוודאים שיש לכם
/ui
בסוף כתובת ה-URL (אם מריצים את הפקודה הזו ב-Cloud Shell, ההפניה האוטומטית בדפדפן גורמת לכך שהסיומת /ui לא מופיעה בסוף). יוצג ממשק משתמש כמו שמוצג בהמשך:
לוחצים על האפשרות 'כלים' בצד ימין כדי לראות את הכלים שהוגדרו. במקרה שלנו, אמורים להיות שני כלים: search-hotels-by-name ו-search-hotels-by-location, כמו שמוצג בהמשך:
פשוט לוחצים על אחד מהכלים (search-hotels-by-location) ומופיע דף שבו אפשר לבדוק את הכלי על ידי הזנת ערכי הפרמטרים הנדרשים ואז לחיצה על הפעלת הכלי כדי לראות את התוצאה. דוגמה להרצה:
ב-MCP Toolkit for Databases מוסבר גם על דרך לבדוק את הכלים באמצעות Python. המידע הזה מופיע כאן.
אם נחזור לתרשים שהוצג קודם (כמו שמופיע בהמשך), נראה שסיימנו להגדיר את מסד הנתונים ואת שרת ה-MCP, ועכשיו יש לנו שתי אפשרויות:
- כדי להבין איך אפשר להגדיר את שרת ה-MCP במסוף או בסביבת פיתוח משולבת (IDE) עם עזרה מ-AI, עוברים לשלב 6. במאמר הזה נסביר איך אנחנו משלבים את השרת MCP Toolbox ב-
Gemini CLI. - כדי להבין איך להשתמש ב-
Agent Development Kit (ADK) using Pythonכדי לכתוב סוכנים משלכם שיכולים להשתמש ב-MCP Server Toolbox ככלי, כדי לענות על שאלות שקשורות למערך הנתונים, עוברים לשלבים 7 ו-8.
6. שילוב של MCP Toolbox ב-Gemini CLI
Gemini CLI הוא סוכן AI בקוד פתוח שמאפשר לנצל את היכולות של Gemini ישירות בטרמינל. אפשר להשתמש בו גם למשימות שקשורות לתכנות וגם למשימות שלא קשורות לתכנות. הוא משולב עם כלים שונים, ויש בו תמיכה בשרתי MCP.
בקטע הזה נגדיר את השרת MCP Toolbox for Databases ב-Gemini CLI, ואז נשתמש ב-Gemini CLI כדי לתקשר עם הנתונים שלנו.
השלב הראשון יהיה לוודא שכלי הארגז פועל באחד מהטרמינלים של Cloud Shell. אם מריצים את השרת ביציאת ברירת המחדל 5000, הממשק של שרת ה-MCP זמין בנקודת הקצה הבאה: http://localhost:5000/mcp.
פותחים טרמינל חדש ויוצרים תיקייה בשם my-gemini-cli-project באופן הבא. עוברים גם לתיקייה my-gemini-cli-project.
mkdir my-gemini-cli-project
cd my-gemini-cli-project
מריצים את הפקודה הבאה כדי להוסיף את שרת ה-MCP לרשימת שרתי ה-MCP שהוגדרו ב-Gemini CLI.
gemini mcp add --scope="project" --transport="http" "MCPToolbox" "http://localhost:5000/mcp"
אפשר לבדוק את הרשימה הנוכחית של שרתי MCP שהוגדרו ב-Gemini CLI באמצעות הפקודה הבאה:
gemini mcp list
באופן אידיאלי, אמור להופיע סימן וי ירוק ליד MCPToolbox שהגדרנו, שמציין ש-Gemini CLI הצליח להתחבר לשרת MCP.
Configured MCP servers:
✓ MCPToolbox: http://localhost:5000/mcp (http) - Connected
לפני שמפעילים את Gemini CLI, כדאי להגדיר את משתני הסביבה הבאים כדי לעזור ל-Gemini CLI להפנות את הבקשות שלכם למודל הנכון.
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global
באותו מסוף, מוודאים שאתם נמצאים בתיקייה my-gemini-cli-project. מפעילים את Gemini CLI באמצעות הפקודה gemini.
ייפתח ממשק Gemini CLI ויוצג בו שרת MCP אחד שהוגדר. אפשר להשתמש בפקודה /mcp list כדי לראות את רשימת שרתי ה-MCP והכלים. לדוגמה, הנה פלט לדוגמה:
עכשיו אפשר לתת כל אחת מההנחיות הבאות:
Which hotels are there in Basel?Tell me more about the Hyatt Regency?
תראו שהשאילתות שלמעלה יגרמו ל-Gemini CLI לבחור את הכלי המתאים מ-MCPToolbox. תתבקשו לתת הרשאה להפעלת הכלי. נותנים לו את ההרשאה הנדרשת, ואז אפשר לראות שהתוצאות מוחזרות ממסד הנתונים.
7. כתיבת הסוכן באמצעות ערכה לפיתוח סוכנים (ADK)
התקנת הערכה לפיתוח סוכנים (ADK)
פותחים כרטיסייה חדשה במסוף ב-Cloud Shell ויוצרים תיקייה בשם my-agents באופן הבא. עוברים גם לתיקייה my-agents.
mkdir my-agents
cd my-agents
עכשיו ניצור סביבה וירטואלית של Python באמצעות venv באופן הבא:
python -m venv .venv
מפעילים את הסביבה הווירטואלית באופן הבא:
source .venv/bin/activate
מתקינים את חבילות ADK ו-MCP Toolbox for Databases יחד עם התלות של langchain באופן הבא:
pip install google-adk toolbox-core
עכשיו תוכלו להפעיל את כלי השירות adk באופן הבא.
adk
תוצג רשימה של פקודות.
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
conformance Conformance testing tools for ADK.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
eval_set Manage Eval Sets.
migrate ADK migration commands.
optimize Optimizes the root agent instructions using the GEPA optimizer.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
יצירת אפליקציית הנציג הראשונה
עכשיו נשתמש ב-adk כדי ליצור scaffolding לאפליקציית סוכן המלונות שלנו באמצעות הפקודה adk create עם שם האפליקציה **(hotel_agent_app)**כפי שמופיע בהמשך.
adk create hotel_agent_app
פועלים לפי השלבים ובוחרים באפשרויות הבאות:
- מודל Gemini לבחירת מודל לסוכן הבסיסי.
- בוחרים ב-Vertex AI עבור ה-Backend.
- יוצגו מזהה הפרויקט ב-Google ואזור ברירת המחדל. בוחרים את ברירת המחדל עצמה.
Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- __init__.py
- agent.py
בודקים את התיקייה שבה נוצרו תבנית ברירת מחדל וקבצים נדרשים לסוכן. אפשר לראות את הקבצים באמצעות הפקודה ls -al במסוף בספרייה <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app.
הקובץ הראשון הוא .env. הקובץ הזה כבר נוצר כמו שצוין קודם, ואפשר פשוט לראות את התוכן שלו שמוצג בהמשך:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
הערכים מציינים שנשתמש ב-Gemini דרך Vertex AI, יחד עם הערכים המתאימים של מזהה הפרויקט ב-Google Cloud והמיקום.
אחרי זה יש את הקובץ __init__.py שמסמן את התיקייה כמודול, ויש בו הצהרה אחת שמייבאת את הסוכן מהקובץ agent.py.
from . import agent
לסיום, נסתכל על הקובץ agent.py. התוכן מוצג בהמשך:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
זהו הסוכן הפשוט ביותר שאפשר לכתוב באמצעות ADK. מתוך מסמכי ה-ADK page, סוכן הוא יחידת ביצוע עצמאית שנועדה לפעול באופן אוטונומי כדי להשיג מטרות ספציפיות. סוכנים יכולים לבצע משימות, ליצור אינטראקציה עם משתמשים, להשתמש בכלים חיצוניים ולתאם עם סוכנים אחרים.
ספציפית, סוכן LLM, שנקרא בדרך כלל Agent, משתמש במודלים גדולים של שפה (LLM) כמנוע הליבה שלו כדי להבין שפה טבעית, להסיק מסקנות, לתכנן, ליצור תשובות ולהחליט באופן דינמי איך להמשיך או באילו כלים להשתמש. לכן הוא אידיאלי למשימות גמישות שמתמקדות בשפה. מידע נוסף על סוכני LLM
נשנה את הקוד של agent.py באופן הבא:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
בדיקה מקומית של אפליקציית הסוכן
בחלון הטרמינל הקיים, מריצים את הפקודה הבאה. מוודאים שאתם נמצאים בתיקיית ההורה (my-agents) שמכילה את התיקייה hotel_agent_app.
adk web
דוגמה להרצה:
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
לוחצים על הקישור האחרון, וצריך להיפתח מסוף אינטרנט לבדיקת הסוכן. הדפדפן אמור להיפתח עם המסך הבא:
שימו לב שבפינה הימנית העליונה, המכשיר hotel_agent_app זוהה. עכשיו אפשר להתחיל לשוחח עם הנציג. תנו כמה הנחיות שקשורות לערים. דוגמה לשיחה:
אפשר להפסיק את התהליך שפועל במסוף Cloud Shell (Ctrl-C).
דרך נוספת לבדיקת הסוכן היא באמצעות הפקודה adk run מהתיקייה my-agents, כמו שמופיע בהמשך.
adk run hotel_agent_app
אפשר לנסות את הפקודה ולנהל שיחה עם הסוכן דרך שורת הפקודה (המסוף). כדי לסגור את השיחה, מקלידים exit.
8. חיבור הסוכן שלנו לכלים
עכשיו אנחנו יודעים איך לכתוב סוכן ולבדוק אותו באופן מקומי. נחבר את הסוכן הזה לכלים. ב-ADK, כלי מייצג יכולת ספציפית שניתנת לסוכן AI, ומאפשרת לו לבצע פעולות ולקיים אינטראקציה עם העולם מעבר ליכולות הליבה שלו של יצירת טקסט וניתוח מידע.
במקרה שלנו, נצייד את הסוכן שלנו בכלים שהגדרנו ב-MCP Toolbox for Databases.
משנים את הקובץ agent.py באמצעות הקוד הבא. שימו לב שאנחנו משתמשים ביציאה 5000 כברירת מחדל בקוד, אבל אם אתם משתמשים במספר יציאה חלופי, אתם צריכים להשתמש בו.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.5-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
עכשיו אפשר לבדוק את הסוכן שיאחזר נתונים אמיתיים ממסד הנתונים של PostgreSQL שהוגדר באמצעות MCP Toolbox for Databases.
כדי לעשות את זה, צריך לפעול לפי הרצף הבא:
בטרמינל אחד של Cloud Shell, מפעילים את MCP Toolbox for Databases. יכול להיות שהיא כבר פועלת באופן מקומי ביציאה 5000, כמו שבדקנו קודם. אם לא, מריצים את הפקודה הבאה (מהתיקייה mcp-toolbox) כדי להפעיל את השרת:
./toolbox --config "tools.yaml"
הפלט שיוצג צריך להראות שהשרת הצליח להתחבר למקורות הנתונים שלנו ושהוא טען את ערכת הכלים והכלים.
אחרי שהשרת של MCP יופעל בהצלחה, במסוף אחר מפעילים את הסוכן כמו שעשינו קודם באמצעות הפקודה adk run (מהתיקייה my-agents) שמוצגת בהמשך. אפשר גם להשתמש בפקודה adk web.
$ adk run hotel_agent_app/
...
Running agent hotel_agent, type exit to exit.
[user]: what can you do for me ?
[hotel_agent]: I can help you find hotels by location or by name.
[user]: I would like to search for hotels?
[hotel_agent]: Great! Do you want to search by location or by hotel name?
[user]: I'd like to search in Basel
[hotel_agent]: Here are some hotels in Basel:
* Holiday Inn Basel (Upper Midscale)
* Hyatt Regency Basel (Upper Upscale)
* Hilton Basel (Luxury)
[user]:
שימו לב שהסוכן משתמש עכשיו בשני הכלים שהגדרנו ב-MCP Toolbox for Databases (search-hotels-by-name ו-search-hotels-by-location) ומספק לנו את האפשרויות הנכונות. אחרי כן, הוא יכול לאחזר את הנתונים ממסד הנתונים של מופע PostgreSQL ולעצב את התגובה בהתאם.
כך מסיימים את הפיתוח והבדיקה המקומיים של סוכן המלונות שיצרנו באמצעות הערכה לפיתוח סוכנים (ADK) ושהופעל על ידי כלים שהגדרנו ב-MCP Toolbox for Databases.
9. (אופציונלי) פריסה של MCP Toolbox for Databases וסוכן ב-Cloud Run
בקטע הקודם השתמשנו במסוף Cloud Shell כדי להפעיל את שרת MCP Toolbox ובדקנו את הכלים באמצעות הסוכן. הפעולה הזו בוצעה באופן מקומי בסביבת Cloud Shell.
יש לכם אפשרות לפרוס את השרת MCP Toolbox ואת הסוכן בשירותי Google Cloud שיכולים לארח את האפליקציות האלה בשבילנו.
אירוח של שרת MCP Toolbox ב-Cloud Run
קודם כול, אפשר להתחיל עם שרת MCP Toolbox ולארח אותו ב-Cloud Run. כך נקבל נקודת קצה ציבורית שנוכל לשלב עם כל אפליקציה אחרת ו/או עם אפליקציות של סוכנים. הוראות לאירוח האתר ב-Cloud Run מפורטות כאן. עכשיו נסביר את השלבים העיקריים.
מפעילים טרמינל חדש של Cloud Shell או משתמשים בטרמינל קיים של Cloud Shell. עוברים לתיקייה mcp-toolbox שבה נמצאים הקובץ הבינארי toolbox והקובץ tools.yaml.
מריצים את הפקודות הבאות (לכל פקודה מצורף הסבר):
מגדירים את המשתנה PROJECT_ID כך שיצביע על מזהה הפרויקט ב-Google Cloud.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_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 ולתקשר עם Cloud SQL.
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/cloudsql.client
נעלה את הקובץ 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
השלב האחרון בפקודת הפריסה המוכרת ל-Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--config=/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 [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
עכשיו אפשר להיכנס לכתובת Service URL שמופיעה למעלה בדפדפן. ההודעה "Hello World" שראינו קודם אמורה להופיע.
אפשר גם להיכנס אל Cloud Run מתוך Google Cloud Console, ושירות Toolbox יופיע ברשימת השירותים ב-Cloud Run.
הערה: אם אתם רוצים להמשיך להריץ את Hotel Agent באופן מקומי ועדיין להתחבר לשירות Cloud Run החדש שפרסתם, אתם צריכים לבצע רק שינוי אחד בקובץ my-agents/hotel_agent_app/agent.py.
במקום:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
משנים אותה לכתובת ה-URL של שירות Cloud Run, כמו שמופיע בהמשך:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
כמו שראינו קודם, אפשר לבדוק את אפליקציית הסוכן באמצעות adk run או adk web.
פריסת אפליקציית סוכן המלונות ב-Cloud Run
קודם כל, צריך לוודא שביצעתם את השינוי ב-my-agents/hotel_agent_app/agent.py כמו שמוסבר למעלה, כך שההפניה היא לכתובת ה-URL של שירות Toolbox שפועל ב-Cloud Run ולא למארח המקומי.
במסוף חדש של Cloud Shell או בסשן מסוף קיים, מוודאים שאתם נמצאים בסביבה הווירטואלית הנכונה של Python שהגדרנו קודם.
קודם כל, ניצור קובץ requirements.txt בתיקייה my-agents/hotel_agent_app כמו שמוצג בהמשך:
google-adk
toolbox-core
עוברים לתיקייה my-agents ומגדירים קודם את משתני הסביבה הבאים:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel_agent_app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
לבסוף, פורסים את אפליקציית הסוכן ב-Cloud Run באמצעות הפקודה adk deploy cloud_run כמו שמופיע בהמשך. אם מתבקשים לאפשר הפעלות לא מאומתות של השירות, צריך להזין 'y' כערך בשלב הזה.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
הפעולה הזו תתחיל את תהליך הפריסה של אפליקציית Hotel Agent ב-Cloud Run. הכלי יעלה את המקורות, יארוז אותם בקונטיינר Docker, יעביר אותם בדחיפה ל-Artifact Registry ואז יפרוס את השירות ב-Cloud Run. זה יימשך כמה דקות, אז כדאי לחכות בסבלנות.
אמורה להופיע הודעה דומה לזו שכאן למטה:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
לאחר פריסה מוצלחת, תקבלו ערך של כתובת ה-URL של השירות, שאליה תוכלו לגשת בדפדפן כדי לראות את אותה אפליקציית אינטרנט שאיפשרה לכם לשוחח עם נציג המלון, כפי שראינו קודם בהגדרה המקומית.
10. הסרת המשאבים
כדי להימנע מחיובים שוטפים בחשבון Google Cloud, חשוב למחוק את המשאבים שיצרנו במהלך הסדנה הזו. נמחק את מכונת Cloud SQL, ואם פרסתם את Toolbox ואת אפליקציית המלונות ב-Cloud Run, נמחק גם את השירותים האלה.
מוודאים שמשתני הסביבה הבאים מוגדרים בצורה נכונה, בהתאם לפרויקט ולאזור:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
שתי הפקודות הבאות מוחקות את שירותי Cloud Run שפרסנו:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
הפקודה הבאה מוחקת את המכונה של Cloud SQL:
gcloud sql instances delete hoteldb-instance
11. מזל טוב
יצרתם בהצלחה סוכן באמצעות הערכה לפיתוח סוכנים (ADK) שמשתמש ב-MCP Toolbox for Databases.