Các công cụ tác nhân cho trải nghiệm trên Maps (trước đây là Maps Grounding Lite) là một dịch vụ của Google Maps Platform có hỗ trợ Giao thức bối cảnh mô hình (MCP) và REST để cung cấp dữ liệu cơ sở cho các ứng dụng AI của bạn bằng dữ liệu không gian địa lý đáng tin cậy từ Google Maps. Các công cụ của Gemini cho phép LLM truy cập vào dữ liệu về địa điểm, thời tiết, chất lượng không khí, phấn hoa và tuyến đường. Các công cụ khác phân giải tên vị trí và URL của Google Maps thành Mã địa điểm. Bạn có thể dùng thử các công cụ tác nhân cho trải nghiệm trên Maps bằng cách bật máy chủ MCP của công cụ này trong bất kỳ công cụ nào hỗ trợ máy chủ MCP. Bạn cũng có thể gọi từng công cụ dưới dạng một phương thức REST. Để biết thông tin chi tiết, hãy xem phần Gọi công cụ bằng REST.
Các công cụ tác nhân cho trải nghiệm trên Maps là một sản phẩm có hai SKU: Essentials và Pro. Mọi yêu cầu đều được tính phí theo gói Essentials, trừ phi yêu cầu đó sử dụng một lựa chọn của gói Pro. Các lựa chọn Pro bổ sung tính năng tìm kiếm địa điểm dọc theo tuyến đường, thông tin chi tiết mở rộng về địa điểm, nhiều địa điểm hơn cho mỗi lượt tìm kiếm, nhiều điểm dừng trung gian hơn cho mỗi tuyến đường, định tuyến theo tình hình giao thông trực tiếp, thông tin dự báo về phấn hoa và chất lượng không khí trong quá khứ. Cả hai SKU đều sử dụng cùng một công cụ, máy chủ MCP, phương thức REST và thông tin xác thực. Để biết thông tin chi tiết, hãy xem bài viết Essentials và Pro.
Công cụ
Các công cụ tác nhân cho Maps Experiments cho phép LLM truy cập vào các khả năng sau của Google Maps:
- Tìm kiếm địa điểm: Yêu cầu thông tin về địa điểm và nhận bản tóm tắt do AI tạo. Câu trả lời cũng bao gồm mã địa điểm, toạ độ vĩ độ/kinh độ và đường liên kết đến Google Maps cho từng địa điểm trong bản tóm tắt. Bạn có thể sử dụng Mã địa điểm và toạ độ vĩ độ/kinh độ với các API khác của Google Maps Platform để hiển thị địa điểm trên bản đồ. Để hiển thị những địa điểm này bằng Places UI Kit mà không mất thêm phí, hãy sử dụng mã thông báo trực quan hoá dữ liệu dựa trên tác nhân (Bản dùng trước). Với gói Pro, bạn có thể yêu cầu Place Details, chẳng hạn như thông tin chi tiết từ các bài đánh giá và tối đa 10 địa điểm cho mỗi yêu cầu.
- Tìm dọc theo tuyến đường:
Tìm các địa điểm dọc theo tuyến đường di chuyển (được chỉ định bằng
retrieval_tokentừcompute_routes,route_endpointshoặcencoded_polyline) và nhận thông tin tóm tắt do AI tạo, thông tin chi tiết về địa điểm, khoảng cách đường vòng và thời gian di chuyển, cũng như mã trực quan hoá dữ liệu tác tử (Bản xem trước). Mỗi yêu cầusearch_along_routeđược tính phí theo SKU Pro. - Tra cứu thời tiết: Yêu cầu thông tin về điều kiện môi trường của một vị trí, bao gồm cả thời tiết (điều kiện hiện tại, thông tin hằng giờ trong 24 giờ qua và thông tin dự báo hằng giờ và hằng ngày trong tối đa 10 ngày) và chất lượng không khí hiện tại hoặc thông tin dự báo trong tối đa 4 ngày. Với gói Pro, bạn cũng có thể yêu cầu thông tin dự báo hằng ngày về phấn hoa trong tối đa 5 ngày (kèm theo thông tin chi tiết về loài thực vật) và nhật ký chất lượng không khí hằng giờ trong tối đa 30 ngày.
Tính toán tuyến đường: Yêu cầu một tuyến đường giữa điểm xuất phát và điểm đến, tuỳ ý thông qua các điểm dừng trung gian, đồng thời trả về khoảng cách, thời gian của tuyến đường và
retrievalTokencho các tuyến đườngDRIVEmà bạn có thể chuyển đếnsearch_along_route. Với gói Pro, các tuyến đường có thể tính đến tình trạng giao thông trực tiếp và bao gồm nhiều điểm dừng trung gian hơn.Phân giải tên và Phân giải URL trên Maps: Phân giải tên vị trí, địa chỉ và URL trên Google Maps thành mã địa điểm. Để biết thêm thông tin, hãy xem Resolution API.
Sau khi bạn bật máy chủ MCP, LLM có thể gọi các công cụ của máy chủ này để lấy thông tin cơ sở cho các loại dữ liệu này. Mô hình ngôn ngữ lớn (LLM) có thể sử dụng thông tin này làm bối cảnh. Tuy nhiên, câu trả lời cuối cùng có thể không bao gồm thông tin chính xác mà máy chủ MCP trả về. Xác minh độ chính xác của câu trả lời được tạo.
Essentials và Pro
Essentials và Pro là hai SKU của cùng một sản phẩm, không phải là các sản phẩm hoặc gói riêng biệt. Một yêu cầu sẽ được tính phí theo gói Pro khi sử dụng một lựa chọn của gói Pro. Mọi yêu cầu khác đều được tính phí theo gói Essentials. Các lựa chọn Pro là các trường thông thường trong yêu cầu của công cụ, vì vậy, LLM có thể sử dụng các lựa chọn này thay cho bạn. Nhân viên hỗ trợ cũng có thể sử dụng cả hai SKU trong cùng một cuộc trò chuyện. Ví dụ: một nhân viên hỗ trợ có thể sử dụng Essentials để tìm quán cà phê gần một địa danh. Sau đó, Gemini có thể dùng Pro để trả lời một câu hỏi nối tiếp về đồ uống đặc trưng và chỗ ngồi của quán. Không có máy chủ, điểm cuối hoặc thông tin xác thực MCP riêng cho Pro.
So sánh các gói Essentials, Pro và Grounding with Google Maps
Tính năng Neo bám vào Google Maps là một sản phẩm riêng biệt. Tính năng này được tích hợp vào các mô hình Gemini trong Gemini API, Google AI Studio và Nền tảng tác nhân Gemini Enterprise. Mô hình sẽ quyết định thời điểm truy vấn Google Maps và trả về câu trả lời có căn cứ kèm theo trích dẫn. Chọn tính năng Neo bám vào Google Maps khi bạn xây dựng trên Gemini và muốn mô hình này xử lý việc neo bám. Chọn các công cụ tác nhân cho Maps Experiments cho các mô hình hoặc khung tác nhân khác, hoặc để kiểm soát trực tiếp từng lệnh gọi công cụ.
Bảng sau đây so sánh SKU Essentials, SKU Pro và tính năng Grounding with Google Maps:
| các công cụ tác nhân cho trải nghiệm trên Maps | Neo bám vào Google Maps | ||
|---|---|---|---|
| SKU Essentials (trước đây là Maps Grounding Lite) |
SKU Pro | ||
| Cách tính phí yêu cầu | Mỗi yêu cầu công cụ không sử dụng lựa chọn Pro | Mỗi yêu cầu search_along_route hoặc bất kỳ yêu cầu nào đến
một công cụ khác sử dụng lựa chọn Pro. Xem phần
Những khoản phí được tính theo SKU Pro. |
Mỗi câu hỏi trên Google Maps hoặc câu lệnh có căn cứ, tuỳ thuộc vào nền tảng và mô hình |
| Mô hình và nền tảng | Bất kỳ mô hình hoặc khung tác nhân nào hỗ trợ MCP hoặc có thể gọi API REST. Một bộ công cụ và cùng một thông tin đăng nhập cho cả hai SKU | Các mô hình Gemini trong Gemini API, Google AI Studio và Nền tảng tác nhân Gemini Enterprise | |
| Kết quả mà các công cụ trả về | Thông tin cốt lõi: Place Details cho tối đa 5 địa điểm cho mỗi lượt tìm kiếm, khoảng cách và thời gian của tuyến đường không có giao thông theo thời gian thực, thời tiết hiện tại và thông tin dự báo (cộng với nhật ký thời tiết hằng giờ trong 24 giờ) và chất lượng không khí hiện tại hoặc dự báo | Mọi tính năng trong gói Essentials, cộng với các địa điểm dọc theo tuyến đường có thời gian và khoảng cách đi đường vòng, Place Details mở rộng (chẳng hạn như thông tin chi tiết từ các bài đánh giá), tối đa 10 địa điểm cho mỗi lượt tìm kiếm, tuyến đường có thông tin giao thông theo thời gian thực, tối đa 25 điểm tham chiếu trung gian, thông tin dự báo về phấn hoa và dữ liệu chất lượng không khí trong quá khứ lên đến 30 ngày | Place Details và thông tin chi tiết từ các bài đánh giá, cũng như thông tin về tuyến đường kèm theo tình hình giao thông theo thời gian thực |
| Yêu cầu mẫu | Câu hỏi về thông tin thực tế và hậu cần: tìm cửa hàng hoặc doanh nghiệp, giờ mở cửa, địa chỉ, thông tin ước tính về khoảng cách hoặc thời gian di chuyển, thời tiết hiện tại, thông tin dự báo thời tiết trong 10 ngày và thông tin dự báo chất lượng không khí hiện tại hoặc trong 4 ngày | Câu hỏi chủ quan, chung chung hoặc chuyên sâu: địa điểm dọc theo tuyến đường, bầu không khí, món ăn đặc trưng, mẹo cho khách tham quan, so sánh từ 6 đến 10 địa điểm, thời gian di chuyển trong tình hình giao thông hiện tại, thông tin dự báo về phấn hoa và dị ứng, cũng như nhật ký chất lượng không khí trong 30 ngày qua | Tìm kiếm đàm thoại, lên kế hoạch hành trình và khám phá địa phương trong Gemini |
| Hình ảnh trực quan của Places UI Kit | Được cung cấp mà không mất thêm phí khi dùng mã thông báo trực quan hoá dữ liệu tác nhân (Bản dùng thử) | Tính phí riêng | |
| Mức sử dụng hằng tháng không tính phí | 10.000 yêu cầu | 5.000 yêu cầu | Tuỳ thuộc vào nền tảng và mô hình. Ví dụ: trong Gemini API, Gemini 3 và các mô hình mới hơn bao gồm 5.000 cụm từ tìm kiếm mỗi tháng mà không mất phí. Sau đó, các cụm từ tìm kiếm sẽ có giá 14 USD cho mỗi 1.000 cụm từ. |
| Giá trả tiền theo mức dùng | 7 USD cho mỗi 1.000 yêu cầu, có chiết khấu theo số lượng | 14 USD/1.000 yêu cầu, có chiết khấu theo số lượng | |
| Đăng ký để lưu | Có trong gói Essentials và Pro | Có trong gói Pro | Không có |
| Bắt đầu | Một cách thiết lập cho cả hai SKU: xem phần Định cấu hình LLM để sử dụng máy chủ MCP hoặc Gọi các công cụ bằng REST. | Gemini API hoặc Nền tảng tác nhân | |
Các lựa chọn này hoạt động theo cùng một cách với cả hai SKU: phương tiện đi lại, thời gian khởi hành và thời gian đến, tuyến đường thay thế, hình nhiều đường của tuyến đường, thông tin tra cứu thời tiết, thông tin tra cứu chất lượng không khí hiện tại và dự báo (bao gồm cả nồng độ chất gây ô nhiễm và thang đo AQI tại địa phương), hệ thống đơn vị thời tiết và Resolution API. Các quy tắc này không thay đổi SKU mà yêu cầu được tính phí.
Những dịch vụ được tính phí theo SKU Pro
Bảng sau đây tóm tắt những tính năng có trong gói Essentials và những tính năng cần có SKU Pro:
| Công cụ | Chức năng | Essentials | Pro |
|---|---|---|---|
| Tìm địa điểm | Số địa điểm cho mỗi yêu cầu | Tối đa là 5 | 6 đến 10 (page_size từ 6 đến 10) |
| Thông tin chi tiết mở rộng về địa điểm trong phần tóm tắt kết quả tìm kiếm (thông tin chi tiết từ các bài đánh giá, món ăn nổi bật trong thực đơn, bầu không khí, mức độ đông đúc của một địa điểm, mẹo cho khách truy cập và khoảng cách hoặc thời gian di chuyển cho các cụm từ tìm kiếm về địa điểm lân cận) | Không có | Có trong gói include_extended_details |
|
| Tìm dọc theo tuyến đường | Địa điểm dọc theo tuyến đường, khoảng cách và thời gian di chuyển của tuyến đường vòng, cũng như thông tin chi tiết về địa điểm mở rộng hoặc thời gian di chuyển của tuyến đường vòng có tính đến tình hình giao thông (không bắt buộc) | Không có | Mọi yêu cầu |
| Tính toán tuyến đường | Lựa chọn ưu tiên về tuyến đường | Không tính đến lưu lượng truy cập trực tiếp | Tính đến tình hình giao thông trực tiếp hoặc dữ liệu theo thời gian thực về phương tiện công cộng cho các tuyến phương tiện công cộng, bằng ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL |
| Số điểm tham chiếu trung gian trên mỗi tuyến đường | Tối đa là 10 | 11 đến 25 (hơn 10 intermediate_waypoints) |
|
| Tra cứu thông tin thời tiết | Thời tiết | Thời tiết hiện tại, thông tin dự báo hằng giờ và hằng ngày (tối đa 10 ngày) và
nhật ký hằng giờ lên đến 24 giờ (WEATHER trong
capabilities hoặc các yêu cầu cũ bỏ qua
capabilities, weather_options,
air_quality_options và language_code) |
Không có lựa chọn Pro (tất cả dữ liệu WEATHER đều có trong
Essentials) |
| Chất lượng không khí | Điều kiện hiện tại, kết quả hằng giờ trong cả ngày hôm nay và thông tin dự báo
hằng giờ trong tối đa 4 ngày (AIR_QUALITY ở
capabilities) |
Chất lượng không khí trong quá khứ tối đa 30 ngày trước
(AIR_QUALITY trong capabilities có
date trước hôm nay hoặc hour trong quá khứ theo
múi giờ của vị trí), khi được trả về trong phản hồi |
|
| Phấn hoa | Không có | Thông tin dự báo hằng ngày về phấn hoa trong tối đa 5 ngày và thông tin chi tiết về các loài thực vật
(POLLEN trong capabilities), khi được trả về trong
phản hồi |
|
| API phân giải | Không có lựa chọn Pro. Tất cả yêu cầu đều được tính phí theo SKU Places API Text Search Essentials (IDs Only) (Tìm kiếm văn bản cơ bản của API Địa điểm (Chỉ mã nhận dạng)) mà không mất phí. | ||
Để biết các tuỳ chọn yêu cầu cho phép từng khả năng, hãy xem phần Tìm kiếm địa điểm, Tìm dọc theo tuyến đường, Tính toán tuyến đường và Tra cứu thông tin thời tiết.
Kiểm soát việc sử dụng Pro
Các lựa chọn chuyên nghiệp được tắt theo mặc định trên search_places, compute_routes và lookup_weather. Mô hình ngôn ngữ lớn (LLM) sẽ đặt các tham số này (hoặc gọi search_along_route) khi yêu cầu của người dùng cần đến chúng và nội dung mô tả công cụ hoặc hướng dẫn của bạn cho phép.
Nội dung mô tả công cụ cho mô hình biết những lựa chọn nào tốn kém hơn và thời điểm sử dụng: page_size trên 5, Place Details mở rộng, hơn 10 điểm tham chiếu trung gian, định tuyến dựa trên thông tin giao thông và search_along_route. Nếu bạn gọi các công cụ bằng REST, mã của bạn sẽ đặt mọi tuỳ chọn. Cách quản lý chi phí:
- Cho mô hình biết khi nào nên dùng các lựa chọn Pro. Ví dụ: "Chỉ đặt
include_extended_detailskhi người dùng hỏi về bài đánh giá, thực đơn hoặc bầu không khí". Hoặc: "Chỉ sử dụngROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMALkhi người dùng hỏi về thời gian di chuyển hiện tại". Hoặc: "Chỉ gọisearch_along_routekhi người dùng yêu cầu tìm địa điểm dọc theo tuyến đường". Hoặc: "Chỉ đưaPOLLENhoặcAIR_QUALITYvào cùng vớidatehoặchourtrong quá khứ khi người dùng hỏi về phấn hoa, dị ứng hoặc chất lượng không khí trong quá khứ". - Để giữ nhân viên hỗ trợ ở SKU Essentials, hãy hướng dẫn mô hình không bao giờ gọi
search_along_routehoặc sử dụng một lựa chọn Pro. Các lựa chọn của gói Pro làinclude_extended_details,page_sizetrên 5,ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, hơn 10 điểm tham chiếu trung gian,POLLENtrongcapabilitiesvàdatehoặchourtrong quá khứ cóAIR_QUALITYtrongcapabilities. Nếu ứng dụng MCP của bạn có thể hạn chế các công cụ hoặc đối số công cụ, thì bạn cũng có thể chặnsearch_along_routevà các giá trị đối số đó trong cấu hình công cụ của ứng dụng. - Theo dõi SKU Maps Grounding Pro trong báo cáo thanh toán và đặt cảnh báo ngân sách.
API phân giải
Các công cụ tác nhân cho Maps Experiments cung cấp Resolution API. API này phân giải văn bản vị trí và URL dạng biểu mẫu tuỳ ý thành giá trị nhận dạng địa điểm có cấu trúc của Google Maps. Resolution API được cung cấp dưới dạng các phương thức REST và công cụ trên máy chủ MCP:
- Phân giải tên (REST, MCP): Phân giải một loạt tên hoặc địa chỉ vị trí thành các thực thể địa điểm cụ thể trên Google Maps. Công cụ này giúp chuyển đổi các cụm từ tìm kiếm không có cấu trúc của người dùng thành mã địa điểm ổn định.
- Phân giải URL của Maps (REST, MCP): Phân giải một loạt URL của Google Maps thành các thực thể địa điểm cụ thể. Các định dạng được hỗ trợ bao gồm URL địa điểm chuẩn và URL rút gọn.
Bạn có thể sử dụng mã địa điểm được trả về với các API khác của Google Maps Platform. Mỗi câu trả lời cũng bao gồm một đường liên kết để lưu các địa điểm đã phân giải dưới dạng danh sách trong Google Maps.
Để biết thêm thông tin, hãy xem bài viết Maps Tools Resolution API.
Dùng thử ứng dụng mẫu (Mở trong thẻ mới)
Thanh toán và hạn mức
Cách tính phí
Với mô hình giá trả tiền theo mức dùng của Google Maps Platform, mức sử dụng các công cụ tác nhân cho trải nghiệm trên Maps được tính cho mỗi yêu cầu. Mỗi yêu cầu đại diện cho một sự kiện thanh toán. Mức sử dụng được theo dõi cho từng SKU sản phẩm. Hoá đơn của bạn cho thấy một mục riêng cho từng SKU ngoài tổng phí. Hãy xem bài viết Tổng quan về báo cáo để biết thêm thông tin.
Mỗi yêu cầu Tìm kiếm địa điểm, Tìm kiếm dọc theo tuyến đường, Tính toán tuyến đường hoặc Tra cứu thời tiết, thông qua máy chủ MCP hoặc bằng REST, đều được tính phí theo một SKU:
Maps Grounding Essentials
hoặc
Maps Grounding Pro.
Mỗi yêu cầu search_along_route và mọi yêu cầu sử dụng một lựa chọn Pro đều được tính phí theo SKU Pro. Một yêu cầu không bao giờ được tính phí theo cả hai SKU và số lượng lựa chọn Pro trong một yêu cầu không làm thay đổi phí. Để biết các chức năng và lựa chọn xác định SKU cho từng công cụ, hãy xem phần Những dịch vụ được tính phí theo SKU Pro.
Yêu cầu Maps Grounding Essentials được tính phí 7 USD/1.000 yêu cầu sau 10.000 yêu cầu đầu tiên mỗi tháng. Yêu cầu Maps Grounding Pro được tính phí 14 USD cho mỗi 1.000 yêu cầu sau 5.000 yêu cầu đầu tiên mỗi tháng. Cả hai SKU đều có chiết khấu theo số lượng khi mức sử dụng hằng tháng cao hơn.
Hãy xem Bảng giá chính và Bảng giá tại Ấn Độ để biết thông tin chi tiết về giá.
Các yêu cầu API phân giải (ResolveNames và ResolveMapsUrls) được tính phí không mất phí theo SKU Places API Tìm kiếm văn bản Essentials (IDs Only).
Nếu hiển thị địa điểm từ phản hồi search_places hoặc search_along_route bằng Places UI Kit, bạn có thể sử dụng mã trực quan hoá dữ liệu tác nhân (Bản xem trước) để không bị tính phí cho các yêu cầu đó của Places UI Kit.
Việc sử dụng SKU Essentials được bao gồm trong các gói Essentials và Pro Đăng ký để tiết kiệm. Việc sử dụng SKU Pro được bao gồm trong gói Pro.
Hạn mức
Các hạn mức sau đây áp dụng cho các công cụ và API do các công cụ tác nhân cho Maps Experiments cung cấp:
- Tìm địa điểm: 300 truy vấn mỗi phút cho mỗi dự án.
- Tìm dọc theo tuyến đường: 300 truy vấn mỗi phút cho mỗi dự án.
- Tra cứu thời tiết: 300 truy vấn mỗi phút cho mỗi dự án.
- Tính toán tuyến đường: 300 truy vấn mỗi phút cho mỗi dự án.
- Phân giải tên: 600 truy vấn mỗi phút cho mỗi dự án.
- Phân giải URL của Maps: 600 truy vấn mỗi phút cho mỗi dự án.
Hạn mức được tính cho từng công cụ và được dùng chung cho SKU Essentials và Pro. Một yêu cầu Pro sử dụng cùng hạn mức với một yêu cầu Essentials cho cùng một công cụ.
Mỗi yêu cầu Resolution API được tính là một truy vấn, bất kể yêu cầu đó chứa bao nhiêu mục.
Chính sách và điều khoản dịch vụ
Các công cụ tác nhân cho Maps Experiments 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ụ. Phần này mô tả các yêu cầu bổ sung về việc sử dụng công cụ tác nhân Trải nghiệm Maps, bao gồm cả LLM tương thích và thông tin ghi nhận tác giả nguồn. Các yêu cầu này áp dụng cho tất cả kết quả, bất kể yêu cầu được tính phí theo SKU nào.
Yêu cầu đối với LLM tương thích
Bạn chỉ được sử dụng các công cụ tác nhân cho Maps Experiments với một LLM tuân thủ Điều khoản dịch vụ của Google Maps Platform.
Ví dụ: bạn chịu trách nhiệm đảm bảo rằng Nội dung trên Google Maps không được lưu vào bộ nhớ đệm, lưu trữ hoặc dùng để cải thiện LLM mà bạn chọn sử dụng. Trước khi sử dụng các công cụ tác nhân cho Maps Experiments, bạn cần xem lại Điều khoản dịch vụ của mọi mô hình mà bạn dự định sử dụng với các công cụ tác nhân cho Maps Experiments. Bạn không được sử dụng các công cụ của tác nhân Maps Experience với bất kỳ mô hình nào sử dụng dữ liệu đầu vào cho mô hình để huấn luyện hoặc cải thiện mô hình. Bạn có trách nhiệm đảm bảo rằng việc bạn sử dụng mô hình này hoàn toàn tuân thủ các quy định hạn chế đối với Nội dung trên Google Maps trong Điều khoản dịch vụ của Google Maps Platform, bao gồm cả các điều khoản dành riêng cho dịch vụ.
Yêu cầu về thông tin ghi công đối với các nguồn của Google Maps
Mỗi câu trả lời của công cụ tác nhân cho trải nghiệm trên Maps đều có nguồn. Khi trình bày kết quả từ các công cụ tác nhân cho Maps Experiments, bạn phải cung cấp các nguồn Google Maps liên quan và đáp ứng các yêu cầu sau:
- Nguồn của Google Maps phải xuất hiện ngay sau nội dung được tạo mà nguồn đó hỗ trợ. Nội dung được tạo này cũng được gọi là Kết quả có căn cứ.
- Người dùng phải xem được các nguồn của Google Maps chỉ bằng một lượt tương tác.
Nguồn cho công cụ Tìm địa điểm và Tìm dọc theo tuyến đường
Trường places của công cụ search_places và trường results[].place của công cụ search_along_route cung cấp các nguồn hỗ trợ summary. Đối với mỗi địa điểm, siêu dữ liệu sau đây sẽ được trả về:
place(tên tài nguyên)idlocationgoogleMapsLinksattribution
Đối với mỗi địa điểm, bạn phải tạo một bản xem trước đường liên kết đáp ứng các yêu cầu sau:
- Ghi nhận từng nguồn cho Google Maps theo nguyên tắc ghi nhận nguồn bằng văn bản cho các công cụ tác nhân cho trải nghiệm trên Maps.
- Liên kết đến nguồn bằng
googleMapsLinks.placeUrltrong phản hồi.
Những yêu cầu này cũng áp dụng cho các bản tóm tắt có chứa Place Details mở rộng về địa điểm từ Pro, chẳng hạn như thông tin chi tiết từ các bài đánh giá. summary trích dẫn từng địa điểm bằng một chỉ mục dựa trên số 0, chẳng hạn như [0], liên kết với một mục trong places hoặc results.
Mỗi địa điểm cũng bao gồm googleMapsLinks.reviewsUrl, liên kết đến các bài đánh giá về địa điểm đó trên Google Maps. Người dùng có thể nhấp vào đường liên kết này để xem các bài đánh giá đằng sau một thông tin chi tiết.
Giao diện ưu tiên giọng nói
Nếu ứng dụng của bạn trình bày kết quả của các công cụ tác nhân cho trải nghiệm Maps Experiments bằng giọng nói, thì bạn cũng phải đáp ứng các yêu cầu đối với giao diện ưu tiên giọng nói. Tóm tắt:
- Nguồn: Hiển thị các nguồn của Google Maps trong một giao diện người dùng đồng hành, cho thấy bản ghi nguyên văn cuộc trò chuyện thoại.
- Thông báo rõ ràng: Tại thời điểm tương tác, hãy thông báo cho người dùng rằng nội dung do AI tạo có thể bao gồm thông tin từ Google Maps. Ngoài ra, hãy cho họ biết rằng họ có thể xem nguồn chi tiết trong giao diện người dùng đồng hành. Bạn có thể làm việc này trên màn hình hoặc bằng giọng nói.
- Thông tin công bố cố định: Đưa ra lời giải thích cố định (ví dụ: trong trình đơn cài đặt giọng nói) rằng nội dung do AI tạo có thể bao gồm nội dung trên Google Maps.
- Câu hỏi của người dùng: Trả lời chính xác câu hỏi của người dùng về nguồn của nội dung và hướng dẫn họ đến giao diện người dùng đồng hành để biết thông tin chi tiết.
Định cấu hình LLM để sử dụng máy chủ MCP
Để sử dụng các công cụ tác nhân cho trải nghiệm trên Maps, bạn cần có một dự án Google Cloud đã bật dịch vụ API các công cụ tác nhân cho trải nghiệm trên Maps. Bạn cũng cần có khoá API hoặc mã ứng dụng OAuth. Sau đó, bạn có thể định cấu hình LLM để truy cập vào máy chủ MCP. Máy chủ MCP sử dụng phương thức truyền tải HTTP có thể truyền trực tuyến.
Bật các công cụ tác nhân cho trải nghiệm Maps Experiments trong dự án trên đám mây của bạn
Cách bật API cho dự án:
- Trong Google Cloud Console, hãy chọn dự án bạn muốn dùng cho các công cụ tác nhân cho Maps Experiments.
- Bật tính năng thanh toán cho dự án trong Google Cloud Console.
- Bật các công cụ tác nhân cho Maps Experiments trong Thư viện API của Google Cloud Console.
Xác thực bằng khoá API
Bạn có thể sử dụng khoá API hiện có với các công cụ tác nhân cho Maps Experiments hoặc tạo một khoá mới. Dù bằng cách nào, hãy bật dịch vụ API công cụ tác nhân cho trải nghiệm trên Maps trên cả dự án Google Cloud và khoá.
Cách xác thực bằng khoá API:
- Tạo hoặc định cấu hình khoá API bằng cách làm theo các bước trong phần Bắt đầu sử dụng Google Maps Platform.
- Truyền khoá đến máy chủ MCP bằng tiêu đề
X-Goog-Api-Key. Bạn cần chỉ định thông tin này dưới dạng tiêu đề HTTP tuỳ chỉnh trong cấu hình công cụ MCP của LLM.
Xác thực bằng OAuth
Bạn có thể xác thực bằng OAuth bằng cách tạo thông tin xác thực OAuth và truyền thông tin đó đến máy chủ lưu trữ MCP hoặc ứng dụng máy chủ MCP.
Cách xác thực bằng OAuth:
- Trong Google Cloud Console, hãy chọn dự án bạn muốn dùng cho các công cụ tác nhân cho trải nghiệm trên Maps.
- Trong trình đơn API và Dịch vụ, hãy chọn Thông tin xác thực.
- Trong trình đơn trên cùng, hãy chọn Tạo thông tin xác thực > Mã ứng dụng khách OAuth.
- Nếu dự án chưa có màn hình xin phép được định cấu hình, hãy nhấp vào Configure consent screen (Định cấu hình màn hình xin phép) rồi làm theo hướng dẫn trên màn hình.
- Trong mục Chỉ số, hãy nhấp vào Tạo ứng dụng OAuth.
- Trên màn hình Tạo mã ứng dụng OAuth, hãy chọn một loại ứng dụng rồi nhập tên cho mã ứng dụng khách.
- Nêu rõ các thông tin chi tiết khác có liên quan đến loại ứng dụng của bạn. Ví dụ: nếu bạn đang tạo một ứng dụng web, hãy thêm URI được uỷ quyền cho các yêu cầu của trình duyệt và máy chủ.
- Sau khi tạo ứng dụng khách, hãy lưu mã ứng dụng khách và mật khẩu ứng dụng khách.
- Khi bạn định cấu hình ứng dụng máy chủ MCP hoặc máy chủ lưu trữ MCP, hãy truyền mã ứng dụng khách OAuth và mật khẩu ứng dụng khách OAuth. Bạn cũng phải yêu cầu phạm vi sau:
https://www.googleapis.com/auth/maps-platform.mapstools.
Để biết thêm thông tin, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.
Định cấu hình LLM để truy cập vào máy chủ MCP của các công cụ tác nhân cho Maps Experiments
Sau khi bật dịch vụ Maps Experiments và tạo thông tin xác thực, bạn có thể định cấu hình LLM để truy cập vào máy chủ MCP. Làm theo tài liệu về cấu hình MCP của LLM và sử dụng URL máy chủ MCP: https://mapstools.googleapis.com/mcp
Để biết thêm thông tin, hãy xem phần Định cấu hình MCP trong một ứng dụng AI.
Định cấu hình các công cụ tác nhân cho trải nghiệm trên Maps bằng Gemini CLI
Phần này cung cấp ví dụ về cách định cấu hình máy chủ MCP của công cụ tác nhân Maps Experience bằng Gemini CLI. Để biết thêm thông tin, hãy xem bài viết Máy chủ MCP có Gemini CLI.
Sau khi bạn cài đặt Gemini CLI, hãy chạy
gemini mcp addđể định cấu hình máy chủ MCP:gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcpNếu cấu hình thành công, bạn sẽ thấy thông báo xác nhận rằng máy chủ đã được thêm vào chế độ cài đặt người dùng của bạn.
Để xác thực rằng máy chủ đang hoạt động, hãy chạy lệnh
/mcp list:> /mcp list Configured MCP servers: maps-experience-agent-tools-mcp - Ready (6 tools) Tools: - compute_routes - lookup_weather - resolve_maps_urls - resolve_names - search_along_route - search_placesBắt đầu Hỏi Maps bằng CLI. Ví dụ: hãy thử "Đề xuất một số nhà hàng ở Mountain View", câu lệnh này sẽ gọi công cụ
search_placesthay cho bạn.
Định cấu hình các công cụ tác nhân cho Maps Experiments bằng Bộ công cụ phát triển tác nhân (ADK)
Phần này trình bày cách định cấu hình máy chủ MCP bằng Bộ công cụ phát triển tác nhân (ADK) trong Python, Java hoặc TypeScript.
Python
Bạn có thể tìm thấy cách triển khai hoàn chỉnh của ví dụ này trên GitHub trong kho lưu trữ adk-samples.
Bước 1: Xác định tác nhân bằng McpToolset cho các công cụ tác nhân cho trải nghiệm trên Maps
Sửa đổi tệp agent.py. Thay thế YOUR_GOOGLE_MAPS_API_KEY bằng khoá API thực tế của bạn.
# ./adk_agent_samples/mcp_agent/agent.py import os from google.adk.agents.llm_agent import Agent from google.adk.tools.mcp_tool import McpToolset from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams # Retrieve the API key from an environment variable or directly insert it. GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY") if not GOOGLE_MAPS_API_KEY: GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE" if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE": print("WARNING: GOOGLE_MAPS_API_KEY is not set.") root_agent = Agent( model='gemini-flash-latest', name='travel_planner_agent', description='A helpful assistant for planning travel routes.', tools=[ McpToolset( connection_params=StreamableHTTPConnectionParams( url="https://mapstools.googleapis.com/mcp", headers={ "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY, "Content-Type": "application/json", "Accept": "application/json, text/event-stream" } ) ) ] )
Bước 2: Đảm bảo __init__.py tồn tại
Đảm bảo bạn có một __init__.py trong cùng thư mục với
agent.py:
from . import agent
Bước 3: Chạy adk web và tương tác
- Đặt biến môi trường:
Đặt khoá API Google Maps làm biến môi trường trong thiết bị đầu cuối:export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
- Chạy
adk web:
Chạy lệnh sau để khởi động giao diện web của ADK:adk web
- Tương tác trong giao diện người dùng:
- Chọn
travel_planner_agent. - Hãy thử những câu lệnh như:
- "Ngày mai tôi sẽ ở San Francisco. Tình hình thời tiết thế nào?"
- "Tìm quán cà phê gần Công viên Cầu Giấy".
- "Tìm đường từ GooglePlex đến SFO."
- Chọn
Java
Xác định một tác nhân khởi chạy McpToolset trong Java.
Thay thế YOUR_GOOGLE_MAPS_API_KEY_HERE bằng khoá API thực tế mà bạn nhận được nếu không sử dụng biến môi trường.
package agents; import com.google.adk.agents.LlmAgent; import com.google.adk.runner.InMemoryRunner; import com.google.adk.sessions.SessionKey; import com.google.adk.tools.mcp.McpToolset; import com.google.adk.tools.mcp.StreamableHttpServerParameters; import com.google.genai.types.Content; import com.google.genai.types.Part; import java.util.HashMap; import java.util.Map; public class MapsAgentCreator { public static void main(String[] args) { String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY"); if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) { googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE"; if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) { System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set."); } } Map<String, String> headers = new HashMap<>(); headers.put("X-Goog-Api-Key", googleMapsApiKey); headers.put("Content-Type", "application/json"); headers.put("Accept", "application/json, text/event-stream"); StreamableHttpServerParameters serverParams = StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp") .headers(headers) .build(); try (McpToolset toolset = new McpToolset(serverParams)) { LlmAgent agent = LlmAgent.builder() .model("gemini-flash-latest") .name("travel_planner_agent") .description("A helpful assistant for planning travel routes.") .tools(toolset) .build(); System.out.println("Agent created: " + agent.name()); InMemoryRunner runner = new InMemoryRunner(agent); String userId = "maps-user-" + System.currentTimeMillis(); String sessionId = "maps-session-" + System.currentTimeMillis(); String promptText = "Please give me directions to the nearest pharmacy to Madison Square Garden."; SessionKey sessionKey = runner.sessionService() .createSession(runner.appName(), userId, null, sessionId) .blockingGet() .sessionKey(); System.out.println("Session created: " + sessionId + " for user: " + userId); Content promptContent = Content.fromParts(Part.fromText(promptText)); System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n"); runner.runAsync(sessionKey, promptContent) .blockingForEach(event -> { System.out.println("Event received: " + event.toJson()); }); } catch (Exception e) { System.err.println("An error occurred: " + e.getMessage()); e.printStackTrace(); } } }
TypeScript
Xác định một tác nhân khởi chạy MCPToolset trong TypeScript:
import 'dotenv/config'; import {LlmAgent, MCPToolset} from "@google/adk"; const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY; if (!googleMapsApiKey) { console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set."); throw new Error( 'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.' ); } export const rootAgent = new LlmAgent({ model: "gemini-flash-latest", name: "travel_planner_agent", description: "A helpful assistant for planning travel.", tools: [ new MCPToolset({ type: "StreamableHTTPConnectionParams", url: "https://mapstools.googleapis.com/mcp", transportOptions: { requestInit: { headers: { "X-Goog-Api-Key": googleMapsApiKey, "Content-Type": "application/json", "Accept": "application/json, text/event-stream" } } } }) ], });
Gọi các công cụ bằng REST
Mỗi công cụ trong bộ công cụ tác nhân cho trải nghiệm trên Maps cũng được cung cấp dưới dạng một phương thức REST. Gọi trực tiếp các phương thức REST khi bạn muốn kết nối các công cụ vào tác nhân hoặc ứng dụng của riêng mình, chẳng hạn như để khai báo các hàm của riêng bạn cho một mô hình, chọn các tuỳ chọn mà mô hình có thể đặt hoặc đặt giá trị mặc định trong mã của bạn.
Bảng sau đây liệt kê phương thức REST cho từng công cụ:
| Công cụ | Phương thức REST |
|---|---|
search_places |
POST https://mapstools.googleapis.com/v1:searchText |
search_along_route |
POST https://mapstools.googleapis.com/v1:searchAlongRoute |
lookup_weather |
POST https://mapstools.googleapis.com/v1:lookupWeather |
compute_routes |
POST https://mapstools.googleapis.com/v1:computeRoutes |
resolve_names |
POST https://mapstools.googleapis.com/v1:resolveNames |
resolve_maps_urls |
POST https://mapstools.googleapis.com/v1:resolveMapsUrls |
Yêu cầu REST có các tuỳ chọn giống như công cụ tương ứng và trả về cùng một phản hồi. Trong phần nội dung yêu cầu và phản hồi REST, tên trường sử dụng kiểu viết lạc đà (viết liền và phân tách bằng chữ cái viết hoa) chữ thường, ví dụ: textQuery thay vì text_query. Yêu cầu REST được tính phí
theo cùng một SKU, tuân theo cùng một quy tắc cho các lựa chọn Pro và được tính vào
cùng một hạn mức như lệnh gọi công cụ MCP.
Để xác thực, hãy sử dụng cùng một dự án trên đám mây và thông tin xác thực trên Google Cloud như đối với máy chủ MCP. Để biết các bước thiết lập, hãy xem phần Định cấu hình LLM để sử dụng máy chủ MCP.
Truyền khoá API trong tiêu đề X-Goog-Api-Key hoặc truyền mã truy cập OAuth có phạm vi https://www.googleapis.com/auth/maps-platform.mapstools trong tiêu đề Authorization.
Ví dụ sau đây gọi phương thức searchText:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"
Thay thế API_KEY bằng khoá API của bạn.
Phản hồi chứa các trường summary, places và contentToken giống như kết quả của công cụ search_places. Hướng dẫn của mỗi công cụ đều có một phiên bản REST của ví dụ về công cụ đó.
Chia sẻ ý kiến phản hồi
Để chia sẻ ý kiến phản hồi về các công cụ tác nhân cho trải nghiệm trên Maps, hãy sử dụng các biểu mẫu sau: