פיתוח סוכן ADK לבינה עסקית מבוססת-מיקום באמצעות שרתי MCP ל-BigQuery ולמפות Google

1. מבוא

ב-Codelab הזה תלמדו איך ליצור סוכן באמצעות ADK שמבוסס על Gemini 3.1 Pro. הסוכן יצויד בכלים משני שרתי MCP מרוחקים (שמתארחים ב-Google) כדי לגשת בצורה מאובטחת ל-BigQuery לצורך קבלת נתונים דמוגרפיים, נתוני תמחור ומכירות, ולמפות Google לצורך ניתוח ואימות של מיקומים בעולם האמיתי.

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

82dd7bd2823a821b.png

מה תעשו

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

מה תצטרכו

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

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

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

יצירת פרויקט ב-Google Cloud

  1. ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.

a3dd2e6dddc8f691.png

  1. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

מפעילים את Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud וכוללת מראש את הכלים הנדרשים.

  1. לוחצים על Activate Cloud Shell (הפעלת Cloud Shell) בחלק העליון של מסוף Google Cloud:

404e4cce0f23e5c5.png

  1. אחרי שמתחברים ל-Cloud Shell, מריצים את הפקודה הבאה כדי לאמת את האימות ב-Cloud Shell:
gcloud auth list
  1. מריצים את הפקודה הבאה כדי לוודא שהפרויקט מוגדר לשימוש ב-gcloud:
gcloud config get project
  1. מוודאים שהפרויקט הוא כמו שציפיתם, ואז מריצים את הפקודה הבאה כדי להגדיר את מזהה הפרויקט:
export PROJECT_ID=$(gcloud config get project)

3. קבל את הקוד

שכפול המאגר

  1. משכפלים את המאגר לסביבת Cloud Shell:
git clone https://github.com/google/mcp.git
  1. עוברים לספריית ההדגמה:
cd mcp/examples/launchmybakery

אימות

מריצים את הפקודה הבאה כדי לבצע אימות באמצעות חשבון Google Cloud. ההרשאה הזו נדרשת כדי ש-ADK יוכל לגשת ל-BigQuery.

gcloud auth application-default login

פועלים לפי ההנחיות כדי להשלים את תהליך האימות.

4. הגדרת הסביבה ו-BigQuery

הפעלת סקריפטים להגדרה

  1. מריצים את הסקריפט להגדרת הסביבה. הסקריפט הזה מפעיל את BigQuery API ואת Google Maps API, ויוצר קובץ .env עם מזהה הפרויקט ומפתח Google Maps API.
chmod +x setup/setup_env.sh
./setup/setup_env.sh
  1. מריצים את סקריפט ההגדרה של BigQuery. הסקריפט הזה מבצע אוטומציה של יצירת קטגוריה של Cloud Storage, העלאת נתונים והקצאת קבוצת הנתונים והטבלאות ב-BigQuery.
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

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

  • דמוגרפיה – נתוני מפקד האוכלוסין ומאפייני האוכלוסייה לפי מיקוד.
  • ‫bakery_prices – תמחור של מתחרים ופרטי מוצרים של מאפים שונים.
  • ‫sales_history_weekly – ביצועי מכירות שבועיים (כמות והכנסה) לפי חנות ומוצר.
  • ‫foot_traffic – ציונים משוערים של תנועה פיזית בחנות לפי מיקוד ושעה ביום.
  1. כדי לוודא שמערך הנתונים והטבלאות נוצרו, נכנסים אל מסוף BigQuery בפרויקט Google Cloud:

6bd0a0cd7522dd11.jpeg

5. התקנת ADK

עכשיו, כשהתשתית מוכנה, ניצור סביבת Python וירטואלית ונתקין את החבילות הנדרשות ל-ADK.

  1. יוצרים סביבה וירטואלית:
python3 -m venv .venv
  1. מפעילים את הסביבה הווירטואלית:
source .venv/bin/activate
  1. מתקינים את ה-ADK:
pip install google-adk==1.28.0
  1. עוברים לספריית הנציגים:
cd adk_agent/

6. בדיקת אפליקציית ה-ADK

לוחצים על הלחצן Open Editor ב-Cloud Shell כדי לפתוח את Cloud Shell Editor ולראות את המאגר המשוכפל בספרייה mcp/examples/launchmybakery.

a940b7eaf3c9f4b3.png

קוד הנציג כבר מופיע בספרייה adk_agent/. בואו נבדוק את מבנה הפתרון:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

קבצים חשובים ב-mcp_bakery_app:

  • ‫agent.py: הלוגיקה הבסיסית שמגדירה את הסוכן, את הכלים שלו ואת המודל (גרסת טרום ההשקה של Gemini 3.1 Pro).
  • ‫tools.py: מכיל הגדרות של כלים מותאמים אישית.
  • ‫.env: מכיל את ההגדרה והסודות של הפרויקט (כמו מפתחות API) שנוצרו על ידי סקריפט ההגדרה.

1. הפעלה של כלי ה-MCP:

עכשיו, פותחים את adk_agent/mcp_bakery_app/tools.py בכלי העריכה כדי להבין איך ערכות הכלים של MCP מאותחלות.

כדי לאפשר לסוכן שלנו לתקשר עם BigQuery ומפות Google, אנחנו צריכים להגדיר את הלקוחות של Model Context Protocol‏ (MCP).

הקוד יוצר חיבורים מאובטחים לשרתי ה-MCP המרוחקים של Google באמצעות StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools
  • Maps Toolset: מגדיר את החיבור לשרת Maps MCP באמצעות מפתח ה-API.
  • ‫BigQuery Toolset: הפונקציה הזו מגדירה את החיבור לשרת BigQuery MCP. הוא משתמש ב-google.auth כדי לאחזר באופן אוטומטי את פרטי הכניסה שלכם ל-Cloud, ליצור אסימון OAuth Bearer ולהוסיף אותו לכותרת Authorization.

2. הגדרת הסוכן:

עכשיו פותחים את adk_agent/mcp_bakery_app/agent.py בעורך כדי לראות איך הסוכן מוגדר.

ה-LlmAgent מאותחל באמצעות מודל gemini-3.1-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)
  • הוראות למערכת: הסוכן מקבל הוראות ספציפיות לשילוב תובנות מ-BigQuery (לנתונים) וממפות Google (לניתוח מיקום).
  • כלים: גם maps_toolset וגם bigquery_toolset מוקצים לסוכן, וכך הוא מקבל גישה ליכולות של שני השירותים.

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

7. צ'אט עם הסוכן

חוזרים לטרמינל ב-Cloud Shell ומריצים את הפקודה הבאה כדי לעבור לספרייה adk_agent (אם עוד לא עשיתם את זה):

cd adk_agent/

מריצים את הפקודה הבאה כדי להפעיל את ממשק האינטרנט של ADK. הפקודה הזו מפעילה שרת אינטרנט קל משקל לאירוח אפליקציית הצ'אט:

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

אחרי שהשרת יתחיל, תופיע ההודעה הבאה ב-Cloud Shell:

+-----------------------------------------------------------------------------+
| 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)

יש שתי דרכים לגשת לממשק המשתמש של ADK:

אפשרות 1: לוחצים על הקישור המקומי לוחצים על הקישור http://127.0.0.1:8000 שמופיע במסוף Cloud Shell.

אפשרות 2: שימוש בתצוגה מקדימה של אתר

  1. לוחצים על הלחצן Web Preview (תצוגה מקדימה באינטרנט) בפינה הימנית העליונה של Cloud Shell.
  2. בוחרים באפשרות שינוי היציאה.
  3. מזינים 8000 כמספר היציאה ולוחצים על שינוי ותצוגה מקדימה.

צילום מסך שמראה איך לפתוח את ממשק המשתמש של ADK

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

  1. חיפוש בשכונה (מאקרו): "אני רוצה לפתוח מאפייה בלוס אנג'לס. תמצא את המיקוד עם הציון הכי גבוה של תנועה פיזית בחנות בבוקר".

5f2a48bebfc49709.png

הסוכן צריך להשתמש בכלים get_table_info ו-execute_sql כדי לשלוח שאילתות לטבלה foot_traffic ב-BigQuery.

  1. אימות המיקום (מיקרו): "אפשר לחפש'מאפיות' במיקוד הזה כדי לראות אם השוק שם רווי?"

32796c9a8cefca7.png

הסוכן צריך להשתמש בכלים search places שבערכת הכלים של מפות Google כדי לענות על השאלה הזו.

כדאי לנסות! כדי לראות את סוכן ה-ADK בפעולה, אפשר לעיין בשאלות לדוגמה הבאות:

  • "אני רוצה לפתוח את המאפייה הרביעית שלי בלוס אנג'לס. אני צריך שכונה עם פעילות מוקדמת. תמצא את המיקוד עם הציון הכי גבוה של תנועת הולכי רגל בבוקר".
  • "תבצע חיפוש של'מאפיות' במיקוד הזה כדי לבדוק אם השוק שם רווי? אם יש יותר מדי, תבדוק אם יש בתי קפה מיוחדים, כדי שאוכל למקם את עצמי לידם ולמשוך תנועה פיזית בחנות.
  • "אוקיי, אני רוצה למצב את המותג הזה כמותג פרימיום. מה המחיר המקסימלי שגובים עבור 'כיכר לחם מחמצת' באזור המטרופולין של לוס אנג'לס?"
  • עכשיו אני רוצה תחזית הכנסות לדצמבר 2025. תעיין בהיסטוריית המכירות שלי ותשתמש בנתונים מהחנות שמניבה את הביצועים הכי טובים לגבי 'לחם מחמצת'. תריץ תחזית לדצמבר 2025 כדי להעריך את הכמות שאמכור. לאחר מכן, מחשבים את סך ההכנסות הצפויות באמצעות מחיר שהוא קצת פחות מהמחיר של פריט הפרימיום שמצאנו (נשתמש ב-18$)."
  • "זה יכסה את שכר הדירה שלי. לסיום, נאמת את הלוגיסטיקה. תמצא את 'Restaurant Depot' הכי קרוב לאזור המוצע ותוודא שזמן הנסיעה קצר מ-30 דקות לצורך מילוי מלאי יומי".

כשמסיימים לבדוק את הסוכן, אפשר לסיים את ממשק האינטרנט של ADK בלחיצה על Ctrl+C במסוף Cloud Shell.

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

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

מריצים את סקריפט הניקוי. הסקריפט הזה ימחק את מערך הנתונים ב-BigQuery, את קטגוריה של Cloud Storage ואת מפתחות ה-API שנוצרו במהלך ההגדרה.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. מזל טוב

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

החיבור בין נתוני ה'ארגון' שלכם ב-BigQuery לבין הקשר של מיקומים בעולם האמיתי מ-מפות Google יצר כלי רב עוצמה שיכול לבצע ניתוח עסקי מורכב – והכול מבוסס על Model Context Protocol‏ (MCP) ועל Gemini.

מה השגתם:

  • תשתית כקוד: הקצאתם מחסן נתונים באמצעות כלי Google Cloud CLI.
  • שילוב עם MCP: חיברתם סוכן AI לשני שרתי MCP מרוחקים שונים (BigQuery ומפות) בלי לכתוב עטיפות API מורכבות.
  • חשיבה רציונלית מאוחדת: יצרתם סוכן AI יחיד שיכול לשלב באופן אסטרטגי תובנות משני תחומים שונים כדי לפתור בעיה עסקית.

מאמרי עזרה