Token visualisasi data agentic

Produk atau fitur ini ada dalam Pratinjau (pra-GA). Produk dan fitur pra-GA mungkin memiliki dukungan terbatas, dan perubahan pada produk serta fitur pra-GA mungkin tidak kompatibel dengan versi pra-GA lainnya. Penawaran Pra-GA tercakup dalam Persyaratan Khusus Layanan Google Maps Platform. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan: Token visualisasi data agentic hanya didukung untuk aplikasi web yang menggunakan Maps JavaScript API. Dukungan untuk Kit UI Places di Places SDK for Android dan Places SDK for iOS akan segera hadir.

Token visualisasi data agentic memungkinkan aplikasi agentic Anda menampilkan elemen Kit UI Tempat untuk tempat dalam respons alat agen Maps Experience (sebelumnya Maps Grounding Lite) tanpa biaya tambahan. Setiap panggilan yang berhasil ke alat search_places akan menampilkan token yang mengidentifikasi tempat dalam respons, baik untuk SKU Essentials maupun Pro. Saat aplikasi klien Anda menambahkan token ke Maps JavaScript API, permintaan Kit UI Places untuk tempat tersebut tidak akan ditagih selama 10 menit setelah token diterbitkan.

Cara kerjanya

Token menghubungkan respons yang di-grounding ke Place Details yang Anda tampilkan bersamanya:

1. Agen Anda memanggil alat search_places di server MCP alat agen Maps Experience. Respons alat mencakup tempat yang mendukung ringkasan dan token di kolom contentToken.
2. Aplikasi Anda membaca token dari respons alat dan mengirimkannya ke aplikasi klien, beserta ID tempat yang ingin Anda tampilkan.
3. Aplikasi klien Anda menambahkan token ke Maps JavaScript API dan membuat elemen Kit UI Tempat untuk tempat tersebut.
4. Google Maps Platform memvalidasi token dengan setiap permintaan Places UI Kit. Jika token valid, permintaan tidak akan ditagih.

Elemen Places UI Kit yang didukung

Token ini berlaku untuk elemen Places UI Kit berikut di Maps JavaScript API:

Elemen	SKU
PlaceDetailsElement	Kueri Kit UI Places
PlaceDetailsCompactElement	Kueri Kit UI Places
AdvancedPlaceDetailsElement	Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactElement	Places UI Kit Pro (Advanced)
AdvancedPlaceListElement	Places UI Kit Pro (Advanced)

Token ini tidak berlaku untuk permintaan lain, seperti permintaan dari elemen Place Search, Advanced Place Search, dan Basic Place Autocomplete, permintaan Places API, dan pemuatan peta. Permintaan ini ditagih dengan tarif standar.

Hanya respons alat agen Maps Experience yang menyertakan token. Jika Anda menampilkan tempat dari respons Grounding with Google Maps menggunakan Places UI Kit, permintaan tersebut akan ditagih dengan tarif standar.

Sebelum memulai

Sebelum Anda menggunakan token visualisasi data agentic, siapkan hal berikut:

• Project Google Cloud dengan API alat agen Maps Experience (mapstools.googleapis.com) dan Places UI Kit API diaktifkan. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi LLM untuk menggunakan server MCP dan Memulai Kit UI Tempat.
• Kredensial dari project tersebut untuk panggilan alat agen Maps Experience dan Maps JavaScript API. Token hanya valid untuk permintaan Places UI Kit dari project yang menerima token tersebut.
• Aplikasi klien yang memuat Maps JavaScript API dari saluran beta dengan menetapkan v=beta.

Menampilkan tempat dari respons yang di-grounding pada sumber informasi

Bagian berikut menunjukkan cara mendapatkan token dari respons alat dan menggunakannya di aplikasi klien Anda. Jika Anda menggunakan Maps Agentic UI Toolkit (Eksperimental), agen dan klien webnya akan menangani langkah-langkah ini untuk Anda.

Mendapatkan token dari respons alat

Alat search_places menampilkan token di kolom contentToken. Dalam hasil permintaan tools/call MCP, kolom ini berada di structuredContent. Respons alat ini mirip dengan berikut ini:

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

Output ini mencakup nilai-nilai berikut:

• PLACE_ID: ID tempat dari suatu tempat dalam respons.
• CONTENT_TOKEN: Token visualisasi data agentic untuk tempat dalam respons. Perlakukan token sebagai string buram, dan jangan ubah token tersebut.

Jika respons tidak menyertakan tempat, respons tidak akan menyertakan token.

Dalam kode aplikasi, baca token dari respons alat—misalnya, dalam callback alat di framework agen Anda—dan kirimkan ke aplikasi klien Anda bersama ID tempat. Jangan mengandalkan LLM untuk mengulangi token dalam outputnya, karena model mungkin mengubah token.

Token hanya mencakup tempat dalam responsnya sendiri. Jika agen Anda memanggil alat search_places lebih dari sekali, kirim setiap token ke aplikasi klien Anda.

Misalnya, jika Anda menggunakan Agent Development Kit (ADK) untuk Python, Anda dapat menyimpan setiap token dalam callback setelah alat:

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

Teruskan fungsi ini sebagai argumen after_tool_callback saat Anda membuat agen, lalu kirim token yang disimpan ke aplikasi klien Anda dengan respons agen. Untuk definisi agen yang lengkap, lihat contoh ADK di Mengonfigurasi LLM untuk menggunakan server MCP.

Menambahkan token dan menampilkan tempat

Di aplikasi klien, teruskan iterable (seperti array) string token yang tidak kosong ke Settings.getInstance().addContentTokens() sebelum Anda membuat elemen Kit UI Tempat untuk tempat tersebut. Metode ini menampilkan error jika Anda meneruskan satu string secara langsung atau jika iterable menyertakan string kosong. Contoh berikut menambahkan token, lalu menampilkan elemen Place Details Compact untuk setiap tempat:

// 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);
  }
}

Masa berlaku token berakhir 10 menit setelah diterbitkan. Maps JavaScript API menyimpan token yang Anda tambahkan dalam memori untuk halaman saat ini dan menghapusnya secara otomatis setelah masa berlakunya habis, sehingga Anda tidak perlu menghapus sendiri token yang sudah tidak berlaku. Jika Anda menambahkan token dari lebih dari satu respons, API akan mengirimkan semua token yang disimpan dengan setiap permintaan dari elemen yang didukung.

Untuk menampilkan beberapa tempat dalam satu elemen, tetapkan properti places dari elemen Daftar Tempat Lanjutan ke ID tempat dari satu atau beberapa respons yang tokennya Anda tambahkan.

Validasi token

Permintaan Places UI Kit tidak ditagih jika semua kondisi berikut terpenuhi:

• Project yang sama: Token dikeluarkan untuk project Google Cloud yang memiliki kunci API yang Anda gunakan untuk memuat Maps JavaScript API.
• Tempat yang di-grounding: Setiap tempat yang diminta elemen dicakup oleh setidaknya satu token yang Anda tambahkan. Elemen dapat menyertakan tempat dari beberapa respons jika Anda menambahkan token dari setiap respons.
• Token yang belum habis masa berlakunya: Untuk setiap tempat, permintaan dibuat dalam waktu 10 menit setelah token yang mencakup tempat tersebut diterbitkan.
• Elemen yang didukung: Permintaan berasal dari elemen Places UI Kit yang didukung.

Elemen yang Anda konfigurasi dengan lokasi, bukan tempat, seperti dengan PlaceDetailsLocationRequestElement, tidak tercakup. Jika elemen Daftar Tempat Lanjutan menyertakan tempat yang tidak tercakup, seluruh permintaan akan ditagih.

Jika ada kondisi yang tidak terpenuhi, elemen akan tetap dimuat, dan permintaan akan ditagih dengan tarif standar untuk SKU-nya. Maps JavaScript API tidak menampilkan error jika token tidak valid.

Penagihan

Anda membayar setiap permintaan alat agen Maps Experience dengan tarif standar. Permintaan Kit UI Tempat yang lulus validasi token tidak akan ditagih, tetapi tetap mengurangi kuota Kit UI Tempat Anda. Permintaan Kit UI Tempat yang tidak lulus validasi token akan ditagih dengan tarif standar untuk SKU Places UI Kit Query atau Places UI Kit Pro (Advanced).

Untuk mengetahui harga, lihat Tabel harga utama dan Tabel harga India.

Persyaratan penggunaan

Hanya untuk penggunaan satu pengguna, respons aktif: Anda harus menggunakan token visualisasi data agentic hanya untuk menampilkan elemen Places UI Kit yang didukung kepada pengguna akhir yang sama dan dalam respons agentic langsung yang menghasilkan token. Anda tidak boleh membagikan, menggabungkan, atau menggunakan kembali token di beberapa pengguna akhir, atau menggunakan token untuk menampilkan tempat di luar respons tersebut (seperti dalam daftar tersimpan, bookmark, atau direktori yang di-cache).

Penggunaan token visualisasi data agentic oleh Anda tunduk pada Persyaratan Layanan Google Maps Platform, termasuk persyaratan khusus layanan. Persyaratan atribusi untuk alat agen Maps Experience juga berlaku.