โทเค็นการแสดงข้อมูลเป็นภาพแบบ Agentic ช่วยให้แอป Agentic แสดงองค์ประกอบ Places UI Kit สำหรับสถานที่ในการตอบกลับของเครื่องมือ Agent ของ Maps Experiments (เดิมคือ Maps Grounding Lite) ได้โดยไม่มีค่าใช้จ่ายเพิ่มเติม การเรียกใช้เครื่องมือ search_places ที่สำเร็จแต่ละครั้งจะแสดงผลโทเค็นที่ระบุสถานที่ในคำตอบสำหรับทั้ง SKU Essentials และ Pro เมื่อแอปไคลเอ็นต์เพิ่มโทเค็นลงใน Maps JavaScript API ระบบจะไม่เรียกเก็บเงินคำขอ Places UI Kit สำหรับสถานที่เหล่านั้นเป็นเวลา 10 นาทีหลังจากออกโทเค็น
วิธีการทำงาน
โทเค็นจะเชื่อมต่อคำตอบที่อิงตามข้อมูลกับรายละเอียดสถานที่ที่คุณแสดงพร้อมกับคำตอบนั้น
- Agent จะเรียกใช้เครื่องมือ
search_placesในเซิร์ฟเวอร์ MCP ของเครื่องมือ Agent สำหรับ Maps Experience การตอบกลับของเครื่องมือจะรวมสถานที่ที่รองรับข้อมูลสรุปและโทเค็นในฟิลด์contentToken - แอปของคุณจะอ่านโทเค็นจากการตอบกลับของเครื่องมือและส่งไปยังแอปไคลเอ็นต์ พร้อมกับรหัสของสถานที่ที่คุณต้องการแสดง
- แอปไคลเอ็นต์จะเพิ่มโทเค็นลงใน Maps JavaScript API และสร้างองค์ประกอบ Places UI Kit สำหรับสถานที่เหล่านั้น
- Google Maps Platform จะตรวจสอบโทเค็นกับคำขอ Places UI Kit แต่ละรายการ หากโทเค็นถูกต้อง ระบบจะไม่เรียกเก็บเงินสำหรับคำขอ
องค์ประกอบ Places UI Kit ที่รองรับ
โทเค็นจะมีผลกับองค์ประกอบ Places UI Kit ต่อไปนี้ใน Maps JavaScript API
โทเค็นนี้ใช้ไม่ได้กับคำขออื่นๆ เช่น คำขอจากองค์ประกอบการค้นหาสถานที่, การค้นหาสถานที่ขั้นสูง และการเติมข้อมูลสถานที่พื้นฐานโดยอัตโนมัติ, คำขอ Places API และการโหลดแผนที่ ระบบจะเรียกเก็บเงินสำหรับคำขอเหล่านี้ในอัตรามาตรฐาน
เฉพาะคำตอบจากเครื่องมือ Agent ของ Maps Experience เท่านั้นที่มีโทเค็น หากคุณแสดงสถานที่จากการตอบกลับการเชื่อมต่อแหล่งข้อมูลกับ Google Maps ด้วย Places UI Kit ระบบจะเรียกเก็บเงินคำขอเหล่านั้นในอัตรามาตรฐาน
ก่อนเริ่มต้น
ก่อนใช้โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic ให้ตั้งค่าต่อไปนี้
- โปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google Cloud ที่เปิดใช้ Maps Experience agent tools API (
mapstools.googleapis.com) และ Places UI Kit API ดูข้อมูลเพิ่มเติมได้ที่กำหนดค่า LLM ให้ใช้เซิร์ฟเวอร์ MCP และเริ่มต้นใช้งาน Places UI Kit - ข้อมูลเข้าสู่ระบบจากโปรเจ็กต์นั้นสำหรับการเรียกใช้เครื่องมือ Agent ของ Maps Experience และ Maps JavaScript API โทเค็นใช้ได้กับคำขอ Places UI Kit จากโปรเจ็กต์ที่ออกโทเค็นให้เท่านั้น
- แอปไคลเอ็นต์ที่โหลด Maps JavaScript API จากเวอร์ชันเบต้าโดยตั้งค่า
v=beta
แสดงสถานที่จากคำตอบที่อิงตามข้อมูล
ส่วนต่อไปนี้แสดงวิธีรับโทเค็นจากการตอบกลับของเครื่องมือและใช้ในแอปไคลเอ็นต์ หากคุณใช้ชุดเครื่องมือ Agentic UI ของ Maps (เวอร์ชันทดลอง) ตัวแทนและไคลเอ็นต์บนเว็บจะจัดการขั้นตอนเหล่านี้ให้คุณ
รับโทเค็นจากการตอบกลับของเครื่องมือ
เครื่องมือ search_places จะแสดงผลโทเค็นในฟิลด์ contentToken ในผลลัพธ์ของคำขอ MCP tools/call ช่องนี้จะอยู่ใน structuredContent การตอบกลับของเครื่องมือจะคล้ายกับตัวอย่างต่อไปนี้
{ "places": [ { "place": "places/PLACE_ID", "id": "PLACE_ID", ... } ], ... "contentToken": "CONTENT_TOKEN" }
เอาต์พุตนี้ประกอบด้วยค่าต่อไปนี้
PLACE_ID: รหัสสถานที่ของสถานที่ในการตอบกลับCONTENT_TOKEN: โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic สำหรับสถานที่ในการตอบกลับ ให้ถือว่าโทเค็นเป็นสตริงทึบแสงและอย่าแก้ไข
หากการตอบกลับไม่มีสถานที่ใดๆ การตอบกลับจะไม่มีโทเค็น
ในโค้ดแอป ให้อ่านโทเค็นจากการตอบกลับของเครื่องมือ เช่น ในการเรียกกลับของเครื่องมือในเฟรมเวิร์กตัวแทน แล้วส่งไปยังแอปไคลเอ็นต์พร้อมรหัสสถานที่ อย่าพึ่งพา LLM ในการทำซ้ำโทเค็นในเอาต์พุต เนื่องจากโมเดลอาจเปลี่ยนโทเค็น
โทเค็นจะครอบคลุมเฉพาะสถานที่ในการตอบกลับของตัวเองเท่านั้น หาก Agent เรียกใช้เครื่องมือ search_places มากกว่า 1 ครั้ง ให้ส่งโทเค็นแต่ละรายการไปยังแอปไคลเอ็นต์
ตัวอย่างเช่น หากคุณใช้ Agent Development Kit (ADK) สำหรับ Python คุณสามารถบันทึกโทเค็นแต่ละรายการใน Callback หลังเครื่องมือได้ดังนี้
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
ส่งฟังก์ชันนี้เป็นอาร์กิวเมนต์ after_tool_callback เมื่อคุณสร้าง Agent แล้วส่งโทเค็นที่บันทึกไว้ไปยังแอปไคลเอ็นต์พร้อมกับการตอบกลับของ Agent ดูคำจำกัดความของ Agent ที่สมบูรณ์ได้จากตัวอย่าง ADK ในหัวข้อกำหนดค่า LLM ให้ใช้เซิร์ฟเวอร์ MCP
เพิ่มโทเค็นและแสดงสถานที่
ในแอปไคลเอ็นต์ ให้ส่งสตริงโทเค็นที่ไม่ใช่ค่าว่างแบบทำซ้ำได้ (เช่น อาร์เรย์) ไปยัง Settings.getInstance().addContentTokens() ก่อนสร้างองค์ประกอบ Places UI Kit สำหรับสถานที่ เมธอดจะแสดงข้อผิดพลาดหากคุณส่งสตริงเดียวโดยตรงหรือหากออบเจ็กต์ที่ทำซ้ำได้มีสตริงว่าง ตัวอย่างต่อไปนี้จะเพิ่มโทเค็น แล้วแสดงองค์ประกอบรายละเอียดสถานที่แบบกะทัดรัดสำหรับสถานที่แต่ละแห่ง
// 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);
}
}
โทเค็นจะหมดอายุภายใน 10 นาทีหลังจากที่ออก Maps JavaScript API จะเก็บโทเค็นที่คุณเพิ่มไว้ในหน่วยความจำสำหรับหน้าปัจจุบันและนำออกโดยอัตโนมัติหลังจากหมดอายุ คุณจึงไม่ต้องนำโทเค็นที่หมดอายุออกด้วยตนเอง หากคุณเพิ่มโทเค็นจากการตอบกลับมากกว่า 1 รายการ API จะส่งโทเค็นที่จัดเก็บไว้ทั้งหมดพร้อมกับคำขอแต่ละรายการจากองค์ประกอบที่รองรับ
หากต้องการแสดงสถานที่หลายแห่งในองค์ประกอบเดียว ให้ตั้งค่าพร็อพเพอร์ตี้ places ขององค์ประกอบรายการสถานที่ขั้นสูงเป็นรหัสสถานที่จากการตอบกลับอย่างน้อย 1 รายการที่คุณเพิ่มโทเค็น
การตรวจสอบโทเค็น
ระบบจะไม่เรียกเก็บเงินสำหรับคำขอ Places UI Kit เมื่อเป็นไปตามเงื่อนไขต่อไปนี้ทั้งหมด
- โปรเจ็กต์เดียวกัน: โทเค็นได้รับการออกให้กับโปรเจ็กต์ Google Cloud ที่เป็นเจ้าของคีย์ API ที่คุณใช้เพื่อโหลด Maps JavaScript API
- สถานที่ที่มีการระบุข้อมูลอ้างอิง: สถานที่ทุกแห่งที่องค์ประกอบขอจะครอบคลุมโดยโทเค็นอย่างน้อย 1 รายการที่คุณเพิ่ม องค์ประกอบหนึ่งๆ สามารถรวมสถานที่จากการตอบกลับหลายรายการได้หากคุณเพิ่มโทเค็นจากการตอบกลับแต่ละรายการ
- โทเค็นที่ยังไม่หมดอายุ: สำหรับแต่ละสถานที่ ระบบจะส่งคำขอภายใน 10 นาทีหลังจากที่ออกโทเค็นที่ครอบคลุมสถานที่นั้น
- องค์ประกอบที่รองรับ: คำขอมาจากองค์ประกอบ Places UI Kit ที่รองรับ
แต่ไม่รวมองค์ประกอบที่คุณกำหนดค่าด้วยสถานที่ตั้งแทนสถานที่ เช่น PlaceDetailsLocationRequestElement หากองค์ประกอบ Advanced Place List มีสถานที่ที่ไม่อยู่ในความคุ้มครอง ระบบจะเรียกเก็บเงินสำหรับคำขอทั้งหมด
หากไม่เป็นไปตามเงื่อนไข องค์ประกอบจะยังคงโหลด และระบบจะเรียกเก็บเงินสำหรับคำขอในอัตรามาตรฐานสำหรับ SKU นั้น Maps JavaScript API จะไม่แสดงข้อผิดพลาดเมื่อโทเค็นไม่ถูกต้อง
การเรียกเก็บเงิน
คุณชำระเงินสำหรับคำขอเครื่องมือ Agent ของ Maps Experiments แต่ละรายการในอัตรามาตรฐาน ระบบจะไม่เรียกเก็บเงินสำหรับคำขอ Places UI Kit ที่ผ่านการตรวจสอบโทเค็น แต่จะยังคงนับรวมในโควต้า Places UI Kit คำขอ Places UI Kit ที่ไม่ผ่านการตรวจสอบโทเค็นจะเรียกเก็บเงินในอัตรามาตรฐานสำหรับ SKU การค้นหา Places UI Kit หรือ Places UI Kit Pro (ขั้นสูง)
ดูราคาได้ที่ตารางราคาหลักและตารางราคาสำหรับอินเดีย
ข้อกำหนดในการใช้งาน
การใช้งานแบบผู้ใช้คนเดียวและมีการตอบสนองที่ใช้งานอยู่เท่านั้น: คุณต้องใช้โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic เพื่อแสดงองค์ประกอบ Places UI Kit ที่รองรับต่อผู้ใช้ปลายทางคนเดียวกันและภายในการตอบสนองแบบ Agentic ทันทีที่สร้างโทเค็นเท่านั้น คุณต้องไม่แชร์ รวม หรือใช้โทเค็นซ้ำกับผู้ใช้ปลายทางหลายราย หรือใช้โทเค็นเพื่อแสดงสถานที่นอกการตอบกลับนั้น (เช่น ในรายการที่บันทึกไว้ บุ๊กมาร์ก หรือไดเรกทอรีที่แคชไว้)
การใช้โทเค็นการแสดงข้อมูลผ่านภาพแบบ Agentic ของคุณขึ้นอยู่กับข้อกำหนดในการให้บริการของ Google Maps Platform รวมถึงข้อกำหนดเฉพาะบริการ ข้อกำหนดการระบุแหล่งที่มาสำหรับเครื่องมือ Agent ของ Maps Experience จะมีผลด้วยเช่นกัน