פיתוח סוכנות נסיעות באמצעות MCP Toolbox למסדי נתונים ו-Agent Development Kit ‏ (ADK)

1. מבוא

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

במהלך ה-codelab, תשתמשו בגישה שלב אחר שלב באופן הבא:

1. הקצאת מסד נתונים של Cloud SQL ל-PostgreSQL שיכלול את מסד הנתונים של המלונות ונתונים לדוגמה.
2. מגדירים את MCP Toolbox for Databases, שמאפשר גישה לנתונים.
3. תכנון ופיתוח של סוכן באמצעות ערכת פיתוח סוכנים (ADK) שישתמש בארגז הכלים של MCP כדי לענות על שאילתות מהמשתמש.
4. הכרת האפשרויות לבדיקת הסוכן וערכת הכלים MCP למסדי נתונים באופן מקומי וב-Google Cloud באמצעות שירות Cloud Run.

מה עושים

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

מה תלמדו

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

מה צריך

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

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

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

יצירת פרויקט

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

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

gcloud auth list

5. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט.

gcloud config list project

6. אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:

gcloud config set project <YOUR_PROJECT_ID>

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

5. הגדרת MCP Toolbox for Databases

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

ערכת הכלים עוזרת לכם ליצור כלי 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=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

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

הגדרת הקובץ tools.yaml

הדרך העיקרית להגדיר את Toolbox היא באמצעות הקובץ tools.yaml. יוצרים קובץ בשם tools.yaml באותה תיקייה, כלומר mcp-toolbox, עם התוכן שמוצג בהמשך.

אפשר להשתמש בעורך nano שזמין ב-Cloud Shell. הפקודה nano היא: "nano tools.yaml".

חשוב להחליף את הערך YOUR_PROJECT_ID במזהה הפרויקט ב-Google Cloud.

sources:
  my-cloud-sql-source:
    kind: cloud-sql-postgres
    project: YOUR_PROJECT_ID
    region: us-central1
    instance: hoteldb-instance
    database: postgres
    user: postgres
    password: "postgres"

tools:
  search-hotels-by-name:
    kind: 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 || '%';
  search-hotels-by-location:
    kind: 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;

toolsets:
   my_first_toolset:
     - search-hotels-by-name
     - search-hotels-by-location

אנחנו צריכים לקבל ממך תיאור קצר של הקובץ:

1. ‫Sources מייצג את מקורות הנתונים השונים שהכלי יכול ליצור איתם אינטראקציה. מקור מייצג מקור נתונים שכלי יכול ליצור איתו אינטראקציה. אפשר להגדיר את Sources כמפה בקטע sources בקובץ tools.yaml. בדרך כלל, הגדרת מקור תכיל את כל המידע שנדרש כדי להתחבר למסד הנתונים ולקיים איתו אינטראקציה. במקרה שלנו, הגדרנו מקור יחיד שמפנה למכונה של Cloud SQL ל-PostgreSQL עם פרטי הכניסה. מידע נוסף זמין במאמר בנושא מקורות.
2. Tools מגדירות פעולות שהסוכן יכול לבצע – כמו קריאה וכתיבה במקור. כלי מייצג פעולה שהסוכן יכול לבצע, כמו הפעלת הצהרת SQL. אפשר להגדיר את Tools כמפה בקטע tools בקובץ tools.yaml. בדרך כלל, כלי יצטרך מקור כדי לפעול. בדוגמה שלנו, אנחנו מגדירים שני כלים: search-hotels-by-name ו-search-hotels-by-location, ומציינים את המקור שהם פועלים עליו, יחד עם ה-SQL והפרמטרים. מידע נוסף זמין במאמר בנושא כלים.
3. לבסוף, יש לנו את Toolset, שמאפשרת להגדיר קבוצות של כלים שרוצים לטעון יחד. האפשרות הזו יכולה להיות שימושית להגדרת קבוצות שונות על סמך סוכן או אפליקציה. במקרה שלנו, יש לנו ערכת כלים אחת בשם my_first_toolset, שמכילה את שני הכלים שהגדרנו.

הפעלת MCP Toolbox for Databases Server

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

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

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

2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources." 
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices." 
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools." 
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets." 
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!" 

שרת MCP Toolbox פועל כברירת מחדל ביציאה 5000. אם אתם מגלים שהיציאה 5000 כבר בשימוש, אתם יכולים להשתמש ביציאה אחרת (למשל 7000) בהתאם לפקודה שמוצגת למטה. במקום יציאת 5000 בפקודות הבאות, צריך להשתמש ב-7000.

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

נשתמש ב-Cloud Shell כדי לבדוק את זה.

לוחצים על Web Preview ב-Cloud Shell כמו שמוצג למטה:

לוחצים על Change port (שינוי היציאה) ומגדירים את היציאה ל-5000 כמו שמוצג למטה. לוחצים על Change and Preview (שינוי ותצוגה מקדימה).

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

בכתובת ה-URL של הדפדפן, מוסיפים את המחרוזת הבאה לסוף כתובת ה-URL:

/api/toolset

יוצגו הכלים שמוגדרים כרגע. דוגמה לפלט:

{
  "serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
  "tools": {
    "search-hotels-by-location": {
      "description": "Search for hotels based on location.  Result is sorted by price from least to most expensive.",
      "parameters": [
        {
          "name": "location",
          "type": "string",
          "required": true,
          "description": "The location of the hotel.",
          "authSources": []
        }
      ],
      "authRequired": []
    },
    "search-hotels-by-name": {
      "description": "Search for hotels based on name.",
      "parameters": [
        {
          "name": "name",
          "type": "string",
          "required": true,
          "description": "The name of the hotel.",
          "authSources": []
        }
      ],
      "authRequired": []
    }
  }
}

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

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

כדי לבדוק את זה, אפשר להריץ את הפקודה הקודמת שבה השתמשנו כדי להפעיל את Toolbox Server עם האפשרות --ui.

כדי לעשות זאת, משביתים את המופע הקודם של MCP Toolbox for Databases Server שאולי פועל ומריצים את הפקודה הבאה:

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

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

2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources." 
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices." 
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools." 
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets." 
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!" 
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui" 

לוחצים על כתובת ה-URL של ממשק המשתמש ומוודאים שמופיע בסוף כתובת ה-URL התו /ui. יוצג ממשק משתמש כמו שמוצג בהמשך:

לוחצים על האפשרות 'כלים' בצד ימין כדי לראות את הכלים שהוגדרו. במקרה שלנו, אמורים להיות שני כלים, כלומר search-hotels-by-name ו-search-hotels-by-location, כמו שמוצג בהמשך:

פשוט לוחצים על אחד מהכלים (search-hotels-by-location) ויוצג דף שבו אפשר לבדוק את הכלי על ידי הזנת ערכי הפרמטרים הנדרשים ואז לחיצה על הפעלת הכלי כדי לראות את התוצאה. דוגמה להרצה:

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

6. כתיבת הסוכן באמצעות ערכה לפיתוח סוכנים (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.
  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.
  run         Runs an interactive CLI for a certain agent.
  web         Starts a FastAPI server with Web UI for agents.

יצירת אפליקציית הנציג הראשונה

עכשיו נשתמש ב-adk כדי ליצור פיגום לאפליקציית סוכן המלונות באמצעות הפקודה adk create עם שם האפליקציה **(hotel-agent-app)**כמו בדוגמה שלמטה.

adk create hotel-agent-app

פועלים לפי השלבים ובוחרים באפשרויות הבאות:

• מודל Gemini לבחירת מודל לסוכן הבסיסי.
• בוחרים ב-Vertex AI עבור הקצה העורפי.
• יוצגו מזהה הפרויקט ב-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

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

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

בפרט, סוכן LLM, שמכונה בדרך כלל סוכן, משתמש במודלים גדולים של שפה (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.

7. חיבור הסוכן שלנו לכלים

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

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

משנים את הקובץ 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 --tools_file "tools.yaml"

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

2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources." 
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices." 
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools." 
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets." 
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!" 

אחרי שהשרת של MCP יופעל בהצלחה, במסוף אחר מפעילים את הסוכן כמו שעשינו קודם באמצעות הפקודה adk run (מהתיקייה my-agents) שמוצגת בהמשך. אפשר גם להשתמש בפקודה adk web.

$ adk run hotel-agent-app/

Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.

user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.

user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?

user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?

user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.

שימו לב שהסוכן משתמש עכשיו בשני הכלים שהגדרנו בארגז הכלים של MCP למסדי נתונים (search-hotels-by-name ו-search-hotels-by-location) ומספק לנו את האפשרויות הנכונות. אחרי כן, הוא יכול לאחזר את הנתונים ממסד הנתונים של מופע PostgreSQL ולעצב את התשובה בהתאם.

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

8. (אופציונלי) פריסת MCP Toolbox for Databases ו-Agent ב-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="--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 [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' שראינו קודם אמורה להופיע. אפשר גם להיכנס לכתובת ה-URL הבאה כדי לראות את הכלים שזמינים:

SERVICE URL/api/toolset

אפשר גם להיכנס אל 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 ולא ב-localhost.

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

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

כדי להימנע מחיובים שוטפים בחשבון 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

10. מזל טוב

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

מאמרי עזרה

• Agent Development Kit
• ארגז הכלים של MCP למסדי נתונים
• התחברות ל-MCP Toolbox מ-IDE
• Cloud SQL ל-PostgreSQL