এজেন্টিক ডেটা ভিজ্যুয়ালাইজেশন টোকেন আপনার এজেন্টিক অ্যাপকে
Maps Experience এজেন্ট টুল (আগে
Maps Grounding Lite নামে পরিচিত ছিল) রেসপন্সে কোনও অতিরিক্ত খরচ ছাড়াই
Places UI Kit এলিমেন্ট
দেখানোর অনুমতি দেয়। search_places টুলে
প্রতিটি সফল কল একটি টোকেন রিটার্ন করে যা Essentials এবং Pro SKU, উভয়ের জন্যই
উত্তরে জায়গা শনাক্ত করে। আপনার ক্লায়েন্ট অ্যাপ Maps JavaScript API-তে
টোকেন যোগ করলে, টোকেন ইস্যু করার পরে ১০ মিনিট পর্যন্ত Places UI Kit-এর করা অনুরোধের জন্য
বিল করা হয় না।
এটি কীভাবে কাজ করে
টোকেনটি আপনার দেখানো জায়গার বিবরণের সাথে গ্রাউন্ডেড উত্তরকে কানেক্ট করে এর সাথে:
- আপনার এজেন্ট Maps Experience এজেন্ট টুল MCP সার্ভারে
search_placesটুল কল করে। টুল থেকে পাওয়া উত্তরে সেইসব জায়গা অন্তর্ভুক্ত থাকে যা সারসংক্ষেপকে সমর্থন করে এবংcontentTokenফিল্ডে একটি টোকেন থাকে। - আপনার অ্যাপ টুল রেসপন্স থেকে টোকেন পড়ে এবং আপনি যেসব জায়গার আইডি দেখাতে চান, সেগুলির সাথে আপনার ক্লায়েন্ট অ্যাপে সেটি পাঠায়।
- আপনার ক্লায়েন্ট অ্যাপ Maps JavaScript API-তে টোকেন যোগ করে এবং সেইসব জায়গার জন্য Places UI Kit এলিমেন্ট তৈরি করে।
- Google Maps Platform প্রতিটি Places UI Kit অনুরোধের সাথে টোকেন যাচাই করে। টোকেনটি সঠিক হলে, অনুরোধের জন্য বিল করা হয় না।
কাজ করে এমন Places UI Kit এলিমেন্ট
Maps JavaScript API-তে নিম্নলিখিত Places UI Kit এলিমেন্টের ক্ষেত্রে টোকেন প্রযোজ্য:
টোকেনটি অন্যান্য অনুরোধের ক্ষেত্রে প্রযোজ্য নয়, যেমন Place Search, Advanced Place Search এবং Basic Place Autocomplete এলিমেন্ট, Places API অনুরোধ এবং ম্যাপ লোড থেকে অনুরোধ। এইসব অনুরোধের জন্য স্ট্যান্ডার্ড রেটে বিল করা হয়।
শুধুমাত্র Maps Experience এজেন্ট টুলের উত্তরে টোকেন অন্তর্ভুক্ত থাকে। আপনি যদি Places UI Kit-এর মাধ্যমে Grounding with Google Maps-এর উত্তর থেকে জায়গা দেখান, তাহলে সেইসব অনুরোধের জন্য স্ট্যান্ডার্ড রেটে বিল করা হয়।
শুরু করার আগে
এজেন্টিক ডেটা ভিজ্যুয়ালাইজেশন টোকেন ব্যবহার করার আগে, নিম্নলিখিতগুলি সেট-আপ করুন:
- Maps Experience এজেন্ট টুল API (
mapstools.googleapis.com) এবং Places UI Kit API চালু করা আছে এমন একটি Google Cloud প্রোজেক্ট। আরও তথ্যের জন্য, MCP সার্ভার ব্যবহার করার জন্য LLM কনফিগার করুন এবং Places UI Kit ব্যবহার শুরু করুন দেখুন। - আপনার Maps Experience এজেন্ট টুল কল এবং Maps JavaScript API, উভয়ের জন্যই সেই প্রোজেক্টের ক্রেডেনশিয়াল। একটি টোকেন শুধুমাত্র Places UI Kit-এর জন্য বৈধ যে প্রোজেক্টের জন্য টোকেনটি ইস্যু করা হয়েছে তার থেকে অনুরোধ।
- একটি ক্লায়েন্ট অ্যাপ যা
v=betaসেট করে বিটা চ্যানেল থেকে Maps JavaScript API লোড করে।
গ্রাউন্ডেড উত্তর থেকে জায়গা দেখান
টুল রেসপন্স থেকে কীভাবে টোকেন পাবেন এবং আপনার ক্লায়েন্ট অ্যাপে সেটি কীভাবে ব্যবহার করবেন তা নিম্নলিখিত বিভাগে দেখানো হয়েছে। আপনি Maps Agentic UI Toolkit (এক্সপেরিমেন্টাল) ব্যবহার করলে, এর এজেন্ট এবং ওয়েব ক্লায়েন্ট আপনার জন্য এইসব ধাপ ম্যানেজ করে।
টুল রেসপন্স থেকে টোকেন পান
search_places টুল contentToken ফিল্ডে টোকেন ফেরত দেয়। MCP tools/call অনুরোধের
ফলাফলে, এই ফিল্ডটি structuredContent-এ আছে। টুল
থেকে পাওয়া উত্তর নিচে উল্লেখ করা উত্তরের মতো:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
এই আউটপুটে নিম্নলিখিত ভ্যালু অন্তর্ভুক্ত থাকে:
PLACE_ID: উত্তরে উল্লেখ করা জায়গার আইডি।CONTENT_TOKEN: উত্তরে দেখানো জায়গার জন্য এজেন্টিক ডেটা ভিজ্যুয়ালাইজেশন টোকেন। টোকেনটিকে একটি অস্বচ্ছ স্ট্রিং হিসেবে বিবেচনা করুন এবং এটি পরিবর্তন করবেন না।
উত্তরে কোনও জায়গা না থাকলে, উত্তরে কোনও টোকেন থাকে না।
আপনার অ্যাপ কোডে, টুল রেসপন্স থেকে টোকেনটি পড়ুন—যেমন, আপনার এজেন্ট ফ্রেমওয়ার্কে একটি টুল কলব্যাকে—এবং জায়গার আইডি সহ আপনার ক্লায়েন্ট অ্যাপে পাঠান। LLM-এর আউটপুটে টোকেন রিপিট করার জন্য LLM-এর উপর নির্ভর করবেন না, কারণ মডেল টোকেন পরিবর্তন করতে পারে।
একটি টোকেন শুধুমাত্র তার নিজস্ব উত্তরে থাকা জায়গাগুলি কভার করে। আপনার এজেন্ট
search_places টুলকে একাধিকবার কল করলে, প্রতিটি টোকেন আপনার ক্লায়েন্ট অ্যাপে পাঠান।
যেমন, আপনি Python-এর জন্য Agent Development Kit (ADK) ব্যবহার করলে, আপনি প্রতিটি টোকেন আফটার-টুল কলব্যাকে সেভ করতে পারবেন:
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 আর্গুমেন্ট হিসেবে পাস করুন এবং তারপরে এজেন্টের উত্তরের সাথে সেভ করা টোকেন আপনার ক্লায়েন্ট অ্যাপে পাঠান। এজেন্টের সম্পূর্ণ সংজ্ঞার জন্য,
MCP সার্ভার ব্যবহার করার জন্য LLM কনফিগার করুন-এ ADK-এর উদাহরণ দেখুন।
টোকেন যোগ করুন এবং জায়গাগুলি দেখান
আপনার ক্লায়েন্ট অ্যাপে, জায়গার জন্য Places UI Kit এলিমেন্ট তৈরি করার আগে Settings.getInstance().addContentTokens()-এ খালি নয় এমন টোকেন স্ট্রিংয়ের ইটারেবল (যেমন, অ্যারে) পাস করুন। আপনি সরাসরি একটি স্ট্রিং পাস করলে বা ইটারেবলে খালি স্ট্রিং থাকলে,
এই পদ্ধতিটি একটি ত্রুটি দেখায়। নিচের
উদাহরণটি একটি টোকেন যোগ করে এবং তারপরে প্রতিটি জায়গার জন্য একটি জায়গার বিবরণ কম্প্যাক্ট এলিমেন্ট
দেখায়:
// 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);
}
}
টোকেন ইস্যু করার ১০ মিনিট পরে সেটির মেয়াদ শেষ হয়ে যায়। Maps JavaScript API বর্তমান পৃষ্ঠার জন্য মেমরিতে আপনার যোগ করা টোকেনগুলি রাখে এবং মেয়াদ শেষ হওয়ার পরে সেগুলি অটোমেটিক সরিয়ে দেয়, তাই আপনাকে মেয়াদ শেষ হওয়া টোকেনগুলি নিজে সরাতে হবে না। আপনি একাধিক উত্তর থেকে টোকেন যোগ করলে, API প্রতিটি অনুরোধের সাথে কাজ করে এমন এলিমেন্ট থেকে সব স্টোর করা টোকেন পাঠায়।
একটি এলিমেন্টে একাধিক জায়গা দেখাতে,
উন্নত জায়গার তালিকা এলিমেন্ট-এর
places প্রপার্টিকে এক বা একাধিক উত্তরের জায়গা আইডিতে সেট করুন, যার টোকেন আপনি যোগ করেছেন।
টোকেন যাচাইকরণ
নিম্নলিখিত সব শর্ত পূরণ হলে Places UI Kit অনুরোধের জন্য বিল করা হয় না:
- একই প্রোজেক্ট: Maps JavaScript API লোড করার জন্য আপনি যে API কী ব্যবহার করেন, সেই API কী-এর মালিকানা যে Google Cloud প্রোজেক্টের কাছে আছে, সেই প্রোজেক্টের জন্য টোকেন ইস্যু করা হয়েছে।
- গ্রাউন্ডেড জায়গা: এলিমেন্ট যেসব জায়গার জন্য অনুরোধ করে, তার প্রত্যেকটি আপনার যোগ করা অন্তত একটি টোকেন দ্বারা কভার করা হয়। আপনি প্রতিটি উত্তর থেকে টোকেন যোগ করলে, একটি এলিমেন্টে একাধিক উত্তরের জায়গা অন্তর্ভুক্ত থাকতে পারে।
- মেয়াদ শেষ না হওয়া টোকেন: প্রতিটি জায়গার জন্য, টোকেন ইস্যু করার ১০ মিনিটের মধ্যে অনুরোধ করা হয়।
- কাজ করে এমন এলিমেন্ট: অনুরোধটি কাজ করে এমন Places UI Kit এলিমেন্ট থেকে আসে।
আপনি কোনও জায়গার পরিবর্তে লোকেশন দিয়ে যেসব এলিমেন্ট কনফিগার করেন, যেমন
PlaceDetailsLocationRequestElement, সেগুলি কভার করা হয় না। কোনও উন্নত জায়গার তালিকা
এলিমেন্টে যদি এমন কোনও জায়গা অন্তর্ভুক্ত থাকে যা কভার করা হয়নি, তাহলে পুরো অনুরোধের জন্য বিল করা হয়।
কোনও শর্ত পূরণ না হলে, এলিমেন্টটি এখনও লোড হয় এবং অনুরোধটি তার SKU-এর জন্য স্ট্যান্ডার্ড রেটে বিল করা হয়। টোকেন সঠিক না হলে Maps JavaScript API কোনও সমস্যা দেখায় না।
বিলিং
আপনি প্রতিটি Maps Experience এজেন্ট টুল অনুরোধের জন্য এর স্ট্যান্ডার্ড রেটে পেমেন্ট করেন। Places UI Kit-এর যেসব অনুরোধ টোকেন যাচাইকরণ পাস করে, সেগুলির জন্য বিল করা হয় না, তবে সেগুলি আপনার Places UI Kit কোটায় গণনা করা হয়। Places UI Kit অনুরোধ যা টোকেন যাচাইকরণ পাস করে না সেগুলির জন্য স্ট্যান্ডার্ড রেটে বিল করা হয় Places UI Kit Query বা Places UI Kit Pro (Advanced) SKU-এর জন্য।
দাম জানতে, মূল দামের টেবিল এবং ভারতের দামের টেবিল দেখুন।
ব্যবহার সংক্রান্ত প্রয়োজনীয়তা
একক-ব্যবহারকারী, শুধুমাত্র অ্যাক্টিভ-রেসপন্স ব্যবহার: আপনাকে অবশ্যই একটি এজেন্টিক ডেটা ভিজ্যুয়ালাইজেশন টোকেন ব্যবহার করতে হবে শুধুমাত্র একই ব্যবহারকারীকে এবং টোকেন তৈরি করা অবিলম্বে এজেন্টিক প্রতিক্রিয়ার মধ্যে সমর্থিত Places UI Kit এলিমেন্ট দেখানোর জন্য। আপনি একাধিক ব্যবহারকারীর মধ্যে টোকেন শেয়ার, পুল বা আবার ব্যবহার করতে পারবেন না অথবা সেই উত্তরের বাইরে জায়গা দেখানোর জন্য টোকেন ব্যবহার করতে পারবেন না (যেমন, সেভ করা তালিকা, বুকমার্ক বা ক্যাশে করা ডিরেক্টরিতে)।
এজেন্টিক ডেটা ভিজ্যুয়ালাইজেশন টোকেন ব্যবহার করার ক্ষেত্রে Google Maps Platform পরিষেবার শর্তাবলী প্রযোজ্য, যার মধ্যে পরিষেবা-নির্দিষ্ট শর্তাবলী অন্তর্ভুক্ত। Maps Experience এজেন্ট টুলের জন্য অ্যাট্রিবিউশন সংক্রান্ত প্রয়োজনীয়তা প্রযোজ্য।