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');
כדי לאמת את הנתונים, מריצים שאילתת SQL מסוג SELECT כמו בדוגמה הבאה:
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.13.1
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
עכשיו יש לנו את הגרסה הבינארית של ערכת הכלים, והיא מוכנה לשימוש. בואו נוודא שהגדרנו את קובץ ההפעלה הבינארי של ארגז הכלים בצורה נכונה ושהוא מציין את הגרסה הנכונה.
מריצים את הפקודה הבאה כדי לקבוע את גרסת כלי הניהול:
./toolbox -v
השלב הבא הוא להגדיר את ארגז הכלים עם מקורות הנתונים והגדרות אחרות.
הגדרת הקובץ 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-09-26T14:00:35.898358+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:00:39.571556+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:00:39.571634+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:00:39.571648+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:00:39.571728+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:00:39.571745+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:00:39.571756+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:00:39.571767+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:00:39.571851+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:00:39.571905+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:00:39.571939+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:00:39.572261+05:30 INFO "Server ready to serve!"
שרת ה-MCP Toolbox פועל כברירת מחדל ביציאה 5000. אם אתם מגלים שהיציאה 5000 כבר נמצאת בשימוש, אתם יכולים להשתמש ביציאה אחרת (למשל 7000) בהתאם לפקודה שמוצגת למטה. במקום היציאה 5000 בפקודות הבאות, צריך להשתמש ב-7000.
./toolbox --config "tools.yaml" --port 7000
נשתמש ב-Cloud Shell כדי לבדוק את זה.
לוחצים על Web Preview (תצוגה מקדימה של אתר) ב-Cloud Shell כמו שמוצג למטה:
לוחצים על Change port (שינוי היציאה) ומגדירים את היציאה ל-5000 כמו שמוצג למטה. לוחצים על Change and Preview (שינוי ותצוגה מקדימה).
הפלט הבא אמור להתקבל:
בדיקת הכלים באמצעות ממשק המשתמש של MCP Toolbox for Databases
ה-Toolbox מספק ממשק חזותי (ממשק המשתמש של ה-Toolbox) לאינטראקציה ישירה עם כלים באמצעות שינוי פרמטרים, ניהול כותרות והפעלת קריאות, והכול בממשק משתמש פשוט באינטרנט.
כדי לבדוק את זה, אפשר להריץ את הפקודה הקודמת שבה השתמשנו כדי להפעיל את Toolbox Server עם האפשרות --ui.
כדי לעשות את זה, צריך להשבית את המכונה הקודמת של MCP Toolbox for Databases Server שאולי פועלת, ולהריץ את הפקודה הבאה:
./toolbox --config "tools.yaml" --ui
הפלט שצריך להופיע הוא שהשרת הצליח להתחבר למקורות הנתונים שלנו וטען את ערכת הכלים והכלים. בהמשך מופיע פלט לדוגמה, שבו מצוין שממשק המשתמש של כלי העריכה פועל.
2026-09-26T14:01:17.208487+05:30 INFO "Starting MCP Toolbox for Databases version 1.13.1+binary.darwin.arm64.e14cda6"
2026-09-26T14:01:20.823447+05:30 INFO "Initialized 1 sources: my-cloud-sql-source"
2026-09-26T14:01:20.82353+05:30 INFO "Initialized 0 authServices: "
2026-09-26T14:01:20.823545+05:30 INFO "Initialized 0 embeddingModels: "
2026-09-26T14:01:20.823629+05:30 INFO "Initialized 2 tools: search-hotels-by-name, search-hotels-by-location"
2026-09-26T14:01:20.823649+05:30 INFO "Initialized 0 prompts: "
2026-09-26T14:01:20.82366+05:30 INFO "Initialized 0 resources: "
2026-09-26T14:01:20.823671+05:30 INFO "Initialized 0 resource templates: "
2026-09-26T14:01:20.823745+05:30 INFO "Initialized 2 groups: my_first_toolset, default"
2026-09-26T14:01:20.823795+05:30 WARN "wildcard (*) allows any website to access the primitives. This creates a security risk regardless of whether you are in a production or local development environment. Recommended to use --allowed-origins with specific local addresses."
2026-09-26T14:01:20.823829+05:30 WARN "wildcard (*) hosts allow any domain to access this resource, making it vulnerable to DNS rebinding attacks regardless of whether you are in a production or local development environment. For improved security, use the --allowed-hosts flag to specify trusted domains."
2026-09-26T14:01:20.824193+05:30 INFO "Server ready to serve!"
2026-09-26T14:01:20.824231+05:30 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, ועכשיו יש לנו שתי אפשרויות:
- כדי להבין איך אפשר להגדיר את שרת ה-MCP בטרמינל או בסביבת פיתוח משולבת (IDE) עם עזרה מ-AI, עוברים לשלב 6. במדריך הזה נסביר איך לשלב את השרת MCP Toolbox שלנו ב-
Gemini CLI. - כדי להבין איך להשתמש ב-
Agent Development Kit (ADK) using Pythonכדי לכתוב סוכנים משלכם שיכולים להשתמש ב-MCP Server Toolbox ככלי, כדי לענות על שאלות שקשורות למערך הנתונים, אפשר לעבור לשלבים 7 ו-8.
6. שילוב של MCP Toolbox ב-Antigravity CLI
Antigravity CLI הוא ממשק משתמש קל משקל לטרמינל (TUI) של Antigravity. הוא כולל את אותן יכולות אג'נטיות ליבה כמו Antigravity (כמו חשיבה רציונלית רב-שלבית, עריכה של כמה קבצים, שימוש בכלים והיסטוריית שיחות) ישירות במסוף. אפשר להשתמש בו גם למשימות שקשורות לתכנות וגם למשימות שלא קשורות לתכנות. הוא משולב עם כלים שונים, ויש בו תמיכה בשרתי MCP.
מכיוון שיש לנו שרת MCP פעיל, המטרה שלנו בקטע הזה היא להגדיר את שרת MCP Toolbox for Databases ב-Antigravity CLI ואז להשתמש ב-Antigravity CLI כדי לתקשר עם הנתונים שלנו.
השלב הראשון יהיה לוודא שכלי הניהול פועל באחד מהטרמינלים של Cloud Shell. אם מריצים את השרת ביציאה שמוגדרת כברירת מחדל 5000, הממשק של שרת ה-MCP זמין בנקודת הקצה הבאה: http://localhost:5000/mcp.
פותחים טרמינל חדש ויוצרים תיקייה בשם my-gemini-cli-project באופן הבא. עוברים גם לתיקייה my-gemini-cli-project.
mkdir my-agy-cli-project
cd my-agy-cli-project
מריצים את הפקודה הבאה כדי להוסיף את שרת ה-MCP לרשימת שרתי ה-MCP שהוגדרו ב-Antigravity CLI.
agy mcp add "MCPToolbox" "http://localhost:5000/mcp"
אפשר לבדוק את הרשימה הנוכחית של שרתי MCP שהוגדרו ב-Antigravity CLI באמצעות הפקודה הבאה:
agy mcp list
באופן אידיאלי, אמור להופיע סימן וי ירוק ליד MCPToolbox שהגדרנו, שמציין ש-Gemini CLI הצליח להתחבר לשרת ה-MCP.
NAME TYPE STATUS COMMAND/URL
MCPToolbox http enabled http://localhost:5000/mcp
לפני שנשיק את Gemini CLI, כדאי להגדיר את משתני הסביבה הבאים כדי לעזור ל-Gemini CLI להפנות את הבקשות שלכם למודל הנכון.
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global
באותו מסוף, מוודאים שאתם נמצאים בתיקייה my-agy-cli-project. מפעילים את Antigravity CLI באמצעות הפקודה agy.
יוצג ממשק Antigravity CLI. אפשר להשתמש בפקודה /mcp כדי לראות את רשימת שרתי ה-MCP והכלים. לדוגמה, הנה פלט לדוגמה:
MCP Servers
Plugins (~/.gemini/config/plugins)
> ✓ MCPToolbox Tools: search-hotels-by-location, search-hotels-by-name
עכשיו אפשר לתת כל אחת מההנחיות הבאות:
Which hotels are there in Basel?Tell me more about the Hyatt Regency?
תראו שהשאילתות שלמעלה יגרמו ל-Antigravity 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
תוצג רשימה של פקודות.
$ 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...
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...
run Runs an agent.
telemetry Manage telemetry settings.
test Runs pytest on agent test JSON files under the specified...
web Starts a FastAPI server with Web UI for agents.
יצירת אפליקציית הסוכן הראשונה
עכשיו נשתמש ב-adk כדי ליצור פיגום לאפליקציית סוכן המלונות באמצעות הפקודה adk create עם שם האפליקציה **(hotel_agent_app)**כפי שמופיע בהמשך.
adk create hotel_agent_app
פועלים לפי השלבים ובוחרים באפשרויות הבאות:
- בוחרים במודל
gemini-3.8-flashכדי לבחור מודל לסוכן הבסיס. - בוחרים באפשרות
Vertex AIעבור ה-backend. - יוצג מזהה פרויקט ברירת המחדל של Google. בוחרים באפשרות הזו.
- יוצג האזור של הפרויקט הנוכחי ב-Google Cloud. מקלידים
global.
Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 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]: global
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app:
- .env
- .gitignore
- __init__.py
- agent.py
בודקים את התיקייה שבה נוצרו תבנית ברירת מחדל והקבצים הנדרשים לסוכן. אפשר לראות את הקבצים באמצעות הפקודה ls -al במסוף בספרייה <YOUR_HOME_FOLDER>/my-agents/hotel_agent_app.
הקובץ הראשון הוא .env. הקובץ הזה כבר נוצר, כמו שצוין קודם, ואפשר פשוט לראות את התוכן שלו שמוצג בהמשך:
GOOGLE_GENAI_USE_ENTERPRISE=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.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
זהו הסוכן הפשוט ביותר שאפשר לכתוב באמצעות ADK. מתוך הדף של תיעוד ה-ADK, סוכן הוא יחידת ביצוע עצמאית שנועדה לפעול באופן אוטונומי כדי להשיג מטרות ספציפיות. סוכנים יכולים לבצע משימות, ליצור אינטראקציה עם משתמשים, להשתמש בכלים חיצוניים ולתאם עם סוכנים אחרים.
במילים אחרות, LLMAgent, שנקרא בדרך כלל Agent, משתמש במודלים גדולים של שפה (LLM) כמנוע הליבה שלו כדי להבין שפה טבעית, להסיק מסקנות, לתכנן, ליצור תשובות ולהחליט באופן דינמי איך להמשיך או באילו כלים להשתמש. לכן הוא אידיאלי למשימות גמישות שמתמקדות בשפה. מידע נוסף על סוכני LLM
נשנה את הקוד של agent.py באופן הבא:
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
model='gemini-3.8-flash',
name='root_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 [61397]
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-3.8-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 search for and find information about hotels! Specifically, I can:
* **Find hotels in a specific city or location:** Look up available hotels, sorted by price from least to most expensive.
* **Search for hotels by name:** Get details on a specific hotel you're interested in.
Feel free to tell me where you're planning to stay or which hotel you'd like to look up!
[user]: I would like to search for hotels?
[hotel_agent]: I'd be happy to help!
Where are you planning to travel, or is there a specific hotel name you have in mind?
[user]: I am planning to travel to Basel
[hotel_agent]: Here are the hotels available in **Basel**, listed from least to most expensive:
1. **Holiday Inn Basel**
* **Price Tier:** Upper Midscale
* **Available Dates:** April 9, 2024 – April 24, 2024
2. **Hyatt Regency Basel**
* **Price Tier:** Upper Upscale
* **Available Dates:** April 2, 2024 – April 20, 2024
3. **Hilton Basel**
* **Price Tier:** Luxury
* **Available Dates:** April 20, 2024 – April 22, 2024
Would you like more details about any of these hotels, or do you have specific travel dates in mind?
[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, ושירות 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 של שירות ארגז הכלים שפועל ב-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_ENTERPRISE=1
לבסוף, פורסים את אפליקציית הסוכן ב-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
הפעולה הזו תתחיל את תהליך הפריסה של אפליקציית סוכן המלונות ב-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. למדתם גם איך לחבר סוכנים למסדי נתונים משלכם, ואיך להתקין את הסוכן ואת ארגז הכלים ב-Cloud Run (אופציונלי).