Membangun Agen ADK Location Intelligence dengan server MCP untuk BigQuery dan Google Maps

1. Pengantar

Dalam Codelab ini, Anda akan membuat agen dengan ADK yang didukung oleh Gemini 3.0 Pro. Agen akan dilengkapi dengan alat dari dua server MCP jarak jauh (yang dihosting Google) untuk mengakses BigQuery secara aman guna mendapatkan data demografi, harga, dan penjualan, serta Google Maps untuk analisis dan validasi lokasi dunia nyata.

Agen mengatur permintaan antara pengguna dan layanan Google Cloud untuk memecahkan masalah bisnis terkait set data toko roti fiktif.

Yang akan Anda lakukan

Siapkan Data: Buat set data toko roti dasar di BigQuery.
Mengembangkan Agen: Bangun agen cerdas menggunakan Agent Development Kit (ADK).
Mengintegrasikan Alat: Lengkapi agen dengan fungsi BigQuery dan Maps melalui server MCP.
Menganalisis Pasar: Berinteraksi dengan agen untuk menilai tren dan saturasi pasar.

Yang Anda butuhkan

Browser web seperti Chrome
Project Google Cloud yang mengaktifkan penagihan atau akun Gmail.

Codelab ini ditujukan bagi developer dari semua level, termasuk pemula. Anda akan menggunakan antarmuka command line di Google Cloud Shell dan kode Python untuk pengembangan ADK. Anda tidak perlu menjadi pakar Python, tetapi pemahaman dasar tentang cara membaca kode akan membantu Anda memahami konsepnya.

2. Sebelum memulai

Buat Project Google Cloud

Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.

Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

Klik Activate Cloud Shell di bagian atas konsol Google Cloud:

Setelah terhubung ke Cloud Shell, jalankan perintah ini untuk memverifikasi autentikasi Anda di Cloud Shell:

gcloud auth list

Jalankan perintah berikut untuk mengonfirmasi bahwa project Anda dikonfigurasi untuk digunakan dengan gcloud:

gcloud config get project

Pastikan project sudah sesuai, lalu jalankan perintah di bawah untuk menetapkan project ID Anda:

export PROJECT_ID=$(gcloud config get project)

3. Dapatkan Kode

Membuat Clone Repositori

Clone repositori ke lingkungan Cloud Shell Anda:

git clone https://github.com/google/mcp.git

Buka direktori demo:

cd mcp/examples/launchmybakery

Authenticate

Jalankan perintah berikut untuk melakukan autentikasi dengan akun Google Cloud Anda. Hal ini diperlukan agar ADK dapat mengakses BigQuery.

gcloud auth application-default login

Ikuti petunjuk untuk menyelesaikan proses autentikasi.

4. Mengonfigurasi lingkungan dan BigQuery

Jalankan Skrip Penyiapan

Jalankan skrip penyiapan lingkungan. Skrip ini mengaktifkan BigQuery API dan Google Maps API, serta membuat file .env dengan Project ID dan Kunci Maps API Anda.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

Jalankan skrip penyiapan BigQuery. Skrip ini mengotomatiskan pembuatan bucket Cloud Storage, mengupload data, serta menyediakan set data dan tabel BigQuery.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Setelah skrip selesai, set data mcp_bakery akan dibuat dan diisi dengan tabel berikut:

demografi - data sensus dan karakteristik populasi menurut kode pos.
bakery_prices - harga dan detail produk pesaing untuk berbagai produk roti.
sales_history_weekly - performa penjualan mingguan (jumlah dan pendapatan) menurut toko dan produk.
foot_traffic - perkiraan skor kunjungan langsung menurut kode pos dan waktu.

Verifikasi bahwa set data dan tabel telah dibuat dengan membuka konsol BigQuery di Project Google Cloud Anda:

5. Instal ADK

Setelah infrastruktur siap, mari kita buat lingkungan Python virtual dan instal paket yang diperlukan untuk ADK.

Buat lingkungan virtual:

python3 -m venv .venv

Aktifkan lingkungan virtual:

source .venv/bin/activate

Instal ADK:

pip install google-adk

Buka direktori agen:

cd adk_agent/

6. Memeriksa aplikasi ADK

Klik tombol Open Editor di Cloud Shell untuk membuka Cloud Shell Editor dan melihat repositori yang di-clone di direktori mcp/examples/launchmybakery.

Kode agen sudah disediakan di direktori adk_agent/. Mari kita pelajari struktur solusi:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

File utama di mcp_bakery_app:

agent.py: Logika inti yang menentukan agen, alatnya, dan model (Pratinjau Gemini 3.0 Pro).
tools.py: Berisi definisi alat kustom.
.env: Berisi konfigurasi project dan secret (seperti kunci API) yang dibuat oleh skrip penyiapan.

1. Inisialisasi Toolset MCP:

Sekarang, buka adk_agent/mcp_bakery_app/tools.py di Editor untuk memahami cara inisialisasi toolset MCP.

Agar agen kami dapat berkomunikasi dengan BigQuery dan Google Maps, kita perlu mengonfigurasi klien Model Context Protocol (MCP).

Kode ini membuat koneksi yang aman ke server MCP jarak jauh Google menggunakan StreamableHTTPConnectionParams.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

Toolset Peta: Mengonfigurasi koneksi ke server MCP Maps menggunakan Kunci API Anda.
Toolset BigQuery: Fungsi ini mengonfigurasi koneksi ke server BigQuery MCP. Library ini menggunakan google.auth untuk otomatis mengambil kredensial Cloud Anda, membuat token OAuth Bearer, dan menyisipkannya ke header Authorization.

2. Definisi Agen:

Sekarang, buka adk_agent/mcp_bakery_app/agent.py di Editor untuk melihat cara agen ditentukan.

LlmAgent diinisialisasi dengan model gemini-3-pro-preview.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

Petunjuk Sistem: Agen diberi petunjuk khusus untuk menggabungkan insight dari BigQuery (untuk data) dan Maps (untuk analisis lokasi).
Alat: maps_toolset dan bigquery_toolset ditetapkan ke agen, sehingga agen memiliki akses ke kemampuan kedua layanan tersebut.

Agen mematuhi petunjuk dan alat yang ditentukan di repo. Jangan ragu untuk mengubah petunjuk untuk melihat pengaruhnya terhadap perilaku agen.

7. Mulai chat dengan agen Anda.

Kembali ke terminal di Cloud Shell dan jalankan perintah ini untuk membuka direktori adk_agent:

cd adk_agent

Jalankan perintah berikut untuk memulai antarmuka web ADK. Perintah ini akan menjalankan server web ringan untuk menghosting aplikasi chat:

adk web

Setelah server dimulai, Anda dapat melakukan chat dengan agen Anda dengan mengklik URL yang diberikan untuk meluncurkan Antarmuka Web ADK.

Berinteraksi dengan Agen dengan mengajukan pertanyaan berikut. Anda akan melihat alat yang relevan dipanggil.

Temukan Lingkungan (Makro): "Saya ingin membuka toko roti di Los Angeles. Temukan kode pos dengan skor traffic jalan kaki pagi tertinggi."

Agen harus menggunakan alat get_table_info dan execute_sql untuk mengkueri tabel foot_traffic di BigQuery.

Validasi Lokasi (Mikro): "Dapatkah Anda menelusuri'Toko roti' di kode pos tersebut untuk melihat apakah sudah banyak toko roti di sana?"

Agen harus menggunakan alat search places di toolset Maps untuk menjawab pertanyaan ini.

Cobalah! Lihat contoh pertanyaan berikut untuk melihat cara kerja agen ADK Anda:

"Saya ingin membuka lokasi toko roti keempat saya di Los Angeles. Saya membutuhkan lingkungan dengan aktivitas pagi. Temukan kode pos dengan skor traffic pejalan kaki 'pagi' tertinggi."
"Dapatkah Anda menelusuri'Toko roti' di kode pos tersebut untuk melihat apakah sudah banyak toko roti di sana? Jika terlalu banyak, cari toko 'Kopi Spesial', agar saya dapat memposisikan diri di dekatnya untuk mencatat traffic pejalan kaki."
"Oke, dan saya ingin memosisikan ini sebagai brand premium. Berapa harga maksimum yang dikenakan untuk 'Sourdough Loaf' di area LA Metro?"
"Sekarang saya ingin proyeksi pendapatan untuk Desember 2025. Lihat histori penjualan saya dan ambil data dari toko dengan performa terbaik saya untuk 'Roti Sourdough'. Jalankan perkiraan untuk Desember 2025 guna memperkirakan jumlah yang akan saya jual. Kemudian, hitung total pendapatan yang diproyeksikan menggunakan harga premium yang kami temukan (mari kita gunakan $18)"
"Itu akan menutupi sewa rumah saya. Terakhir, mari kita verifikasi logistik. Temukan "Restaurant Depot" terdekat dengan area yang diusulkan dan pastikan waktu berkendara kurang dari 30 menit untuk pengisian ulang harian."

8. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama Codelab ini.

Jalankan skrip pembersihan. Skrip ini akan menghapus set data BigQuery, bucket Cloud Storage, dan kunci API yang dibuat selama penyiapan.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Selamat

Misi Selesai! Anda telah berhasil membuat Agen Analisis Lokasi menggunakan Agent Development Kit (ADK).

Dengan menjembatani kesenjangan antara data "perusahaan" Anda di BigQuery dan konteks lokasi dunia nyata dari Google Maps, Anda telah membuat alat canggih yang mampu melakukan penalaran bisnis yang kompleks - semuanya didukung oleh Model Context Protocol (MCP) dan Gemini.

Yang telah Anda capai:

Infrastructure as Code: Anda menyediakan stack data menggunakan alat Google Cloud CLI.
Integrasi MCP: Anda menghubungkan agen AI ke dua server MCP jarak jauh yang berbeda (BigQuery & Maps) tanpa menulis wrapper API yang kompleks.
Penalaran Terpadu: Anda membuat satu agen yang mampu menggabungkan insight secara strategis dari dua domain berbeda untuk memecahkan masalah bisnis.