Mã thông báo trực quan hoá dữ liệu của tác nhân

Mã thông báo trực quan hoá dữ liệu dựa trên tác nhân cho phép ứng dụng dựa trên tác nhân của bạn hiển thị các phần tử Places UI Kit cho các địa điểm trong phản hồi của các công cụ tác nhân cho trải nghiệm trên Maps (trước đây là Maps Grounding Lite) mà không mất thêm phí. Mỗi lệnh gọi thành công đến công cụ search_places hoặc search_along_route đều trả về một mã thông báo xác định các địa điểm trong phản hồi, cho cả SKU Essentials và Pro. Khi ứng dụng khách của bạn thêm mã thông báo vào API JavaScript của Maps, SDK Địa điểm cho Android hoặc SDK Địa điểm cho iOS, các yêu cầu của Places UI Kit cho những địa điểm đó sẽ không bị tính phí trong 10 phút sau khi mã thông báo được cấp.

Cách hoạt động

Mã thông báo này kết nối câu trả lời có căn cứ với thông tin chi tiết về địa điểm mà bạn hiển thị cùng với câu trả lời đó:

  1. Tác nhân của bạn gọi công cụ search_places hoặc search_along_route trên máy chủ MCP của các công cụ tác nhân cho trải nghiệm trên Maps. Câu trả lời của công cụ bao gồm những địa điểm hỗ trợ bản tóm tắt và một mã thông báo trong trường contentToken.
  2. Ứng dụng của bạn đọc mã thông báo từ phản hồi của công cụ và gửi mã thông báo đó đến ứng dụng khách, cùng với mã nhận dạng của những địa điểm mà bạn muốn hiển thị.
  3. Ứng dụng khách của bạn sẽ thêm mã thông báo vào Maps JavaScript API hoặc truyền mã thông báo đó trong mỗi yêu cầu của thành phần di động, đồng thời tạo các phần tử Places UI Kit cho những địa điểm đó.
  4. Google Maps Platform xác thực mã thông báo theo từng yêu cầu của Places UI Kit. Nếu mã thông báo hợp lệ, yêu cầu sẽ không bị tính phí.

Các phần tử được hỗ trợ trong Places UI Kit

API JavaScript cho Maps

Mã thông báo này áp dụng cho các thành phần sau đây của Places UI Kit trong Maps JavaScript API:

Phần tử SKU
PlaceDetailsElement Truy vấn Places UI Kit
PlaceDetailsCompactElement Truy vấn Places UI Kit
AdvancedPlaceDetailsElement Places UI Kit Pro (Nâng cao)
AdvancedPlaceDetailsCompactElement Places UI Kit Pro (Nâng cao)
AdvancedPlaceListElement Places UI Kit Pro (Nâng cao)

SDK Địa điểm dành cho Android

Fragment/hàm composable SKU
PlaceDetailsFragment Truy vấn Places UI Kit
PlaceDetailsCompactFragment Truy vấn Places UI Kit
AdvancedPlaceDetailsFragment Places UI Kit Pro (Nâng cao)
AdvancedPlaceDetailsCompactFragment Places UI Kit Pro (Nâng cao)
AdvancedPlaceListFragment Places UI Kit Pro (Nâng cao)
AdvancedPlaceDetails Places UI Kit Pro (Nâng cao)
AdvancedPlaceDetailsCompact Places UI Kit Pro (Nâng cao)
PlaceMarker Places UI Kit Pro (Nâng cao)

SDK Địa điểm dành cho iOS

Cấu trúc SKU
PlaceDetailsView Truy vấn Places UI Kit
PlaceDetailsCompactView Truy vấn Places UI Kit
AdvancedPlaceDetailsView Places UI Kit Pro (Nâng cao)
AdvancedPlaceDetailsCompactView Places UI Kit Pro (Nâng cao)
AdvancedPlaceListView Places UI Kit Pro (Nâng cao)
PlaceMarker Places UI Kit Pro (Nâng cao)

Mã thông báo này không áp dụng cho các yêu cầu khác, chẳng hạn như yêu cầu từ các thành phần Tìm kiếm địa điểm, Tìm kiếm địa điểm nâng cao và Place Autocomplete cơ bản, yêu cầu của Places API và lượt tải bản đồ. Những yêu cầu này được tính phí theo mức giá tiêu chuẩn.

Chỉ những câu trả lời của công cụ tác nhân cho Maps Experiments mới có mã thông báo. Nếu bạn hiển thị địa điểm từ phản hồi của tính năng Neo bám vào Google Maps bằng Places UI Kit, thì những yêu cầu đó sẽ được tính phí theo mức giá tiêu chuẩn.

Trước khi bắt đầu

Trước khi sử dụng mã thông báo trực quan hoá dữ liệu dựa trên tác nhân, hãy thiết lập những thông tin sau:

  • Một dự án trên đám mây của Google Cloud đã bật API công cụ tác nhân Maps Experience (mapstools.googleapis.com) và API Places UI Kit. Để biết thêm thông tin, hãy xem bài viết Định cấu hình LLM để sử dụng máy chủ MCP và Bắt đầu sử dụng Places UI Kit cho JavaScript, Android hoặc iOS.
  • Thông tin xác thực của dự án đó cho cả lệnh gọi công cụ tác nhân cho trải nghiệm trên Maps và Maps JavaScript API, Places SDK for Android hoặc Places SDK for iOS. Mã thông báo chỉ có hiệu lực đối với các yêu cầu của Places UI Kit từ dự án mà mã thông báo được cấp.
  • Một ứng dụng khách tải API JavaScript của Maps từ kênh thử nghiệm beta bằng cách đặt v=beta. Đối với thiết bị di động, hãy sử dụng Places SDK cho Android phiên bản 6.1.0 trở lên hoặc Places Swift SDK (GooglePlacesSwift) phiên bản 11.4.0.

Hiển thị các địa điểm từ một câu trả lời có căn cứ

Các phần sau đây trình bày cách lấy mã thông báo từ phản hồi của công cụ và sử dụng mã thông báo đó trong ứng dụng khách. Nếu bạn sử dụng Maps Agentic UI Toolkit (Thử nghiệm), thì tác nhân và ứng dụng web của bộ công cụ này sẽ xử lý các bước này cho bạn.

Lấy mã thông báo từ phản hồi của công cụ

Công cụ search_places và search_along_route trả về mã thông báo trong trường contentToken. Trong kết quả của yêu cầu MCP tools/call, trường này nằm trong structuredContent. Trong phản hồi từ phương thức REST searchText hoặc searchAlongRoute, đây là trường cấp cao nhất. Phản hồi search_places tương tự như sau (phản hồi search_along_route trả về từng địa điểm bên trong results[].place):

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

Kết quả này bao gồm các giá trị sau:

  • PLACE_ID: Mã địa điểm của một địa điểm trong phản hồi.
  • CONTENT_TOKEN: Mã thông báo trực quan hoá dữ liệu dựa trên tác nhân cho các địa điểm trong phản hồi. Hãy coi mã thông báo này là một chuỗi mờ và không sửa đổi mã thông báo này.

Nếu phản hồi không bao gồm địa điểm nào, thì phản hồi sẽ không bao gồm mã thông báo.

Trong mã ứng dụng, hãy đọc mã thông báo từ phản hồi của công cụ (ví dụ: trong lệnh gọi lại công cụ trong khung tác nhân) rồi gửi mã thông báo đó đến ứng dụng khách cùng với mã địa điểm. Đừng dựa vào LLM để lặp lại mã thông báo trong kết quả của nó, vì mô hình có thể thay đổi mã thông báo.

Mã thông báo chỉ bao gồm các địa điểm trong phản hồi của chính mã thông báo đó. Nếu tác nhân của bạn gọi điện bằng tác nhân search_places hoặc search_along_route nhiều lần, hãy gửi từng mã thông báo đến ứng dụng khách.

Ví dụ: nếu sử dụng Bộ phát triển tác nhân (ADK) cho Python, bạn có thể lưu từng mã thông báo trong lệnh gọi lại sau công cụ:

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

Truyền hàm này dưới dạng đối số after_tool_callback khi bạn tạo tác nhân, sau đó gửi mã thông báo đã lưu đến ứng dụng khách bằng phản hồi của tác nhân. Để biết định nghĩa đầy đủ về tác nhân, hãy xem các ví dụ về ADK trong phần Định cấu hình LLM để sử dụng máy chủ MCP.

Thêm mã thông báo và hiển thị địa điểm

API JavaScript cho Maps

Trong ứng dụng khách, hãy truyền một chuỗi mã thông báo không trống có thể lặp lại (chẳng hạn như một mảng) đến Settings.getInstance().addContentTokens() trước khi bạn tạo các phần tử Places UI Kit cho địa điểm. Phương thức này sẽ gửi một lỗi nếu bạn truyền trực tiếp một chuỗi đơn hoặc nếu đối tượng lặp lại chứa một chuỗi trống. Ví dụ sau đây thêm một mã thông báo, sau đó hiển thị một phần tử Chi tiết địa điểm thu gọn cho mỗi địa điểm:

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

Mã thông báo sẽ hết hạn sau 10 phút kể từ khi được cấp. Maps JavaScript API lưu giữ các mã thông báo mà bạn thêm vào bộ nhớ cho trang hiện tại và tự động xoá các mã thông báo đó sau khi hết hạn, vì vậy, bạn không cần phải tự xoá các mã thông báo đã hết hạn. Nếu bạn thêm mã thông báo từ nhiều phản hồi, API sẽ gửi tất cả mã thông báo được lưu trữ cùng với mỗi yêu cầu từ một phần tử được hỗ trợ.

Để hiển thị nhiều địa điểm trong một phần tử, hãy đặt thuộc tính places của phần tử Danh sách địa điểm nâng cao thành mã địa điểm từ một hoặc nhiều phản hồi có mã thông báo mà bạn đã thêm.

SDK Địa điểm dành cho Android

Truyền trực tiếp contentTokens: Set<String> vào mỗi truy vấn thành phần.

Mã thông báo sẽ hết hạn sau 10 phút kể từ khi được cấp. SDK không lưu trữ mã thông báo trên các yêu cầu hoặc theo dõi thời gian hết hạn.

Jetpack Compose (AdvancedPlaceDetails, AdvancedPlaceDetailsCompact, PlaceMarker):

val placeRef = PlaceReference.PlaceId(
    placeId = placeId,
    contentTokens = setOf(contentToken),
)
// Or with a resource name:
// PlaceReference.ResourceName(resourceName = resourceName, contentTokens = setOf(contentToken))

Mảnh (PlaceDetailsFragment, PlaceDetailsCompactFragment, AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment):

fragment.loadWithPlaceId(placeId, setOf(contentToken))
// Or: fragment.loadWithResourceName(resourceName, setOf(contentToken))

Mảnh danh sách địa điểm (AdvancedPlaceListFragment):

advancedPlaceListFragment.configureFromPlaceIds(placeIds, setOf(contentToken))
// Or: advancedPlaceListFragment.configureFromResourceNames(resourceNames, setOf(contentToken))

SDK Địa điểm dành cho iOS

SDK cung cấp các trường hợp enum PlaceIdentifier chuyên biệt (.placeIDWithTokens hoặc .resourceNameWithTokens) được truyền vào các trình khởi tạo PlaceDetailsQuery(identifier:) và PlaceMarker(identifier:...) hiện có.

Mã thông báo sẽ hết hạn sau 10 phút kể từ khi được cấp. SDK không lưu trữ mã thông báo trên các yêu cầu hoặc theo dõi thời gian hết hạn.

// Place Details and Advanced Place Details (full and compact):
@State var query = PlaceDetailsQuery(
  identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
)
// Or: .resourceNameWithTokens(resourceName, contentTokens: [contentToken])


// Advanced Place List:
@State var queries = [
  PlaceDetailsQuery(
    identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
  )
]
// Place Marker:
PlaceMarker(
  identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken]),
  markerIcon: .type,
  markerText: .rating
)

Xác thực mã thông báo

Yêu cầu về Places UI Kit sẽ không bị tính phí khi đáp ứng tất cả các điều kiện sau:

  • Cùng một dự án: Mã thông báo được cấp cho dự án Google Cloud sở hữu khoá API mà bạn dùng để tải API JavaScript của Maps, SDK Địa điểm cho Android hoặc SDK Địa điểm cho iOS.
  • Vị trí có căn cứ: Mọi vị trí mà phần tử yêu cầu đều được bao gồm trong ít nhất một mã thông báo có trong yêu cầu. Một phần tử có thể bao gồm các địa điểm từ nhiều phản hồi nếu bạn thêm mã thông báo từ mỗi phản hồi.
  • Mã thông báo chưa hết hạn: Đối với mỗi địa điểm, yêu cầu được thực hiện trong vòng 10 phút kể từ khi mã thông báo bao gồm địa điểm đó được cấp.
  • Phần tử được hỗ trợ: Yêu cầu đến từ một phần tử hoặc thành phần được hỗ trợ của Places UI Kit.

Các phần tử mà bạn định cấu hình bằng một vị trí thay vì một địa điểm, chẳng hạn như bằng PlaceDetailsLocationRequestElement, sẽ không được đề cập. Nếu một phần tử Danh sách địa điểm nâng cao bao gồm bất kỳ địa điểm nào không được áp dụng, thì toàn bộ yêu cầu sẽ được tính phí.

Nếu không đáp ứng bất kỳ điều kiện nào, thì phần tử vẫn tải và yêu cầu sẽ được tính phí theo mức giá chuẩn cho SKU của phần tử đó. Maps JavaScript API, SDK Địa điểm dành cho Android và SDK Địa điểm dành cho iOS không trả về lỗi khi mã thông báo không hợp lệ.

Giới hạn (chỉ dành cho SDK Địa điểm cho Android và iOS)

  • Có tối đa 100 mã thông báo riêng biệt cho mỗi yêu cầu. Mã thông báo thừa sẽ bị cắt bớt và có nhật ký cảnh báo.
  • Mỗi mã thông báo có tối đa 2.048 byte UTF-8. Mã thông báo quá lớn sẽ bị loại bỏ kèm theo nhật ký cảnh báo, còn mã thông báo trống hoặc trùng lặp sẽ bị bỏ qua.
  • Các truy vấn toạ độ (PlaceReference.Coordinates và PlaceIdentifier.coordinate) không chấp nhận mã thông báo.
  • Trên iOS AdvancedPlaceListView, nếu có bất kỳ truy vấn nào trong danh sách thiếu mã địa điểm hoặc tên tài nguyên không trống, thì hệ thống sẽ không gửi mã thông báo nào cho danh sách đó.

Thanh toán

Bạn trả phí cho mỗi yêu cầu sử dụng các công cụ tác nhân cho trải nghiệm trên Maps theo mức giá tiêu chuẩn. Những yêu cầu của Places UI Kit vượt qua quy trình xác thực mã thông báo sẽ không bị tính phí, nhưng vẫn được tính vào hạn mức của Places UI Kit. Những yêu cầu của Places UI Kit không vượt qua được quy trình xác thực mã thông báo, hoặc những yêu cầu có mã thông báo không hợp lệ hoặc đã hết hạn, sẽ được tính phí theo mức giá tiêu chuẩn cho SKU Places UI Kit Query hoặc Places UI Kit Pro (Advanced).

Để biết giá, hãy xem Bảng giá chính và Bảng giá tại Ấn Độ.

Yêu cầu về việc sử dụng

Chỉ dùng cho một người dùng, phản hồi chủ động: Bạn chỉ được sử dụng mã thông báo trực quan hoá dữ liệu của tác nhân để hiển thị các phần tử được hỗ trợ của Places UI Kit cho cùng một người dùng cuối và trong phản hồi tức thì của tác nhân đã tạo mã thông báo. Bạn không được chia sẻ, gộp hoặc sử dụng lại mã thông báo cho nhiều người dùng cuối, hoặc sử dụng mã thông báo để hiển thị các địa điểm bên ngoài phản hồi đó (chẳng hạn như trong danh sách đã lưu, dấu trang hoặc thư mục được lưu vào bộ nhớ đệm).

Việc bạn sử dụng mã thông báo trực quan hoá dữ liệu dựa trên tác nhân phải tuân theo Điều khoản dịch vụ của Google Maps Platform, bao gồm cả điều khoản dành riêng cho dịch vụ. Yêu cầu ghi công đối với các công cụ tác nhân cho trải nghiệm trên Maps cũng được áp dụng.