ابزارهای عامل Maps Experience (با نام قبلی Maps Grounding Lite) سرویسی از Google Maps Platform با پشتیبانی از «پروتکل زمینه مدل» (MCP) است که برنامه‌های هوش مصنوعی شما را با داده‌های زمین‌مکانی معتبر از Google Maps زمینه‌سازی می‌کند. سرور MCP ابزارهایی ارائه می‌دهد که به مدل‌های زبانی بزرگ امکان می‌دهد به داده‌های مکان‌ها، آب‌وهوا، و مسیرها دسترسی داشته باشند. ابزارهای دیگر نام مکان‌ها و نشانی‌های وب Google Maps را به «شناسه مکان» تبدیل می‌کنند. می‌توانید با فعال کردن ابزارهای عامل «تجربه Maps» در هر ابزاری که از سرورهای MCP پشتیبانی می‌کند، آن‌ها را امتحان کنید.
ابزارهای عامل Maps Experience یک محصول با دو شناسه کالا است: Essentials و Pro. همه درخواست‌ها تحت Essentials صورت‌حساب می‌شوند، مگراینکه از گزینه Pro استفاده کنند. گزینه‌های Pro جزئیات گسترده مکان، مکان‌های بیشتر در هر جستجو، ایستگاه‌های میانی بیشتر در هر مسیر، و مسیریابی با ترافیک زنده را اضافه می‌کند. درطول «دسترسی عمومی محدود»، گزینه‌های Pro فقط برای پروژه‌های موجود در فهرست مجاز Pro دردسترس است. هر دو SKU از سرور MCP، ابزارها، و اعتبارنامه‌های یکسانی استفاده می‌کنند. برای جزئیات، Essentials و Pro را ببینید.
ابزارها
ابزارهای عامل «تجربه Maps» به مدل‌های زبانی بزرگ اجازه می‌دهد به قابلیت‌های Google Maps زیر دسترسی داشته باشند:
- جستجوی مکان‌ها: درباره مکان‌ها اطلاعات درخواست کنید و خلاصه‌های تولیدشده با هوش مصنوعی دریافت کنید. پاسخ همچنین شامل «شناسه جا»، مختصات، و پیوندهای Google Maps برای هر مکان در خلاصه است. می‌توانید از «شناسه‌های مکان» و مختصات با دیگر میاناهای برنامه‌سازی کاربردی «پلاتفرم Google Maps» برای نمایش مکان‌ها روی نقشه استفاده کنید. با Pro، می‌توانید جزئیات گسترده مکان، مثل اطلاعات آماری برگرفته از مرورها، و حداکثر ۱۰ مکان در هر درخواست را درخواست کنید.
- جستجوی آب‌وهوا: درخواست اطلاعات درباره آب‌وهوا و برگرداندن شرایط فعلی، پیش‌بینی‌های ساعتی، و پیش‌بینی‌های روزانه.
محاسبه مسیرها: درخواست مسیر بین مبدأ و مقصد، به‌صورت اختیاری ازطریق ایستگاه‌های میانی، و برگرداندن فاصله و مدت‌زمان مسیر. با Pro، مسیرها می‌توانند شرایط ترافیک زنده را درنظر بگیرند و شامل توقف‌های میانی بیشتری باشند.
حل‌وفصل نام‌ها و حل‌وفصل نشانی‌های وب Maps: نام‌های مکان، نشانی‌ها، و نشانی‌های وب Google Maps را به «شناسه‌های مکان» تبدیل کنید. برای اطلاعات بیشتر، Resolution API را ببینید.
پس‌از فعال کردن سرور MCP، مدل‌های زبانی بزرگ می‌توانند ابزارهای آن را فراخوانی کنند تا اطلاعات زمینه‌ای برای این نوع داده‌ها دریافت کنند. مدل زبانی بزرگ می‌تواند از این اطلاعات برای بافت استفاده کند. بااین‌حال، پاسخ نهایی آن ممکن است حاوی اطلاعات دقیقی که سرور MCP برگردانده است نباشد. باید صحت پاسخ تولیدشده را بررسی کنید.
Essentials و Pro
Essentials و Pro دو SKU از یک محصول هستند، نه محصولات یا طرح‌های جداگانه. وقتی در درخواستی از گزینه 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 را برای دیگر مدل‌ها یا چارچوب‌های نماینده، یا برای کنترل مستقیم هر فراخوانی ابزار انتخاب کنید.
| ابزارهای عامل تجربه Maps | پایه‌مندسازی با Google Maps | ||
|---|---|---|---|
| Essentials SKU (Maps Grounding Lite سابق) |
واحد نگهداری موجودی Pro | ||
| نحوه صدور صورت‌حساب برای درخواست‌ها | هر درخواست ابزاری که از گزینه Pro استفاده نمی‌کند | هر درخواست ابزاری که از گزینه Pro استفاده می‌کند:
include_extended_details،
page_size بالاتر از ۵،
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، یا بیش‌از ۱۰
نقطه‌مسیر میانی |
هر پُرسمان Google Maps یا پیام‌واره بااستناد، بسته به پلاتفرم و مدل |
| مدل‌ها و پلاتفرم‌ها | هر مدل یا چارچوب عاملی که از MCP پشتیبانی کند. یک سرور MCP، یک مجموعه ابزار، و اعتبارنامه‌های یکسان برای هر دو SKU | مدل‌های Gemini در Gemini API، Google AI Studio، و Gemini Enterprise Agent Platform | |
| آنچه ابزارها برمی‌گردانند | حقایق اصلی: جزئیات مکان برای حداکثر ۵ مکان در هر جستجو، مسافت و مدت‌زمان مسیر بدون ترافیک زنده، و آب‌وهوای فعلی و پیش‌بینی‌ها | همه موارد موجود در Essentials، به‌علاوه جزئیات گسترده مکان (مثل اطلاعات آماری برگرفته از مرورها)، حداکثر ۱۰ مکان در هر جستجو، مسیرهای دارای ترافیک زنده، و حداکثر ۲۵ نقطه‌مسیر میانی | جزئیات جاها و اطلاعات آماری برگرفته از مرورها، و اطلاعات مسیر با ترافیک زنده |
| درخواست‌های نمونه | سؤالات واقعی و لجستیکی: پیدا کردن فروشگاه‌ها یا کسب‌وکارها، ساعات کاری، نشانی‌ها، و تخمین مسافت یا زمان سفر | سؤالات ذهنی یا کلی: جو، غذاهای ویژه، نکات بازدیدکننده، مقایسه ۶ تا ۱۰ مکان، و زمان سفر در ترافیک فعلی | جستجوی مکالمه‌ای، برنامه‌ریزی سفر، و کاوش محلی در Gemini |
| مصورسازی‌های کیت میانای کاربر «جاها» | بدون هزینه اضافی با کد دیداری‌سازی داده‌های عاملی (پیش‌نمایش) ارائه می‌شود | صورت‌حساب جداگانه صادر می‌شود | |
| استفاده رایگان در ماه | ۱۰٬۰۰۰ درخواست | ۵٬۰۰۰ درخواست | به پلاتفرم و مدل بستگی دارد. برای مثال، در Gemini API، مدل‌های Gemini 3 و جدیدتر شامل ۵٬۰۰۰ پرسمان جستجوی رایگان در ماه هستند. پس‌از آن، هزینه پرسمان‌های جستجو ۱۴ دلار به‌ازای هر ۱۰۰۰ پرسمان است. |
| قیمت پرداخت به اندازه استفاده | ۷ دلار به‌ازای هر ۱۰۰۰ درخواست، با تخفیف حجمی | ۱۴ دلار به‌ازای هر ۱۰۰۰ درخواست. برای قیمت‌گذاری انبوه، با بخش فروش تماس بگیرید. | |
| برای ذخیره کردن، مشترک شوید | در طرح‌های Essentials و Pro گنجانده شده است | لحاظ‌نشده | دردسترس نیست |
| شروع کنید | یک راه‌اندازی برای هر دو SKU: پیکربندی LLM برای استفاده از سرور MCP را ببینید. درطول «دسترسی عمومی محدود»، گزینه‌های Pro به پروژه‌ای در فهرست مجاز Pro نیز نیاز دارند. | Gemini API یا Agent Platform | |
این گزینه‌ها با هر دو SKU به یک شکل کار می‌کنند: حالت‌های سفر، زمان‌های حرکت و ورود، مسیرهای جایگزین، چندخطی‌های مسیر، جستجوهای آب‌وهوا، و Resolution API. این تنظیمات شناسه کالای درخواست را که تحت آن صورت‌حساب صادر می‌شود تغییر نمی‌دهند.
آنچه تحت SKU حرفه‌ای صورت‌حساب می‌شود
| ابزار | قابلیت | Essentials | Pro |
|---|---|---|---|
| جستجوی مکان‌ها | مکان‌ها در هر درخواست | حداکثر تا ۵ | ۶ تا ۱۰ (page_size از ۶ تا ۱۰) |
| جزئیات گسترده مکان در خلاصه‌های جستجو (اطلاعات آماری از مرورها، نکات برجسته منو، جو، میزان شلوغی مکان، نکاتی برای بازدیدکنندگان، و مسافت یا مدت سفر برای پُرسمان‌های مجاورت) | دردسترس نیست | دردسترس با include_extended_details |
|
| محاسبه کردن مسیرها | اولویت مسیریابی | ترافیک زنده را درنظر نمی‌گیرد | ترافیک زنده یا داده‌های حمل‌ونقل عمومی هم‌زمان برای مسیرهای حمل‌ونقل عمومی را با ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL درنظر می‌گیرد |
| نقطه‌مسیرهای میانی در هر مسیر | حداکثر تا ۱۰ | ۱۱ تا ۲۵ (بیشتر از ۱۰ intermediate_waypoints) |
|
| Lookup weather و Resolution API | گزینه‌های Pro وجود ندارد. همه درخواست‌ها تحت شناسه محصول Essentials صورت‌حساب می‌شوند. | ||
برای گزینه‌های درخواست که هر قابلیت را فعال می‌کند، جستجوی مکان‌ها و محاسبه مسیرها را ببینید.
گزینه‌های Pro درطول «دسترسی عمومی محدودشده»
درطول «دسترسی عمومی محدودشده»، گزینه‌های Pro فقط برای پروژه‌های Google Cloud در فهرست مجاز Pro دردسترس است. برای درخواست دسترسی، با بخش فروش تماس بگیرید. وقتی پروژه‌ای در فهرست مجاز قرار می‌گیرد، هر کلید API و کارخواه OAuth در آن می‌تواند از گزینه‌های Pro استفاده کند.
اگر پروژه‌تان هنوز در فهرست مجاز نیست، درخواست‌هایی که از گزینه‌های Pro استفاده می‌کنند به‌صورت زیر رسیدگی می‌شوند:
- جستجوی مکان‌ها:
include_extended_detailsنادیده گرفته می‌شود و پاسخ حداکثر شامل ۵ مکان است، حتی اگرpage_sizeرا بالاتر تنظیم کنید. صورت‌حساب درخواست تحت SKU «اصول» صادر می‌شود. - محاسبه مسیرها:
ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALبه‌عنوانROUTING_PREFERENCE_TRAFFIC_UNAWAREدرنظر گرفته می‌شود و درخواست تحت «واحد نگهداری موجودی» Essentials صورت‌حساب می‌شود. درخواست با بیش‌از ۱۰ نقطه‌مسیر میانی، خطایINVALID_ARGUMENTرا برمی‌گرداند.
برای بررسی اینکه پروژه‌تان در فهرست مجاز قرار دارد یا نه،
درخواست search_places را با تنظیم page_size روی ۱۰ ارسال کنید. از پُرسمان گسترده‌ای مثل restaurants in
Chicago استفاده کنید. پروژه‌ای که در فهرست مجازها قرار دارد می‌تواند بیش‌از ۵ مکان را برگرداند که تحت
«واحد نگهداری سهام Pro» صورت‌حساب می‌شود. پروژه‌های دیگر حداکثر ۵ مکان را برمی‌گردانند.
کنترل استفاده از Pro
گزینه‌های Pro به‌طور پیش‌فرض خاموش هستند. وقتی درخواست کاربر آن‌ها را فراخوانی کند و طرح‌واره ابزار یا دستورالعمل‌های شما اجازه دهد، مدل زبانی بزرگ آن‌ها را تنظیم می‌کند. طرح ابزار
مقادیر page_size را تا ۵ و حداکثر ۱۰ نقطه‌مسیر میانی توصیف می‌کند.
بنابراین، مدل‌ها فقط زمانی از حد استفاده بالاتر Pro استفاده می‌کنند که دستورالعمل‌های شما آن را درخواست کند. برای مدیریت هزینه‌ها:
- به مدل بگویید چه زمانی گزینه‌های Pro مناسب هستند. برای مثال: «
include_extended_detailsرا فقط زمانی روی True تنظیم کن که کاربر درباره مرورها، منوها، یا جو سؤال می‌کند.» یا: «فقط وقتی کاربر مدت سفر فعلی را می‌پرسد، ازROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALاستفاده کن.» - برای نگه داشتن نماینده در SKU Essentials، به مدل دستور دهید که هرگز از گزینه Pro استفاده نکند. گزینه‌های Pro عبارت‌اند از
include_extended_details،page_sizeبالاتر از ۵،ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، و بیش‌از ۱۰ نقطه‌مسیر میانی. اگر کارخواه MCP شما می‌تواند آرگومان‌های ابزار را محدود کند، می‌توانید آن مقادیر را در پیکربندی ابزار آن نیز مسدود کنید. - مصرفتان را در گزارش‌های صورت‌حساب پایش کنید و هشدارهای بودجه را تنظیم کنید.
Resolution API
ابزارهای عامل Maps Experience، Resolution API را ارائه می‌دهد. این API نوشتار مکان با قالب آزاد و نشانی‌های وب را به شناسه‌های مکان ساختاریافته Google Maps تبدیل می‌کند. Resolution API به‌عنوان روش‌های REST و به‌عنوان ابزار در سرور MCP دردسترس است:
- حل کردن نام‌ها (REST، MCP): حل کردن دسته‌ای از نام‌ها یا نشانی‌های مکان به نهادهای مکان خاص در Google Maps. این کار برای زمینه‌سازی پُرسمان‌های کاربر ساختارنیافته در «شناسه‌های مکان» پایدار مفید است.
- Resolve Maps URLs (REST، MCP): دسته‌ای از نشانی‌های وب Google Maps را به نهادهای مکان خاصی تبدیل می‌کند. قالب‌های پشتیبانی‌شده شامل نشانی‌های وب مکان استاندارد و نشانی‌های وب کوتاه می‌شود.
می‌توانید از «شناسه‌های مکان» برگردانده‌شده با دیگر میاناهای برنامه‌سازی کاربردی Google Maps Platform استفاده کنید. هر پاسخ همچنین شامل پیوندی است که مکان‌های حل‌شده را به‌عنوان فهرستی در Google Maps ذخیره می‌کند.
برای اطلاعات بیشتر، Maps Tools Resolution API را ببینید.
امتحان کردن برنامه نمونه (باز کردن در برگه جدید)
صورت‌حساب و سهمیه‌ها
نحوه صدور صورت‌حساب برای شما
با مدل قیمت‌گذاری پرداخت به اندازه استفاده «پلاتفرم Google Maps»، استفاده از ابزارهای عامل Maps Experience برای هر درخواست محاسبه می‌شود. هر درخواست نشان‌دهنده یک رویداد صورت‌حساب است. استفاده برای هر واحد نگهداری موجودی محصول ردیابی می‌شود. صورت‌حساب شما علاوه‌بر هزینه‌های کل، یک مورد سطری برای هر SKU نشان می‌دهد. برای اطلاعات بیشتر، نمای کلی گزارش‌دهی را ببینید.
هر درخواست «جستجوی مکان‌ها»، «محاسبه مسیرها»، یا «جستجوی آب‌وهوا» دقیقاً تحت یک شناسه کالا، Essentials یا Pro، صورت‌حساب می‌شود. درخواستی که از هر گزینه Pro استفاده می‌کند تحت شناسه Pro صورت‌حساب می‌شود. هرگز تحت هر دو SKU صورت‌حساب صادر نمی‌شود و تعداد گزینه‌های Pro هزینه را تغییر نمی‌دهد. گزینه‌های زیر شناسه کالا را تعیین می‌کنند:
| ابزار | Essentials | Pro |
|---|---|---|
search_places |
هر درخواستی بدون گزینه Pro: page_size از ۵ یا کمتر، و include_extended_details تنظیم‌نشده یا false |
include_extended_details روی true، یا page_size از ۶ تا ۱۰ تنظیم شد |
compute_routes |
هر درخواستی بدون گزینه Pro: routing_preference تنظیم‌نشده یا ROUTING_PREFERENCE_TRAFFIC_UNAWARE، و ۱۰ نقطه‌مسیر میانی یا کمتر، با هر حالت سفر |
routing_preference روی ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL، یا ۱۱ تا ۲۵ نقطه‌مسیر میانی تنظیم شده است |
lookup_weather |
همه درخواست‌ها | — |
برای قیمت‌گذاری Essentials، جزئیات شناسه کالا Essentials را ببینید. درخواست‌های Pro با نرخ ۱۴٫۰۰ دلار به‌ازای هر ۱٬۰۰۰ درخواست پس‌از ۵٬۰۰۰ درخواست اول در هر ماه صورت‌حساب می‌شود. برای قیمت‌گذاری حجمی، با بخش فروش تماس بگیرید.
درطول «دسترسی عمومی محدود»، گزینه‌های Pro فقط بر پروژه‌های موجود در فهرست مجاز Pro اعمال می‌شوند. برای جزئیات، گزینه‌های Pro درطول «دسترسی عمومی محدودشده» را ببینید.
برای جزئیات قیمت‌گذاری، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.
درخواست‌های Resolution API (ResolveNames و ResolveMapsUrls) تحت شناسه واحد نگهداری موجودی Places API Text Search Essentials (IDs Only) بدون هزینه صورت‌حساب می‌شوند.
استفاده از SKU «ملزومات» نیز در بسته‌های «ملزومات» و Pro مشترک شوید تا صرفه‌جویی کنید گنجانده شده است. «واحد نگهداری موجودی» Pro در بسته‌های «مشترک شوید تا صرفه‌جویی کنید» گنجانده نشده است.
سهمیه‌ها
سهمیه‌های زیر برای ابزارها و میاناهای برنامه‌سازی کاربردی ارائه‌شده توسط ابزارهای عامل Maps Experience اعمال می‌شود:
- جستجوی مکان‌ها: ۳۰۰ پُرسمان در دقیقه، برای هر پروژه.
- جستجوی آب‌وهوا: ۳۰۰ پُرسمان در دقیقه، برای هر پروژه.
- محاسبه مسیرها: ۳۰۰ پُرسمان در دقیقه، برای هر پروژه.
- حل کردن نام‌ها: ۶۰۰ پُرسمان در دقیقه، برای هر پروژه.
- حل‌وفصل نشانی‌های وب Maps: ۶۰۰ پرسمان در دقیقه، برای هر پروژه.
سهمیه‌ها برای هر ابزار محاسبه می‌شود و بین SKUهای Essentials و Pro مشترک است. درخواست Pro همان سهمیه‌ای را مصرف می‌کند که درخواست Essentials برای همان ابزار مصرف می‌کند.
هر درخواست Resolution API، صرف‌نظر از تعداد مواردی که دربردارد، به‌عنوان یک پُرسمان محسوب می‌شود.
خط‌مشی‌ها و شرایط خدمات
ابزارهای عامل «تجربه Maps» تابع شرایط خدمات Google Maps Platform، ازجمله شرایط خاص سرویس است. این بخش الزامات استفاده اضافی را برای ابزارهای عامل «تجربه Maps» شرح می‌دهد، ازجمله «مدل‌های زبانی بزرگ» سازگار و ذکر منبع. این الزامات برای همه نتایج اعمال می‌شود، صرف‌نظر از اینکه درخواست تحت کدام SKU صورت‌حساب می‌شود.
الزامات مدل‌های زبانی بزرگ سازگار
فقط می‌توانید از ابزارهای عامل Maps Experience با LLM استفاده کنید که با «شرایط خدمات پلاتفرم Google Maps» مطابقت داشته باشد.
برای مثال، شما مسئول هستید که مطمئن شوید «محتوای Google Maps» توسط مدل زبانی بزرگی که برای استفاده انتخاب می‌کنید ذخیره موقت یا ذخیره نمی‌شود یا برای بهبود آن استفاده نمی‌شود. قبل‌از استفاده از ابزارهای عامل Maps Experience، باید «شرایط خدمات» هر مدلی را که قصد دارید با ابزارهای عامل Maps Experience استفاده کنید مرور کنید. نباید از ابزارهای عامل «تجربه Maps» با مدل‌هایی استفاده کنید که از داده‌های ورودی به مدل برای آموزش یا بهبود مدل استفاده می‌کنند. مسئولیت اطمینان از اینکه استفاده شما از مدل کاملاً با محدودیت‌های «محتوای Google Maps» در «شرایط خدمات Google Maps Platform»، ازجمله شرایط خاص سرویس، مطابقت دارد برعهده شما است.
الزامات ذکر منبع برای منابع Google Maps
هر پاسخ ابزار از ابزارهای نماینده «تجربه Maps» شامل منابع است. وقتی نتایج را از ابزارهای عامل Maps Experience ارائه می‌دهید، باید منابع Google Maps مربوطه را اضافه کنید و شرایط زیر را برآورده کنید:
- منابع Google Maps باید بلافاصله پس‌از محتوای تولیدشده‌ای که منابع از آن پشتیبانی می‌کنند، آورده شوند. به این محتوای تولیدشده خروجی مستند نیز گفته می‌شود.
- منابع Google Maps باید در یک تعامل کاربر قابل‌مشاهده باشد.
منابع ابزار «جستجوی مکان‌ها»
فیلد places ابزار search_places منابعی را ارائه می‌دهد که از summary پشتیبانی می‌کنند. برای places، فراداده زیر برگردانده می‌شود:
place(نام منبع)idlocationgoogleMapsLinks
برای هر مکان، باید پیش‌نمایش پیوندی تولید کنید که این الزامات را برآورده کند:
- هر منبع را به Google Maps ارجاع دهید و دستورالعمل‌های ارجاع متنی ابزارهای نماینده تجربه Maps را دنبال کنید.
- بااستفاده از
places.googleMapsLinks.placeUrlموجود در پاسخ، به منبع پیوند دهید.
این الزامات برای خلاصه‌هایی که شامل جزئیات گسترده مکان از Pro هستند، مانند اطلاعات برگرفته از مرورها، نیز اعمال می‌شود. summary هر مکان را با
نمایه صفرپایه، مثلاً [0]، ذکر می‌کند که به ورودی‌ای در places نگاشت می‌شود. هر
مکان همچنین شامل googleMapsLinks.reviewsUrl است که به مرورهای مکان در Google Maps پیوند می‌دهد. کاربران می‌توانند آن را دنبال کنند تا مرورهای پشت یک
اطلاعات آماری را ببینند.
میاناهای صوتی-محور
اگر برنامه‌تان نتایج ابزارهای عامل «تجربه Maps» را به‌صورت صوتی ارائه می‌دهد، باید الزامات میاناهای صوتی را نیز برآورده کنید. به‌طور خلاصه:
- منبع‌یابی: منابع Google Maps را در یک میانای کاربری همراه نمایش دهید که سوابق تاریخی مکالمه صوتی را به‌صورت کلمه‌به‌کلمه نشان می‌دهد.
- شفاف‌سازی فعال: در زمان تعامل، به کاربران بگویید که محتوای تولیدشده با هوش مصنوعی ممکن است حاوی اطلاعاتی از Google Maps باشد. همچنین به آن‌ها بگویید که منابع دقیق در واسط کاربر همراه دردسترس است. می‌توانید این کار را روی صفحه‌نمایش یا با صدا انجام دهید.
- شفاف‌سازی دائمی: توضیحی دائمی، مثلاً در منو تنظیمات گفتار، ارائه دهید که محتوای تولیدشده با هوش مصنوعی ممکن است شامل محتوای Google Maps باشد.
- پرسش‌های کاربر: به سؤالات کاربران درباره منبع محتوا به‌طور دقیق پاسخ دهید و آن‌ها را برای جزئیات به میانای کاربری همراه هدایت کنید.
پیکربندی کردن مدل‌های زبانی بزرگ برای استفاده از سرور MCP
برای استفاده از ابزارهای عامل «تجربه Maps»، به پروژه Google Cloud با سرویس API ابزارهای عامل تجربه Maps فعال‌شده نیاز دارید. همچنین به کلید میانای API یا شناسه کارخواه OAuth نیاز دارید. سپس می‌توانید مدل‌های زبانی بزرگ را برای دسترسی به سرور MCP پیکربندی کنید. سرور MCP از انتقال HTTP جاری‌سازی‌پذیر استفاده می‌کند.
ابزارهای عامل Maps Experience را در پروژه Google Cloud خود فعال کنید
برای فعال کردن میانای برنامه‌سازی کاربردی در پروژه‌تان:
- در کنسول Google Cloud، پروژه‌ای را که می‌خواهید برای ابزارهای عامل Maps Experience استفاده کنید انتخاب کنید.
- صورت‌حساب را برای پروژه در کنسول Google Cloud فعال کنید.
- ابزارهای نماینده «تجربه Maps» را در کتابخانه میانای برنامه‌سازی کاربردی کنسول Google Cloud فعال کنید.
اصالت‌سنجی بااستفاده از کلید میانای API
می‌توانید از کلید میانای برنامه‌سازی کاربردی موجود با ابزارهای نماینده «تجربه Maps» استفاده کنید یا کلید جدیدی ایجاد کنید. در هر دو حالت، سرویس API ابزارهای نماینده تجربه Maps را هم در پروژه Google Cloud و هم در کلید فعال کنید.
برای اصالت‌سنجی بااستفاده از کلید میانای API:
- با دنبال کردن مراحل شروع به کار با پلاتفرم Google Maps، کلید میانای برنامه‌سازی کاربردی ایجاد یا پیکربندی کنید.
- کلید را بااستفاده از سرصفحه
X-Goog-Api-Keyبه سرور MCP ارسال کنید. باید این را به‌عنوان سرایند HTTP سفارشی در پیکربندی ابزار MCP مدل زبانی بزرگ مشخص کنید.
اصالت‌سنجی بااستفاده از OAuth
می‌توانید با ایجاد اعتبارنامه‌های OAuth و ارسال آن‌ها به میزبان MCP یا برنامه سرور MCP، بااستفاده از OAuth اصالت‌سنجی کنید.
برای اصالت‌سنجی بااستفاده از OAuth:
- در کنسول Google Cloud، پروژه‌ای را که می‌خواهید برای ابزارهای عامل Maps Experience استفاده کنید انتخاب کنید.
- در منو میانای برنامه‌سازی کاربردی و سرویس‌ها، اعتبارنامه‌ها را انتخاب کنید.
- در منو بالایی، ایجاد اطلاعات کاربری > شناسه کارخواه OAuth را انتخاب کنید.
- اگر پروژه صفحه رضایت پیکربندی‌شده ندارد، روی پیکربندی صفحه رضایت کلیک کنید و دستورالعمل‌های روی صفحه را دنبال کنید.
- در بخش سنجه‌ها، روی ایجاد کارخواه OAuth کلیک کنید.
- در صفحه ایجاد شناسه کارخواه OAuth، نوع برنامه را انتخاب کنید و نامی برای شناسه کارخواه وارد کنید.
- جزئیات اضافی مربوط به نوع درخواستتان را مشخص کنید. برای مثال، اگر درحال ایجاد برنامه وب هستید، شناسه منبع یکسان مجاز برای درخواست‌های مرورگر و سرور اضافه کنید.
- وقتی کارخواه ایجاد شد، شناسه و رمز کارخواه را ذخیره کنید.
- وقتی میزبان 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 (5 tools) Tools: - compute_routes - lookup_weather - resolve_maps_urls - resolve_names - 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»
فایل 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: "SseConnectionParams", url: "https://mapstools.googleapis.com/mcp", headers: { "X-Goog-Api-Key": googleMapsApiKey, "Content-Type": "application/json", "Accept": "application/json, text/event-stream" } }) ], });
درحال هم‌رسانی بازخورد
برای هم‌رسانی بازخورد درباره ابزارهای نماینده «تجربه Maps»، از فرم‌های زیر استفاده کنید: