एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन की मदद से, आपका एजेंटिक ऐप्लिकेशन, Maps Experience एजेंट टूल (पहले इसका नाम Maps Grounding Lite था) के रिस्पॉन्स में जगहों के लिए, जगहों की जानकारी देने वाली यूआई किट के एलिमेंट दिखा सकता है. इसके लिए, कोई अतिरिक्त शुल्क नहीं देना पड़ता. search_places टूल को किए गए हर सफल कॉल से एक टोकन मिलता है. यह टोकन, Essentials और Pro, दोनों एसकेयू के लिए, जवाब में जगहों की पहचान करता है. जब आपका क्लाइंट ऐप्लिकेशन, Maps JavaScript API में टोकन जोड़ता है, तो जगहों की जानकारी देने वाली यूआई किट से उन जगहों के लिए किए गए अनुरोधों के लिए, टोकन जारी होने के बाद 10 मिनट तक शुल्क नहीं लिया जाता.
यह कैसे काम करता है
टोकन, ग्राउंडेड रिस्पॉन्स को जगह की उस जानकारी से जोड़ता है जो उसके साथ दिखाई जाती है:
- आपका एजेंट, Maps Experience एजेंट टूल के एमसीपी सर्वर पर
search_placesटूल को कॉल करता है. टूल के जवाब में, खास जानकारी के साथ-साथcontentTokenफ़ील्ड में एक टोकन भी शामिल होता है. - आपका ऐप्लिकेशन, टूल के रिस्पॉन्स से टोकन को पढ़ता है और उसे आपके क्लाइंट ऐप्लिकेशन को भेजता है. साथ ही, उन जगहों के आईडी भी भेजता है जिन्हें आपको दिखाना है.
- आपका क्लाइंट ऐप्लिकेशन, Maps JavaScript API में टोकन जोड़ता है और उन जगहों के लिए Places यूआई किट के एलिमेंट बनाता है.
- Google Maps Platform, जगहों की जानकारी देने वाली यूआई किट के हर अनुरोध के साथ टोकन की पुष्टि करता है. अगर टोकन मान्य है, तो अनुरोध के लिए शुल्क नहीं लिया जाता.
जगहों की जानकारी देने वाली यूआई किट के साथ काम करने वाले एलिमेंट
यह टोकन, Maps JavaScript API में जगहों की जानकारी देने वाली यूआई किट के इन एलिमेंट पर लागू होता है:
यह टोकन अन्य अनुरोधों पर लागू नहीं होता. जैसे, Place Search, Advanced Place Search, और Basic Place Autocomplete एलिमेंट, Places API के अनुरोध, और मैप लोड होने से जुड़े अनुरोध. इन अनुरोधों के लिए, स्टैंडर्ड दरों के हिसाब से बिलिंग की जाती है.
सिर्फ़ Maps Experience एजेंट टूल के जवाबों में टोकन शामिल होता है. अगर जगहों की जानकारी देने वाली यूआई किट की मदद से, Google Maps से जानकारी लेने की सुविधा के रिस्पॉन्स में जगहों की जानकारी दिखाई जाती है, तो उन अनुरोधों के लिए स्टैंडर्ड दरों के हिसाब से शुल्क लिया जाता है.
शुरू करने से पहले
एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन का इस्तेमाल करने से पहले, ये सेट अप करें:
- Maps Experience agent tools API (
mapstools.googleapis.com) और जगहों की जानकारी देने वाली यूआई किट API की सुविधा वाला Google क्लाउड प्रोजेक्ट. ज़्यादा जानकारी के लिए, एमसीपी सर्वर का इस्तेमाल करने के लिए एलएलएम कॉन्फ़िगर करना और जगहों की जानकारी देने वाली यूआई किट का इस्तेमाल शुरू करना लेख पढ़ें. - Maps Experience एजेंट टूल कॉल और Maps JavaScript API, दोनों के लिए उस प्रोजेक्ट के क्रेडेंशियल. टोकन सिर्फ़ उस प्रोजेक्ट से जगहों की जानकारी देने वाली यूआई किट के अनुरोधों के लिए मान्य होता है जिसके लिए टोकन जारी किया गया था.
v=betaसेट करके, बीटा चैनल से Maps JavaScript API लोड करने वाला क्लाइंट ऐप्लिकेशन.
भरोसेमंद सोर्स से मिले जवाब में मौजूद जगहों की जानकारी दिखाना
यहां दिए गए सेक्शन में, टूल के रिस्पॉन्स से टोकन पाने और उसे अपने क्लाइंट ऐप्लिकेशन में इस्तेमाल करने का तरीका बताया गया है. अगर Maps एजेंटिक यूआई टूलकिट (एक्सपेरिमेंट के तौर पर उपलब्ध) का इस्तेमाल किया जाता है, तो इसका एजेंट और वेब क्लाइंट आपके लिए ये चरण पूरे करते हैं.
टूल के रिस्पॉन्स से टोकन पाना
search_places टूल, contentToken फ़ील्ड में टोकन दिखाता है. एमसीपी tools/call के अनुरोध के नतीजे में, यह फ़ील्ड structuredContent में होता है. टूल का जवाब कुछ इस तरह का होता है:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
इस आउटपुट में ये वैल्यू शामिल होती हैं:
PLACE_ID: जवाब में किसी जगह का आईडी.CONTENT_TOKEN: जवाब में मौजूद जगहों के लिए, एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन. टोकन को एक ओपेक स्ट्रिंग के तौर पर इस्तेमाल करें और उसमें बदलाव न करें.
अगर जवाब में कोई जगह शामिल नहीं है, तो जवाब में कोई टोकन शामिल नहीं होता.
अपने ऐप्लिकेशन कोड में, टूल के रिस्पॉन्स से टोकन को पढ़ें. उदाहरण के लिए, अपने एजेंट फ़्रेमवर्क में टूल कॉलबैक में. इसके बाद, इसे जगह के आईडी के साथ अपने क्लाइंट ऐप्लिकेशन पर भेजें. एलएलएम पर भरोसा न करें कि वह अपने आउटपुट में टोकन को दोहराएगा, क्योंकि मॉडल टोकन को बदल सकता है.
टोकन में सिर्फ़ वे जगहें शामिल होती हैं जो उसके जवाब में मौजूद होती हैं. अगर आपका एजेंट search_places टूल को एक से ज़्यादा बार कॉल करता है, तो हर टोकन को अपने क्लाइंट ऐप्लिकेशन पर भेजें.
उदाहरण के लिए, अगर Python के लिए एजेंट डेवलपमेंट किट (एडीके) का इस्तेमाल किया जाता है, तो हर टोकन को टूल के बाद वाले कॉलबैक में सेव किया जा सकता है:
from typing import Any, Optional
from google.adk.tools.base_tool import BaseTool
from google.adk.tools.tool_context import ToolContext
def save_content_token(
tool: BaseTool,
args: dict[str, Any],
tool_context: ToolContext,
tool_response: dict[str, Any],
) -> Optional[dict[str, Any]]:
"""Saves the agentic data visualization token from a Maps tool response."""
structured_content = tool_response.get("structuredContent") or {}
token = structured_content.get("contentToken")
if token:
tokens = tool_context.state.get("content_tokens", [])
tool_context.state["content_tokens"] = tokens + [token]
# Return None to pass the original tool response to the model.
return None
एजेंट बनाते समय, इस फ़ंक्शन को after_tool_callback आर्ग्युमेंट के तौर पर पास करें. इसके बाद, सेव किए गए टोकन को एजेंट के जवाब के साथ अपने क्लाइंट ऐप्लिकेशन पर भेजें. एजेंट की पूरी परिभाषाओं के लिए, एमसीपी सर्वर का इस्तेमाल करने के लिए एलएलएम कॉन्फ़िगर करें में ADK के उदाहरण देखें.
टोकन जोड़ना और जगहों की जानकारी दिखाना
अपने क्लाइंट ऐप्लिकेशन में, जगहों के लिए Places यूआई किट के एलिमेंट बनाने से पहले, Settings.getInstance().addContentTokens() को खाली न होने वाली टोकन स्ट्रिंग का एक इटरेबल (जैसे कि कलेक्शन) पास करें. अगर सीधे तौर पर कोई सिंगल स्ट्रिंग पास की जाती है या इटरेबल में कोई खाली स्ट्रिंग शामिल होती है, तो यह तरीका गड़बड़ी दिखाता है. यहां दिए गए उदाहरण में, एक टोकन जोड़ा गया है. इसके बाद, हर जगह के लिए Place Details Compact एलिमेंट दिखाया गया है:
// The token and place IDs come from the search_places tool response.
async function displayGroundedPlaces(contentToken, placeIds) {
const {Settings} = await google.maps.importLibrary('core');
const {
PlaceDetailsCompactElement,
PlaceDetailsPlaceRequestElement,
PlaceStandardContentElement,
} = await google.maps.importLibrary('places');
// Add the token before you create Places UI Kit elements.
Settings.getInstance().addContentTokens([contentToken]);
const container = document.getElementById('agent-response');
for (const placeId of placeIds) {
const placeDetails = new PlaceDetailsCompactElement();
placeDetails.append(
new PlaceDetailsPlaceRequestElement({place: placeId}),
new PlaceStandardContentElement(),
);
container.append(placeDetails);
}
}
टोकन जारी होने के 10 मिनट बाद, उनकी समयसीमा खत्म हो जाती है. Maps JavaScript API, मौजूदा पेज के लिए जोड़े गए टोकन को मेमोरी में सेव रखता है. साथ ही, समयसीमा खत्म होने के बाद उन्हें अपने-आप हटा देता है. इसलिए, आपको समयसीमा खत्म हो चुके टोकन खुद हटाने की ज़रूरत नहीं पड़ती. अगर एक से ज़्यादा जवाबों से टोकन जोड़े जाते हैं, तो एपीआई, स्टोर किए गए सभी टोकन को, काम करने वाले एलिमेंट से मिले हर अनुरोध के साथ भेजता है.
एक एलिमेंट में कई जगहों की जानकारी दिखाने के लिए, ऐडवांस प्लेस लिस्ट एलिमेंट की places प्रॉपर्टी को एक या उससे ज़्यादा जवाबों के जगह के आईडी पर सेट करें. ये जवाब वे होने चाहिए जिनके टोकन आपने जोड़े हैं.
टोकन की पुष्टि करना
जगहों की जानकारी देने वाली यूआई किट के अनुरोध के लिए शुल्क तब नहीं लिया जाता, जब ये सभी शर्तें पूरी होती हैं:
- एक ही प्रोजेक्ट: टोकन उस Google Cloud प्रोजेक्ट को जारी किए गए थे जिसके पास वह एपीआई पासकोड है जिसका इस्तेमाल Maps JavaScript API को लोड करने के लिए किया जाता है.
- तथ्यों पर आधारित जगहें: एलिमेंट के अनुरोध की गई हर जगह, आपके जोड़े गए कम से कम एक टोकन में शामिल होनी चाहिए. अगर हर रिस्पॉन्स से टोकन जोड़ा जाता है, तो किसी एलिमेंट में कई रिस्पॉन्स से मिली जगहों की जानकारी शामिल हो सकती है.
- ऐसे टोकन जिनकी समयसीमा खत्म नहीं हुई है: हर जगह के लिए, अनुरोध उस टोकन के जारी होने के 10 मिनट के अंदर किया जाता है जिसमें वह जगह शामिल है.
- इस्तेमाल किया जा सकने वाला एलिमेंट: अनुरोध, इस्तेमाल किए जा सकने वाले जगहों की जानकारी देने वाली यूआई किट एलिमेंट से आता है.
ऐसे एलिमेंट शामिल नहीं किए जाते जिन्हें आपने किसी जगह के बजाय, किसी जगह की जानकारी के साथ कॉन्फ़िगर किया हो. जैसे, PlaceDetailsLocationRequestElement. अगर ऐडवांस प्लेस लिस्ट एलिमेंट में कोई ऐसी जगह शामिल है जो कवर नहीं की गई है, तो पूरे अनुरोध के लिए बिल भेजा जाता है.
अगर कोई शर्त पूरी नहीं होती है, तो भी एलिमेंट लोड होता है. साथ ही, अनुरोध के लिए उसके एसकेयू की स्टैंडर्ड दर के हिसाब से बिल भेजा जाता है. टोकन के अमान्य होने पर, Maps JavaScript API कोई गड़बड़ी नहीं दिखाता.
बिलिंग
Maps Experiments के एजेंट टूल के हर अनुरोध के लिए, आपको सामान्य दर के हिसाब से पेमेंट करना होगा. Places यूआई किट के जिन अनुरोधों की टोकन की पुष्टि हो जाती है उनके लिए शुल्क नहीं लिया जाता. हालांकि, उन्हें Places यूआई किट के कोटे में गिना जाता है. जगहों की जानकारी देने वाली यूआई किट के जिन अनुरोधों की पुष्टि नहीं हो पाती है उनके लिए, Places UI Kit Query या Places UI Kit Pro (Advanced) एसकेयू के लिए तय की गई सामान्य दर के हिसाब से बिलिंग की जाती है.
कीमतों के लिए, कीमतों की मुख्य टेबल और भारत के लिए कीमतों की टेबल देखें.
इस्तेमाल से जुड़ी ज़रूरी शर्तें
सिर्फ़ एक उपयोगकर्ता के लिए, ऐक्टिव-रिस्पॉन्स के तौर पर इस्तेमाल करना: आपको एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन का इस्तेमाल सिर्फ़ उसी असली उपयोगकर्ता को जगहों की जानकारी देने वाली यूआई किट के काम करने वाले एलिमेंट दिखाने के लिए करना चाहिए. साथ ही, यह टोकन जनरेट करने वाले एजेंटिक रिस्पॉन्स के अंदर ही होना चाहिए. आपको एक से ज़्यादा असली उपयोगकर्ताओं के साथ टोकन शेयर नहीं करने चाहिए, उन्हें पूल नहीं करना चाहिए या उन्हें फिर से इस्तेमाल नहीं करना चाहिए. इसके अलावा, आपको उस जवाब के बाहर की जगहों को दिखाने के लिए टोकन का इस्तेमाल नहीं करना चाहिए. जैसे, सेव की गई सूचियों, बुकमार्क या कैश मेमोरी में सेव की गई डायरेक्ट्री में.
एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन के इस्तेमाल पर, Google Maps Platform की सेवा की शर्तें लागू होती हैं. इनमें सेवा से जुड़ी खास शर्तें भी शामिल हैं. Maps Experience एजेंट टूल के लिए, जानकारी के स्रोत की ज़रूरी शर्तें भी लागू होती हैं.