Temsilci tabanlı veri görselleştirme jetonu

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örüntülemesine olanak tanır. search_places veya search_along_route 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:

1. Temsilciniz, Maps Experience temsilci araçları MCP sunucusunda search_places veya search_along_route aracını çağırır. Aracın yanıtında, özeti destekleyen yerler ve contentToken alanında bir jeton bulunur.
2. Uygulamanız, araç yanıtındaki jetonu okur ve göstermek istediğiniz yerlerin kimlikleriyle birlikte istemci uygulamanıza gönderir.
3. İstemci uygulamanız, jetonu Maps JavaScript API'ye ekler ve bu yerler için Places UI Kit öğeleri oluşturur.
4. 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ı 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 Haritalar deneyimi 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=beta ayarı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, aracın yanıtından jetonun 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 aracısı ve web istemcisi bu adımları sizin için gerçekleştirir.

Araç yanıtından jetonu alma

search_places ve search_along_route araçları, jetonu contentToken alanında döndürür. Bir MCP tools/call isteğinin sonucunda bu alan structuredContent biçimindedir. searchText veya searchAlongRoute REST yönteminden gelen yanıtta üst düzey bir alandır. search_places yanıtı, aşağıdakine benzer (search_along_route yanıtı, her yeri results[].place içinde döndürür):

{
  "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 herhangi bir yer yoksa yanıt bir jeton içermez.

Uygulama kodunuzda, araç yanıtındaki jetonu okuyun (örneğin, 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 veya search_along_route yöntemini 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ğırma işlevine 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 Settings.getInstance().addContentTokens() öğesine boş olmayan jeton dizelerinden oluşan bir yinelenebilir (ör. dizi) 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 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);
  }
}

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üreleri dolduktan sonra otomatik olarak kaldırır. Bu nedenle, süresi dolan 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 andan 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. Gelişmiş Yer Listesi öğ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 Maps Experiments ajan araçları isteği için standart ücreti ödersiniz. 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 tabanlı veri görselleştirme jetonunu yalnızca desteklenen Places UI Kit öğelerini aynı son kullanıcıya ve jetonu oluşturan anlık temsilci tabanlı 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 bu yanıtın dışındaki yerleri (ör. kayıtlı listeler, yer işaretleri veya önbelleğe alınmış dizinler) göstermek için jeton 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.