Temsilci tabanlı veri görselleştirme jetonu, temsilci tabanlı uygulamanızın, Maps Experience temsilci araçları (eski adıyla Maps Grounding Lite) yanıtındaki yerler için Places UI Kit öğelerini ek ücret ödemeden göstermesine olanak tanır. search_places aracına yapılan her başarılı çağrı, hem Essentials hem de Pro SKU'ları için yanıttaki yerleri tanımlayan bir jeton döndürür. İstemci uygulamanız jetonu Maps JavaScript API'ye eklediğinde, bu yerler için Places UI Kit istekleri, jetonun verilmesinden sonraki 10 dakika boyunca faturalandırılmaz.
İşleyiş şekli
Jeton, dayanaklı bir yanıtı, yanıtla birlikte gösterdiğiniz yer ayrıntılarına bağlar:
- Temsilciniz, Haritalar Deneyimi temsilci araçları MCP sunucusundaki
search_placesaracını çağırır. Aracın yanıtı, özeti destekleyen yerleri vecontentTokenalanında bir jeton içerir. - Uygulamanız, araç yanıtındaki jetonu okur ve göstermek istediğiniz yerlerin kimlikleriyle birlikte istemci uygulamanıza gönderir.
- İstemci uygulamanız, jetonu Maps JavaScript API'ye ekler ve bu yerler için Places UI Kit öğeleri oluşturur.
- Google Haritalar Platformu, her Places UI Kit isteğinde jetonu doğrular. Jeton geçerliyse istek faturalandırılmaz.
Desteklenen Places UI Kit öğeleri
Jeton, Maps JavaScript API'deki aşağıdaki Places UI Kit öğeleri için geçerlidir:
Jeton; Yer Arama, Gelişmiş Yer Arama ve Temel Yer Adı Otomatik Tamamlama öğelerinden gelen istekler, Places API istekleri ve harita yüklemeleri gibi diğer istekler için geçerli değildir. Bu istekler standart ücretlerle faturalandırılır.
Yalnızca Haritalar Deneyimi temsilci araçlarının yanıtları jetonu içerir. Google Haritalar ile Temellendirme yanıtındaki yerleri Places UI Kit ile gösterirseniz bu istekler standart ücretlerle faturalandırılır.
Başlamadan önce
Temsilci veri görselleştirme jetonunu kullanmadan önce aşağıdakileri ayarlayın:
- Maps Experience Agent Tools API (
mapstools.googleapis.com) ve Places UI Kit API'nin etkinleştirildiği bir Google Cloud projesi Daha fazla bilgi için LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma ve Places UI Kit'i kullanmaya başlama başlıklı makaleleri inceleyin. - Hem Maps Experiments temsilci araçları çağrılarınız hem de Maps JavaScript API için bu projeden alınan kimlik bilgileri. Jeton yalnızca, jetonun verildiği projeden gelen Places UI Kit istekleri için geçerlidir.
v=betaayarını yaparak Maps JavaScript API'yi beta kanalından yükleyen bir istemci uygulaması.
Temellendirilmiş yanıttaki yerleri gösterme
Aşağıdaki bölümlerde, jetonun araç yanıtından nasıl alınacağı ve istemci uygulamanızda nasıl kullanılacağı gösterilmektedir. Haritalar ajan tabanlı kullanıcı arayüzü araç seti'ni (deneysel) kullanıyorsanız bu adımları aracısı ve web istemcisi sizin için gerçekleştirir.
Araç yanıtından jetonu alma
search_places aracı, jetonu contentToken alanında döndürür. MCP tools/call isteğinin sonucunda bu alan structuredContent biçimindedir. Aracın yanıtı aşağıdakine benzer:
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
Bu çıkış aşağıdaki değerleri içerir:
PLACE_ID: Yanıttaki bir yerin yer kimliği.CONTENT_TOKEN: Yanıttaki yerler için temsilci veri görselleştirme jetonu. Jetonu opak bir dize olarak değerlendirin ve değiştirmeyin.
Yanıtta yer yoksa yanıt bir jeton içermez.
Uygulama kodunuzda, araç yanıtındaki jetonu okuyun (ör. temsilci çerçevenizdeki bir araç geri çağırma işlevinde) ve yer kimlikleriyle birlikte istemci uygulamanıza gönderin. Model, jetonu değiştirebileceğinden LLM'nin çıktısında jetonu tekrarlayacağına güvenmeyin.
Bir jeton yalnızca kendi yanıtındaki yerleri kapsar. Temsilciniz search_places aracını birden fazla kez çağırırsa her jetonu istemci uygulamanıza gönderin.
Örneğin, Python için Agent Development Kit (ADK) kullanıyorsanız her jetonu bir araç sonrası geri çağırmaya kaydedebilirsiniz:
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
Temsilcinizi oluştururken bu işlevi after_tool_callback bağımsız değişkeni olarak iletin ve ardından kaydedilen jetonları temsilcinin yanıtıyla birlikte istemci uygulamanıza gönderin. Temsilci tanımlarının tamamı için LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma bölümündeki ADK örneklerine bakın.
Jetonu ekleme ve yerleri görüntüleme
İstemci uygulamanızda, yerler için Places UI Kit öğeleri oluşturmadan önce boş olmayan jeton dizelerinin yinelenebilir bir öğesini (ör. dizi) Settings.getInstance().addContentTokens() yöntemine iletin. Doğrudan tek bir dize iletirseniz veya yinelenebilir öğe boş bir dize içeriyorsa yöntem bir hata verir. Aşağıdaki örnekte bir jeton eklenir ve ardından her yer için bir Yer Ayrıntıları Kompakt öğesi gösterilir:
// 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);
}
}
Jetonların süresi, oluşturulduktan 10 dakika sonra sona erer. Maps JavaScript API, eklediğiniz jetonları geçerli sayfa için bellekte tutar ve süresi dolduktan sonra otomatik olarak kaldırır. Bu nedenle, süresi dolmuş jetonları kendiniz kaldırmanız gerekmez. Birden fazla yanıttan jeton eklerseniz API, depolanan tüm jetonları desteklenen bir öğeden gelen her istekle birlikte gönderir.
Tek bir öğede birden fazla yer göstermek için Gelişmiş Yer Listesi öğesinin places özelliğini, jetonlarını eklediğiniz bir veya daha fazla yanıttaki yer kimliklerine ayarlayın.
Jeton doğrulama
Aşağıdaki koşulların tümü karşılandığında Places UI Kit isteği faturalandırılmaz:
- Aynı proje: Jetonlar, Maps JavaScript API'yi yüklemek için kullandığınız API anahtarının sahibi olan Google Cloud projesine verilmiştir.
- Temellendirilmiş yerler: Öğenin istediği her yer, eklediğiniz en az bir jetonla kapsanır. Her yanıttan jeton eklerseniz bir öğe birden fazla yanıttaki yerleri içerebilir.
- Süresi dolmamış jetonlar: Her yer için istek, yeri kapsayan bir jetonun verildiği tarihten itibaren 10 dakika içinde yapılır.
- Desteklenen öğe: İstek, desteklenen bir Places UI Kit öğesinden gelir.
PlaceDetailsLocationRequestElement gibi bir yer yerine konumla yapılandırdığınız öğeler kapsama dahil değildir. Advanced Place List öğesi, kapsanmayan bir yer içeriyorsa isteğin tamamı faturalandırılır.
Herhangi bir koşul karşılanmazsa öğe yine de yüklenir ve istek, SKU'su için standart ücret üzerinden faturalandırılır. Maps JavaScript API, jeton geçerli olmadığında hata döndürmez.
Faturalandırma
Her bir Maps Experiments temsilci araçları isteği için standart ücret üzerinden ödeme yaparsınız. Jeton doğrulamasını geçen Places UI Kit istekleri faturalandırılmaz ancak Places UI Kit kotanıza dahil edilir. Jeton doğrulamasını geçemeyen Places UI Kit istekleri, Places UI Kit Query veya Places UI Kit Pro (Advanced) SKU'su için standart ücret üzerinden faturalandırılır.
Fiyatlar için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.
Kullanım şartları
Yalnızca tek kullanıcı ve etkin yanıt kullanımı: Temsilci veri görselleştirme jetonunu yalnızca desteklenen Places UI Kit öğelerini aynı son kullanıcıya ve jetonu oluşturan anlık temsilci yanıtı içinde göstermek için kullanmanız gerekir. Jetonları birden fazla son kullanıcı arasında paylaşmamalı, birleştirmemeli veya yeniden kullanmamalı ya da bir jetonu, ilgili yanıtın dışındaki yerleri (ör. kayıtlı listeler, yer işaretleri veya önbelleğe alınmış dizinler) göstermek için kullanmamalısınız.
Temsilci veri görselleştirme jetonunu kullanımınız, hizmete özel şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'na tabidir. Haritalar Deneyimi temsilci araçları için ilişkilendirme şartları da geçerlidir.