Công cụ của tác nhân Maps Experience

Công cụ tác nhân Trải nghiệm 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) để 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. Máy chủ MCP cung cấp các công cụ cho phép LLM truy cập vào dữ liệu về địa điểm, thời tiết 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ụ của tác nhân Maps Experience bằng cách bật các công cụ này trong bất kỳ công cụ nào hỗ trợ máy chủ MCP.

Công cụ tác nhân Maps Experience 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 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 và định tuyến theo tình hình giao thông trực tiếp. Trong giai đoạn Phát hành rộng rãi có hạn chế, các lựa chọn của gói Pro chỉ dành cho những dự án nằm trong danh sách cho phép của gói Pro. Cả hai SKU đều sử dụng cùng một máy chủ, công cụ và thông tin đăng nhập MCP. Để 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ụ của tác nhân Trải nghiệm Maps cho phép LLM truy cập vào các chức 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. Phản hồi cũng bao gồm Mã địa điểm, toạ độ và đường liên kết đến Google Maps cho từng địa điểm trong phần tóm tắt. Bạn có thể sử dụng Mã địa điểm và toạ độ với các API khác của Google Maps Platform để hiển thị địa điểm trên bản đồ. Với gói Pro, bạn có thể yêu cầu thông tin chi tiết mở rộng về địa điểm, 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.
  • Tra cứu thời tiết: Yêu cầu thông tin về thời tiết và trả về tình hình hiện tại, thông tin dự báo hằng giờ và thông tin dự báo hằng 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, có thể đi qua các điểm dừng trung gian, đồng thời trả về khoảng cách và thời gian của tuyến đường. Với gói Pro, các tuyến đường có thể tính đến tình trạng giao thông theo thời gian thực 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ủ đó để 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ề. Bạn nên xác minh tính 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 Grounding with Google Maps khi bạn xây dựng trên Gemini và muốn mô hình xử lý việc liên kết thông tin. Chọn các công cụ của tác nhân Maps Experience 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ụ.

Công cụ của tác nhân Maps Experience 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 công cụ sử dụng một lựa chọn Pro: include_extended_details, page_size trên 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL hoặc hơn 10 điểm tham chiếu trung gian Mỗi câu lệnh có căn cứ hoặc truy vấn trên Google Maps, 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. Một máy chủ MCP, 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 mỗi lần 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, cũng như thời tiết hiện tại và thông tin dự báo Mọi tính năng trong gói Essentials, cộng thêm thông tin chi tiết mở rộng về địa điểm (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 và tối đa 25 điểm tham chiếu trung gian 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ỉ và thông tin ước tính về khoảng cách hoặc thời gian di chuyển Câu hỏi chủ quan hoặc chung chung: 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 và thời gian di chuyển trong tình hình giao thông hiện tại 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 sử dụng mã thông báo trực quan hoá dữ liệu tác nhân (Bản dùng thử) Được tính phí riêng
Mức sử dụng miễn phí mỗi tháng 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 có 5.000 cụm từ tìm kiếm miễn phí mỗi tháng. Sau đó, các cụm từ tìm kiếm sẽ có giá 14 USD/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. Liên hệ với bộ phận bán hàng để biết giá theo số lượng.
Đăng ký để lưu Có trong gói Essentials và Pro Không bao gồm Không có
Bắt đầu Một 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. Trong giai đoạn Phát hành rộng rãi có hạn chế, các lựa chọn Pro cũng yêu cầu một dự án trong danh sách cho phép của Pro. 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 di chuyển, 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 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 khoản phí được tính theo 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 tham quan 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í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 về phương tiện công cộng theo thời gian thực cho các tuyến phương tiện công cộng, với 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)
Lookup weather và Resolution API Không có lựa chọn Pro. Tất cả yêu cầu đều được tính phí theo SKU Essentials.

Để biết các tuỳ chọn yêu cầu cho phép từng chức năng, hãy xem phần Tìm địa điểm và Tính toán tuyến đường.

Các lựa chọn Pro trong giai đoạn Phát hành rộng rãi có hạn chế

Trong giai đoạn GA có hạn chế, các lựa chọn Pro chỉ dành cho những dự án trên đám mây trên Google Cloud nằm trong danh sách cho phép của Pro. Liên hệ với bộ phận bán hàng để yêu cầu quyền truy cập. Sau khi một dự án được đưa vào danh sách cho phép, mọi khoá API và ứng dụng OAuth trong dự án đó đều có thể sử dụng các lựa chọn của Gemini Pro.

Nếu dự án của bạn chưa có trong danh sách cho phép, thì các yêu cầu sử dụng các lựa chọn Pro sẽ được xử lý như sau:

  • Tìm địa điểm: include_extended_details bị bỏ qua và phản hồi chứa tối đa 5 địa điểm, ngay cả khi bạn đặt page_size cao hơn. Yêu cầu này được tính phí theo SKU Essentials.
  • Tính toán tuyến đường: ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL được coi là ROUTING_PREFERENCE_TRAFFIC_UNAWARE và yêu cầu được tính phí theo SKU Essentials. Yêu cầu có hơn 10 điểm tham chiếu trung gian sẽ trả về lỗi INVALID_ARGUMENT.

Để kiểm tra xem dự án của bạn có nằm trong danh sách cho phép hay không, hãy gửi một search_places yêu cầu có page_size được đặt thành 10. Sử dụng một cụm từ tìm kiếm rộng, chẳng hạn như restaurants in Chicago. Một dự án trong danh sách cho phép có thể trả về hơn 5 địa điểm, được tính phí theo SKU Pro. Các dự án khác trả về tối đa 5 địa điểm.

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. LLM sẽ đặt các tham số này khi yêu cầu của người dùng yêu cầu và giản đồ công cụ hoặc hướng dẫn của bạn cho phép. Giản đồ công cụ mô tả các giá trị page_size lên đến 5 và tối đa 10 điểm tham chiếu trung gian. Do đó, các mô hình chỉ sử dụng hạn mức cao hơn của gói Pro khi chỉ dẫn của bạn yêu cầu. 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_details khi 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ụng ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL khi người dùng yêu cầu thời gian di chuyển hiện tại".
  • Để giữ cho một tác nhân ở SKU Essentials, hãy hướng dẫn mô hình không bao giờ sử dụng lựa chọn Pro. Các lựa chọn của gói Pro là include_extended_details, page_size trên 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL và hơn 10 điểm tham chiếu trung gian. Nếu ứng dụng MCP của bạn có thể hạn chế đối số của công cụ, thì bạn cũng có thể chặn các giá trị đó trong cấu hình công cụ.
  • Theo dõi mức sử dụng trong báo cáo thanh toán và đặt cảnh báo ngân sách.

API phân giải

Công cụ tác nhân Trải nghiệm Maps cung cấp Resolution API. API này phân giải văn bản vị trí và URL dạng tuỳ ý thành giá trị nhận dạng địa điểm có cấu trúc trên 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. Điều này rất hữu ích cho việc 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 (API giải quyết vấn đề về công cụ của Maps).

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ụ của tác nhân Maps Experience đượ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 hàng cho mỗi 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 địa điểm, Tính toán tuyến đường hoặc Tra cứu thời tiết đều được tính phí theo đúng một SKU, Essentials hoặc Pro. Yêu cầu sử dụng bất kỳ lựa chọn nào của gói Pro sẽ được tính phí theo SKU Pro. Bạn sẽ không bao giờ bị tính phí theo cả hai SKU và số lượng lựa chọn Pro không làm thay đổi khoản phí. Các lựa chọn sau đây xác định SKU:

Công cụ Essentials Pro
search_places Mọi yêu cầu không có lựa chọn Pro: page_size từ 5 trở xuống và include_extended_details chưa đặt hoặc false include_extended_details được đặt thành true hoặc page_size từ 6 đến 10
compute_routes Mọi yêu cầu không có lựa chọn Pro: routing_preference không được đặt hoặc ROUTING_PREFERENCE_TRAFFIC_UNAWARE và có tối đa 10 điểm tham chiếu trung gian, với mọi phương tiện di chuyển routing_preference được đặt thành ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL hoặc từ 11 đến 25 điểm tham chiếu trung gian
lookup_weather Mọi yêu cầu —

Để biết giá của Essentials, hãy xem phần Thông tin chi tiết về SKU Essentials. Yêu cầu 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. Liên hệ với bộ phận bán hàng để biết giá theo số lượng.

Trong giai đoạn Phát hành rộng rãi có hạn chế, các lựa chọn của gói Pro chỉ có hiệu lực đối với những dự án trong danh sách cho phép của gói Pro. Để biết thông tin chi tiết, hãy xem phần Các lựa chọn cho gói Pro trong giai đoạn phát hành rộng rãi có hạn chế.

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í ở mức 0 đồng theo SKU Places API Tìm kiếm văn bản Essentials (IDs Only).

Mức sử dụng SKU Essentials cũng được tính vào các gói Đăng ký để tiết kiệm Essentials và Pro. SKU Pro không có trong các gói Đăng ký để tiết kiệm.

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ụ của tác nhân Maps Experience cung cấp:

  • Tìm địa điểm: 300 truy vấn mỗi phút, mỗi dự án.
  • Tra cứu thời tiết: 300 truy vấn mỗi phút, mỗi dự án.
  • Tính toán tuyến đường: 300 truy vấn mỗi phút, mỗi dự án.
  • Phân giải tên: 600 truy vấn mỗi phút, mỗi dự án.
  • Phân giải URL của Maps: 600 truy vấn mỗi phút, mỗi dự án.

Hạn mức được tính theo từng công cụ và được chia sẻ giữa SKU Essentials và SKU Pro. Một yêu cầu Pro tiêu thụ hạn mức tương đương 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ụ của tác nhân Maps Experience phải tuân thủ Đ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 đối với các công cụ của tác nhân Maps Experience, 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 của Maps Experience 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ụ của tác nhân Maps Experience, 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ụ của tác nhân Maps Experience. Bạn không được sử dụng các công cụ tác nhân của 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 trên Google Maps

Mỗi câu trả lời của công cụ tác nhân Maps Experience đều có nguồn. Khi trình bày kết quả từ các công cụ của tác nhân Maps Experience, 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

Trường places của công cụ search_places cung cấp các nguồn hỗ trợ summary. Đối với places, siêu dữ liệu sau đây sẽ được trả về:

  • place (tên tài nguyên)
  • id
  • location
  • googleMapsLinks

Đố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:

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 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, ví dụ: [0], liên kết với một mục trong places. 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ể làm theo hướng dẫn để 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ông cụ tác nhân Trải nghiệm Maps 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 các nguồn chi tiết có 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ụ của tác nhân Maps Experience, bạn cần có một dự án trên đám mây của Google Cloud đã bật dịch vụ API Công cụ của tác nhân Maps Experience. 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ông cụ tác nhân Maps Experience trên dự án trên đám mây của bạn

Cách bật API cho dự án:

  1. Trong Google Cloud Console, hãy chọn dự án bạn muốn dùng cho các công cụ của tác nhân Maps Experience.
  2. Bật tính năng thanh toán cho dự án trong Google Cloud Console.
  3. Bật các công cụ của tác nhân Maps Experience 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ụ của tác nhân Maps Experience 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 Maps Experience trên cả dự án trên đám mây của Google và khoá.

Cách xác thực bằng khoá API:

  1. 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.
  2. 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ủ MCP hoặc ứng dụng máy chủ MCP.

Cách xác thực bằng OAuth:

  1. Trong Google Cloud Console, hãy chọn dự án bạn muốn dùng cho các công cụ của tác nhân Maps Experience.
  2. Trong trình đơn API và Dịch vụ, hãy chọn Thông tin xác thực.
  3. 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.
  4. 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.
  5. Trong mục Chỉ số, hãy nhấp vào Tạo ứng dụng OAuth.
  6. Trên màn hình Create OAuth client ID (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.
  7. 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ủ.
  8. 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.
  9. 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ông cụ tác nhân Maps Experience

Sau khi bật dịch vụ Công cụ tác nhân Maps Experience 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 bài viết Định cấu hình MCP trong một ứng dụng AI.

Định cấu hình các công cụ của tác nhân Maps Experience 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.

  1. 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/mcp

    Nế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.

  2. Để xác thực rằng máy chủ đang hoạt động đúng cách, hãy chạy lệnh /mcp list:

    > /mcp list

Configured MCP servers:

maps-experience-agent-tools-mcp - Ready (5 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_places

  3. Bắt đầu Hỏi Maps bằng CLI. Ví dụ: hãy thử "Đề xuất cho tôi một số nhà hàng ở Mountain View". Thao tác này sẽ gọi công cụ search_places thay mặt bạn.

Định cấu hình các công cụ của tác nhân Maps Experience 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 các công cụ tác nhân McpToolset cho Maps Experience

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
  1. Đặ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"
  2. Chạy adk web:
    Chạy lệnh sau để khởi động giao diện web ADK: 
    adk web
  3. Tương tác trong giao diện người dùng:
    • Chọn travel_planner_agent.
    • Hãy thử các 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."

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: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});

Chia sẻ ý kiến phản hồi

Để chia sẻ ý kiến phản hồi về các công cụ của nhân viên hỗ trợ Maps Experience, hãy sử dụng các biểu mẫu sau: