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ử Bộ công cụ giao diện người dùng của Địa điểm cho các địa điểm trong phản hồi của công cụ tác nhân Trải nghiệm 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 sẽ 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, 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 một 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 đó:
- Tác nhân của bạn gọi công cụ
search_placestrên máy chủ MCP của công cụ tác nhân Trải nghiệm Maps. Phản hồ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ườngcontentToken. - Ứ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ị.
- Ứng dụng khách của bạn sẽ thêm mã thông báo vào Maps JavaScript API và tạo các phần tử Places UI Kit cho những địa điểm đó.
- 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
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:
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 phần tử 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 Maps Experience 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. - Thông tin xác thực của dự án đó cho cả lệnh gọi công cụ của nhân viên hỗ trợ Maps Experience và Maps JavaScript API. Mã thông báo chỉ hợp lệ cho các yêu cầu của Places UI Kit từ dự án mà mã thông báo được cấp.
- Ứng dụng khách tải Maps JavaScript API từ kênh thử nghiệm beta bằng cách đặt
v=beta.
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 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. Phản hồi của công cụ tương tự như sau:
{ "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à đừ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 gọi công cụ search_places nhiều lần, hãy gửi từng mã thông báo đến ứng dụng khách của bạn.
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 một 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
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 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);
}
}
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.
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 Maps JavaScript API.
- Địa điểm có căn cứ: Mọi địa điểm mà phần tử yêu cầu đều được bao gồm trong ít nhất một mã thông báo mà bạn đã thêm. 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ử đượ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 được 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á tiêu chuẩn cho SKU của phần tử đó. Maps JavaScript API không trả về lỗi khi mã thông báo không hợp lệ.
Thanh toán
Bạn trả phí cho mỗi yêu cầu về công cụ tác nhân của Maps Experience 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 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ụ của tác nhân Maps Experience cũng được áp dụng.