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.1 Pro. Agen ini 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 di dunia nyata.

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

Yang akan Anda lakukan

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

Yang akan 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 ahli Python, tetapi pemahaman dasar tentang cara membaca kode akan membantu Anda memahami konsepnya.

2. Sebelum memulai

Membuat Project Google Cloud

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

2. 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 dan sudah dilengkapi dengan alat yang diperlukan.

1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud:

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

gcloud auth list

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

gcloud config get project

4. Konfirmasi bahwa project sudah sesuai dengan yang diharapkan, lalu jalankan perintah di bawah untuk menetapkan project id:

export PROJECT_ID=$(gcloud config get project)

3. Dapatkan Kode

Membuat Clone Repositori

1. Buat clone repositori ke lingkungan Cloud Shell Anda:

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

2. Buka direktori demo:

cd mcp/examples/launchmybakery

Mengautentikasi

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.

Catatan: ADK tidak otomatis memperbarui token OAuth 2.0 Anda. Jika sesi chat Anda berlangsung lebih dari 60 menit, Anda mungkin perlu melakukan autentikasi ulang menggunakan perintah di atas.

4. Mengonfigurasi lingkungan dan BigQuery

Menjalankan Skrip Penyiapan

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

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

2. Jalankan skrip penyiapan BigQuery. Skrip ini mengotomatiskan pembuatan bucket Cloud Storage, mengupload data, dan menyediakan set data serta 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:

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

3. 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.

1. Buat lingkungan virtual:

python3 -m venv .venv

2. Aktifkan lingkungan virtual:

source .venv/bin/activate

3. Instal ADK:

pip install google-adk==1.28.0

4. 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 solusinya:

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.1 Pro).
• tools.py: Berisi definisi alat kustom.
• .env: Berisi konfigurasi dan secret project Anda (seperti kunci API) yang dibuat oleh skrip penyiapan.

1. Inisialisasi Alat MCP:

Sekarang, buka adk_agent/mcp_bakery_app/tools.py di Editor untuk memahami cara alat MCP diinisialisasi.

Agar agen kita 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

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

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.1-pro-preview.

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

root_agent = LlmAgent(
    model='gemini-3.1-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. Anda dapat mengubah petunjuk untuk melihat pengaruhnya terhadap perilaku agen.

7. Chat dengan agen Anda

Kembali ke terminal di Cloud Shell dan jalankan perintah ini untuk membuka direktori adk_agent (jika Anda belum melakukannya):

cd adk_agent/

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

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Setelah server dimulai, Anda akan melihat hal berikut di Cloud Shell:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Anda memiliki dua opsi untuk mengakses UI ADK:

Opsi 1: Klik link lokal Klik link http://127.0.0.1:8000 yang muncul di terminal Cloud Shell Anda.

Opsi 2: Menggunakan Pratinjau Web

1. Klik tombol Web Preview di sudut kanan atas Cloud Shell.
2. Pilih Change port.
3. Masukkan 8000 sebagai nomor port, lalu klik Change and Preview.

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

1. Menemukan Kawasan (Makro): "Saya ingin membuka toko roti di Los Angeles. Temukan kode pos dengan skor kunjungan langsung pagi tertinggi.

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

2. Memvalidasi Lokasi (Mikro): "Dapatkah Anda menelusuri 'Toko Roti' di kode pos tersebut untuk melihat apakah sudah jenuh?"

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

Cobalah! Lihat pertanyaan contoh ini untuk melihat agen ADK Anda beraksi:

• "Saya ingin membuka lokasi toko roti keempat saya di Los Angeles. Saya memerlukan lingkungan dengan aktivitas pagi. Temukan kode pos dengan skor kunjungan langsung 'pagi' tertinggi.
• "Dapatkah Anda menelusuri 'Toko Roti' di kode pos tersebut untuk melihat apakah sudah jenuh? Jika terlalu banyak, periksa toko 'Kopi Spesial', sehingga saya dapat menempatkan diri di dekatnya untuk mendapatkan traffic pengunjung."
• "Oke, dan saya ingin memposisikan ini sebagai merek premium. Berapa harga maksimum yang dikenakan untuk 'Roti Sourdough' di area LA Metro?"
• "Sekarang saya ingin proyeksi pendapatan untuk Desember 2025. Lihat histori penjualan saya dan ambil data dari toko saya yang berkinerja terbaik untuk 'Roti Sourdough'. Jalankan perkiraan untuk Desember 2025 guna memperkirakan kuantitas yang akan saya jual. Kemudian, hitung total pendapatan yang diproyeksikan menggunakan harga premium yang kita temukan (gunakan $18)"
• "Itu akan menutupi sewa saya. Terakhir, mari kita verifikasi logistik. Temukan "Restaurant Depot" terdekat ke area yang diusulkan dan pastikan waktu mengemudi kurang dari 30 menit untuk pengisian ulang harian.

Setelah selesai menguji agen, Anda dapat menghentikan antarmuka web ADK dengan menekan Ctrl+C di terminal Cloud Shell.

8. Pembersihan

Untuk menghindari biaya berkelanjutan ke 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 membangun Agen Location Intelligence 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:

• Infrastruktur sebagai Kode: Anda menyediakan data stack 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 membangun satu agen yang mampu menggabungkan insight secara strategis dari dua domain berbeda untuk memecahkan masalah bisnis.

Dokumen referensi

• Menggunakan server MCP BigQuery
• Menggunakan Server MCP Maps Groundling Lite
• Mengautentikasi MCP