ابزارهای عامل Maps Experience (Maps Grounding Lite سابق) سرویسی از Google Maps Platform است که با Model Context Protocol (MCP) و پشتیبانی REST، برنامه‌های هوش مصنوعی شما را با داده‌های زمین‌مکانی معتبر از Google Maps زمینه‌سازی می‌کند. ابزارهای آن به مدل‌های زبانی بزرگ امکان می‌دهد به داده‌های مکان‌ها، آب‌وهوا، کیفیت هوا، گرده‌ها، و مسیرها دسترسی داشته باشند. ابزارهای دیگر نام مکان‌ها و نشانی‌های وب Google Maps را به شناسه مکان تبدیل می‌کنند. می‌توانید ابزارهای عامل Maps Experience را با فعال کردن سرور MCP آن در هر ابزاری که از سرورهای MCP پشتیبانی می‌کند امتحان کنید. همچنین می‌توانید هر ابزار را به‌عنوان یک روش REST فراخوانی کنید. برای جزئیات، فراخوانی ابزارها با REST را ببینید.
ابزارهای عامل Maps Experience یک محصول با دو شناسه کالا است: Essentials و Pro. همه درخواست‌ها تحت Essentials صورت‌حساب می‌شوند، مگراینکه از گزینه Pro استفاده کنند. گزینه‌های Pro جستجوی مکان‌ها درطول مسیر، جزئیات گسترده مکان، مکان‌های بیشتر در هر جستجو، توقف‌های میانی بیشتر در هر مسیر، مسیریابی با ترافیک زنده، پیش‌بینی گرده، و کیفیت هوای تاریخی را اضافه می‌کند. هر دو SKU از ابزارها، سرور MCP، روش‌های REST، و اطلاعات کاربری یکسانی استفاده می‌کنند. برای جزئیات، Essentials و Pro را ببینید.
ابزارها
ابزارهای عامل Maps Experience به مدل‌های زبانی بزرگ امکان می‌دهد به قابلیت‌های Google Maps زیر دسترسی داشته باشند:
- جستجوی مکان‌ها: درباره مکان‌ها اطلاعات درخواست کنید و خلاصه‌های تولیدشده با هوش مصنوعی دریافت کنید. پاسخ همچنین شامل شناسه‌های مکان، مختصات طول/عرض جغرافیایی، و پیوندهای Google Maps برای هر مکان در خلاصه است. می‌توانید از شناسه‌های جا و مختصات طول/عرض جغرافیایی با دیگر میاناهای برنامه‌سازی کاربردی پلاتفرم Google Maps برای نمایش جاها روی نقشه استفاده کنید. برای نمایش این مکان‌ها با «کیت میانای کاربر جاها» بدون هزینه اضافی، از نشان تجسم داده‌های عاملی (پیش‌نمایش) استفاده کنید. با Pro، می‌توانید جزئیات گسترده مکان، مانند اطلاعات آماری از مرورها، و حداکثر ۱۰ مکان در هر درخواست را درخواست کنید.
- جستجو درطول مسیر:
مکان‌های موجود درطول مسیر سفر را (که بااستفاده از
retrieval_tokenازcompute_routes،route_endpoints، یاencoded_polylineمشخص شده است) پیدا کنید و خلاصه تولیدشده با هوش مصنوعی، جزئیات مکان، فاصله انحراف از مسیر و مدت سفر، و نشان تجسم داده‌های عاملی (پیش‌نمایش) را دریافت کنید. هر درخواستsearch_along_routeتحت شناسه Pro صورت‌حساب می‌شود. - جستجوی آب‌وهوا: درخواست شرایط محیطی برای یک مکان، ازجمله آب‌وهوا (شرایط فعلی، سابقه ساعتی ۲۴ ساعته، و پیش‌بینی‌های ساعتی و روزانه تا ۱۰ روز) و کیفیت هوای فعلی یا پیش‌بینی‌شده تا ۴ روز. با Pro، می‌توانید پیش‌بینی گرده روزانه تا ۵ روز (با جزئیات گونه‌های گیاهی) و سابقه کیفیت هوا ساعتی تا ۳۰ روز را نیز درخواست کنید.
محاسبه مسیرها: درخواست مسیر بین مبدأ و مقصد، به‌صورت اختیاری ازطریق ایستگاه‌های میانی، و برگرداندن فاصله، مدت، و
retrievalTokenبرای مسیرهایDRIVEکه می‌توانید بهsearch_along_routeارسال کنید. با Pro، مسیرها می‌توانند شرایط ترافیک زنده را درنظر بگیرند و شامل توقف‌های میانی بیشتری باشند.حل‌وفصل نام‌ها و حل‌وفصل نشانی‌های وب Maps: نام‌های مکان، نشانی‌ها، و نشانی‌های وب Google Maps را به شناسه مکان تبدیل می‌کند. برای اطلاعات بیشتر، Resolution API را ببینید.
پس‌از فعال کردن سرور MCP، مدل‌های زبانی بزرگ می‌توانند ابزارهای آن را فراخوانی کنند تا اطلاعات زمینه‌ای برای این نوع داده‌ها دریافت کنند. مدل زبانی بزرگ می‌تواند از این اطلاعات برای بافت استفاده کند. بااین‌حال، پاسخ نهایی آن ممکن است دقیقاً حاوی اطلاعاتی نباشد که سرور MCP برگردانده است. درستی پاسخ تولیدشده را درستی‌سنجی کنید.
Essentials و Pro
Essentials و Pro دو شناسه محصول از یک محصول هستند، نه محصولات یا طرح‌های جداگانه. وقتی در درخواستی از گزینه Pro استفاده شود، هزینه آن تحت Pro صورت‌حساب می‌شود. همه درخواست‌های دیگر تحت Essentials صورت‌حساب می‌شود. گزینه‌های Pro فیلدهای معمولی در درخواست ابزار هستند، بنابراین مدل زبانی بزرگ می‌تواند از آن‌ها ازجانب شما استفاده کند. نماینده می‌تواند از هر دو SKU در یک مکالمه استفاده کند. برای مثال، نماینده ممکن است از Essentials برای پیدا کردن قهوه‌سراهای نزدیک یک مکان دیدنی استفاده کند. سپس ممکن است از Pro برای پاسخ دادن به سؤال بعدی درباره نوشیدنی‌های ویژه و صندلی‌های آن استفاده کند. سرور MCP، نقطه پایانی، یا اطلاعات اعتباری جداگانه‌ای برای Pro وجود ندارد.
مقایسه Essentials، Pro، و «پایه‌مندسازی با Google Maps»
پایه‌مندسازی با Google Maps محصولی جداگانه است. این ویژگی در مدل‌های Gemini در Gemini API، Google AI Studio، و Gemini Enterprise Agent Platform تعبیه شده است. مدل تصمیم می‌گیرد که چه زمانی از Google Maps پُرسمان کند و پاسخ‌های مستدل را با استناد برمی‌گرداند. وقتی روی Gemini می‌سازید و می‌خواهید مدل پایه‌مندسازی را مدیریت کند، «پایه‌مندسازی با Google Maps» را انتخاب کنید. ابزارهای عامل Maps Experience را برای مدل‌ها یا چارچوب‌های عامل دیگر، یا برای کنترل مستقیم هر فراخوانی ابزار انتخاب کنید.
جدول زیر شناسه Essentials، شناسه Pro، و «پایه‌مندسازی با Google Maps» را مقایسه می‌کند:
| ابزارهای عامل Maps Experience | پایه‌مندسازی با Google Maps | ||
|---|---|---|---|
| Essentials SKU (Maps Grounding Lite سابق) |
Pro SKU | ||
| نحوه صدور صورت‌حساب برای درخواست‌ها | هر درخواست ابزاری که از گزینه Pro استفاده نمی‌کند | هر درخواست search_along_route، یا هر درخواستی به
ابزار دیگری که از گزینه Pro استفاده می‌کند. به
What's billed under the Pro SKU مراجعه کنید. |
هر پُرسمان Google Maps یا پیام‌واره بااستناد، بسته به پلاتفرم و مدل |
| مدل‌ها و پلاتفرم‌ها | هر مدل یا چارچوب عاملی که از MCP پشتیبانی کند یا بتواند REST APIs را فراخوانی کند. یک مجموعه ابزار و اعتبارنامه یکسان برای هر دو شناسه واحد کالا | مدل‌های Gemini در Gemini API، Google AI Studio، و Gemini Enterprise Agent Platform | |
| آنچه ابزارها برمی‌گردانند | حقایق اصلی: جزئیات مکان برای حداکثر ۵ مکان در هر جستجو، مسافت و مدت‌زمان مسیر بدون ترافیک زنده، آب‌وهوای فعلی و پیش‌بینی‌ها (به‌علاوه سابقه آب‌وهوای ساعتی ۲۴ ساعته)، و کیفیت هوای فعلی یا پیش‌بینی‌شده | همه موارد موجود در Essentials، به‌علاوه مکان‌های موجود در مسیر با زمان و مسافت انحراف، جزئیات گسترده مکان (مانند اطلاعات آماری از مرورها)، حداکثر ۱۰ مکان در هر جستجو، مسیرهای دارای ترافیک زنده، حداکثر ۲۵ نقطه‌مسیر میانی، پیش‌بینی گرده، و حداکثر ۳۰ روز کیفیت هوای تاریخی | جزئیات جاها و اطلاعات آماری برگرفته از مرورها، و اطلاعات مسیر با ترافیک زنده |
| درخواست‌های نمونه | پرسش‌های واقعی و لجستیکی: پیدا کردن فروشگاه‌ها یا کسب‌وکارها، ساعت کاری، نشانی‌ها، برآورد فاصله یا مدت سفر، آب‌وهوای کنونی، پیش‌بینی آب‌وهوای ۱۰ روزه، و پیش‌بینی کیفیت هوای کنونی یا ۴ روزه | سؤالات ذهنی، کلی، یا تخصصی: مکان‌های موجود در مسیر، جو، غذاهای ویژه، نکته‌های بازدیدکنندگان، مقایسه ۶ تا ۱۰ مکان، مدت سفر در ترافیک فعلی، پیش‌بینی گرده و آلرژی، و سابقه کیفیت هوا در ۳۰ روز گذشته | جستجوی مکالمه‌ای، برنامه‌ریزی سفر، و کاوش محلی در Gemini |
| مصورسازی‌های کیت میانای کاربر «جاها» | بدون هزینه اضافی با نشان‌واره تجسم داده‌های عاملی (پیش‌نمایش) ارائه می‌شود | صورت‌حساب جداگانه صادر می‌شود | |
| استفاده ماهانه بدون هزینه | ۱۰٬۰۰۰ درخواست | ۵٬۰۰۰ درخواست | به پلاتفرم و مدل بستگی دارد. برای مثال، در Gemini API، مدل‌های Gemini 3 و جدیدتر شامل ۵٬۰۰۰ پُرسمان جستجو در ماه بدون هزینه هستند. پس‌از آن، هزینه پرسمان‌های جستجو ۱۴ دلار به‌ازای هر ۱۰۰۰ پرسمان است. |
| قیمت پرداخت به اندازه استفاده | ۷ دلار به‌ازای هر ۱۰۰۰ درخواست، با تخفیف‌های حجمی | ۱۴٫۰۰ دلار برای هر ۱٬۰۰۰ درخواست، با تخفیف‌های حجمی | |
| برای ذخیره کردن، مشترک شوید | در طرح‌های Essentials و Pro گنجانده شده است | در طرح Pro گنجانده شده است | دردسترس نیست |
| شروع کنید | یک راه‌اندازی برای هر دو SKU: پیکربندی LLM برای استفاده از سرور MCP یا فراخوانی ابزارها با REST را ببینید. | Gemini API یا Agent Platform | |
این گزینه‌ها با هر دو SKU به یک شکل کار می‌کنند: حالت‌های سفر، زمان‌های حرکت و ورود، مسیرهای جایگزین، چندخطی‌های مسیر، جستجوهای آب‌وهوا، جستجوهای کیفیت هوای فعلی و پیش‌بینی‌شده (ازجمله غلظت آلاینده‌ها و مقیاس‌های AQI محلی)، سیستم‌های واحد آب‌وهوا، و Resolution API. آن‌ها تغییری در اینکه درخواست تحت کدام SKU صورت‌حساب می‌شود ایجاد نمی‌کنند.
آنچه تحت SKU حرفه‌ای صورت‌حساب می‌شود
جدول زیر خلاصه می‌کند که کدام قابلیت‌ها در Essentials گنجانده شده‌اند و کدام قابلیت‌ها به Pro SKU نیاز دارند:
| ابزار | قابلیت | Essentials | Pro |
|---|---|---|---|
| جستجوی مکان‌ها | مکان‌ها در هر درخواست | حداکثر تا ۵ | ۶ تا ۱۰ (page_size از ۶ تا ۱۰) |
| جزئیات گسترده مکان در خلاصه‌های جستجو (اطلاعات آماری از مرورها، نکات برجسته منو، جو، میزان شلوغی مکان، نکاتی برای بازدیدکنندگان، و مسافت یا زمان سفر برای پُرسمان‌های مجاورتی) | دردسترس نیست | دردسترس با include_extended_details |
|
| جستجو در طول مسیر | مکان‌های موجود در مسیر، فاصله انحراف و زمان سفر، و جزئیات اختیاری گسترده مکان یا زمان‌های انحراف با آگاهی از ترافیک | دردسترس نیست | همه درخواست‌ها |
| محاسبه کردن مسیرها | اولویت مسیریابی | ترافیک زنده را درنظر نمی‌گیرد | ترافیک زنده یا داده‌های حمل‌ونقل عمومی هم‌زمان برای مسیرهای حمل‌ونقل عمومی را با ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL درنظر می‌گیرد |
| نقاط‌مسیر میانی در هر مسیر | حداکثر تا ۱۰ | ۱۱ تا ۲۵ (بیشتر از ۱۰ intermediate_waypoints) |
|
| جستجوی آب‌وهوا | آب‌وهوا | آب‌وهوای فعلی، پیش‌بینی‌های ساعتی و روزانه (تا ۱۰ روز)، و
سابقه ساعتی تا ۲۴ ساعت (WEATHER در
capabilities، یا درخواست‌های قدیمی که
capabilities، weather_options،
air_quality_options، و language_code را حذف می‌کنند) |
گزینه‌های Pro وجود ندارد (همه داده‌های WEATHER در
Essentials گنجانده شده است) |
| کیفیت هوا | شرایط فعلی، نتایج ساعتی کل روز امروز، و پیش‌بینی‌های ساعتی تا ۴ روز (AIR_QUALITY در capabilities) |
کیفیت هوای گذشته تا ۳۰ روز قبل
(AIR_QUALITY در capabilities با
date قبل‌از امروز یا hour گذشته در
منطقه زمانی مکان)، وقتی در پاسخ برگردانده می‌شود |
|
| گرده | دردسترس نیست | پیش‌بینی‌های روزانه گرده تا ۵ روز و جزئیات گونه‌های گیاهی
(POLLEN در capabilities)، وقتی در
پاسخ برگردانده شود |
|
| Resolution API | گزینه‌های Pro وجود ندارد. همه درخواست‌ها تحت شناسه محصول Places API Text Search Essentials (IDs Only) بدون هزینه صورت‌حساب می‌شوند. | ||
برای گزینه‌های درخواست که هر قابلیت را فعال می‌کند، به جستجوی مکان‌ها، جستجو درطول مسیر، محاسبه مسیرها، و جستجوی آب‌وهوا مراجعه کنید.
کنترل استفاده از Pro
گزینه‌های Pro به‌طور پیش‌فرض در search_places، compute_routes، و
lookup_weather خاموش است. وقتی درخواست کاربر به آن‌ها نیاز داشته باشد و شرح ابزار یا دستورالعمل‌های شما اجازه دهد، مدل زبانی بزرگ آن‌ها را تنظیم می‌کند یا search_along_route را فراخوانی می‌کند.
توضیحات ابزار به مدل می‌گوید کدام گزینه‌ها هزینه بیشتری دارند و چه زمانی باید از آن‌ها استفاده کرد: page_size بالای ۵، جزئیات مکان گسترده، بیش‌از ۱۰ نقطه‌مسیر میانی، مسیریابی با آگاهی از ترافیک، و search_along_route. اگر ابزارها را با REST فراخوانی کنید، کد شما هر گزینه را تنظیم می‌کند. برای مدیریت هزینه‌ها:
- به مدل بگویید چه زمانی گزینه‌های Pro مناسب هستند. برای مثال: «
include_extended_detailsرا فقط وقتی تنظیم کن که کاربر درباره مرورها، منوها، یا جو سؤال می‌کند.» یا: «فقط وقتی کاربر مدت سفر فعلی را می‌پرسد، ازROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALاستفاده کن.» یا: «search_along_routeرا فقط وقتی کاربر مکان‌های موجود در مسیر را درخواست می‌کند فراخوانی کن.» یا: «POLLEN، یاAIR_QUALITYرا باdateیاhourگذشته اضافه کنید، فقط زمانی که کاربر درباره گرده، آلرژی، یا سابقه کیفیت هوا می‌پرسد.» - برای نگه داشتن نماینده در SKU Essentials، به مدل دستور دهید که هرگز
search_along_routeرا فراخوانی نکند یا از گزینه Pro استفاده نکند. گزینه‌های Pro عبارت‌اند ازinclude_extended_details،page_sizeبالای ۵،ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، بیش‌از ۱۰ نقطه‌مسیر میانی،POLLENدرcapabilities، وdateیاhourگذشته باAIR_QUALITYدرcapabilities. اگر کارخواه MCP شما می‌تواند ابزارها یا آرگومان‌های ابزار را محدود کند، می‌توانیدsearch_along_routeو آن مقادیر آرگومان را در پیکربندی ابزار آن مسدود کنید. - شناسه محصول Maps Grounding Pro را در گزارش‌های صورت‌حساب خود پایش کنید و هشدارهای بودجه را تنظیم کنید.
Resolution API
ابزارهای عامل Maps Experience، Resolution API را ارائه می‌دهد. این میانای برنامه‌سازی کاربردی نوشتار مکان با قالب آزاد و نشانی‌های وب را به شناسه‌های مکان ساختاریافته Google Maps تبدیل می‌کند. Resolution API به‌صورت روش‌های REST و ابزارهایی در سرور MCP دردسترس است:
- Resolve names (REST، MCP): دسته‌ای از نام‌ها یا نشانی‌های مکان را به نهادهای مکان خاص در Google Maps تبدیل می‌کند. این ابزار کمک می‌کند پُرسمان‌های ساختارنیافته کاربر به شناسه‌های مکان پایدار تبدیل شود.
- حل کردن نشانی‌های وب Maps (REST، MCP): حل کردن دسته‌ای از نشانی‌های وب Google Maps به نهادهای مکان خاص. قالب‌های پشتیبانی‌شده شامل نشانی‌های وب مکان استاندارد و نشانی‌های وب کوتاه می‌شود.
می‌توانید از شناسه‌های مکان برگردانده‌شده با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform استفاده کنید. هر پاسخ همچنین شامل پیوندی است که مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره می‌کند.
برای اطلاعات بیشتر، Maps Tools Resolution API را ببینید.
برنامه نمونه را امتحان کنید (در برگه جدیدی باز می‌شود)
صورت‌حساب و سهمیه‌ها
نحوه صدور صورت‌حساب برای شما
با مدل قیمت‌گذاری پرداخت به اندازه استفاده «پلاتفرم Google Maps»، استفاده از ابزارهای عامل Maps Experience برای هر درخواست محاسبه می‌شود. هر درخواست نشان‌دهنده یک رویداد صورت‌حساب است. استفاده برای هر واحد نگهداری موجودی محصول ردیابی می‌شود. صورت‌حساب شما علاوه‌بر کل هزینه‌ها، یک مورد سطری برای هر SKU نشان می‌دهد. برای اطلاعات بیشتر، نمای کلی گزارش‌دهی را ببینید.
هر درخواست «جستجوی مکان‌ها»، «جستجو درطول مسیر»، «محاسبه مسیرها»، یا «جستجوی آب‌وهوا»
ازطریق سرور MCP یا با REST، تحت یک SKU صورت‌حساب می‌شود:
Maps Grounding Essentials
یا
Maps Grounding Pro.
هر درخواست search_along_route و هر درخواستی که از گزینه Pro استفاده می‌کند
تحت شناسه Pro صورت‌حساب می‌شود. درخواست هرگز تحت هر دو SKU صورت‌حساب نمی‌شود و
تعداد گزینه‌های Pro در درخواست، هزینه را تغییر نمی‌دهد. برای
قابلیت‌ها و گزینه‌هایی که SKU را برای هر ابزار تعیین می‌کنند، به
آنچه تحت SKU حرفه‌ای صورت‌حساب می‌شود مراجعه کنید.
درخواست‌های مبانی زمینه‌سازی Maps پس‌از ۱۰٬۰۰۰ درخواست اول در هر ماه، به‌ازای هر ۱٬۰۰۰ درخواست ۷٫۰۰ دلار صورت‌حساب می‌شود. Maps Grounding Pro درخواست‌ها با نرخ ۱۴٫۰۰ دلار به‌ازای هر ۱٬۰۰۰ درخواست پس‌از ۵٬۰۰۰ درخواست اول در هر ماه صورت‌حساب می‌شود. هر دو SKU برای استفاده ماهانه بیشتر تخفیف حجمی دارند.
برای جزئیات قیمت‌گذاری، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.
درخواست‌های Resolution API (ResolveNames و ResolveMapsUrls) تحت شناسه محصول
Places API Text Search Essentials (IDs Only)
بدون هزینه صورت‌حساب می‌شوند.
اگر مکان‌های پاسخ search_places یا search_along_route را با «کیت میانای کاربر جاها» نمایش می‌دهید، می‌توانید از نشان تجسم داده‌های عاملی (پیش‌نمایش) استفاده کنید تا برای آن درخواست‌های «کیت میانای کاربر جاها» صورت‌حساب صادر نشود.
استفاده از SKU «اصلی» در طرح‌های «اصلی» و «حرفه‌ای» مشترک شوید تا صرفه‌جویی کنید گنجانده شده است. استفاده از SKU «حرفه‌ای» در طرح «حرفه‌ای» گنجانده شده است.
سهمیه‌ها
سهمیه‌های زیر برای ابزارها و میاناهای برنامه‌سازی کاربردی ارائه‌شده توسط ابزارهای عامل Maps Experience اعمال می‌شود:
- جستجوی مکان‌ها: ۳۰۰ پُرسمان در دقیقه برای هر پروژه.
- جستجو درطول مسیر: ۳۰۰ پُرسمان در دقیقه برای هر پروژه.
- جستجوی آب‌وهوا: ۳۰۰ پُرسمان در دقیقه برای هر پروژه.
- محاسبه مسیرها: ۳۰۰ پُرسمان در دقیقه برای هر پروژه.
- حل‌وفصل نام‌ها: ۶۰۰ پُرسمان در دقیقه برای هر پروژه.
- Resolve Maps URLs: ۶۰۰ پرسمان در دقیقه برای هر پروژه.
سهمیه‌ها برای هر ابزار محاسبه می‌شود و بین SKUهای Essentials و Pro مشترک است. درخواست Pro همان سهمیه‌ای را مصرف می‌کند که درخواست Essentials برای همان ابزار مصرف می‌کند.
هر درخواست Resolution API به‌عنوان یک پُرسمان محسوب می‌شود، صرف‌نظر از اینکه چند مورد در آن وجود داشته باشد.
خط‌مشی‌ها و شرایط خدمات
ابزارهای عامل Maps Experience تابع شرایط خدمات پلاتفرم Google Maps، ازجمله شرایط خاص سرویس است. این بخش الزامات استفاده اضافی را برای ابزارهای عامل «تجربه Maps» شرح می‌دهد، ازجمله مدل‌های زبانی بزرگ سازگار و ذکر منبع. این الزامات برای همه نتایج اعمال می‌شود، صرف‌نظر از اینکه درخواست تحت کدام SKU صورت‌حساب می‌شود.
الزامات مدل‌های زبانی بزرگ سازگار
فقط می‌توانید از ابزارهای عامل Maps Experience با مدل زبانی بزرگی استفاده کنید که با «شرایط خدمات پلاتفرم Google Maps» مطابقت داشته باشد.
برای مثال، شما مسئول هستید که مطمئن شوید «محتوای Google Maps» توسط مدل زبانی بزرگی که برای استفاده انتخاب می‌کنید ذخیره یا در حافظه نهان ذخیره نمی‌شود یا برای بهبود آن استفاده نمی‌شود. قبل‌از استفاده از ابزارهای عامل Maps Experience، باید «شرایط خدمات» هر مدلی را که قصد دارید با ابزارهای عامل Maps Experience استفاده کنید مرور کنید. نباید از ابزارهای عامل «تجربه Maps» با مدل‌هایی استفاده کنید که از داده‌های ورودی به مدل برای آموزش یا بهبود مدل استفاده می‌کنند. مسئولیت اطمینان از اینکه استفاده شما از مدل کاملاً با محدودیت‌های «محتوای Google Maps» در «شرایط خدمات Google Maps Platform»، ازجمله شرایط خاص سرویس، مطابقت دارد برعهده شما است.
الزامات ذکر منبع برای منابع Google Maps
هر پاسخ ابزار از ابزارهای عامل Maps Experience شامل منابع است. وقتی نتایج ابزارهای عامل Maps Experience را ارائه می‌دهید، باید منابع Google Maps مربوطه را اضافه کنید و شرایط زیر را برآورده کنید:
- منابع Google Maps باید بلافاصله پس‌از محتوای تولیدشده‌ای که منابع از آن پشتیبانی می‌کنند، آورده شود. به این محتوای تولیدشده خروجی مستند نیز گفته می‌شود.
- منابع Google Maps باید در یک تعامل کاربر قابل‌مشاهده باشد.
منابع ابزارهای «جستجوی مکان‌ها» و «جستجو درطول مسیر»
فیلد search_places ابزار places و فیلد search_along_route ابزار results[].place منابعی را ارائه می‌دهند که از summary پشتیبانی می‌کنند. برای هر
مکان، فراداده زیر برگردانده می‌شود:
place(نام منبع)idlocationgoogleMapsLinksattribution
برای هر مکان، باید پیش‌نمایش پیوندی تولید کنید که این الزامات را برآورده کند:
- هر منبع را به Google Maps نسبت دهید و دستورالعمل‌های ارجاع نوشتاری ابزارهای عامل Maps Experience را دنبال کنید.
- بااستفاده از
googleMapsLinks.placeUrlاز پاسخ، به منبع پیوند دهید.
این الزامات برای خلاصه‌هایی که شامل جزئیات گسترده مکان از Pro هستند، مانند اطلاعات برگرفته از مرورها، نیز اعمال می‌شوند. summary هر مکان را با یک نمایه صفرپایه، مانند [0]، ذکر می‌کند که به یک ورودی در places یا results نگاشت می‌شود.
هر مکان همچنین شامل googleMapsLinks.reviewsUrl است که به مرورهای آن مکان در Google Maps پیوند می‌دهد. کاربران می‌توانند آن را دنبال کنند تا مرورهای پشت یک
اطلاعات آماری را ببینند.
میاناهای صوتی-محور
اگر برنامه‌تان نتایج ابزارهای عامل Maps Experience را به‌صورت صوتی ارائه می‌دهد، باید الزامات مربوط به میاناهای صوتی را نیز رعایت کنید. به‌طور خلاصه:
- منبع‌یابی: منابع Google Maps را در یک میانای کاربری همراه نمایش دهید که سابقه تاریخی کلمه‌به‌کلمه مکالمه صوتی را نشان می‌دهد.
- شفاف‌سازی فعال: در زمان تعامل، به کاربران بگویید که محتوای تولیدشده با هوش مصنوعی ممکن است حاوی اطلاعاتی از Google Maps باشد. همچنین به آن‌ها بگویید که منابع دقیق در واسط کاربر همراه دردسترس است. می‌توانید این کار را روی صفحه‌نمایش یا با صدا انجام دهید.
- شفاف‌سازی دائمی: توضیحی دائمی، مثلاً در منو تنظیمات گفتار، ارائه دهید که محتوای تولیدشده با هوش مصنوعی ممکن است شامل محتوای Google Maps باشد.
- پرسش‌های کاربر: به سؤالات کاربران درباره منبع محتوا به‌طور دقیق پاسخ دهید و آن‌ها را برای جزئیات به میانای کاربری همراه هدایت کنید.
پیکربندی کردن مدل‌های زبانی بزرگ برای استفاده از سرور MCP
برای استفاده از ابزارهای عامل Maps Experience، به پروژه Google Cloud با سرویس API ابزارهای عامل Maps Experience فعال‌شده نیاز دارید. همچنین به کلید میانای API یا شناسه کارخواه OAuth نیاز دارید. سپس می‌توانید مدل‌های زبانی بزرگ را برای دسترسی به سرور MCP پیکربندی کنید. سرور MCP از انتقال Streamable HTTP استفاده می‌کند.
ابزارهای عامل Maps Experience را در پروژه Google Cloud خود فعال کنید
برای فعال کردن میانای برنامه‌سازی کاربردی در پروژه:
- در کنسول Google Cloud، پروژه‌ای را که می‌خواهید برای ابزارهای عامل Maps Experience استفاده کنید انتخاب کنید.
- صورت‌حساب را برای پروژه در کنسول Google Cloud فعال کنید.
- ابزارهای عامل Maps Experience را در کتابخانه میانای برنامه‌سازی کاربردی کنسول Google Cloud فعال کنید.
اصالت‌سنجی بااستفاده از کلید میانای API
می‌توانید از کلید میانای برنامه‌سازی کاربردی موجود با ابزارهای عامل Maps Experience استفاده کنید یا کلید جدیدی ایجاد کنید. در هر دو حالت، سرویس API ابزارهای عامل Maps Experience را هم در پروژه Google Cloud و هم در کلید فعال کنید.
برای اصالت‌سنجی بااستفاده از کلید میانای برنامه‌سازی کاربردی (API):
- با دنبال کردن مراحل شروع به کار با Google Maps Platform، کلید میانای برنامه‌سازی کاربردی ایجاد یا پیکربندی کنید.
- کلید را بااستفاده از سرصفحه
X-Goog-Api-Keyبه سرور MCP ارسال کنید. باید این را به‌عنوان سرایند HTTP سفارشی در پیکربندی ابزار MCP مدل زبانی بزرگ مشخص کنید.
اصالت‌سنجی بااستفاده از OAuth
می‌توانید با ایجاد اعتبارنامه‌های OAuth و ارسال آن‌ها به میزبان MCP یا برنامه سرور MCP، بااستفاده از OAuth اصالت‌سنجی کنید.
برای اصالت‌سنجی بااستفاده از OAuth:
- در کنسول Google Cloud، پروژه‌ای را که می‌خواهید برای ابزارهای عامل Maps Experience استفاده کنید انتخاب کنید.
- در منو میانای برنامه‌سازی کاربردی و سرویس‌ها، اعتبارنامه‌ها را انتخاب کنید.
- در منو بالایی، ایجاد اطلاعات کاربری > شناسه کارخواه OAuth را انتخاب کنید.
- اگر پروژه صفحه رضایت پیکربندی‌شده ندارد، روی پیکربندی صفحه رضایت کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید.
- در بخش سنجه‌ها، روی ایجاد کارخواه OAuth کلیک کنید.
- در صفحه ایجاد شناسه کارخواه OAuth، نوع برنامه را انتخاب کنید و نامی برای شناسه کارخواه وارد کنید.
- جزئیات اضافی مربوط به نوع درخواستتان را مشخص کنید. برای مثال، اگر درحال ایجاد برنامه وب هستید، URIهای مجاز را برای درخواست‌های مرورگر و سرور اضافه کنید.
- وقتی کارخواهتان ایجاد شد، شناسه کارخواه و رمز را ذخیره کنید.
- هنگام پیکربندی میزبان MCP یا برنامه سرور MCP، شناسه کارخواه OAuth و رمز را ارسال کنید. همچنین باید حوزه زیر را درخواست کنید:
https://www.googleapis.com/auth/maps-platform.mapstools.
برای اطلاعات بیشتر، استفاده از OAuth 2.0 برای دسترسی به Google APIs را ببینید.
پیکربندی کردن مدل‌های زبانی بزرگ برای دسترسی به سرور MCP ابزارهای عامل Maps Experience
پس‌از فعال کردن سرویس ابزارهای عامل Maps Experience و ایجاد اعتبارنامه، می‌توانید مدل‌های زبانی بزرگ را برای دسترسی به سرور MCP پیکربندی کنید. از مستندات پیکربندی MCP مدل زبانی بزرگ خود پیروی کنید و از نشانی وب سرور MCP زیر استفاده کنید: https://mapstools.googleapis.com/mcp
برای اطلاعات بیشتر، پیکربندی MCP در برنامه هوش مصنوعی را ببینید.
پیکربندی کردن ابزارهای عامل Maps Experience با Gemini CLI
این بخش نمونه‌ای از نحوه پیکربندی سرور MCP ابزارهای عامل Maps Experience بااستفاده از Gemini CLI ارائه می‌دهد. برای جزئیات بیشتر، سرورهای MCP با Gemini CLI را ببینید.
پس‌از نصب Gemini CLI، برای پیکربندی سرور MCP،
gemini mcp addرا اجرا کنید: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با CLI شروع به پرسیدن سؤالات مربوط به Maps کنید. برای مثال، «چند رستوران در Mountain View توصیه کن» را امتحان کنید که ابزار
search_placesرا ازطرف شما فراخوانی می‌کند.
پیکربندی ابزارهای عامل Maps Experience با Agent Development Kit (ADK)
این بخش نحوه پیکربندی سرور MCP را با Agent Development Kit (ADK) در Python، Java، یا TypeScript نشان می‌دهد.
Python
می‌توانید پیاده‌سازی کامل این نمونه را در GitHub در مخزن adk-samples پیدا کنید.
مرحله ۱: تعریف کردن «نماینده» با McpToolset برای ابزارهای نماینده Maps Experience
فایل agent.py را اصلاح کنید. YOUR_GOOGLE_MAPS_API_KEY را با کلید میانای برنامه‌سازی کاربردی واقعی‌تان جایگزین کنید.
# ./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" } ) ) ] )
مرحله ۲: مطمئن شوید __init__.py وجود دارد
مطمئن شوید که __init__.py در همان دایرکتوری
agent.py شما باشد:
from . import agent
مرحله ۳: اجرا کردن adk web و تعامل کردن
- تنظیم متغیر محیطی:
کلید Google Maps API خود را به‌عنوان متغیر محیطی در پایانه تنظیم کنید:export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
- اجرای
adk web:
فرمان زیر را برای شروع میانای وب ADK اجرا کنید:adk web
- تعامل در میانای کاربر:
travel_planner_agentرا انتخاب کنید؛- پیام‌واره‌هایی مثل این را امتحان کنید:
- «فردا در سان‌فرانسیسکو خواهم بود. آب‌وهوا چطور است؟»
- «قهوه‌سراهای نزدیک پارک ملت را پیدا کن.»
- «مسیرهای GooglePlex به SFO را دریافت کن.»
جاوا
عاملی را تعریف کنید که 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 Experience به‌عنوان روش 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 تحت همان SKUها صورت‌حساب می‌شوند، از همان قوانین برای گزینه‌های Pro پیروی می‌کنند، و در همان سهمیه‌های فراخوانی‌های ابزار MCP محاسبه می‌شوند.
برای اصالت‌سنجی، از همان پروژه Google Cloud و اعتبارنامه‌های سرور MCP استفاده کنید. برای مراحل راه‌اندازی، به
پیکربندی مدل‌های زبانی بزرگ برای استفاده از سرور MCP مراجعه کنید.
کلید میانای برنامه‌سازی کاربردی را در سرصفحه X-Goog-Api-Key ارسال کنید، یا کد دسترسی OAuth را با دامنه https://www.googleapis.com/auth/maps-platform.mapstools در سرصفحه Authorization ارسال کنید.
مثال زیر روش 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، از فرم‌های زیر استفاده کنید: