עם מק"ט Pro, אפשר להשתמש ביכולות נוספות של כלי הסוכן של Maps Experience. כדי לקבל גישה, פנו למחלקת המכירות.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

כלי הסוכן של Maps Experience

כלי הסוכן של Maps Experience (לשעבר Maps Grounding Lite) הם שירות של הפלטפורמה של מפות Google עם תמיכה ב-Model Context Protocol ‏ (MCP) כדי לעגן את אפליקציות ה-AI שלכם בנתונים גיאו-מרחביים מהימנים ממפות Google. שרת ה-MCP מספק כלים שמאפשרים למודלי LLM לגשת לנתונים על מקומות, מזג אוויר ומסלולים. כלים אחרים פותרים שמות של מיקומים וכתובות URL של מפות Google למזהי מקומות. כדי לנסות את כלי הסוכן של Maps Experience, אתם יכולים להפעיל אותם בכל כלי שתומך בשרתי MCP.

המוצר "כלי סוכנים של Maps Experience" כולל שני מק"טים: Essentials ו-Pro. כל בקשה מחויבת במסגרת Essentials, אלא אם היא משתמשת באפשרות Pro. אפשרויות Pro מוסיפות פרטי מקומות מורחבים, יותר מקומות לכל חיפוש, יותר עצירות ביניים לכל מסלול וניתוב עם תנועה בזמן אמת. במהלך תקופת הזמינות הכללית המוגבלת, האפשרויות של Pro זמינות רק לפרויקטים שנמצאים ברשימת ההיתרים של Pro. שני המק"טים משתמשים באותו שרת MCP, באותם כלים ובאותם פרטי כניסה. לפרטים נוספים, קראו את המאמר Essentials ו-Pro.

כלים

הכלים של Maps Experiments מאפשרים למודלי LLM לגשת ליכולות הבאות של מפות Google:

חיפוש מקומות: בקשת מידע על מקומות וקבלת סיכומים שנוצרו על ידי AI. התשובה כוללת גם מזהי מקומות, קואורדינטות וקישורים למפות Google לכל מקום בסיכום. אתם יכולים להשתמש במזהי המקומות ובקואורדינטות עם ממשקי API אחרים של Google Maps Platform כדי להציג מקומות במפה. בתוכנית Pro, אתם יכולים לבקש פרטים מורחבים על מקומות, כמו תובנות מביקורות, ועד 10 מקומות בכל בקשה.
חיפוש מזג אוויר: בקשת מידע על מזג האוויר והחזרת התנאים הנוכחיים, תחזיות לפי שעה ותחזיות יומיות.
חישוב מסלולים: בקשת מסלול בין נקודת מוצא לנקודת יעד, עם אפשרות לעצירות ביניים, והחזרת המרחק ומשך הזמן של המסלול. בגרסת Pro, המסלולים יכולים להתחשב במצב התנועה בזמן אמת ולכלול יותר עצירות ביניים.

הערה: כלי הסוכן של Maps Experience לא מספקים מסלול מפורט או מידע על ניווט. מסלולים שמחושבים בלי אפשרויות Pro לא מביאים בחשבון את התנועה בזמן אמת.
Resolve names ו-Resolve Maps URLs: המרת שמות של מיקומים, כתובות וכתובות URL של מפות Google למזהי מקומות. מידע נוסף מופיע במאמר בנושא Resolution API.

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

‫Essentials ו-Pro

‫Essentials ו-Pro הם שני מק"טים של אותו מוצר, ולא מוצרים או תוכניות נפרדים. בקשה מחויבת במסגרת Pro כשהיא משתמשת באפשרות של Pro. כל בקשה אחרת מחויבת במסגרת Essentials. האפשרויות של Pro הן שדות רגילים בבקשת הכלי, כך שמודל LLM יכול להשתמש בהן בשבילכם. נציג יכול גם להשתמש בשני המק"טים באותה שיחה. לדוגמה, סוכן יכול להשתמש ב-Essentials כדי למצוא בתי קפה ליד נקודת ציון. אחר כך, הוא יכול להשתמש ב-Pro כדי לענות על שאלה נוספת לגבי המשקאות המיוחדים והמקומות במסעדה. אין שרת MCP, נקודת קצה (endpoint) או פרטי כניסה נפרדים ל-Pro.

השוואה בין Essentials,‏ Pro ו"עיגון בעזרת מפות Google"

עיגון בעזרת מפות Google הוא מוצר נפרד. הוא מובנה במודלים של Gemini ב-Gemini API, ב-Google AI Studio וב-Gemini Enterprise Agent Platform. המודל מחליט מתי לשלוח שאילתה למפות Google ומחזיר תשובות מבוססות עם ציטוטים. כדאי לבחור ב"עיגון בעזרת מפות Google" כשאתם מפתחים ב-Gemini ורוצים שהמודל יטפל בעיגון. כדי להשתמש במודלים או במסגרות אחרות של סוכנים, או כדי לשלוט ישירות בכל קריאה לכלי, אתם יכולים לבחור כלים של סוכנים ב-Maps Experience.

	כלי הסוכן של Maps Experience		עיגון בעזרת מפות Google
	‫Essentials SKU (לשעבר Maps Grounding Lite)	מק"ט של Pro	עיגון בעזרת מפות Google
איך מתבצע החיוב על הבקשות	כל בקשה לכלי שלא משתמשת באפשרות Pro	כל בקשה לכלי שמשתמשת באפשרות Pro: `include_extended_details`, `page_size` מעל 5, `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`, או יותר מ-10 נקודות ביניים	כל שאילתה במפות Google או הנחיה מעוגנת, בהתאם לפלטפורמה ולמודל
מודלים ופלטפורמות	כל מודל או מסגרת של סוכן שתומכים ב-MCP. שרת MCP אחד, קבוצת כלים אחת ואותם פרטי כניסה לשני המק"טים.		מודלים של Gemini ב-Gemini API, ב-Google AI Studio וב-Gemini Enterprise Agent Platform
מה הכלים מחזירים	עובדות בסיסיות: פרטים של עד 5 מקומות לכל חיפוש, מרחק ומשך זמן של מסלול בלי תנועה בזמן אמת, ומזג האוויר הנוכחי ותחזיות	כל מה שכלול ב-Essentials, וגם פרטי מקומות מורחבים (כמו תובנות מביקורות), עד 10 מקומות לכל חיפוש, מסלולים עם עדכוני תנועה בזמן אמת ועד 25 נקודות ציון ביניים	פרטים על מקומות ותובנות מביקורות, ומידע על מסלולים עם מצב התנועה בזמן אמת
דוגמאות לבקשות	שאלות עובדתיות ולוגיסטיות: חיפוש חנויות או עסקים, שעות פתיחה, כתובות והערכות של מרחק או זמן הגעה	שאלות סובייקטיביות או כלליות: אווירה, מנות דגל, טיפים למבקרים, השוואות בין 6 עד 10 מקומות וזמני נסיעה במצב התנועה הנוכחי	חיפוש בממשק שיחה, תכנון מסלול נסיעה וגילוי מקומות ב-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	לא כלול	לא זמין
שנתחיל?	הגדרה אחת לשני המק"טים: ראו הגדרת מודלי LLM לשימוש בשרת MCP. במהלך תקופת הזמינות הכללית המוגבלת, כדי להשתמש באפשרויות של Pro צריך גם פרויקט שמופיע ברשימת ההיתרים של Pro.		‫Gemini API או Agent Platform

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

מה מחויב במסגרת המק"ט של Pro

כלי	פונקציה	Essentials	Pro
חיפוש מקומות	מקומות לכל בקשה	עד 5	‫6 עד 10 (`page_size` מתוך 6 עד 10)
חיפוש מקומות	פרטים מורחבים על מקומות בסיכומי החיפוש (תובנות מביקורות, מנות פופולריות בתפריט, אווירה, עומס במקום, טיפים ממבקרים ומרחק או זמן הגעה לשאילתות קרבה)	לא זמין	זמין ב-`include_extended_details`
חישוב מסלולים	העדפת ניתוב	לא מביא בחשבון את מצב התנועה בזמן אמת	התחשבות במצב התנועה בזמן אמת, או בנתוני תחבורה ציבורית בזמן אמת במסלולי תחבורה ציבורית, באמצעות `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`
חישוב מסלולים	נקודות ציון ביניים בכל מסלול	עד 10	‫11 עד 25 (יותר מ-10 `intermediate_waypoints`)
Lookup weather ו-Resolution API	אין אפשרויות ל-Pro. כל הבקשות מחויבות במק"ט של Essentials.

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

אפשרויות ב-Pro במהלך הזמינות הכללית המוגבלת

במהלך הזמינות הכללית המוגבלת, האפשרויות של Pro זמינות רק לפרויקטים ב-Google Cloud שנמצאים ברשימת ההיתרים של Pro. כדי לבקש גישה, פנו למחלקת המכירות. אחרי שפרויקט נמצא ברשימת ההיתרים, כל מפתח API ולקוח OAuth שבו יכולים להשתמש באפשרויות של Pro.

אם הפרויקט שלכם עדיין לא ברשימת ההיתרים, בקשות שמשתמשות באפשרויות של Pro מטופלות באופן הבא:

חיפוש מקומות: המערכת מתעלמת מהפרמטר include_extended_details, והתגובה מכילה עד 5 מקומות, גם אם הגדרתם ערך גבוה יותר לפרמטר page_size. הבקשה מחויבת במק"ט של Essentials.
חישוב מסלולים: המערכת מתייחסת ל-ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL כאל ROUTING_PREFERENCE_TRAFFIC_UNAWARE, והבקשה מחויבת לפי המק"ט של Essentials. בקשה עם יותר מ-10 נקודות ציון ביניים מחזירה שגיאה מסוג INVALID_ARGUMENT.

כדי לבדוק אם הפרויקט שלכם נמצא ברשימת ההיתרים, שלחו בקשת search_places כשהערך של page_size מוגדר ל-10. משתמשים בשאילתה רחבה, כמו restaurants in Chicago. פרויקט ברשימת ההיתרים יכול להחזיר יותר מ-5 מקומות, והחיוב עליהם יתבצע לפי המק"ט של גרסת Pro. בפרויקטים אחרים, המערכת מחזירה עד 5 מקומות.

שליטה בשימוש ב-Pro

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

אפשר להגיד למודל מתי להשתמש באפשרויות של Pro. לדוגמה: "תגדיר את include_extended_details רק כשהמשתמש שואל על ביקורות, תפריטים או אווירה". או: "השתמש ב-ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL רק כשהמשתמש מבקש את זמן ההגעה הנוכחי".
כדי להשאיר את הסוכן במק"ט Essentials, צריך להנחות את המודל לא להשתמש אף פעם באפשרות Pro. האפשרויות ב-Pro הן include_extended_details, page_size מעל 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL ויותר מ-10 נקודות ציון ביניים. אם לקוח ה-MCP שלכם יכול להגביל את הארגומנטים של הכלים, אתם יכולים גם לחסום את הערכים האלה בהגדרות הכלי.
עקבו אחרי השימוש בדוחות החיוב והגדירו התראות לגבי תקציב.

Resolution API

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

כל בקשה של Search places,‏ Compute routes או Lookup weather מחויבת במק"ט אחד בדיוק, Essentials או Pro. בקשה שמשתמשת באחת מהאפשרויות של Pro מחויבת לפי המק"ט של Pro. החיוב אף פעם לא מתבצע בשני המק"טים, ומספר האפשרויות של Pro לא משנה את החיוב. האפשרויות הבאות קובעות את המק"ט:

כלי	Essentials	Pro
`search_places`	כל בקשה בלי אפשרות Pro: ‏`page_size` של 5 או פחות, ו-`include_extended_details` לא מוגדר או `false`	‫`include_extended_details` מוגדר לערך `true`, או `page_size` מ-6 עד 10
`compute_routes`	כל בקשה בלי אפשרות Pro: ‏`routing_preference` לא מוגדר או `ROUTING_PREFERENCE_TRAFFIC_UNAWARE`, ו-10 נקודות ציון או פחות, עם כל אמצעי תחבורה	הערך של `routing_preference` מוגדר ל-`ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`, או 11 עד 25 נקודות ציון ביניים
`lookup_weather`	כל בקשה	—

לפרטי המק"ט של Essentials בקשות Pro מחויבות בסכום של 14.00 $לכל 1,000 בקשות אחרי 5,000 הבקשות הראשונות בכל חודש. פנו למחלקת המכירות כדי לקבל מחיר מיוחד לכמות גדולה.

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

פרטי התמחור מופיעים בטבלת התמחור הראשית ובטבלת התמחור בהודו.

בקשות Resolution API (‏ResolveNames ו-ResolveMapsUrls) מחויבות ללא תשלום במסגרת המק"ט Places API Text Search Essentials (IDs Only).

השימוש במק"ט של Essentials כלול גם בחבילות Subscribe to save של Essentials ו-Pro. המק"ט של Pro לא כלול בחבילות "נרשמים וחוסכים".

מכסות

המכסות הבאות חלות על הכלים וממשקי ה-API שכלולים ב-Maps Experience agent tools:

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

דרישות הייחוס למקורות של מפות Google

כל תשובה של סוכן Maps Experience כוללת מקורות. כשמציגים תוצאות מהכלים של סוכן Maps Experience, צריך לכלול את המקורות המשויכים של מפות Google ולעמוד בדרישות הבאות:

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

מקורות לכלי "חיפוש מקומות"

השדה places של הכלי search_places מספק מקורות שתומכים ב-summary. עבור places, המטא-נתונים הבאים מוחזרים:

place (שם המשאב)
id
location
googleMapsLinks

לכל מקום, צריך ליצור תצוגה מקדימה של קישור שעומדת בדרישות הבאות:

לשייך כל מקור למפות Google, בהתאם להנחיות לשיוך טקסט בכלי הסוכן של Maps Experiments.
מקשרים למקור באמצעות השדה places.googleMapsLinks.placeUrl מהתשובה.

הדרישות האלה חלות גם על סיכומים שכוללים פרטי מקומות מורחבים מ-Pro, כמו תובנות מביקורות. השדה summary מציין כל מקום באמצעות אינדקס מבוסס-אפס, לדוגמה [0], שממופה לרשומה ב-places. כל מקום כולל גם את googleMapsLinks.reviewsUrl, שמקשר לביקורות על המקום במפות Google. המשתמשים יכולים ללחוץ על הקישור כדי לראות את הביקורות שמאחורי התובנה.

ממשקים שמופעלים באמצעות הקול

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

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

הגדרת מודלי LLM לשימוש בשרת ה-MCP

כדי להשתמש בכלי הסוכן של Maps Experience, צריך פרויקט בענן ב-Google Cloud שבו מופעל שירות ה-API של כלי הסוכן של Maps Experience. אתם צריכים גם מפתח API או מזהה לקוח ב-OAuth. לאחר מכן, אתם יכולים להגדיר למודלי ה-LLM גישה לשרת ה-MCP. שרת ה-MCP משתמש בתעבורת HTTP שניתנת להעברה בסטרימינג.

מפעילים את כלי הסוכן של Maps Experience בפרויקט בענן של Google.

כדי להפעיל את ה-API בפרויקט:

במסוף Google Cloud, בוחרים את הפרויקט שרוצים להשתמש בו בשביל הכלים של סוכן Maps Experience.
מפעילים את החיוב בפרויקט במסוף Google Cloud.
מפעילים את כלי הסוכן של Maps Experience בספריית ה-API במסוף Google Cloud.

אימות באמצעות מפתח API

אתם יכולים להשתמש במפתח API קיים עם כלי הסוכן של Maps Experience, או ליצור מפתח חדש. בכל מקרה, צריך להפעיל את שירות ה-API של כלי הסוכן של Maps Experience גם בפרויקט בענן ב-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, לוחצים על Create OAuth client.
במסך Create OAuth client ID, בוחרים סוג אפליקציה ומזינים שם למזהה לקוח OAuth.
מציינים את הפרטים הנוספים שרלוונטיים לסוג האפליקציה. לדוגמה, אם אתם יוצרים אפליקציית אינטרנט, הוסיפו מזהי URI מורשים לבקשות מהדפדפן ומהשרת.
אחרי שיוצרים את הלקוח, שומרים את מזהה הלקוח והסוד.
כשמגדירים את אפליקציית המארח או שרת ה-MCP, צריך להעביר את מזהה הלקוח וסוד הלקוח של לקוח OAuth. צריך גם לבקש את ההיקף הבא: https://www.googleapis.com/auth/maps-platform.mapstools.

למידע נוסף, קראו את המאמר שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

הגדרת מודלי LLM לגישה לשרת ה-MCP של כלי הסוכן של Maps Experience

אחרי שמפעילים את השירות Maps Experience agent tools ויוצרים פרטי כניסה, אפשר להגדיר למודלי ה-LLM גישה לשרת ה-MCP. פועלים לפי ההוראות להגדרת MCP במודל ה-LLM ומשתמשים בכתובת ה-URL של שרת ה-MCP: https://mapstools.googleapis.com/mcp

מידע נוסף זמין במאמר הגדרת MCP באפליקציית AI.

הגדרת הכלים של סוכן Maps Experience באמצעות 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 (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

מתחילים לשאול שאלות שקשורות ל-Ask Maps באמצעות ה-CLI. לדוגמה, נסו להגיד "תמליץ לי על מסעדות בתל אביב". בתגובה, המודל אמור להפעיל את הכלי search_places.

הגדרת כלי הסוכן של Maps Experience באמצעות הערכה לפיתוח סוכנים (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"

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: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

שיתוף משוב

כדי לשלוח משוב על כלי הסוכנים של Maps Experience, אתם יכולים להשתמש בטפסים הבאים: