एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन

एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन की मदद से, आपका एजेंटिक ऐप्लिकेशन, Maps Experience एजेंट टूल (पहले Maps Grounding Lite के नाम से जाना जाता था) के रिस्पॉन्स में जगहों के लिए, जगहों की जानकारी देने वाली यूआई किट के एलिमेंट दिखा सकता है. इसके लिए, कोई शुल्क नहीं देना पड़ता. search_places या search_along_route टूल को किए गए हर सफल कॉल से, एक टोकन मिलता है. यह टोकन, जवाब में जगहों की पहचान करता है. यह Essentials और Pro, दोनों एसकेयू के लिए होता है. जब आपका क्लाइंट ऐप्लिकेशन, Maps JavaScript API में टोकन जोड़ता है, तो जगहों की जानकारी देने वाली यूआई किट से उन जगहों के लिए किए गए अनुरोधों के लिए, टोकन जारी होने के बाद 10 मिनट तक शुल्क नहीं लिया जाता.

यह कैसे काम करता है

टोकन, ग्राउंडेड रिस्पॉन्स को उस जगह की जानकारी से जोड़ता है जिसे आपने उसके साथ दिखाया है:

1. आपका एजेंट, Maps Experience एजेंट टूल के एमसीपी सर्वर पर search_places या search_along_route टूल को कॉल करता है. टूल के जवाब में, समरी में दी गई जानकारी को सपोर्ट करने वाली जगहों की जानकारी और contentToken फ़ील्ड में एक टोकन शामिल होता है.
2. आपका ऐप्लिकेशन, टूल के रिस्पॉन्स से टोकन को पढ़ता है और उसे आपके क्लाइंट ऐप्लिकेशन को भेजता है. साथ ही, उन जगहों के आईडी भी भेजता है जिन्हें आपको दिखाना है.
3. आपका क्लाइंट ऐप्लिकेशन, Maps JavaScript API में टोकन जोड़ता है और उन जगहों के लिए Places यूआई किट के एलिमेंट बनाता है.
4. Google Maps Platform, जगहों की जानकारी देने वाली यूआई किट के हर अनुरोध के साथ टोकन की पुष्टि करता है. अगर टोकन मान्य है, तो अनुरोध के लिए शुल्क नहीं लिया जाता.

जगहों की जानकारी देने वाली यूआई किट के साथ काम करने वाले एलिमेंट

यह टोकन, Maps JavaScript API में जगहों की जानकारी देने वाली यूआई किट के इन एलिमेंट पर लागू होता है:

यह टोकन अन्य अनुरोधों पर लागू नहीं होता. जैसे, Place Search, Advanced Place Search, और Basic Place Autocomplete एलिमेंट, Places API के अनुरोध, और मैप लोड करने के अनुरोध. इन अनुरोधों के लिए, स्टैंडर्ड दरों के हिसाब से बिलिंग की जाती है.

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

शुरू करने से पहले

एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन का इस्तेमाल करने से पहले, ये सेट अप करें:

• Maps Experience agent tools API (mapstools.googleapis.com) और जगहों की जानकारी देने वाली यूआई किट API की सुविधा वाला Google क्लाउड प्रोजेक्ट. ज़्यादा जानकारी के लिए, एमसीपी सर्वर का इस्तेमाल करने के लिए एलएलएम कॉन्फ़िगर करना और जगहों की जानकारी देने वाली यूआई किट का इस्तेमाल शुरू करना लेख पढ़ें.
• Maps एक्सपीरियंस एजेंट टूल कॉल और Maps JavaScript API, दोनों के लिए उस प्रोजेक्ट के क्रेडेंशियल. टोकन सिर्फ़ उस प्रोजेक्ट से जगहों की जानकारी देने वाली यूआई किट के अनुरोधों के लिए मान्य होता है जिसके लिए टोकन जारी किया गया था.
• v=beta सेट करके, बीटा चैनल से Maps JavaScript API लोड करने वाला क्लाइंट ऐप्लिकेशन.

भरोसेमंद सोर्स से मिले जवाब में जगहों की जानकारी दिखाना

यहां दिए गए सेक्शन में, टूल के रिस्पॉन्स से टोकन पाने और उसे अपने क्लाइंट ऐप्लिकेशन में इस्तेमाल करने का तरीका बताया गया है. अगर Maps एजेंटिक यूआई टूलकिट (एक्सपेरिमेंट के तौर पर उपलब्ध) का इस्तेमाल किया जाता है, तो इसका एजेंट और वेब क्लाइंट आपके लिए ये चरण पूरे करते हैं.

टूल के रिस्पॉन्स से टोकन पाना

search_places और search_along_route टूल, टोकन को contentToken फ़ील्ड में दिखाते हैं. एमसीपी tools/call के अनुरोध के नतीजे में, यह फ़ील्ड structuredContent में होता है. searchText या searchAlongRoute REST तरीके से मिले जवाब में, यह टॉप-लेवल फ़ील्ड होता है. search_places का रिस्पॉन्स, इस तरह का होता है (search_along_route रिस्पॉन्स, results[].place में मौजूद हर जगह की जानकारी दिखाता है):

{
  "places": [
    {
      "place": "places/PLACE_ID",
      "id": "PLACE_ID"
    }
  ],
  "contentToken": "CONTENT_TOKEN"
}

इस आउटपुट में ये वैल्यू शामिल होती हैं:

• PLACE_ID: जवाब में किसी जगह का आईडी.
• CONTENT_TOKEN: जवाब में मौजूद जगहों के लिए, एजेंटिक डेटा विज़ुअलाइज़ेशन टोकन. टोकन को ओपेक स्ट्रिंग के तौर पर इस्तेमाल करें और उसमें बदलाव न करें.

अगर जवाब में कोई जगह शामिल नहीं है, तो जवाब में कोई टोकन शामिल नहीं होता.

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

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

उदाहरण के लिए, अगर 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 or search_along_route 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 एक्सपीरियंस एजेंट टूल के हर अनुरोध के लिए, आपको सामान्य दर के हिसाब से पेमेंट करना होगा. Places यूआई किट के जिन अनुरोधों की टोकन की पुष्टि हो जाती है उनके लिए शुल्क नहीं लिया जाता. हालांकि, उन्हें Places यूआई किट के कोटे में गिना जाता है. जगहों की जानकारी देने वाली यूआई किट के जिन अनुरोधों की पुष्टि नहीं हो पाती है उनके लिए, Places UI Kit Query या Places UI Kit Pro (ऐडवांस) एसकेयू के लिए तय की गई सामान्य दर के हिसाब से बिलिंग की जाती है.

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

इस्तेमाल से जुड़ी ज़रूरी शर्तें

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

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