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

1. מבוא

בשיעור הזה תלמדו איך ליצור סוכן באמצעות ADK שמבוסס על Gemini 3.0 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 Console, בדף לבחירת הפרויקט, בוחרים פרויקט ב-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 אמור להיווצר ולאכלס את הטבלאות הבאות:

  • demographics – נתוני מפקד האוכלוסין ומאפייני האוכלוסייה לפי מיקוד.
  • ‫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. עוברים לספריית הנציגים:
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.0 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, ליצור אסימון Bearer של OAuth ולהוסיף אותו לכותרת Authorization.

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

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

ה-LlmAgent מאותחל עם מודל gemini-3-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3-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

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

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

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

5f2a48bebfc49709.png

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

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

32796c9a8cefca7.png

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

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

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

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

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

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

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

9. מזל טוב

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

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

מה השגתם:

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

מאמרי עזרה