Alat agen Maps Experience

Alat agen Maps Experience (sebelumnya Maps Grounding Lite) adalah layanan Google Maps Platform dengan dukungan Model Context Protocol (MCP) untuk melakukan grounding pada aplikasi AI Anda dengan data geospasial tepercaya dari Google Maps. Server MCP menyediakan alat yang memungkinkan LLM mengakses data tempat, cuaca, dan rute. Alat lain me-resolve nama lokasi dan URL Google Maps ke ID Tempat. Anda dapat mencoba alat agen Maps Experience dengan mengaktifkannya di alat apa pun yang mendukung server MCP.

Alat agen Maps Experience adalah satu produk dengan dua SKU: Essentials dan Pro. Setiap permintaan ditagih berdasarkan Essentials, kecuali jika menggunakan opsi Pro. Opsi Pro menambahkan detail tempat yang diperluas, lebih banyak tempat per penelusuran, lebih banyak perhentian per rute, dan pemilihan rute dengan lalu lintas real-time. Selama GA Terbatas, opsi Pro hanya tersedia untuk project dalam daftar yang diizinkan untuk Pro. Kedua SKU menggunakan server, alat, dan kredensial MCP yang sama. Untuk mengetahui detailnya, lihat Essentials dan Pro.

Alat

Alat agen Maps Experience memungkinkan LLM mengakses kemampuan Google Maps berikut:

• Telusuri tempat: Minta informasi tentang tempat dan dapatkan ringkasan buatan AI. Responsnya juga menyertakan ID Tempat, koordinat, dan link Google Maps untuk setiap tempat dalam ringkasan. Anda dapat menggunakan ID Tempat dan koordinat dengan API Google Maps Platform lainnya untuk menampilkan tempat di peta. Dengan Pro, Anda dapat meminta detail tempat yang diperluas, seperti insight dari ulasan, dan hingga 10 tempat per permintaan.
• Lookup weather: Meminta informasi tentang cuaca dan menampilkan kondisi saat ini, prakiraan cuaca per jam, dan prakiraan cuaca harian.

• Compute routes: Meminta rute antara tempat asal dan tujuan, secara opsional melalui perhentian perantara, dan menampilkan jarak serta durasi rute. Dengan Pro, rute dapat memperhitungkan kondisi lalu lintas langsung dan menyertakan lebih banyak perhentian antara.

  Catatan: Alat agen Maps Experience tidak memberikan rute langkah demi langkah atau informasi navigasi. Rute yang dihitung tanpa opsi Pro tidak memperhitungkan lalu lintas real-time.

• Selesaikan nama dan Selesaikan URL Maps: Selesaikan nama lokasi, alamat, dan URL Google Maps ke ID Tempat. Untuk informasi selengkapnya, lihat Resolution API.

Setelah Anda mengaktifkan server MCP, LLM dapat memanggil alatnya untuk mendapatkan informasi grounding untuk jenis data ini. LLM dapat menggunakan informasi ini untuk konteks. Namun, respons akhirnya mungkin tidak menyertakan informasi persis yang ditampilkan oleh server MCP. Anda harus memverifikasi keakuratan respons yang dihasilkan.

Essentials dan Pro

Pro hanya tersedia untuk pelanggan tertentu. Hubungi bagian penjualan untuk mempelajari lebih lanjut.

Essentials dan Pro adalah dua SKU dari produk yang sama, bukan produk atau paket terpisah. Permintaan akan ditagih berdasarkan Pro jika menggunakan opsi Pro. Setiap permintaan lainnya ditagih berdasarkan Essentials. Opsi Pro adalah kolom biasa dalam permintaan alat, sehingga LLM dapat menggunakannya atas nama Anda. Agen juga dapat menggunakan kedua SKU dalam percakapan yang sama. Misalnya, agen mungkin menggunakan Essentials untuk menemukan kedai kopi di dekat tempat terkenal. Kemudian, model ini mungkin menggunakan Pro untuk menjawab pertanyaan lanjutan tentang minuman khas dan tempat duduk mereka. Tidak ada server, endpoint, atau kredensial MCP terpisah untuk Pro.

Membandingkan Essentials, Pro, dan Grounding with Google Maps

Grounding with Google Maps adalah produk terpisah. Fitur ini disertakan dalam model Gemini di Gemini API, Google AI Studio, dan Gemini Enterprise Agent Platform. Model akan memutuskan kapan harus mengkueri Google Maps dan menampilkan jawaban yang di-grounding dengan kutipan. Pilih Grounding with Google Maps saat Anda membangun di Gemini dan ingin model menangani grounding. Pilih alat agen Maps Experience untuk model atau framework agen lainnya, atau untuk kontrol langsung atas setiap panggilan alat.

	Alat agen Maps Experience		Grounding dengan Google Maps
	SKU Essentials (sebelumnya Maps Grounding Lite)	SKU Pro
Cara penagihan permintaan	Setiap permintaan alat yang tidak menggunakan opsi Pro	Setiap permintaan alat yang menggunakan opsi Pro: include_extended_details, page_size di atas 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, atau lebih dari 10 titik jalan perantara	Setiap kueri Google Maps atau perintah yang di-grounding, bergantung pada platform dan model
Model dan platform	Framework model atau agen apa pun yang mendukung MCP. Satu server MCP, satu set alat, dan kredensial yang sama untuk kedua SKU		Model Gemini di Gemini API, Google AI Studio, dan Gemini Enterprise Agent Platform
Hasil yang ditampilkan alat	Fakta inti: detail tempat untuk maksimal 5 tempat per penelusuran, jarak dan durasi rute tanpa lalu lintas real-time, serta cuaca dan prakiraan cuaca saat ini	Semua yang ada di Essentials, ditambah detail tempat yang diperluas (seperti insight dari ulasan), hingga 10 tempat per penelusuran, rute dengan lalu lintas live, dan hingga 25 titik jalan perantara	Detail dan insight tempat dari ulasan, serta informasi rute dengan lalu lintas real-time
Contoh permintaan	Pertanyaan faktual dan logistik: menemukan toko atau bisnis, jam buka, alamat, dan perkiraan jarak atau waktu perjalanan	Pertanyaan subjektif atau luas: suasana, hidangan khas, tips pengunjung, perbandingan 6 hingga 10 tempat, dan waktu perjalanan dalam lalu lintas saat ini	Penelusuran berbasis percakapan, perencanaan itinerari, dan penemuan lokal di Gemini
Visualisasi Kit UI Places	Disertakan tanpa biaya tambahan dengan token visualisasi data agentic (Pratinjau)		Ditagihkan terpisah
Penggunaan gratis per bulan	10.000 permintaan	5.000 permintaan	Bergantung pada platform dan model. Misalnya, di Gemini API, Gemini 3 dan model yang lebih baru menyertakan 5.000 kueri penelusuran gratis per bulan. Setelah itu, kueri penelusuran dikenai biaya $14 per 1.000 kueri.
Harga bayar sesuai penggunaan	$7,00 per 1.000 permintaan, dengan diskon volume	$14,00 per 1.000 permintaan. Hubungi bagian penjualan untuk mengetahui harga volume.
Berlangganan untuk menghemat	Disertakan dalam paket Essentials dan Pro	Tidak disertakan	Tidak tersedia
Mulai	Satu penyiapan untuk kedua SKU: lihat Mengonfigurasi LLM untuk menggunakan server MCP. Selama GA Terbatas, opsi Pro juga memerlukan project di daftar yang diizinkan Pro.		Gemini API atau Agent Platform

Opsi ini berfungsi dengan cara yang sama untuk kedua SKU: mode transportasi, waktu keberangkatan dan waktu tiba, rute alternatif, polyline rute, pencarian cuaca, dan Resolution API. ID ini tidak mengubah SKU yang digunakan untuk menagih permintaan.

Yang ditagih dalam SKU Pro

Alat	Kemampuan	Essentials	Pro
Menelusuri tempat	Tempat per permintaan	Maksimal 5	6 hingga 10 (page_size dari 6 hingga 10)
	Detail tempat yang diperluas dalam ringkasan penelusuran (insight dari ulasan, sorotan menu, suasana, tingkat kesibukan tempat, tips pengunjung, dan jarak atau waktu perjalanan untuk kueri kedekatan)	Tidak tersedia	Tersedia dengan include_extended_details
Menghitung rute	Preferensi pemilihan rute	Tidak memperhitungkan lalu lintas real-time	Memperhitungkan lalu lintas langsung, atau data transportasi umum real-time untuk rute transportasi umum, dengan ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL
	Titik jalan perantara per rute	Maksimal 10	11 hingga 25 (lebih dari 10 intermediate_waypoints)
Lookup weather dan Resolution API	Tidak ada opsi Pro. Semua permintaan ditagih berdasarkan SKU Essentials.

Untuk opsi permintaan yang mengaktifkan setiap kemampuan, lihat Menelusuri tempat dan Menghitung rute.

Opsi Pro selama GA Terbatas

Selama GA Terbatas, opsi Pro hanya tersedia untuk project Google Cloud yang ada dalam daftar yang diizinkan untuk Pro. Hubungi bagian penjualan untuk meminta akses. Setelah project masuk dalam daftar yang diizinkan, setiap kunci API dan klien OAuth di dalamnya dapat menggunakan opsi Pro.

Jika project Anda belum ada dalam daftar yang diizinkan, permintaan yang menggunakan opsi Pro akan ditangani sebagai berikut:

• Search places: include_extended_details diabaikan, dan responsnya berisi maksimal 5 tempat, meskipun Anda menetapkan page_size lebih tinggi. Permintaan ditagih berdasarkan SKU Essentials.
• Compute routes: ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL diperlakukan sebagai ROUTING_PREFERENCE_TRAFFIC_UNAWARE, dan permintaan ditagih berdasarkan SKU Essentials. Permintaan dengan lebih dari 10 titik jalan perantara akan menampilkan error INVALID_ARGUMENT.

Untuk memeriksa apakah project Anda ada dalam daftar yang diizinkan, kirim permintaan search_places dengan page_size ditetapkan ke 10. Gunakan kueri yang luas, seperti restaurants in Chicago. Project dalam daftar yang diizinkan dapat menampilkan lebih dari 5 tempat, yang ditagih berdasarkan SKU Pro. Project lain menampilkan maksimal 5 tempat.

Mengontrol penggunaan Pro

Opsi Pro dinonaktifkan secara default. LLM akan menetapkannya saat permintaan pengguna memanggilnya dan skema alat atau petunjuk Anda mengizinkannya. Skema alat menjelaskan nilai page_size hingga 5 dan maksimal 10 titik jalan perantara. Oleh karena itu, model hanya menggunakan batas Pro yang lebih tinggi jika petunjuk Anda memintanya. Untuk mengelola biaya:

• Beri tahu model kapan opsi Pro sesuai. Misalnya: "Tetapkan include_extended_details hanya jika pengguna bertanya tentang ulasan, menu, atau suasana." Atau: "Gunakan ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL hanya saat pengguna meminta waktu perjalanan saat ini."
• Agar agen tetap menggunakan SKU Essentials, instruksikan model untuk tidak pernah menggunakan opsi Pro. Opsi Pro adalah include_extended_details, page_size di atas 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, dan lebih dari 10 titik jalan perantara. Jika klien MCP Anda dapat membatasi argumen alat, Anda juga dapat memblokir nilai tersebut dalam konfigurasi alatnya.
• Pantau penggunaan Anda di laporan penagihan dan tetapkan pemberitahuan anggaran.

Resolution API

Alat agen Maps Experience menyediakan Resolution API. API ini me-resolve teks lokasi dan URL bentuk bebas menjadi ID tempat Google Maps yang terstruktur. Resolution API tersedia sebagai metode REST dan sebagai alat di server MCP:

• Menyelesaikan nama (REST, MCP): Menyelesaikan sekumpulan nama atau alamat lokasi ke entity tempat tertentu di Google Maps. Hal ini berguna untuk mengaitkan kueri pengguna yang tidak terstruktur ke ID Tempat yang stabil.
• Resolve Maps URLs (REST, MCP): Me-resolve sekumpulan URL Google Maps ke entity tempat tertentu. Format yang didukung mencakup URL tempat standar dan URL yang dipersingkat.

Anda dapat menggunakan ID Tempat yang ditampilkan dengan Google Maps Platform API lainnya. Setiap respons juga menyertakan link yang menyimpan tempat yang di-resolve sebagai daftar di Google Maps.

Untuk mengetahui informasi selengkapnya, lihat Maps Tools Resolution API.

Coba aplikasi contoh (Buka di tab baru)

Penagihan dan kuota

Cara Anda ditagih

Dengan model harga bayar sesuai penggunaan Google Maps Platform, penggunaan alat agen Maps Experience dihitung untuk setiap permintaan. Setiap permintaan mewakili satu peristiwa penagihan. Penggunaan dilacak untuk setiap SKU produk. Tagihan Anda menampilkan item baris untuk setiap SKU selain total tagihan Anda. Lihat Ringkasan pelaporan untuk mengetahui informasi selengkapnya.

Setiap permintaan Telusuri tempat, Hitung rute, atau Cari cuaca ditagih berdasarkan satu SKU, Essentials atau Pro. Permintaan yang menggunakan opsi Pro akan ditagih berdasarkan SKU Pro. Penagihan tidak pernah dilakukan untuk kedua SKU, dan jumlah opsi Pro tidak mengubah biaya. Opsi berikut menentukan SKU:

Alat	Essentials	Pro
search_places	Permintaan apa pun tanpa opsi Pro: page_size 5 atau kurang, dan include_extended_details tidak ditetapkan atau false	include_extended_details ditetapkan ke true, atau page_size dari 6 hingga 10
compute_routes	Semua permintaan tanpa opsi Pro: routing_preference tidak ditetapkan atau ROUTING_PREFERENCE_TRAFFIC_UNAWARE, dan 10 atau kurang titik jalan perantara, dengan mode perjalanan apa pun	routing_preference ditetapkan ke ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, atau 11 hingga 25 titik jalan perantara
lookup_weather	Setiap permintaan	—

Untuk mengetahui harga Essentials, lihat detail SKU Essentials. Permintaan Pro ditagih sebesar $14,00 per 1.000 permintaan setelah 5.000 permintaan pertama setiap bulan. Hubungi bagian penjualan untuk mengetahui harga volume.

Selama GA Terbatas, opsi Pro hanya berlaku pada project dalam daftar yang diizinkan Pro. Untuk mengetahui detailnya, lihat Opsi Pro selama GA Terbatas.

Lihat Tabel harga utama dan Tabel harga India untuk mengetahui detail harga.

Permintaan Resolution API (ResolveNames dan ResolveMapsUrls) ditagih tanpa biaya berdasarkan SKU Places API Text Search Essentials (IDs Only).

Penggunaan SKU Essentials juga disertakan dalam paket Berlangganan untuk berhemat Essentials dan Pro. SKU Pro tidak disertakan dalam paket Berlangganan untuk menghemat.

Kuota

Kuota berikut berlaku untuk alat dan API yang disediakan oleh alat agen Maps Experience:

• Search places: 300 kueri per menit, per project.
• Pencarian cuaca: 300 kueri per menit, per project.
• Compute routes: 300 kueri per menit, per project.
• Menyelesaikan nama: 600 kueri per menit, per project.
• Menyelesaikan URL Maps: 600 kueri per menit, per project.

Kuota dihitung per alat dan digunakan bersama oleh SKU Essentials dan Pro. Permintaan Pro menggunakan kuota yang sama dengan permintaan Essentials untuk alat yang sama.

Setiap permintaan Resolution API dihitung sebagai satu kueri, terlepas dari jumlah item yang dimuatnya.

Kebijakan dan persyaratan layanan

Alat agen Maps Experience tunduk pada Persyaratan Layanan Google Maps Platform, termasuk persyaratan khusus layanan. Bagian ini menjelaskan persyaratan penggunaan tambahan untuk alat agen Maps Experience, termasuk LLM yang kompatibel dan atribusi sumber. Persyaratan ini berlaku untuk semua hasil, apa pun SKU yang ditagih untuk permintaan.

Persyaratan untuk LLM yang Kompatibel

Anda hanya boleh menggunakan alat agen Maps Experience dengan LLM yang mematuhi Persyaratan Layanan Google Maps Platform.

Misalnya, Anda bertanggung jawab untuk memastikan bahwa Konten Google Maps tidak di-cache, disimpan, atau digunakan untuk meningkatkan kualitas LLM yang Anda pilih untuk digunakan. Sebelum menggunakan alat agen Maps Experience, Anda harus meninjau Persyaratan Layanan untuk model apa pun yang ingin Anda gunakan dengan alat agen Maps Experience. Anda tidak boleh menggunakan alat agen Maps Experience dengan model apa pun yang menggunakan input data ke dalam model untuk pelatihan atau peningkatan model apa pun. Anda bertanggung jawab untuk memastikan bahwa penggunaan model oleh Anda sepenuhnya mematuhi batasan terkait Konten Google Maps dalam Persyaratan Layanan Google Maps Platform, termasuk persyaratan khusus layanan.

Persyaratan atribusi untuk sumber Google Maps

Setiap respons alat dari alat agen Maps Experience menyertakan sumber. Saat menampilkan hasil dari alat agen Maps Experience, Anda harus menyertakan sumber Google Maps terkait dan memenuhi persyaratan berikut:

• Sumber Google Maps harus langsung mengikuti konten yang dihasilkan yang didukung oleh sumber tersebut. Konten yang dihasilkan ini juga disebut sebagai Output Grounding.
• Sumber Google Maps harus dapat dilihat dalam satu interaksi pengguna.

Sumber untuk alat Telusuri tempat

Kolom places alat search_places menyediakan sumber yang mendukung summary. Untuk places, metadata berikut ditampilkan:

• place (nama resource)
• id
• location
• googleMapsLinks

Untuk setiap tempat, Anda harus membuat pratinjau link yang memenuhi persyaratan berikut:

• Atribusikan setiap sumber ke Google Maps, dengan mengikuti panduan atribusi teks alat agen Maps Experience.
• Tautkan ke sumber menggunakan places.googleMapsLinks.placeUrl dari respons.

Persyaratan ini juga berlaku untuk ringkasan yang menyertakan detail tempat yang diperluas dari Pro, seperti insight dari ulasan. summary mengutip setiap tempat dengan indeks berbasis nol, misalnya [0], yang dipetakan ke entri di places. Setiap tempat juga menyertakan googleMapsLinks.reviewsUrl, yang tertaut ke ulasan tempat tersebut di Google Maps. Pengguna dapat mengikutinya untuk melihat ulasan di balik insight.

Antarmuka yang mengutamakan suara

Jika aplikasi Anda menampilkan hasil alat agen Maps Experience melalui suara, Anda juga harus memenuhi persyaratan untuk antarmuka yang mengutamakan suara. Rangkuman:

• Sumber: Menampilkan sumber Google Maps di UI pendamping yang menampilkan rekaman historis verbatim dari percakapan suara.
• Pengungkapan aktif: Pada saat interaksi, beri tahu pengguna bahwa konten buatan AI mungkin menyertakan informasi dari Google Maps. Beri tahu juga bahwa sumber mendetail tersedia di UI pendamping. Anda dapat melakukannya di layar atau dengan suara.
• Pengungkapan persisten: Simpan penjelasan persisten, misalnya di menu setelan suara, bahwa konten buatan AI dapat menyertakan konten Google Maps.
• Pertanyaan pengguna: Jawab pertanyaan pengguna secara akurat tentang sumber konten, dan arahkan mereka ke UI pendamping untuk mengetahui detailnya.

Mengonfigurasi LLM untuk menggunakan server MCP

Untuk menggunakan alat agen Maps Experience, Anda memerlukan project Google Cloud dengan layanan API alat agen Maps Experience yang diaktifkan. Anda juga memerlukan kunci API atau client ID OAuth. Kemudian, Anda dapat mengonfigurasi LLM untuk mengakses server MCP. Server MCP menggunakan transpor HTTP yang Dapat Di-streaming.

Mengaktifkan alat agen Maps Experience di project Google Cloud Anda

Untuk mengaktifkan API di project Anda:

1. Di Konsol Google Cloud, pilih project yang ingin Anda gunakan untuk alat agen Maps Experience.
2. Aktifkan penagihan untuk project di Konsol Google Cloud.
3. Aktifkan alat agen Maps Experience di Library API Konsol Google Cloud.

Melakukan autentikasi menggunakan kunci API

Anda dapat menggunakan kunci API yang ada dengan alat agen Maps Experience atau membuat kunci API baru. Apa pun caranya, aktifkan layanan API Maps Experience agent tools di project Google Cloud dan kunci.

Catatan: Untuk pengujian dan pembuatan prototipe, Anda juga dapat menggunakan Maps Demo Key tanpa biaya, tanpa akun penagihan.

Untuk melakukan autentikasi menggunakan kunci API:

1. Buat atau konfigurasikan kunci API dengan mengikuti langkah-langkah di Memulai Google Maps Platform.
2. Teruskan kunci ke server MCP menggunakan header X-Goog-Api-Key. Anda harus menentukannya sebagai header HTTP kustom dalam konfigurasi alat MCP LLM.

Catatan: Saat Anda membuat atau mengonfigurasi kunci API, batasi penggunaannya dengan menerapkan pembatasan yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Membatasi kunci API.

Melakukan autentikasi menggunakan OAuth

Anda dapat melakukan autentikasi menggunakan OAuth dengan membuat kredensial OAuth dan meneruskannya ke aplikasi host MCP atau server MCP.

Untuk melakukan autentikasi menggunakan OAuth:

1. Di Konsol Google Cloud, pilih project yang ingin Anda gunakan untuk alat agen Maps Experience.
2. Di menu API & Services, pilih Credentials.
3. Di menu atas, pilih Create credentials > OAuth client ID.
4. Jika project tidak memiliki layar izin yang dikonfigurasi, klik Configure consent screen dan ikuti petunjuk di layar.
5. Di bagian Metrik, klik Buat klien OAuth.
6. Di layar Create OAuth client ID, pilih jenis aplikasi dan masukkan nama untuk client ID.
7. Tentukan detail tambahan yang relevan dengan jenis permohonan Anda. Misalnya, jika Anda membuat aplikasi web, tambahkan URI yang diizinkan untuk permintaan browser dan server.
8. Setelah klien Anda dibuat, simpan client ID dan rahasia klien.
9. Saat Anda mengonfigurasi aplikasi host MCP atau server MCP, teruskan client ID dan rahasia OAuth Anda. Anda juga harus meminta cakupan berikut: https://www.googleapis.com/auth/maps-platform.mapstools.

Untuk mengetahui informasi selengkapnya, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Mengonfigurasi LLM untuk mengakses server MCP alat agen Maps Experience

Setelah mengaktifkan layanan Maps Experience agent tools dan membuat kredensial, Anda dapat mengonfigurasi LLM untuk mengakses server MCP. Ikuti dokumentasi konfigurasi MCP LLM Anda dan gunakan URL server MCP: https://mapstools.googleapis.com/mcp

Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi MCP di aplikasi AI.

Mengonfigurasi alat agen Maps Experience dengan Gemini CLI

Bagian ini memberikan contoh cara mengonfigurasi server MCP alat agen Maps Experience menggunakan Gemini CLI. Untuk mengetahui detail selengkapnya, lihat Server MCP dengan Gemini CLI.

1. Setelah menginstal Gemini CLI, jalankan gemini mcp add untuk mengonfigurasi server 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
   

   Jika konfigurasi berhasil, Anda akan melihat konfirmasi bahwa server telah ditambahkan ke setelan pengguna.

2. Untuk memvalidasi bahwa server berfungsi dengan benar, jalankan perintah /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. Mulai ajukan pertanyaan terkait Maps dengan CLI. Misalnya, coba "Rekomendasikan beberapa restoran di Mountain View" yang akan memanggil alat search_places atas nama Anda.

Catatan: Untuk menggunakan OAuth dengan ekstensi Gemini CLI, lihat bagian Gemini CLI di dokumentasi MCP di Google Cloud.

Mengonfigurasi alat agen Maps Experience dengan Agent Development Kit (ADK)

Bagian ini menunjukkan cara mengonfigurasi server MCP dengan Agent Development Kit (ADK) di Python, Java, atau TypeScript.

Catatan: Pastikan Anda telah mengaktifkan alat agen Maps Experience dan mendapatkan kunci API.

Python

Anda dapat menemukan implementasi lengkap contoh ini di GitHub di repositori adk-samples.

Langkah 1: Tentukan Agen Anda dengan McpToolset untuk alat agen Maps Experience

Ubah file agent.py Anda. Ganti YOUR_GOOGLE_MAPS_API_KEY dengan kunci API Anda yang sebenarnya.

# ./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"
                }
            )
        )
    ]
)
    

Langkah 2: Pastikan __init__.py Ada

Pastikan Anda memiliki __init__.py di direktori yang sama dengan agent.py:

from . import agent
    

Langkah 3: Jalankan adk web dan Berinteraksi

1. Tetapkan Variabel Lingkungan:
   Tetapkan kunci Google Maps API Anda sebagai variabel lingkungan di terminal:

   export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
           

2. Jalankan adk web:
   Jalankan perintah berikut untuk memulai antarmuka web ADK:

   adk web
           

3. Berinteraksi di UI:
   • Pilih travel_planner_agent.
   • Coba perintah seperti:
     • "Saya akan berada di San Francisco besok. Bagaimana kondisi cuacanya?"
     • "Cari kedai kopi di dekat Golden Gate Park."
     • "Dapatkan rute dari GooglePlex ke SFO."

Java

Tentukan agen yang melakukan inisialisasi McpToolset di Java. Ganti YOUR_GOOGLE_MAPS_API_KEY_HERE dengan kunci API sebenarnya yang Anda peroleh jika Anda tidak menggunakan variabel lingkungan.

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

Tentukan agen yang melakukan inisialisasi MCPToolset di 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"
            }
        })
    ],
});
    

Membagikan masukan

Untuk memberikan masukan tentang alat agen Maps Experience, gunakan formulir berikut:

• Laporkan bug
• Mengirim permintaan fitur
• Berikan masukan