הכלים האג'נטיים בממשק Maps Experience (לשעבר Maps Grounding Lite) הם שירות של Google Maps Platform עם תמיכה ב-Model Context Protocol (MCP) וב-REST, שמאפשר לעגן את אפליקציות ה-AI בנתונים גיאו-מרחביים מהימנים ממפות Google. הכלים שלו מאפשרים למודלי LLM לגשת לנתונים על מקומות, מזג אוויר, איכות האוויר, אבקנים ומסלולים. כלים אחרים ממירים שמות של מיקומים וכתובות URL של מפות Google למזהי מקומות. כדי לנסות את הכלים האג'נטיים בממשק Maps, אתם יכולים להפעיל את שרת ה-MCP שלו בכל כלי שתומך בשרתי MCP. אפשר גם לקרוא לכל כלי כשיטת REST. לפרטים נוספים, קראו את המאמר קריאה לכלים באמצעות REST.
הכלים האג'נטיים בממשק Maps Experience הם מוצר אחד עם שני מק"טים: Essentials ו-Pro. כל בקשה מחויבת במסגרת Essentials, אלא אם היא משתמשת באפשרות Pro. האפשרויות בתוכנית Pro כוללות חיפוש מקומות לאורך מסלול, פרטי מקומות מורחבים, יותר מקומות לכל חיפוש, יותר עצירות ביניים לכל מסלול, מסלול עם תנועה בזמן אמת, תחזיות אבקנים ואיכות אוויר היסטורית. שני המק"טים משתמשים באותם כלים, שרת MCP, שיטות REST ופרטי כניסה. לפרטים נוספים, קראו את המאמר Essentials ו-Pro.
כלים
הכלים האג'נטיים בממשק Maps Experiments מאפשרים למודלי LLM לגשת ליכולות הבאות של מפות Google:
- חיפוש מקומות: בקשת מידע על מקומות וקבלת סיכומים שנוצרו על ידי AI. התשובה כוללת גם מזהי מקומות, קואורדינטות של קווי רוחב ואורך וקישורים למפות Google לכל מקום בסיכום. אתם יכולים להשתמש במזהי המקומות ובקואורדינטות של קווי הרוחב והאורך בממשקי API אחרים של הפלטפורמה של מפות Google כדי להציג מקומות במפה. כדי להציג את המקומות האלה באמצעות Places UI Kit ללא עלות נוספת, השתמשו באסימון להצגה חזותית של נתונים באמצעות סוכנים (גרסת טרום-השקה). בגרסת Pro, אתם יכולים לבקש Place Details, כמו תובנות מביקורות, ועד 10 מקומות בכל בקשה.
- חיפוש לאורך המסלול:
חיפוש מקומות לאורך מסלול נסיעה – שצוין באמצעות
retrieval_tokenמ-compute_routes, מ-route_endpointsאו מ-encoded_polyline– וקבלת סיכום שנוצר על ידי AI, פרטי מקום, מרחק מעקף וזמן נסיעה, ואסימון להמחשה חזותית של נתונים מבוססי-סוכן (גרסת טרום-השקה). כל בקשה שלsearch_along_routeמחויבת במסגרת המק"ט של Pro. - חיפוש מזג אוויר: בקשת תנאי סביבה למיקום, כולל מזג אוויר (תנאים נוכחיים, היסטוריה של 24 שעות, ותחזיות שעתיות ויומיות של עד 10 ימים) ואיכות האוויר הנוכחית או תחזית של עד 4 ימים. בגרסת Pro אפשר גם לבקש תחזיות יומיות של אבקנים ל-5 ימים (עם פרטים על מיני הצמחים) והיסטוריה של איכות האוויר לפי שעה ל-30 ימים.
Compute routes: בקשת מסלול בין נקודת מוצא לנקודת יעד, עם אפשרות לעצירות ביניים, והחזרת המרחק, משך הזמן ו-
retrievalTokenשלDRIVEמסלולים שאפשר להעביר אלsearch_along_route. בגרסת Pro, המסלולים יכולים להתחשב במצב התנועה בזמן אמת ולכלול יותר עצירות ביניים.פתרון שמות ו- פתרון כתובות URL של מפות Google: פתרון שמות של מיקומים, כתובות וכתובות URL של מפות Google למזהי מקומות. מידע נוסף מופיע במאמר בנושא Resolution API.
אחרי שמפעילים את שרת ה-MCP, מודלי LLM יכולים להפעיל את הכלים שלו כדי לקבל מידע מבוסס-קרקע לסוגי הנתונים האלה. ה-LLM יכול להשתמש במידע הזה כהקשר. עם זאת, יכול להיות שהתשובה הסופית שלו לא תכלול את המידע המדויק ששרת ה-MCP החזיר. בודקים אם התשובה שנוצרה מדויקת.
Essentials ו-Pro
Essentials ו-Pro הם שני מק"טים של אותו מוצר, ולא מוצרים או תוכניות נפרדים. בקשה מחויבת לפי Pro כשמשתמשים באפשרות של Pro. כל בקשה אחרת מחויבת במסגרת Essentials. האפשרויות של Pro הן שדות רגילים בבקשת הכלי, כך ש-LLM יכול להשתמש בהן בשבילכם. נציג יכול גם להשתמש בשני המק"טים באותה שיחה. לדוגמה, נציג יכול להשתמש ב-Essentials כדי למצוא בתי קפה ליד נקודת ציון. אחר כך, הוא יכול להשתמש ב-Pro כדי לענות על שאלה נוספת לגבי המשקאות המיוחדים והמקומות במסעדה. אין שרת, נקודת קצה או פרטי כניסה נפרדים ל-MCP ב-Pro.
השוואה בין Essentials, Pro ו"עיגון בעזרת מפות Google"
עיגון בעזרת מפות Google הוא מוצר נפרד. הוא מובנה במודלים של Gemini ב-Gemini API, ב-Google AI Studio וב-Gemini Enterprise Agent Platform. המודל מחליט מתי לשלוח שאילתה למפות Google ומחזיר תשובות מבוססות עם ציטוטים. בחרו באפשרות "עיגון בעזרת מפות Google" כשאתם מפתחים ב-Gemini ורוצים שהמודל יטפל בעיגון. כדאי לבחור בכלים של Maps Experiments למודלים אחרים או למסגרות אחרות של סוכנים, או כדי לשלוט ישירות בכל קריאת API לכלי.
בטבלה הבאה מוצגת השוואה בין המק"ט Essentials, המק"ט Pro ו"עיגון בעזרת מפות Google":
| כלים אג'נטיים בממשק Maps | עיגון בעזרת מפות Google | ||
|---|---|---|---|
| מק"ט Essentials (לשעבר Maps Grounding Lite) |
מק"ט של Pro | ||
| איך מתבצע החיוב על הבקשות | כל בקשה לכלי שלא משתמשת באפשרות Pro | כל בקשה ל-search_along_route, או כל בקשה לכלי אחר שמשתמש באפשרות Pro. מה מחויב במק"ט של Pro? |
כל שאילתה במפות Google או הנחיה מעוגנת, בהתאם לפלטפורמה ולמודל |
| מודלים ופלטפורמות | כל מודל או מסגרת של סוכן שתומכים ב-MCP או יכולים להפעיל ממשקי API בארכיטקטורת REST. קבוצה אחת של כלים ואותם פרטי כניסה לשני המק"טים | מודלים של Gemini ב-Gemini API, ב-Google AI Studio וב-Gemini Enterprise Agent Platform | |
| מה הכלים מחזירים | עובדות בסיסיות: פרטים של עד 5 מקומות לכל חיפוש, מרחק ומשך זמן של מסלול בלי דיווחי תנועה בזמן אמת, מזג האוויר הנוכחי ותחזיות (בנוסף להיסטוריית מזג האוויר השעתית ב-24 השעות האחרונות), ואיכות האוויר הנוכחית או החזויה | כל מה שכלול ב-Essentials, וגם מקומות לאורך מסלול עם זמן ומרחק של עיקוף, פרטי מקומות מורחבים (כמו תובנות מביקורות), עד 10 מקומות לכל חיפוש, מסלולים עם תנועה בזמן אמת, עד 25 נקודות ציון ביניים, תחזיות אבקנים ועד 30 ימים של היסטוריית איכות האוויר | פרטים על מקומות ותובנות מביקורות, ומידע על מסלולים עם נתוני תנועה בזמן אמת |
| דוגמאות לבקשות | שאלות עובדתיות ולוגיסטיות: חיפוש חנויות או עסקים, שעות פתיחה, כתובות, הערכות של מרחק או זמן הגעה, מזג האוויר הנוכחי, תחזיות מזג אוויר ל-10 ימים ותחזיות נוכחיות או ל-4 ימים של איכות האוויר | שאלות סובייקטיביות, כלליות או ספציפיות: מקומות לאורך מסלול, אווירה, מנות דגל, טיפים למבקרים, השוואות בין 6 עד 10 מקומות, זמני הגעה בתנועה הנוכחית, תחזיות של אבקנים ואלרגיות והיסטוריית איכות האוויר ב-30 הימים האחרונים | חיפוש בממשק שיחה, תכנון מסלול נסיעה וגילוי מקומות ב-Gemini |
| רכיבי המחשה של Places UI Kit | כלול ללא עלות נוספת באסימון להצגה חזותית של נתונים באמצעות סוכנים (גרסת טרום-השקה) | חיוב בנפרד | |
| שימוש חודשי ללא תשלום | 10,000 בקשות | 5,000 בקשות | תלוי בפלטפורמה ובמודל. לדוגמה, ב-Gemini API, מודלים של Gemini 3 ומעלה כוללים 5,000 שאילתות חיפוש בחודש ללא תשלום. לאחר מכן, שאילתות החיפוש עולות 14 $לכל 1,000 שאילתות. |
| מחיר לתשלום לפי שימוש | 7.00$ לכל 1,000 בקשות, עם הנחות על נפח השימוש | 14.00$ לכל 1,000 בקשות, עם הנחות על נפח השימוש | |
| נרשמים למינוי וחוסכים | כלול בתוכניות Essentials ו-Pro | כלול בתוכנית Pro | לא זמין |
| שנתחיל? | הגדרה אחת לשני המק"טים: עיינו במאמר הגדרת מודלים גדולים של שפה (LLM) לשימוש בשרת MCP או קריאה לכלים באמצעות REST. | Gemini API או Agent Platform | |
האפשרויות האלה פועלות באותו אופן בשני המק"טים: אמצעי הגעה, זמני יציאה וזמן הגעה, מסלולים חלופיים, קווים פוליגוניים של מסלולים, חיפושי מזג אוויר, חיפושים של איכות האוויר הנוכחית והחזויה (כולל ריכוזי מזהמים וסולמות AQI מקומיים), מערכות יחידות של מזג אוויר ו-Resolution API. הם לא משנים את המק"ט שלפיו בקשה מחויבת.
מה מחויב במסגרת המק"ט של Pro
בטבלה הבאה מפורטות היכולות שנכללות ב-Essentials והיכולות שדורשות את המק"ט של Pro:
| כלי | פונקציה | Essentials | Pro |
|---|---|---|---|
| חיפוש מקומות | מקומות לכל בקשה | עד 5 | 6 עד 10 (page_size מ-6 עד 10) |
| פרטים מורחבים על מקומות בסיכומי החיפוש (תובנות מביקורות, הדגשות בתפריט, אווירה, רמת העומס במקום, טיפים למבקרים, ומרחק או זמן הגעה לשאילתות קרבה) | לא זמין | זמין ב-include_extended_details |
|
| חיפוש לאורך המסלול | מקומות לאורך מסלול, מרחק וזמן הגעה של עיקוף, ואפשרות לפרטים מורחבים על מקומות או זמני עיקוף בהתאם למצב התנועה | לא זמין | כל בקשה |
| חישוב מסלולים | העדפת ניתוב | לא מביא בחשבון את מצב התנועה בזמן אמת | התחשבות בעומסי תנועה בזמן אמת, או בנתוני תחבורה ציבורית בזמן אמת במסלולי תחבורה ציבורית, באמצעות ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL |
| נקודות ציון ביניים בכל מסלול | עד 10 | 11 עד 25 (יותר מ-10 intermediate_waypoints) |
|
| חיפוש מזג אוויר | מזג אוויר | מזג האוויר הנוכחי, תחזיות לפי שעה ולפי יום (עד 10 ימים) והיסטוריה של עד 24 שעות לפי שעה (WEATHER ב-capabilities, או בקשות מדור קודם שמשמיטות את capabilities, weather_options, air_quality_options ו-language_code) |
אין אפשרויות Pro (כל הנתונים של WEATHER כלולים ב-Essentials) |
| איכות האוויר | מזג האוויר הנוכחי, תוצאות שעתיות לכל היום ותחזיות שעתיות עד 4 ימים (AIR_QUALITY בcapabilities) |
נתונים היסטוריים של איכות האוויר עד 30 יום בעבר (AIR_QUALITY ב-capabilities עם date לפני היום או hour בעבר באזור הזמן של המיקום), כשהם מוחזרים בתגובה |
|
| אבקנים | לא זמין | תחזיות יומיות של אבקנים עד 5 ימים ופרטים על מיני צמחים (POLLEN ב-capabilities), כשהם מוחזרים בתגובה |
|
| Resolution API | אין אפשרויות Pro. כל הבקשות מחויבות לפי המק"ט Places API חיפוש טקסט הנחיות בסיסיות להתאמת תוכן לחיפוש (IDs Only) ללא תשלום. | ||
כדי לראות את אפשרויות הבקשה שמפעילות כל יכולת, עיינו במאמרים חיפוש מקומות, חיפוש לאורך המסלול, חישוב מסלולים וחיפוש מזג אוויר.
שליטה בשימוש ב-Pro
האפשרויות המתקדמות מושבתות כברירת מחדל במכשירים search_places, compute_routes ו-lookup_weather. מודל שפה גדול (LLM) מגדיר אותם – או קורא ל-search_along_route – כשהבקשה של המשתמש דורשת זאת, ותיאור הכלי או ההוראות שלכם מאפשרים זאת.
תיאורי הכלים מציינים למודל אילו אפשרויות עולות יותר ומתי להשתמש בהן: page_size מעל 5, Place Details מורחבים, יותר מ-10 נקודות ציון ביניים, ניתוב עם התחשבות בתנועה ו-search_along_route. אם אתם קוראים לכלים באמצעות REST, הקוד שלכם מגדיר כל אפשרות. כדי לנהל את העלויות:
- אפשר להגיד למודל מתי להשתמש באפשרויות של Pro. לדוגמה: "תגדיר את
include_extended_detailsרק כשהמשתמש שואל על ביקורות, תפריטים או אווירה". או: "השתמש ב-ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALרק כשהמשתמש מבקש את זמן ההגעה הנוכחי". או: "צריך להפעיל אתsearch_along_routeרק כשהמשתמש מבקש מקומות לאורך מסלול". או: "צריך לכלול אתPOLLENאו אתAIR_QUALITYעםdateאוhourבעבר, רק כשהמשתמש שואל על אבקנים, אלרגיות או איכות האוויר בעבר". - כדי להשאיר נציג במק"ט Essentials, צריך להורות למודל לא להפעיל אף פעם את
search_along_routeאו להשתמש באפשרות Pro. האפשרויות ב-Pro הןinclude_extended_details,page_sizeמעל 5,ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, יותר מ-10 נקודות ציון ביניים,POLLENב-capabilities, וdateאוhourקודמים עםAIR_QUALITYב-capabilities. אם לקוח ה-MCP שלכם יכול להגביל כלים או ארגומנטים של כלים, אתם יכולים גם לחסום אתsearch_along_routeואת ערכי הארגומנטים האלה בהגדרות הכלי. - עוקבים אחרי המק"ט של Maps Grounding Pro בדוחות החיוב ומגדירים התראות תקציב.
Resolution API
הכלים האג'נטיים בממשק Maps מספקים את Resolution API. הוא מפענח טקסט חופשי של מיקום וכתובות URL למזהי מקומות מובְנים במפות Google. Resolution API זמין כשיטות REST וככלים בשרת ה-MCP:
- זיהוי שמות (REST, MCP): זיהוי קבוצה של שמות או כתובות של מיקומים לישויות ספציפיות של מקומות במפות Google. הכלי הזה עוזר להמיר שאילתות לא מובנות של משתמשים למזהי מקומות יציבים.
- Resolve Maps URLs (REST, MCP): המרה של קבוצת כתובות URL של מפות Google לישויות ספציפיות של מקומות. הפורמטים הנתמכים כוללים כתובות URL רגילות של מקומות וכתובות URL מקוצרות.
אתם יכולים להשתמש במזהי המקומות שמוחזרים עם ממשקי API אחרים של Google Maps Platform. כל תשובה כוללת גם קישור ששומר את המקומות שזוהו כרשימה במפות Google.
מידע נוסף זמין במאמר Maps Tools Resolution API.
התנסות באפליקציה לדוגמה (פתיחה בכרטיסייה חדשה)
חיוב ומכסות
איך מתבצע החיוב
במודל התמחור "תשלום לפי שימוש" של Google Maps Platform, השימוש בכלים אג'נטיים בממשק מפות מחושב לכל בקשה. כל בקשה מייצגת אירוע חיוב אחד. השימוש נמדד לכל מק"ט של מוצר. בחשבון מופיע פריט לכל מק"ט, בנוסף לחיובים הכוללים. מידע נוסף מופיע בסקירה הכללית על דיווח.
כל בקשה לחיפוש מקומות, חיפוש לאורך המסלול, חישוב מסלולים או בדיקת מזג האוויר, דרך שרת MCP או באמצעות REST, מחויבת לפי מק"ט אחד:
Maps Grounding Essentials
או
Maps Grounding Pro.
כל בקשה של search_along_route וכל בקשה שמשתמשת באפשרות Pro מחויבת במסגרת המק"ט של Pro. בקשה אף פעם לא מחויבת בשני המק"טים, ומספר האפשרויות של Pro בבקשה לא משנה את החיוב. במאמר מה מחויב במק"ט Pro מפורטות היכולות והאפשרויות שקובעות את המק"ט של כל כלי.
בקשות Maps Grounding Essentials מחויבות בסכום של 7.00 $לכל 1,000 בקשות אחרי 10,000 הבקשות הראשונות בכל חודש. בקשות Maps Grounding Pro מחויבות בסכום של 14.00 $לכל 1,000 בקשות אחרי 5,000 הבקשות הראשונות בכל חודש. בשני המק"טים יש הנחות על נפח שימוש חודשי גבוה יותר.
לפרטים על המחירים, קראו את טבלת התמחור הראשית ואת טבלת התמחור בהודו.
בקשות Resolution API (ResolveNames ו-ResolveMapsUrls) מחויבות ללא תשלום במסגרת המק"ט Places API Text Search Essentials (IDs Only).
אם אתם מציגים את המקומות מתשובה של search_places או search_along_route באמצעות Places UI Kit, אתם יכולים להשתמש באסימון להצגת נתונים של סוכן (גרסת טרום-השקה (Preview)) כדי שלא תחויבו על הבקשות האלה ל-Places UI Kit.
השימוש במק"ט Essentials כלול בתוכניות Essentials ו-Pro Subscribe to save. השימוש במק"ט Pro כלול בתוכנית Pro.
מכסות
המכסות הבאות חלות על הכלים וממשקי ה-API שמסופקים על ידי הכלים האג'נטיים בממשק Maps:
- חיפוש מקומות: 300 שאילתות לדקה לכל פרויקט.
- חיפוש לאורך המסלול: 300 שאילתות לדקה לכל פרויקט.
- חיפוש מזג אוויר: 300 שאילתות לדקה לכל פרויקט.
- חישוב מסלולים: 300 שאילתות לדקה לכל פרויקט.
- Resolve names: 600 שאילתות לדקה לכל פרויקט.
- Resolve Maps URLs: 600 שאילתות לדקה לכל פרויקט.
המכסות נספרות לכל כלי ומשותפות למק"טים של Essentials ו-Pro. בקשה ב-Pro צורכת את אותה מכסה כמו בקשה ב-Essentials לאותו כלי.
כל בקשת API ל-Resolution נספרת כשאילתה אחת, בלי קשר למספר הפריטים שהיא מכילה.
מדיניות ותנאים והגבלות
השימוש בכלים אג'נטיים בממשק Maps Experience כפוף לתנאים ולהגבלות של Google Maps Platform, כולל התנאים הספציפיים לשירות. בקטע הזה מתוארות דרישות שימוש נוספות בכלים של סוכן Maps Experience, כולל מודלים תואמים של LLM ושיוך למקור. הדרישות חלות על כל התוצאות, לא משנה באיזה מק"ט הבקשה מחויבת.
הדרישות לגבי מודלי LLM תואמים
מותר להשתמש בכלים האג'נטיים בממשק Maps Experience רק עם מודל LLM שעומד בתנאים ובהגבלות של Google Maps Platform.
לדוגמה, אתם אחראים לוודא שהתוכן של מפות Google לא נשמר במטמון, לא מאוחסן ולא משמש לשיפור ה-LLM שבחרתם להשתמש בו. לפני שמשתמשים בכלים אג'נטיים של Maps Experiments, צריך לקרוא את התנאים וההגבלות של כל מודל שמתכוונים להשתמש בו עם הכלים האלה. אסור להשתמש בכלים של סוכני Maps Experience עם מודלים שמשתמשים בנתונים שהוזנו במודל לצורך אימון או שיפור של המודל. באחריותכם לוודא שהשימוש שלכם במודל עומד באופן מלא בהגבלות על התוכן של מפות Google שמפורטות בתנאים ובהגבלות של Google Maps Platform, כולל התנאים הספציפיים לשירות.
דרישות הייחוס למקורות של מפות Google
כל תגובה של הכלים האג'נטיים ב-Maps Experience כוללת מקורות. כשאתם מציגים תוצאות מהכלים האג'נטיים ב-Maps Experiments, אתם צריכים לכלול את המקורות המשויכים של מפות Google ולעמוד בדרישות הבאות:
- המקורות של מפות Google חייבים להופיע מיד אחרי התוכן שנוצר שהמקורות תומכים בו. התוכן שנוצר נקרא גם פלט מבוסס-מקורות.
- המקורות של מפות Google צריכים להיות גלויים באינטראקציה אחת של המשתמש.
מקורות לכלים "חיפוש מקומות" ו"חיפוש לאורך המסלול"
השדה search_places tool places והשדה search_along_route tool results[].place מספקים מקורות שתומכים ב-summary. לכל מקום, המטא-נתונים הבאים מוחזרים:
place(שם המשאב)idlocationgoogleMapsLinksattribution
לכל מקום, צריך ליצור תצוגה מקדימה של קישור שעומדת בדרישות הבאות:
- לשייך כל מקור למפות Google, בהתאם להנחיות לשיוך טקסט בכלים אג'נטיים בממשק Maps.
- קישור למקור באמצעות
googleMapsLinks.placeUrlמהתשובה.
הדרישות האלה חלות גם על סיכומים שכוללים פרטי מקומות מורחבים מ-Pro, כמו תובנות מביקורות. השדה summary מציין כל מקום באמצעות אינדקס מבוסס-אפס, כמו [0], שממופה לרשומה ב-places או ב-results.
כל מקום כולל גם את googleMapsLinks.reviewsUrl, שמקשר לביקורות על המקום במפות Google. המשתמשים יכולים ללחוץ על הקישור כדי לראות את הביקורות שמאחורי התובנה.
ממשקים שמופעלים באמצעות הקול
אם האפליקציה שלכם מציגה תוצאות של כלים אג'נטיים בממשק Maps Experiments באמצעות קול, אתם צריכים לעמוד גם בדרישות לגבי ממשקים שמופעלים קודם כל באמצעות הקול. לסיכום:
- מקורות: הצגת המקורות של מפות Google בממשק משתמש נלווה שמציג תיעוד היסטורי מילה במילה של השיחה הקולית.
- גילוי נאות פעיל: בזמן האינטראקציה, צריך להודיע למשתמשים שהתוכן שנוצר על ידי AI עשוי לכלול מידע ממפות Google. כדאי גם להגיד להם שהמקורות המפורטים זמינים בממשק המשתמש של Companion. אפשר לעשות את זה במסך או באמצעות הקול.
- גילוי נאות קבוע: צריך להציג הסבר קבוע, למשל בתפריט הגדרות הקול, שתוכן שנוצר על ידי AI עשוי לכלול תוכן ממפות Google.
- פניות של משתמשים: לענות בצורה מדויקת על שאלות של משתמשים לגבי מקור התוכן, ולהפנות אותם לממשק המשתמש של האפליקציה הנלווית כדי לקבל פרטים.
הגדרת מודלי LLM לשימוש בשרת ה-MCP
כדי להשתמש בכלים האג'נטיים בממשק מפות Google, צריך פרויקט ב-Google Cloud שבו מופעל שירות ה-API של הכלים האג'נטיים בממשק מפות Google. אתם צריכים גם מפתח API או מזהה לקוח ב-OAuth. לאחר מכן, אתם יכולים להגדיר את מודלי ה-LLM כך שתהיה להם גישה לשרת ה-MCP. שרת ה-MCP משתמש בתעבורת Streamable HTTP.
מפעילים את הכלים האג'נטיים בממשק Maps Experiments בפרויקט בענן ב-Google Cloud.
כדי להפעיל את ה-API בפרויקט:
- במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו לכלי סוכן של Maps Experience.
- מפעילים את החיוב בפרויקט במסוף Google Cloud.
- מפעילים את הכלים של Maps Experiments בספריית ה-API במסוף Google Cloud.
אימות באמצעות מפתח API
אתם יכולים להשתמש במפתח API קיים עם הכלים האג'נטיים ב-Maps Experiments, או ליצור מפתח חדש. בכל מקרה, צריך להפעיל את שירות ה-API של כלים אג'נטיים בממשק Maps Experiments גם בפרויקט בענן ב-Google Cloud וגם במפתח.
כדי לאמת באמצעות מפתח API:
- כדי ליצור או להגדיר מפתח API, פועלים לפי השלבים שמפורטים במאמר תחילת השימוש ב-Google Maps Platform.
- מעבירים את המפתח לשרת ה-MCP באמצעות הכותרת
X-Goog-Api-Key. צריך לציין את זה ככותרת HTTP בהתאמה אישית בהגדרות של כלי ה-MCP של ה-LLM.
אימות באמצעות OAuth
כדי לבצע אימות באמצעות OAuth, אתם יכולים ליצור פרטי כניסה ל-OAuth ולהעביר אותם לאפליקציית המארח של ה-MCP או לשרת ה-MCP.
כדי לבצע אימות באמצעות OAuth:
- במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו לכלי סוכן של Maps Experience.
- בתפריט API & Services, לוחצים על Credentials.
- בתפריט העליון, לוחצים על Create credentials > OAuth client ID.
- אם לפרויקט אין מסך הסכמה מוגדר, לוחצים על Configure consent screen ופועלים לפי ההוראות במסך.
- בקטע Metrics, לוחצים על יצירת לקוח OAuth.
- במסך Create OAuth client ID, בוחרים את סוג האפליקציה ומזינים שם למזהה הלקוח.
- מציינים את הפרטים הנוספים שרלוונטיים לסוג האפליקציה. לדוגמה, אם אתם יוצרים אפליקציית אינטרנט, הוסיפו כתובות URI מורשות לבקשות מהדפדפן ומהשרת.
- אחרי שיוצרים את הלקוח, שומרים את מזהה הלקוח והסוד.
- כשמגדירים את אפליקציית מארח ה-MCP או שרת ה-MCP, צריך להעביר את מזהה הלקוח וסוד הלקוח של לקוח OAuth. צריך גם לבקש את ההיקף הבא:
https://www.googleapis.com/auth/maps-platform.mapstools.
למידע נוסף, קראו את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.
הגדרת מודלי LLM לגישה לשרת ה-MCP של הכלים האג'נטיים בממשק Maps
אחרי שמפעילים את השירות Maps Experiments agent tools ויוצרים פרטי כניסה, אפשר להגדיר למודלי ה-LLM גישה לשרת ה-MCP. פועלים לפי ההוראות להגדרת MCP במודל ה-LLM ומשתמשים בכתובת ה-URL של שרת ה-MCP: https://mapstools.googleapis.com/mcp
מידע נוסף זמין במאמר הגדרת MCP באפליקציית AI.
הגדרת כלים אג'נטיים ב-Maps Experiments באמצעות Gemini CLI
בקטע הזה מוסבר איך להגדיר את שרת ה-MCP של כלי הסוכן של Maps Experience באמצעות Gemini CLI. מידע נוסף זמין במאמר שרתי MCP עם Gemini CLI.
אחרי שמתקינים את Gemini CLI, מריצים את הפקודה
gemini mcp addכדי להגדיר את שרת ה-MCP:gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcpאם ההגדרה בוצעה בהצלחה, אמור להופיע אישור שהשרת נוסף להגדרות המשתמש.
כדי לוודא שהשרת פועל, מריצים את הפקודה
/mcp list:> /mcp list Configured MCP servers: maps-experience-agent-tools-mcp - Ready (6 tools) Tools: - compute_routes - lookup_weather - resolve_maps_urls - resolve_names - search_along_route - search_placesמתחילים לשאול שאלות שקשורות ל-Ask Maps באמצעות ה-CLI. לדוגמה, נסו את ההנחיה "תמליץ על מסעדות במאונטיין ויו", שתפעיל את הכלי
search_placesבשבילכם.
הגדרת כלים של Maps Experiments באמצעות ערכת פיתוח הסוכנים (ADK)
בקטע הזה מוסבר איך להגדיר את שרת ה-MCP באמצעות הערכה לפיתוח סוכנים (ADK) ב-Python, ב-Java או ב-TypeScript.
Python
הטמעה מלאה של הדוגמה הזו זמינה ב-GitHub, במאגר adk-samples.
שלב 1: מגדירים את הסוכן באמצעות McpToolset לכלים סוכניים ב-Maps Experiments
משנים את הקובץ agent.py. מחליפים את YOUR_GOOGLE_MAPS_API_KEY במפתח ה-API שלכם.
# ./adk_agent_samples/mcp_agent/agent.py import os from google.adk.agents.llm_agent import Agent from google.adk.tools.mcp_tool import McpToolset from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams # Retrieve the API key from an environment variable or directly insert it. GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY") if not GOOGLE_MAPS_API_KEY: GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE" if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE": print("WARNING: GOOGLE_MAPS_API_KEY is not set.") root_agent = Agent( model='gemini-flash-latest', name='travel_planner_agent', description='A helpful assistant for planning travel routes.', tools=[ McpToolset( connection_params=StreamableHTTPConnectionParams( url="https://mapstools.googleapis.com/mcp", headers={ "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY, "Content-Type": "application/json", "Accept": "application/json, text/event-stream" } ) ) ] )
שלב 2: מוודאים ש-__init__.py קיים
מוודאים שיש לכם __init__.py באותה ספרייה שבה נמצא הקובץ agent.py:
from . import agent
שלב 3: מפעילים את adk web ומתחילים להשתמש
- הגדרת משתנה סביבה:
מגדירים את מפתח Google Maps API כמשתנה סביבה בטרמינל:export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
- מריצים את
adk web:
מריצים את הפקודה הבאה כדי להפעיל את ממשק האינטרנט של ADK:adk web
- אינטראקציה בממשק המשתמש:
- בחר את רשת ה-
travel_planner_agent. - אפשר לנסות הנחיות כמו:
- "אני אהיה בתל אביב מחר. מה מזג האוויר?"
- "Find coffee shops near Golden Gate Park" (חפש בתי קפה ליד פארק גולדן גייט).
- "Get directions from GooglePlex to SFO" (קבלת מסלול מ-GooglePlex אל SFO).
- בחר את רשת ה-
Java
מגדירים סוכן שמפעיל את McpToolset ב-Java.
אם אתם לא משתמשים במשתנה סביבה, החליפו את YOUR_GOOGLE_MAPS_API_KEY_HERE במפתח ה-API שקיבלתם.
package agents; import com.google.adk.agents.LlmAgent; import com.google.adk.runner.InMemoryRunner; import com.google.adk.sessions.SessionKey; import com.google.adk.tools.mcp.McpToolset; import com.google.adk.tools.mcp.StreamableHttpServerParameters; import com.google.genai.types.Content; import com.google.genai.types.Part; import java.util.HashMap; import java.util.Map; public class MapsAgentCreator { public static void main(String[] args) { String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY"); if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) { googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE"; if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) { System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set."); } } Map<String, String> headers = new HashMap<>(); headers.put("X-Goog-Api-Key", googleMapsApiKey); headers.put("Content-Type", "application/json"); headers.put("Accept", "application/json, text/event-stream"); StreamableHttpServerParameters serverParams = StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp") .headers(headers) .build(); try (McpToolset toolset = new McpToolset(serverParams)) { LlmAgent agent = LlmAgent.builder() .model("gemini-flash-latest") .name("travel_planner_agent") .description("A helpful assistant for planning travel routes.") .tools(toolset) .build(); System.out.println("Agent created: " + agent.name()); InMemoryRunner runner = new InMemoryRunner(agent); String userId = "maps-user-" + System.currentTimeMillis(); String sessionId = "maps-session-" + System.currentTimeMillis(); String promptText = "Please give me directions to the nearest pharmacy to Madison Square Garden."; SessionKey sessionKey = runner.sessionService() .createSession(runner.appName(), userId, null, sessionId) .blockingGet() .sessionKey(); System.out.println("Session created: " + sessionId + " for user: " + userId); Content promptContent = Content.fromParts(Part.fromText(promptText)); System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n"); runner.runAsync(sessionKey, promptContent) .blockingForEach(event -> { System.out.println("Event received: " + event.toJson()); }); } catch (Exception e) { System.err.println("An error occurred: " + e.getMessage()); e.printStackTrace(); } } }
TypeScript
מגדירים סוכן שמפעיל את MCPToolset ב-TypeScript:
import 'dotenv/config'; import {LlmAgent, MCPToolset} from "@google/adk"; const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY; if (!googleMapsApiKey) { console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set."); throw new Error( 'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.' ); } export const rootAgent = new LlmAgent({ model: "gemini-flash-latest", name: "travel_planner_agent", description: "A helpful assistant for planning travel.", tools: [ new MCPToolset({ type: "StreamableHTTPConnectionParams", url: "https://mapstools.googleapis.com/mcp", transportOptions: { requestInit: { headers: { "X-Goog-Api-Key": googleMapsApiKey, "Content-Type": "application/json", "Accept": "application/json, text/event-stream" } } } }) ], });
קריאה לכלים באמצעות REST
כל כלי באוסף הכלים של Maps Experiments זמין גם כ-method של REST. אתם יכולים להפעיל את השיטות של REST ישירות כשאתם רוצים לחבר את הכלים לסוכן או לאפליקציה שלכם – לדוגמה, כדי להצהיר על פונקציות משלכם למודל, לבחור אילו אפשרויות המודל יכול להגדיר או להגדיר ערכי ברירת מחדל בקוד.
בטבלה הבאה מפורטת שיטת ה-REST לכל כלי:
| כלי | שיטת REST |
|---|---|
search_places |
POST https://mapstools.googleapis.com/v1:searchText |
search_along_route |
POST https://mapstools.googleapis.com/v1:searchAlongRoute |
lookup_weather |
POST https://mapstools.googleapis.com/v1:lookupWeather |
compute_routes |
POST https://mapstools.googleapis.com/v1:computeRoutes |
resolve_names |
POST https://mapstools.googleapis.com/v1:resolveNames |
resolve_maps_urls |
POST https://mapstools.googleapis.com/v1:resolveMapsUrls |
בקשת REST מקבלת את אותן האפשרויות כמו הכלי המתאים ומחזירה את אותה התשובה. בגוף הבקשה והתגובה של REST, שמות השדות כתובים בקאמל קייס קטן – לדוגמה, textQuery במקום text_query. בקשות REST מחויבות לפי אותם מק"טים, כפופות לאותם כללים לגבי אפשרויות Pro ונכללות באותן מכסות כמו קריאות API לכלי MCP.
כדי לאמת, צריך להשתמש באותו פרויקט בענן ב-Google Cloud ובאותם פרטי כניסה כמו בשרת ה-MCP. איך מגדירים את שרת ה-MCP במודלי LLM
מעבירים מפתח API בכותרת X-Goog-Api-Key, או מעבירים טוקן גישה של OAuth עם ההיקף https://www.googleapis.com/auth/maps-platform.mapstools בכותרת Authorization.
בדוגמה הבאה מתבצעת קריאה ל-method searchText:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"
מחליפים את הערך API_KEY במפתח ה-API שלכם.
התשובה מכילה את אותם שדות summary, places ו-contentToken כמו תוצאת הכלי search_places. במדריך של כל כלי מוצגת גרסת REST של הדוגמה שלו.
שיתוף משוב
כדי לשלוח משוב על הכלים האג'נטיים ב-Maps Experience, אתם יכולים להשתמש בטפסים הבאים: