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

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

מידע על Codelab זה

subjectהעדכון האחרון: מאי 20, 2025
account_circleנכתב על ידי Romin Irani, Jack Wotherspoon

1.‏ מבוא

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

במהלך הקודלאב, נשתמש בגישה הדרגתית לפי השלבים הבאים:

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

b3768488d144b8f6.png

מה עליכם לעשות

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

מה תלמדו

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

מה צריך להכין

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

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

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

יצירת פרויקט

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

תמונה של הלחצן להפעלת Cloud Shell

  1. אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהמזהה של הפרויקט מוגדר כפרויקט באמצעות הפקודה הבאה:
gcloud auth list
  1. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהפקודה gcloud מכירה את הפרויקט.
gcloud config list project
  1. אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:
gcloud config set project <YOUR_PROJECT_ID>
  1. מפעילים את ממשקי ה-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.

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

gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres

ביצוע הפקודה הזו נמשך כ-3-5 דקות. אחרי שהפקודה תושלם, אמור להופיע פלט שמציין שהפקודה הושלמה, יחד עם פרטי המכונה של Cloud SQL, כמו NAME, ‏ DATABASE_VERSION, ‏ LOCATION וכו'.

4.‏ הכנת מסד הנתונים של מלונות

עכשיו נצטרך ליצור נתוני דוגמה לסוכנות המלונות.

נכנסים לדף Cloud SQL במסוף Cloud.hoteldb-instance אמור להופיע כעמודה מוכנה. לוחצים על שם המכונה (hoteldb-instance) כמו שמוצג בהמשך:

29dbc55e97f6f7b.png

בתפריט הימני של Cloud SQL, עוברים לאפשרות התפריט Cloud SQL Studio כפי שמוצג בהמשך:

c11cc134c83ce327.png

תתבקשו להיכנס ל-Cloud SQL Studio, שבו נריץ כמה פקודות SQL. בוחרים באפשרות postgres עבור מסד הנתונים, ועבור 'משתמש' ו'סיסמה', הערך לשימוש הוא postgres. לוחצים על AUTHENTICATE.

קודם נוצר את טבלת המלונות בהתאם לסכימה שמופיעה בהמשך. בחלונית אחת של Editor ב-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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
 
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
 
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
 
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
 
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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;

בטבלה hotels אמורים להופיע מספר רשומות, כמו שמוצג בהמשך:

a7dd838f1962d412.png

השלמנו את תהליך ההגדרה של מכונה של Cloud SQL ויצאנו את נתוני הדוגמה שלנו. בקטע הבא נסביר איך מגדירים את Toolbox של MCP למסדי נתונים.

5.‏ הגדרת MCP Toolbox למסדי נתונים

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

Toolbox עוזר לכם ליצור כלים של AI גנרטיבי שמאפשרים לנציגי התמיכה לגשת לנתונים במסד הנתונים שלכם. ארגז הכלים מספק:

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

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

58d1dd1727fe9e1e.png

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

התקנת ארגז הכלים

פותחים את Cloud Shell Terminal ויוצרים תיקייה בשם mcp-toolbox.

mkdir mcp-toolbox

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

cd mcp-toolbox

מתקינים את הגרסה הבינארית של MCP Toolbox למסדי נתונים באמצעות הסקריפט שבהמשך:

export VERSION=0.3.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.
   parameters:
     - name: location
       type: string
       description: The location of the hotel.
   statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';

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"

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

./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"

שרת MCP Toolbox פועל כברירת מחדל ביציאה 5000. נשתמש ב-Cloud Shell כדי לבדוק את זה.

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

f990712162e8e924.png

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

d1b9de0c46ecef8a.png

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

2fdcdac326034d41.png

בכתובת ה-URL בדפדפן, מוסיפים את הטקסט הבא בסוף כתובת ה-URL:

/api/toolset

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

{
  "serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
  "tools": {
    "search-hotels-by-location": {
      "description": "Search for hotels based on location.",
      "parameters": [
        {
          "name": "location",
          "type": "string",
          "description": "The location of the hotel.",
          "authSources": []
        }
      ]
    },
    "search-hotels-by-name": {
      "description": "Search for hotels based on name.",
      "parameters": [
        {
          "name": "name",
          "type": "string",
          "description": "The name of the hotel.",
          "authSources": []
        }
      ]
    }
  }
}

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

6.‏ כתיבת הסוכן שלנו באמצעות Agent Development Kit‏ (ADK)

התקנה של Agent Development Kit‏ (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 באופן הבא:

pip install google-adk toolbox-core

עכשיו תוכלו להפעיל את השירות adk באופן הבא.

adk

תוצג רשימה של פקודות.

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --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.0-flash-001
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 [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:

Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py

בודקים את התיקייה שבה נוצרו תבנית ברירת המחדל והקבצים הנדרשים ל-Agent.

קובץ .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.0-flash-001',
   
name='root_agent',
   
description='A helpful assistant for user questions.',
   
instruction='Answer user questions to the best of your knowledge',
)

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

באופן ספציפי, LLMAgent, שנקרא בדרך כלל Agent, משתמש במודלים גדולים של שפה (LLM) כמנוע הליבה שלו כדי להבין שפה טבעית, לחשוב, לתכנן, ליצור תשובות ולהחליט באופן דינמי איך להמשיך או באילו כלים להשתמש. לכן, הוא אידיאלי למשימות גמישות שמתמקדות בשפה. כאן אפשר לקרוא מידע נוסף על סוכני LLM.

נשנה את הקוד של agent.py באופן הבא:

from google.adk.agents import Agent

root_agent = Agent(
   
model='gemini-2.0-flash-001',
   
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 [5015]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

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

9a297ffb7ecfa1a7.png

שימו לב שבפינה הימנית העליונה זוהתה האפליקציה hotel-agent-app. עכשיו אפשר להתחיל את השיחה עם הנציג. נותנים כמה הנחיות לגבי ערים. בהמשך מוצגת דוגמה לשיחה:

b732feb383668869.png

אפשר לכבות את התהליך שפועל במסוף Cloud Shell (Ctrl-C).

דרך נוספת לבדוק את ה-Agent היא באמצעות הפקודה adk run, כפי שמופיע בהמשך מהתיקייה my-agents.

adk run hotel-agent-app

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

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

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

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

משנים את הקובץ agent.py באמצעות הקוד הבא:

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.0-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"

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

./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"

אחרי ששרת ה-MCP מופעל בהצלחה, מריצים את ה-Agent במסוף אחר כמו שעשינו קודם באמצעות הפקודה 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 Toolbox for Databases‏ (search-hotels-by-name ו-search-hotels-by-location) ומספק לנו את האפשרויות הנכונות. לאחר מכן, הוא יכול לאחזר את הנתונים בצורה חלקה ממסד הנתונים של מכונה של PostgreSQL ולעצב את התגובה בהתאם.

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

8.‏ (אופציונלי) פריסת MCP Toolbox למסדי נתונים ולסוכן ב-Cloud Run

בקטע הקודם השתמשנו במסוף Cloud Shell כדי להפעיל את השרת של MCP Toolbox ובדקנו את הכלים באמצעות הסוכן. הקוד הזה פועל באופן מקומי בסביבת Cloud Shell.

יש לכם אפשרות לפרוס את השרת של MCP Toolbox ואת ה-Agent בשירותי 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 כסוד. מכיוון שאנחנו צריכים להתקין את Toolbox ב-Cloud Run, נשתמש בקובץ האימג' העדכני ביותר של ה-Container עבור Toolbox ונגדיר אותו במשתנה 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, ותראו את השירות 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, כפי שראינו קודם.

פריסה של אפליקציית Hotel Agent ב-Cloud Run

השלב הראשון הוא לוודא שביצעתם את השינוי ב-my-agents/hotel-agent-app/agent.py לפי ההוראות שלמעלה, כדי שתוביל לכתובת ה-URL של שירות Toolbox שפועל ב-Cloud Run ולא למארח המקומי.

ב-Cloud Shell Terminal חדש או בסשן Terminal קיים, מוודאים שנמצאים בסביבה הווירטואלית הנכונה של 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 באמצעות הפקודה cloud_run‏ adk deploy כפי שמופיעה בהמשך. אם תתבקשו לאפשר הפעלות לא מאומתות של השירות, מזינים '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/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
|  Building and deploying... Uploading sources.                                                                                                                                                                      
  |  Uploading sources...                                                                                                                                                                                            
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/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].                                  
  OK Creating Revision...                                                                                                                                                                                            
  OK Routing traffic...                                                                                                                                                                                              
Done.                                                                                                                                                                                                                
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623

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

56bc8b29fa9c9989.png

9.‏ מזל טוב

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

מסמכי עזר