Maps Experience एजेंट के टूल

Maps Experience agent tools (पहले इसका नाम Maps Grounding Lite था), Google Maps Platform की एक सेवा है. इसमें मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) और REST की सुविधा मिलती है. इससे Google Maps के भरोसेमंद जियोस्पेशल डेटा की मदद से, एआई ऐप्लिकेशन को बेहतर बनाया जा सकता है. इसके टूल, एलएलएम को जगहों, मौसम, एयर क्वालिटी, पराग, और रास्तों का डेटा ऐक्सेस करने की सुविधा देते हैं. अन्य टूल, जगह के नाम और Google Maps के यूआरएल को जगह के आईडी में बदल देते हैं. Maps एक्सपीरियंस एजेंट टूल को आज़माने के लिए, एमसीपी सर्वर के साथ काम करने वाले किसी भी टूल में इसका एमसीपी सर्वर चालू करें. हर टूल को REST तरीके के तौर पर भी कॉल किया जा सकता है. ज़्यादा जानकारी के लिए, REST का इस्तेमाल करके टूल को कॉल करना लेख पढ़ें.

Maps Experience agent tools एक प्रॉडक्ट है, जिसके दो एसकेयू हैं: Essentials और Pro. हर अनुरोध के लिए Essentials के तहत बिलिंग की जाती है. हालांकि, अगर Pro विकल्प का इस्तेमाल किया जाता है, तो उसके हिसाब से बिलिंग की जाती है. Pro प्लान में ये सुविधाएं मिलती हैं: किसी रास्ते पर Place Search करना, किसी जगह की ज़्यादा जानकारी पाना (Place Details), हर खोज के लिए ज़्यादा जगहें देखना, हर रास्ते पर ज़्यादा स्टॉप देखना, लाइव ट्रैफ़िक के साथ रास्ता देखना, पॉलेन (Pollen) के पूर्वानुमान देखना, और एयर क्वालिटी का इतिहास देखना. दोनों एसकेयू एक ही टूल, एमसीपी सर्वर, REST मेथड, और क्रेडेंशियल का इस्तेमाल करते हैं. ज़्यादा जानकारी के लिए, Essentials और Pro देखें.

टूल

Maps एक्सपीरियंस एजेंट टूल की मदद से, एलएलएम को Google Maps की इन सुविधाओं का ऐक्सेस मिलता है:

• जगहें खोजना: जगहों के बारे में जानकारी का अनुरोध करें और एआई से जनरेट की गई खास जानकारी पाएं. जवाब में, खास जानकारी में मौजूद हर जगह के लिए, जगह के आईडी, अक्षांश/देशांतर निर्देशांक, और Google Maps में किसी जगह पर ले जाने वाला लिंक भी शामिल होते हैं. मैप पर जगहों को दिखाने के लिए, जगह के आईडी और अक्षांश/देशांतर निर्देशांकों को Google Maps Platform के अन्य एपीआई के साथ इस्तेमाल किया जा सकता है. जगहों की जानकारी देने वाली यूआई किट की मदद से, इन जगहों को बिना किसी शुल्क के दिखाने के लिए, एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) का इस्तेमाल करें. Pro प्लान के साथ, किसी जगह के बारे में ज़्यादा जानकारी पाने का अनुरोध किया जा सकता है. जैसे, समीक्षाओं से मिली अहम जानकारी. साथ ही, हर अनुरोध में ज़्यादा से ज़्यादा 10 जगहों की जानकारी पाई जा सकती है.
• रास्ते में पड़ने वाली जगहें खोजना: retrieval_token, compute_routes, route_endpoints या encoded_polyline का इस्तेमाल करके, यात्रा के रास्ते में पड़ने वाली जगहें खोजें. साथ ही, एआई से जनरेट की गई खास जानकारी, जगह की जानकारी, रास्ते से भटकने की दूरी, यात्रा में लगने वाला समय, और एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) पाएं. search_along_route के हर अनुरोध के लिए, Pro SKU के तहत शुल्क लिया जाता है.
• मौसम की जानकारी देखना: किसी जगह के मौसम की जानकारी का अनुरोध करें. इसमें मौसम (मौजूदा स्थिति, पिछले 24 घंटों का इतिहास, और अगले 10 दिनों तक के लिए हर घंटे और हर दिन का पूर्वानुमान) और मौजूदा या अगले चार दिनों तक के लिए एयर क्वालिटी का पूर्वानुमान शामिल है. Pro वर्शन में, आपको हर दिन के हिसाब से पांच दिनों तक पराग कणों के पूर्वानुमान की जानकारी भी मिल सकती है. इसमें पौधों की प्रजातियों की जानकारी भी शामिल होती है. साथ ही, आपको हर घंटे के हिसाब से 30 दिनों तक की एयर क्वालिटी का इतिहास भी मिल सकता है.

• रास्ते की जानकारी पाना: शुरुआती जगह और मंज़िल के बीच के रास्ते की जानकारी का अनुरोध करें. इसके लिए, बीच में पड़ने वाले स्टॉप की जानकारी भी दी जा सकती है. इसके बाद, रास्ते की दूरी, लगने वाले समय, और DRIVE रास्तों के लिए retrievalToken की जानकारी पाएं. इस जानकारी को search_along_route को पास किया जा सकता है. Pro वर्शन में, रास्तों को लाइव ट्रैफ़िक की स्थितियों के हिसाब से तय किया जा सकता है. साथ ही, इसमें बीच में ज़्यादा स्टॉप शामिल किए जा सकते हैं.

• नामों को रिज़ॉल्व करना और Maps के यूआरएल को रिज़ॉल्व करना: जगहों के नाम, पते, और Google Maps के यूआरएल को जगह के आईडी में रिज़ॉल्व करें. ज़्यादा जानकारी के लिए, Resolution API लेख पढ़ें.

एमसीपी सर्वर को चालू करने के बाद, एलएलएम इसके टूल को कॉल कर सकते हैं. इससे इन डेटा टाइप के लिए, ग्राउंडिंग की जानकारी मिल सकती है. एलएलएम, इस जानकारी का इस्तेमाल कॉन्टेक्स्ट के तौर पर कर सकता है. हालांकि, ऐसा हो सकता है कि इसके फ़ाइनल जवाब में वह सटीक जानकारी शामिल न हो जो एमसीपी सर्वर ने दी थी. जनरेट किए गए जवाब के सटीक होने की पुष्टि करें.

Essentials और Pro

Essentials और Pro, एक ही प्रॉडक्ट के दो एसकेयू हैं. ये अलग-अलग प्रॉडक्ट या प्लान नहीं हैं. Pro विकल्प का इस्तेमाल करने पर, अनुरोध के लिए Pro के हिसाब से शुल्क लिया जाता है. अन्य सभी अनुरोधों के लिए, Essentials के तहत शुल्क लिया जाता है. Pro वर्शन के विकल्प, टूल के अनुरोध में सामान्य फ़ील्ड होते हैं. इसलिए, एलएलएम आपकी ओर से इनका इस्तेमाल कर सकता है. कोई एजेंट एक ही बातचीत में, दोनों एसकेयू का इस्तेमाल भी कर सकता है. उदाहरण के लिए, कोई एजेंट किसी लैंडमार्क के आस-पास कॉफ़ी शॉप ढूंढने के लिए, Essentials का इस्तेमाल कर सकता है. इसके बाद, वह Pro का इस्तेमाल करके, उनके सिग्नेचर ड्रिंक और बैठने की जगह के बारे में पूछे गए सवाल का जवाब दे सकता है. Pro के लिए कोई अलग एमसीपी सर्वर, एंडपॉइंट या क्रेडेंशियल नहीं होता.

Essentials, Pro, और Grounding with Google Maps की तुलना करना

Grounding with Google Maps एक अलग प्रॉडक्ट है. यह Gemini API, Google AI Studio, और Gemini Enterprise Agent Platform में Gemini मॉडल के साथ काम करता है. मॉडल यह तय करता है कि Google Maps से कब क्वेरी करनी है. साथ ही, वह उद्धरणों के साथ सटीक जवाब देता है. अगर आपको Gemini का इस्तेमाल करके कोई ऐप्लिकेशन बनाना है और मॉडल से ग्राउंडिंग करानी है, तो Google Maps से जानकारी लेने की सुविधा चुनें. अन्य मॉडल या एजेंट फ़्रेमवर्क के लिए, Maps एक्सपीरियंस एजेंट टूल चुनें. इसके अलावा, हर टूल कॉल को सीधे तौर पर कंट्रोल करने के लिए भी इन्हें चुना जा सकता है.

यहां दी गई टेबल में, Essentials SKU, Pro SKU, और Google Maps से जानकारी लेने की सुविधा की तुलना की गई है:

ये विकल्प, दोनों एसकेयू के साथ एक ही तरह से काम करते हैं: यात्रा के मोड, जाने और पहुंचने का समय, वैकल्पिक रास्ते, रास्ते की पॉलीलाइन, मौसम की जानकारी, मौजूदा और आने वाले समय की एयर क्वालिटी की जानकारी (इसमें प्रदूषण फैलाने वाले कारकों की मात्रा और स्थानीय एक्यूआई स्केल शामिल हैं), मौसम की यूनिट सिस्टम, और Resolution API. इनसे यह नहीं बदलता कि किसी अनुरोध के लिए किस एसकेयू के तहत बिल भेजा जाएगा.

Pro एसकेयू के तहत किस चीज़ का बिल भेजा जाता है

यहां दी गई टेबल में बताया गया है कि Essentials में कौनसी सुविधाएं शामिल हैं और किन सुविधाओं के लिए Pro एसकेयू की ज़रूरत होती है:

हर सुविधा को चालू करने वाले अनुरोध के विकल्पों के लिए, जगहें खोजें, रास्ते के आस-पास की जगहें खोजें, रास्ते कैलकुलेट करें, और मौसम की जानकारी देखें पर जाएं.

Pro के इस्तेमाल को कंट्रोल करना

search_places, compute_routes, और lookup_weather पर, प्रो मोड के विकल्प डिफ़ॉल्ट रूप से बंद होते हैं. एलएलएम उन्हें सेट करता है या search_along_route को कॉल करता है. ऐसा तब होता है, जब उपयोगकर्ता के अनुरोध के लिए उनकी ज़रूरत होती है और टूल के ब्यौरे या आपके निर्देशों में इसकी अनुमति होती है. टूल की जानकारी से मॉडल को पता चलता है कि किन विकल्पों की कीमत ज़्यादा है और उन्हें कब इस्तेमाल करना है: page_size से ज़्यादा, जगह की ज़्यादा जानकारी, 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, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, 10 से ज़्यादा इंटरमीडिएट वेपॉइंट, capabilities में POLLEN, और capabilities में AIR_QUALITY के साथ पिछला date या hour. अगर आपका एमसीपी क्लाइंट, टूल या टूल के आर्ग्युमेंट पर पाबंदी लगा सकता है, तो टूल के कॉन्फ़िगरेशन में जाकर search_along_route और आर्ग्युमेंट की उन वैल्यू को भी ब्लॉक किया जा सकता है.
• अपनी बिलिंग रिपोर्ट में Maps Grounding Pro SKU पर नज़र रखें और बजट से जुड़ी सूचनाएं सेट करें.

Resolution API

Maps एक्सपीरियंस एजेंट टूल, रिज़ॉल्यूशन एपीआई उपलब्ध कराता है. यह फ़्री-फ़ॉर्म में मौजूद जगह की जानकारी वाले टेक्स्ट और यूआरएल को, Google Maps पर मौजूद जगह के स्ट्रक्चर्ड आइडेंटिफ़ायर में बदलता है. Resolution API, REST मेथड और एमसीपी सर्वर पर टूल के तौर पर उपलब्ध है:

• नामों को रिज़ॉल्व करना (REST, MCP): Google Maps पर, जगहों के नाम या पतों के बैच को किसी खास जगह की इकाइयों के साथ रिज़ॉल्व करें. इस टूल की मदद से, उपयोगकर्ता की क्वेरी को जगह के आईडी में बदला जा सकता है.
• Maps के यूआरएल रिज़ॉल्व करना (REST, MCP): Google Maps के यूआरएल के बैच को किसी खास जगह की इकाइयों के लिए रिज़ॉल्व करें. इस्तेमाल किए जा सकने वाले फ़ॉर्मैट में, जगह के स्टैंडर्ड यूआरएल और छोटे किए गए यूआरएल शामिल हैं.

जगह के आईडी को Google Maps Platform के अन्य एपीआई के साथ इस्तेमाल किया जा सकता है. हर जवाब में एक लिंक भी शामिल होता है. इस लिंक की मदद से, खोजी गई जगहों को Google Maps में एक सूची के तौर पर सेव किया जा सकता है.

ज़्यादा जानकारी के लिए, Maps Tools Resolution API देखें.

सैंपल के तौर पर मिला ऐप्लिकेशन आज़माएं (नए टैब में खोलें)

बिलिंग और कोटा

बिलिंग का तरीका

Google Maps Platform के इस्तेमाल के हिसाब से पैसे चुकाने के मॉडल के तहत, Maps एक्सपीरियंस एजेंट टूल के इस्तेमाल का हिसाब हर अनुरोध के लिए लगाया जाता है. हर अनुरोध, एक बिलिंग इवेंट को दिखाता है. हर प्रॉडक्ट SKU के लिए, इस्तेमाल को ट्रैक किया जाता है. आपके बिल में, कुल शुल्क के अलावा हर SKU के लिए एक लाइन आइटम दिखता है. ज़्यादा जानकारी के लिए, रिपोर्टिंग की खास जानकारी देखें.

एमसीपी सर्वर या REST के ज़रिए, Search places, Search along route, Compute routes या Lookup weather के लिए किए गए हर अनुरोध को एक एसकेयू के तहत बिल किया जाता है: Maps Grounding Essentials या Maps Grounding Pro. search_along_route के हर अनुरोध और Pro विकल्प का इस्तेमाल करने वाले किसी भी अनुरोध के लिए, Pro SKU के तहत बिल भेजा जाता है. किसी अनुरोध के लिए, दोनों एसकेयू के तहत बिल नहीं भेजा जाता. साथ ही, किसी अनुरोध में Pro सुविधाओं की संख्या से शुल्क में कोई बदलाव नहीं होता. हर टूल के लिए एसकेयू तय करने वाली सुविधाओं और विकल्पों के बारे में जानने के लिए, Pro एसकेयू के तहत किस चीज़ का शुल्क लिया जाता है लेख पढ़ें.

Maps Grounding Essentials के लिए, हर महीने पहले 10,000 अनुरोधों के बाद, हर 1,000 अनुरोधों के लिए 7 डॉलर का शुल्क लिया जाता है. Maps Grounding Pro के लिए, हर महीने शुरुआती 5,000 अनुरोधों के बाद, हर 1,000 अनुरोधों के लिए 14 डॉलर का शुल्क लिया जाता है. दोनों एसकेयू के लिए, हर महीने ज़्यादा इस्तेमाल करने पर वॉल्यूम के हिसाब से छूट मिलती है.

कीमत की जानकारी के लिए, कीमत की मुख्य टेबल और भारत के लिए कीमत की टेबल देखें.

Places API टेक्स्ट से खोजें Essentials (IDs Only) एसकेयू के तहत, रिज़ॉल्यूशन एपीआई अनुरोधों (ResolveNames और ResolveMapsUrls) के लिए कोई शुल्क नहीं लिया जाता.

अगर जगहों की जानकारी देने वाली यूआई किट की मदद से, search_places या search_along_route के रिस्पॉन्स से जगहों की जानकारी दिखाई जाती है, तो एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन (झलक) का इस्तेमाल किया जा सकता है. इससे जगहों की जानकारी देने वाली यूआई किट के उन अनुरोधों के लिए शुल्क नहीं लिया जाएगा.

Essentials SKU का इस्तेमाल, Essentials और Pro Subscribe to save प्लान में शामिल है. Pro SKU का इस्तेमाल, Pro प्लान में शामिल है.

कोटा

Maps Experience एजेंट टूल से मिलने वाले टूल और एपीआई पर, ये कोटा लागू होते हैं:

• जगहें खोजना: हर प्रोजेक्ट के लिए, हर मिनट 300 क्वेरी.
• रास्ते में पड़ने वाले स्टॉप खोजना: हर प्रोजेक्ट के लिए, हर मिनट में 300 क्वेरी.
• मौसम की जानकारी देखना: हर प्रोजेक्ट के लिए, हर मिनट 300 क्वेरी.
• रास्ते की जानकारी पाना: हर प्रोजेक्ट के लिए, हर मिनट 300 क्वेरी.
• नामों को रिज़ॉल्व करना: हर प्रोजेक्ट के लिए, हर मिनट 600 क्वेरी.
• Maps के यूआरएल रिज़ॉल्व करना: हर प्रोजेक्ट के लिए, हर मिनट 600 क्वेरी.

हर टूल के लिए कोटा गिना जाता है. साथ ही, Essentials और Pro एसकेयू के बीच शेयर किया जाता है. Pro प्लान के तहत किए गए अनुरोध के लिए, Essentials प्लान के तहत किए गए अनुरोध के बराबर ही कोटा खर्च होता है.

रिज़ॉल्यूशन एपीआई के हर अनुरोध को एक क्वेरी के तौर पर गिना जाता है. इससे कोई फ़र्क़ नहीं पड़ता कि उसमें कितने आइटम शामिल हैं.

नीतियां और सेवा की शर्तें

Maps एक्सपीरियंस एजेंट टूल पर, Google Maps Platform की सेवा की शर्तें लागू होती हैं. इनमें सेवा से जुड़ी खास शर्तें भी शामिल हैं. इस सेक्शन में, Maps Experience एजेंट के टूल इस्तेमाल करने से जुड़ी अन्य ज़रूरी शर्तों के बारे में बताया गया है. इनमें, साथ काम करने वाले एलएलएम और सोर्स एट्रिब्यूशन शामिल हैं. ये ज़रूरी शर्तें सभी नतीजों पर लागू होती हैं. इससे कोई फ़र्क़ नहीं पड़ता कि अनुरोध के लिए किस एसकेयू के तहत बिल भेजा गया है.

साथ काम करने वाले एलएलएम के लिए ज़रूरी शर्तें

Maps एक्सपीरियंस एजेंट टूल का इस्तेमाल सिर्फ़ ऐसे एलएलएम के साथ किया जा सकता है जो Google Maps Platform की सेवा की शर्तों का पालन करता हो.

उदाहरण के लिए, यह पक्का करना आपकी ज़िम्मेदारी है कि Google Maps के कॉन्टेंट को कैश मेमोरी में सेव न किया जाए, सेव न किया जाए या आपके चुने गए एलएलएम को बेहतर बनाने के लिए इस्तेमाल न किया जाए. Maps एक्सपीरियंस एजेंट टूल इस्तेमाल करने से पहले, आपको उस मॉडल की सेवा की शर्तें देखनी होंगी जिसे आपको Maps एक्सपीरियंस एजेंट टूल के साथ इस्तेमाल करना है. Maps Experience एजेंट टूल का इस्तेमाल, ऐसे किसी भी मॉडल के साथ नहीं किया जाना चाहिए जो मॉडल में डाले गए डेटा का इस्तेमाल, मॉडल को ट्रेनिंग देने या उसे बेहतर बनाने के लिए करता है. यह पक्का करना आपकी ज़िम्मेदारी है कि मॉडल का इस्तेमाल, Google Maps Platform की सेवा की शर्तों में Google Maps के कॉन्टेंट पर लगाई गई पाबंदियों के मुताबिक हो. इसमें सेवा की खास शर्तें भी शामिल हैं.

Google Maps के सोर्स के लिए, एट्रिब्यूशन से जुड़ी ज़रूरी शर्तें

Maps एक्सपीरियंस एजेंट टूल से मिले हर जवाब में सोर्स शामिल होते हैं. Maps एक्सपीरियंस एजेंट टूल से मिले नतीजे दिखाते समय, आपको Google Maps के सोर्स शामिल करने होंगे. साथ ही, इन ज़रूरी शर्तों को पूरा करना होगा:

• Google Maps के सोर्स, जनरेट किए गए उस कॉन्टेंट के तुरंत बाद दिखने चाहिए जो सोर्स के साथ काम करता है. जनरेट किए गए इस कॉन्टेंट को ग्राउंडेड आउटपुट भी कहा जाता है.
• Google Maps के सोर्स, उपयोगकर्ता के एक इंटरैक्शन में दिखने चाहिए.

जगहें खोजने और रास्ते में पड़ने वाली जगहें खोजने वाले टूल के लिए सोर्स

search_places टूल places फ़ील्ड और search_along_route टूल results[].place फ़ील्ड, summary के साथ काम करने वाले सोर्स उपलब्ध कराते हैं. हर जगह के लिए, यह मेटाडेटा दिखाया जाता है:

• place (संसाधन का नाम)
• id
• location
• googleMapsLinks
• attribution

आपको हर जगह के लिए, लिंक की झलक जनरेट करनी होगी. इसके लिए, ये ज़रूरी शर्तें पूरी करनी होंगी:

• Maps एक्सपीरियंस एजेंट टूल के टेक्स्ट एट्रिब्यूशन के दिशा-निर्देशों का पालन करते हुए, हर सोर्स का एट्रिब्यूशन Google Maps को दें.
• जवाब में मौजूद googleMapsLinks.placeUrl का इस्तेमाल करके, सोर्स पर जाएं.

ये शर्तें, Pro से मिलने वाली जगह की ज़्यादा जानकारी वाली खास जानकारी पर भी लागू होती हैं. जैसे, समीक्षाओं से मिली अहम जानकारी. summary, हर जगह को शून्य से शुरू होने वाले इंडेक्स के साथ दिखाता है. जैसे, [0], जो places या results में मौजूद किसी एंट्री पर मैप करता है. हर जगह के लिए googleMapsLinks.reviewsUrl भी शामिल है. यह Google Maps पर उस जगह की समीक्षाओं से लिंक करता है. उपयोगकर्ता इस लिंक पर क्लिक करके, किसी इनसाइट के पीछे की समीक्षाएं देख सकते हैं.

वॉइस-फ़र्स्ट इंटरफ़ेस

अगर आपका ऐप्लिकेशन, Maps एक्सपीरियंस एजेंट टूल के नतीजों को बोलकर सुनाता है, तो आपको वॉइस-फ़र्स्ट इंटरफ़ेस की ज़रूरी शर्तें भी पूरी करनी होंगी. सारांश में:

• सोर्सिंग: Google Maps के सोर्स को कंपैनियन यूज़र इंटरफ़ेस (यूआई) में दिखाएं. इसमें, बोलकर की गई बातचीत का पुराना रिकॉर्ड हूबहू दिखता है.
• साफ़ तौर पर जानकारी देना: इंटरैक्शन के समय, उपयोगकर्ताओं को बताएं कि एआई से बनाए गए कॉन्टेंट में, Google Maps से ली गई जानकारी शामिल हो सकती है. उन्हें यह भी बताएँ कि सोर्स की पूरी जानकारी, कंपैनियन यूआई में उपलब्ध है. ऐसा स्क्रीन पर या बोलकर किया जा सकता है.
• लगातार जानकारी देना: उपयोगकर्ताओं को लगातार यह जानकारी दें कि एआई से बनाए गए कॉन्टेंट में Google Maps का कॉन्टेंट शामिल हो सकता है. उदाहरण के लिए, आवाज़ की सेटिंग वाले मेन्यू में यह जानकारी दें.
• उपयोगकर्ताओं के सवाल: कॉन्टेंट के सोर्स के बारे में उपयोगकर्ताओं के सवालों के सटीक जवाब दें. साथ ही, ज़्यादा जानकारी के लिए उन्हें कंपैनियन यूज़र इंटरफ़ेस (यूआई) पर भेजें.

एमसीपी सर्वर का इस्तेमाल करने के लिए एलएलएम कॉन्फ़िगर करना

Maps एक्सपीरियंस एजेंट टूल इस्तेमाल करने के लिए, आपके पास एक Google Cloud प्रोजेक्ट होना चाहिए. साथ ही, उसमें Maps एक्सपीरियंस एजेंट टूल एपीआई सेवा चालू होनी चाहिए. आपको एपीआई पासकोड या OAuth क्लाइंट आईडी की भी ज़रूरत होगी. इसके बाद, एमसीपी सर्वर को ऐक्सेस करने के लिए एलएलएम को कॉन्फ़िगर किया जा सकता है. एमसीपी सर्वर, स्ट्रीम किए जा सकने वाले एचटीटीपी ट्रांसपोर्ट का इस्तेमाल करता हो.

अपने Google Cloud प्रोजेक्ट पर Maps Experience एजेंट टूल चालू करें

अपने प्रोजेक्ट में एपीआई चालू करने के लिए:

1. Google Cloud Console में, वह प्रोजेक्ट चुनें जिसका इस्तेमाल आपको Maps एक्सपीरियंस एजेंट टूल के लिए करना है.
2. Google Cloud Console में जाकर, प्रोजेक्ट के लिए बिलिंग की सुविधा चालू करें.
3. Google Cloud Console API लाइब्रेरी में जाकर, Maps एक्सपीरियंस एजेंट टूल चालू करें.

एपीआई पासकोड का इस्तेमाल करके पुष्टि करना

Maps Experience एजेंट टूल के साथ किसी मौजूदा एपीआई पासकोड का इस्तेमाल किया जा सकता है या नया एपीआई पासकोड बनाया जा सकता है. दोनों ही मामलों में, Google Cloud प्रोजेक्ट और एपीआई कुंजी, दोनों पर Maps Experience agent tools एपीआई सेवा चालू करें.

एपीआई पासकोड का इस्तेमाल करके पुष्टि करने के लिए:

1. Google Maps Platform का इस्तेमाल शुरू करना में दिया गया तरीका अपनाकर, एपीआई पासकोड बनाएं या कॉन्फ़िगर करें.
2. X-Goog-Api-Key हेडर का इस्तेमाल करके, कुंजी को एमसीपी सर्वर को पास करें. आपको इसे एलएलएम के एमसीपी टूल कॉन्फ़िगरेशन में, कस्टम एचटीटीपी हेडर के तौर पर बताना होगा.

OAuth का इस्तेमाल करके पुष्टि करना

OAuth क्रेडेंशियल बनाकर और उन्हें एमसीपी होस्ट या एमसीपी सर्वर ऐप्लिकेशन को पास करके, OAuth का इस्तेमाल करके पुष्टि की जा सकती है.

OAuth का इस्तेमाल करके पुष्टि करने के लिए:

1. Google Cloud Console में, वह प्रोजेक्ट चुनें जिसका इस्तेमाल आपको Maps एक्सपीरियंस एजेंट टूल के लिए करना है.
2. एपीआई और सेवाएं मेन्यू में जाकर, क्रेडेंशियल चुनें.
3. सबसे ऊपर दिए गए मेन्यू में, क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी को चुनें.
4. अगर प्रोजेक्ट के लिए, सहमति वाली स्क्रीन कॉन्फ़िगर नहीं की गई है, तो सहमति वाली स्क्रीन कॉन्फ़िगर करें पर क्लिक करें. इसके बाद, स्क्रीन पर दिए गए निर्देशों का पालन करें.
5. मेट्रिक सेक्शन में, OAuth क्लाइंट बनाएं पर क्लिक करें.
6. OAuth क्लाइंट आईडी बनाएं स्क्रीन पर, ऐप्लिकेशन का टाइप चुनें और क्लाइंट आईडी के लिए कोई नाम डालें.
7. अपने ऐप्लिकेशन के टाइप के हिसाब से, अन्य जानकारी दें. उदाहरण के लिए, अगर कोई वेब ऐप्लिकेशन बनाया जा रहा है, तो ब्राउज़र और सर्वर के अनुरोधों के लिए, अनुमति वाले यूआरआई जोड़ें.
8. क्लाइंट बन जाने के बाद, क्लाइंट आईडी और सीक्रेट को सेव करें.
9. एमसीपी होस्ट या एमसीपी सर्वर ऐप्लिकेशन को कॉन्फ़िगर करते समय, अपना OAuth क्लाइंट आईडी और सीक्रेट पास करें. आपको इस स्कोप का भी अनुरोध करना होगा: https://www.googleapis.com/auth/maps-platform.mapstools.

ज़्यादा जानकारी के लिए, Google API को ऐक्सेस करने के लिए OAuth 2.0 का इस्तेमाल करना लेख पढ़ें.

Maps एक्सपीरियंस एजेंट टूल के एमसीपी सर्वर को ऐक्सेस करने के लिए, एलएलएम कॉन्फ़िगर करें

Maps Experience agent tools सेवा को चालू करने और क्रेडेंशियल बनाने के बाद, एलएलएम को एमसीपी सर्वर ऐक्सेस करने के लिए कॉन्फ़िगर किया जा सकता है. अपने एलएलएम के एमसीपी कॉन्फ़िगरेशन से जुड़े दस्तावेज़ में दिए गए निर्देशों का पालन करें और एमसीपी सर्वर के इस यूआरएल का इस्तेमाल करें: https://mapstools.googleapis.com/mcp

ज़्यादा जानकारी के लिए, एआई ऐप्लिकेशन में एमसीपी को कॉन्फ़िगर करना लेख पढ़ें.

Gemini CLI की मदद से, Maps एक्सपीरियंस एजेंट टूल कॉन्फ़िगर करना

इस सेक्शन में, Gemini सीएलआई का इस्तेमाल करके, Maps Experience एजेंट टूल के एमसीपी सर्वर को कॉन्फ़िगर करने का उदाहरण दिया गया है. ज़्यादा जानकारी के लिए, Gemini सीएलआई के साथ एमसीपी सर्वर देखें.

1. Gemini सीएलआई इंस्टॉल करने के बाद, एमसीपी सर्वर को कॉन्फ़िगर करने के लिए 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
   

   अगर कॉन्फ़िगरेशन पूरा हो गया है, तो आपको पुष्टि करने वाला एक मैसेज दिखेगा. इसमें बताया जाएगा कि सर्वर को आपकी उपयोगकर्ता सेटिंग में जोड़ दिया गया है.

2. यह पुष्टि करने के लिए कि सर्वर काम कर रहा है, /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
   

3. सीएलआई की मदद से, Maps से जुड़े सवाल पूछना शुरू करें. उदाहरण के लिए, "माउंटेन व्यू में कुछ रेस्टोरेंट के सुझाव दो" प्रॉम्प्ट आज़माएँ. इससे आपकी ओर से search_places टूल को कॉल किया जाएगा.

Agent Development Kit (ADK) की मदद से, Maps एक्सपीरियंस एजेंट टूल कॉन्फ़िगर करना

इस सेक्शन में, Python, Java या TypeScript में Agent Development Kit (ADK) के साथ एमसीपी सर्वर को कॉन्फ़िगर करने का तरीका बताया गया है.

# ./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"
                }
            )
        )
    ]
)
    

from . import agent
    

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();
        }
    }
}
    

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 एक्सपीरियंस एजेंट टूल में मौजूद हर टूल, REST तरीके के तौर पर भी उपलब्ध है. जब आपको टूल को अपने एजेंट या ऐप्लिकेशन में जोड़ना हो, तो सीधे REST मेथड को कॉल करें. उदाहरण के लिए, किसी मॉडल के लिए अपने फ़ंक्शन तय करने, यह चुनने कि मॉडल कौनसे विकल्प सेट कर सकता है या अपने कोड में डिफ़ॉल्ट वैल्यू सेट करने के लिए.

इस टेबल में, हर टूल के लिए REST मेथड की जानकारी दी गई है:

REST अनुरोध में, उससे जुड़े टूल के जैसे ही विकल्प होते हैं और यह वही जवाब देता है. REST अनुरोध और रिस्पॉन्स बॉडी में, फ़ील्ड के नाम लोअर कैमल केस का इस्तेमाल करते हैं—उदाहरण के लिए, text_query के बजाय textQuery. REST अनुरोधों के लिए, उन्हीं एसकेयू के तहत बिलिंग की जाती है और Pro विकल्पों के लिए उन्हीं नियमों का पालन किया जाता है. साथ ही, इन्हें एमसीपी टूल कॉल के समान कोटा में गिना जाता है.

पुष्टि करने के लिए, उसी Google Cloud प्रोजेक्ट और क्रेडेंशियल का इस्तेमाल करें जो एमसीपी सर्वर के लिए इस्तेमाल किया गया है. सेटअप करने का तरीका जानने के लिए, एमसीपी सर्वर का इस्तेमाल करने के लिए एलएलएम कॉन्फ़िगर करना लेख पढ़ें. X-Goog-Api-Key हेडर में एपीआई पासकोड पास करें या Authorization हेडर में https://www.googleapis.com/auth/maps-platform.mapstools स्कोप के साथ OAuth ऐक्सेस टोकन पास करें.

यहां दिए गए उदाहरण में, 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 को अपने एपीआई पासकोड से बदलें.

रिस्पॉन्स में summary, places, और contentToken फ़ील्ड शामिल होते हैं. ये फ़ील्ड, search_places टूल के रिज़ल्ट में भी शामिल होते हैं. हर टूल की गाइड में, उसके उदाहरण का REST वर्शन दिखाया जाता है.

सुझाव/राय देना या शिकायत करना

Maps Experience एजेंट टूल के बारे में सुझाव/राय देने या शिकायत करने के लिए, इन फ़ॉर्म का इस्तेमाल करें:

• किसी गड़बड़ी की शिकायत करना
• सुविधा का अनुरोध सबमिट करना
• सुझाव या राय देना