Tutorial Google ADK: Membangun Agen Logistik Server MCP

Hambatan terbesar dalam membangun agen AI canggih saat ini bukan pada modelnya, melainkan integrasinya. Jika Anda ingin agen mengakses sepuluh alat enterprise yang berbeda, biasanya Anda harus menulis sepuluh pembungkus API yang berbeda. Berdasarkan pengalaman saya, hal ini menimbulkan kelelahan membuat wrapper dan beban pemeliharaan yang besar. Setiap kali API berubah, agen Anda rusak.

Solusinya ada pada kemitraan antara Google Agent Development Kit (ADK) dan Model Context Protocol (MCP). Jika kita menganggap AI sebagai pekerja, ADK adalah "otak" (mengorkestrasi logika dan memori), sementara MCP adalah "tangan" (cara standar untuk mengambil dan menggunakan alat apa pun).

Dalam tutorial ini, kita akan membangun agen pemulihan logistik nyata menggunakan ADK. Agen akan:

1. Menjalankan kueri BigQuery untuk pesanan terlambat prioritas tinggi. 
2. Menghitung jarak berkendara nyata dari gudang ke pelanggan menggunakan server MCP Google Maps. 
3. Merekomendasikan tindakan pemulihan, seperti meningkatkan ke pengiriman udara untuk pengiriman jarak jauh.

Semua ini terjadi tanpa menulis satu baris pun kode API kustom. Agen secara otomatis menemukan dan menggunakan alat-alatnya.

Baru mengenal Google Cloud? Saya merekomendasikan memulai dengan kursus gratis Introduction to GCP untuk mencakup penagihan, proyek, dan layanan dasar.

Apa itu Google ADK?

Google Agent Development Kit (ADK) adalah kerangka kerja open-source dari Google, berorientasi kode, untuk membangun, menguji, dan menerapkan agen AI. Sementara kerangka kerja seperti LangChain berfokus pada rangkaian (chains), ADK dibangun untuk eksekusi. ADK menyediakan struktur standar tentang bagaimana agen berpikir, menggunakan seperangkat alat, dan berjalan di lingkungan produksi.

Berikut konsep kuncinya:

• Agen: Entitas inti yang didefinisikan oleh modelnya (misalnya, Gemini 2.0 Flash) dan seperangkat instruksinya.
• Toolset: Kumpulan kapabilitas. Alih-alih mendefinisikan alat secara manual, kita mengarahkan ADK ke server MCP, dan ia secara otomatis "mempelajari" alat-alatnya.
• Runner: Mesin eksekusi yang mengelola status percakapan dan loop iteratif "Thought-Action-Observation".

Pendekatan berorientasi kode ini memungkinkan kita menggunakan pengontrol versi, pengujian, dan CI/CD sebagaimana pada perangkat lunak biasa. ADK juga menawarkan integrasi mendalam dengan Google, sehingga server MCP terkelola hampir tidak memerlukan penerapan apa pun untuk BigQuery atau Maps.

Untuk perbandingan penyedia cloud "tiga besar" dan layanannya, pastikan untuk melihat panduan kami tentang AWS vs. Azure vs. Google Cloud.

Arsitektur Integrasi dan Alur Logika Google ADK

Agen pemulihan logistik kita mengikuti jalur penalaran yang jelas untuk menyelesaikan masalah bisnis. Memahami alurnya akan membantu saat Anda mulai menulis instruksi prompt nanti.

Loop penalarannya mengikuti langkah-langkah ini:

1. Agen memanggil MCP BigQuery untuk menemukan baris dengan status='Delayed' dan priority='High'. 

2. Untuk setiap pesanan yang dikembalikan, agen mengekstrak alamat gudang dan pelanggan. 

3. Agen memanggil MCP Google Maps untuk setiap pesanan guna menghitung jarak berkendara. 

4. Agen menerapkan logika bisnis (misalnya, jarak di atas 500 mil berarti pengiriman udara) dan menyajikan tabel rekomendasi dalam markdown.

Menyiapkan Server MCP

Sebelum mulai menulis kode, kita perlu menyiapkan infrastruktur cloud dasar dan menyiapkan server MCP. Berdasarkan pengalaman saya, menyiapkan izin IAM dengan benar adalah bagian terpenting pada fase ini.

Langkah 1: Menginisialisasi Google Cloud CLI 

Pastikan Anda telah memasang Google Cloud CLI terlebih dahulu. Untuk memulai, buka terminal Anda dan jalankan perintah berikut untuk menautkan lingkungan lokal ke akun Google Anda:

gcloud init

Setelah menjalankannya, jendela peramban akan terbuka otomatis. Anda akan diminta masuk dengan akun Google Anda. Setelah masuk, klik Allow untuk memberikan izin kepada CLI mengelola sumber daya Anda. 

Kembali ke terminal, prompt akan meminta Anda memilih proyek default. Jika Anda sudah membuatnya, pilih ID proyek tersebut, atau buat proyek baru di terminal.

Langkah 2: Menyiapkan penagihan

Untuk menggunakan layanan API, Anda perlu menyiapkan penagihan. Meski begitu, Google Cloud memberi Anda kredit gratis sebesar $300 selama 90 hari untuk mencoba layanan seperti Compute, GKE, dan Maps, dan kredit gratis tersebut lebih dari cukup untuk contoh di tutorial ini. Anda hanya akan ditagih jika mengaktifkan pembayaran sesuai pemakaian atau prabayar. Untuk menyiapkan penagihan:

1. Buka halaman penagihan Google Console dan masuk dengan akun yang Anda gunakan untuk gcloud.

2. Buat akun penagihan jika Anda belum memilikinya (menambahkan metode pembayaran diperlukan, tetapi kredit gratis akan digunakan terlebih dahulu).

3. Tautkan akun penagihan ke proyek Anda: Billing → Link a project → pilih proyek Anda, atau jalankan:

gcloud billing projects link YOUR_PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

Langkah 3: Mengaktifkan API inti dan layanan MCP

Berikutnya, kita perlu mengaktifkan API produk utama. Ini memungkinkan agen mengakses layanan data mentah seperti BigQuery dan Maps.

gcloud services enable bigquery.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable mapstools.googleapis.com

Sekarang, kita harus mengaktifkan Managed MCP Endpoints. Saya merasa bermanfaat memikirkan ini sebagai antarmuka penerjemah yang berada di atas API biasa. 

Pertama, mari simpan ID proyek dan email akun Anda di variabel lingkungan. Ini mencegah kita harus mengetiknya secara manual untuk setiap perintah berikutnya:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)

Dengan variabel tersebut disetel, jalankan perintah berikut untuk mengaktifkan fitur beta MCP untuk proyek Anda. Perintah ini memberi tahu Google untuk menyiapkan endpoint MCP jarak jauh yang akan dipanggil agen Anda:

gcloud beta services mcp enable bigquery.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable mapstools.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable container.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable compute.googleapis.com --project=$PROJECT_ID

Langkah 3: Konfigurasikan IAM dan Kunci Maps 

MCP menggunakan model keamanan "dua lapis". Anda memerlukan izin untuk berbicara dengan server MCP itu sendiri dan izin terpisah untuk mengakses data sebenarnya (seperti baris dalam tabel). Anda dapat melakukannya menggunakan gcloud CLI atau UI Google Cloud Console.

Opsi IAM A: Menggunakan gcloud CLI 

Untuk memberikan izin pada akun Anda menggunakan MCP dan berinteraksi dengan BigQuery, jalankan tiga perintah ini:

# Izin untuk berbicara dengan MCP Translator
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# Izin untuk menjalankan job BigQuery dan melihat data
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.dataViewer"

Opsi IAM B: Menggunakan Google Cloud Console (UI)

Jika Anda lebih suka antarmuka visual, Anda dapat mengikuti langkah-langkah ini di peramban:

1. Buka halaman IAM & Admin di Google Cloud Console Anda.
2. Temukan alamat email Anda dalam daftar dan klik ikon Edit Member (pensil).
3. Klik Add Another Role dan cari MCP Tool User.
4. Ulangi proses untuk menambahkan BigQuery Data Viewer dan BigQuery Job User.
5. Klik Save.

Buat kunci API Maps

Terakhir, buat kunci API Maps. Berbeda dengan BigQuery, yang menggunakan kredensial login Anda, server MCP Maps menggunakan kunci ini untuk penagihan dan pelacakan kuota: 

gcloud alpha services api-keys create --display-name="Maps-MCP-Key"

Langkah 4: Memvalidasi server secara lokal dengan MCP Inspector

Sebelum menulis kode Python, kita harus melakukan pemeriksaan cepat menggunakan MCP Inspector. Kita akan menggunakan perintah npx, yaitu alat yang hadir bersama Node.js. 

Tujuannya adalah memungkinkan Anda menjalankan sebuah paket (seperti inspector) seketika tanpa harus memasangnya permanen di komputer. Jalankan ini di terminal Anda:

npx @modelcontextprotocol/inspector

Ini akan meluncurkan antarmuka web di peramban Anda (biasanya di http://localhost:3000). Saya membuat pilihan spesifik dalam daftar penyiapan di bawah untuk memastikan kita menguji versi Remote Managed dari server Google, bukan mock lokal:

1. Transport type: Streamable HTTP. Kita memilih ini karena merupakan protokol standar produksi yang digunakan Google untuk server cloud terkelola.

2. URL: Masukkan https://mapstools.googleapis.com/mcp. Ini adalah pintu depan langsung ke MCP Maps Google.

3. Connection Type: via Proxy. Ini adalah pilihan krusial. Dengan memilih "Proxy," inspector akan menggunakan login gcloud lokal Anda untuk menangani semua jabat tangan keamanan yang kompleks secara otomatis.

4. Custom Headers: Tambahkan X-Goog-Api-Key dan tempel kunci Anda dari Langkah 3.

5. Klik Connect.

Sekarang Anda seharusnya melihat status Connected berwarna hijau. Klik tombol List Tools untuk melihat daftar setiap kapabilitas yang ditawarkan server. Jika Anda melihat compute_routes dalam daftar tersebut, infrastruktur Anda sudah dikonfigurasi dengan sempurna.

Untuk pemahaman lebih dalam tentang cara menggunakan BigQuery, Maps, dan layanan Google lainnya untuk agen Anda, pastikan untuk melihat tutorial ini tentang Google MCP Servers.

Membangun Agen Server MCP dengan Google ADK

Dengan infrastruktur siap, sekarang kita beralih ke lingkungan pengembangan lokal. Kita akan mulai dengan menata berkas proyek.

Langkah 1: Menyiapkan struktur proyek dan dependensi

Untuk memulai, buat folder untuk proyek Anda dan siapkan lingkungan virtual.

mkdir my-agents
cd my-agents
python -m venv .venv
source .venv/bin/activate

Perintah terakhir di atas untuk pengguna macOS atau Linux; jika Anda menggunakan Windows, gunakan .venv\Scripts\activate sebagai gantinya.

Selanjutnya, Anda dapat memasang paket google-adk beserta pustaka pendukungnya.

pip install google-adk google-generativeai python-dotenv httpx  google-auth

Satu hal lagi yang perlu Anda lakukan adalah membuat berkas .env di folder root untuk menyimpan PROJECT_ID dan MAPS_API_KEY yang Anda hasilkan pada langkah sebelumnya.

Langkah 2: Mengonfigurasi toolset MCP

Dalam skrip bernama tools.py, kita bukan menulis kode untuk "mengambil data." Sebaliknya, kita menulis kode untuk terhubung ke server yang tahu cara mengambil data. 

Saya mendapati bahwa memisahkan alat dari logika membuat proyek jauh lebih mudah di-debug. Karena kita berbicara dengan endpoint Google Cloud jarak jauh, kita menggunakan StreamableHTTPConnectionParams untuk menangani header autentikasi.

import os
import google.auth
import google.auth.transport.requests
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

# --- BigQuery Toolset ---
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())
        
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://bigquery.googleapis.com/mcp",
            headers={
                "Authorization": f"Bearer {credentials.token}",
                # 'x-goog-user-project' is vital for BigQuery billing
                "x-goog-user-project": project_id,
                "Content-Type": "application/json"
            }
        )
    )

# --- Maps Toolset ---
def get_maps_mcp_toolset():
    maps_api_key = os.getenv('MAPS_API_KEY')
    
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mapstools.googleapis.com/mcp",
            headers={
                "X-Goog-Api-Key": maps_api_key,
                "Content-Type": "application/json"
            }
        )
    )

Langkah 3: Mendefinisikan misi agen

Sekarang kita membangun "otaknya." Berdasarkan pengalaman saya, menggunakan salah satu model Gemini Flash adalah pilihan terbaik di sini karena sangat cepat dalam memanggil alat. 

Kita memberikan agen prosedur operasi standar melalui instruksi dalam berkas agent.py. Perhatikan bagaimana kita menggunakan pipeline empat langkah yang jelas untuk mencegah agen menjadi bingung.

from .tools import get_maps_mcp_toolset, get_bigquery_mcp_toolset
from google.adk.agents import LlmAgent

# We're giving the agent a very structured 'Instruction' set. 
# Think of this as the SOP (Standard Operating Procedure) for your agent.
root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='logistics_recovery_agent',
    instruction="""
      You are an expert Retail Operations Recovery Agent. 
      Your job is to find high-priority problems and solve them using the tools provided.

      Step 1: Use 'execute_sql' to find orders where status is 'Delayed' and priority is 'High'.
      Step 2: For every result, pull the warehouse and customer addresses.
      Step 3: Call the Maps 'compute_routes' tool to find the exact drive distance.
      Step 4: Use this logic: If distance > 500 miles, recommend 'Air Shipping'. 
            Otherwise, recommend 'Regional Express Ground'.
    
      Output the final result as a clean Markdown table.
    """,
    # We simply drop our toolsets here. 
    # ADK handles the complexity of deciding which tool to call when.
    tools=[get_maps_mcp_toolset(), get_bigquery_mcp_toolset()]
)

Langkah 4: Menjalankan loop agen 

Untuk menjalankan agen, kita menggunakan runner. Komponen ini melacak status percakapan agar agen tahu apa yang telah diselesaikan dan apa yang perlu dilakukan berikutnya.

from google.adk.runners import Runner
from google.genai import types

async def main():
    # The Runner acts as the host for our agent.
    runner = Runner(app_name="logistics_app", agent=root_agent)

    # Wrap the user input in the standard GenAI Content format
    user_input = "Identify high-priority delayed orders and suggest recovery shipping methods."
    content = types.Content(role="user", parts=[types.Part(text=user_input)])

    print("--- Starting Smart Logistics Agent ---")
    
    # We use run_async to stream the 'events' (Thoughts and Tool Calls)
    async for event in runner.run_async(user_id="admin_user", new_message=content):
        # We only want to print the text part of the response to the console
        if hasattr(event, 'content') and event.content.parts:
            print(event.content.parts[0].text)

Apa yang terjadi di balik layar?

Saat Anda memanggil runner.run_async, ADK memulai loop iteratif:

1. Gemini berpikir: "Saya perlu melihat pesanan yang terlambat terlebih dahulu."

2. ADK bertindak: Ia memanggil alat execute_sql dari toolset MCP BigQuery Anda.

3. Observasi: Alat mengembalikan data pesanan.

4. Gemini berpikir: "Sekarang saya butuh jarak untuk dua pesanan ini."

5. ADK bertindak: Ia memanggil alat MCP Maps dua kali.

6. Respons Akhir: Gemini melihat semua data, menerapkan logika "500 mil" Anda, dan memformat tabelnya.

Menguji Agen Google ADK Kita di Web Console

Walaupun terminal bagus untuk log, ADK menyertakan web console bawaan yang memvisualisasikan penalaran internal agen. Saya mendapati ini sebagai alat paling membantu untuk debugging.

Luncurkan antarmuka dengan menjalankan adk web. Setelah server berjalan, buka peramban Anda ke http://127.0.0.1:8000. Anda akan melihat antarmuka bersih seperti obrolan tempat Anda dapat mengirim perintah: "Identify high-priority delayed orders and suggest recovery shipping methods."

Menganalisis jejak eksekusi

Konsol ADK menyediakan "trace" yang transparan tentang bagaimana tepatnya agen berinteraksi dengan infrastruktur cloud Anda.

Mari kita uraikan langkah demi langkah:

1. Jabat tangan alat: Perhatikan ikon berlabel execute_sql dan compute_routes. Dalam trace, ikon petir menunjukkan pemanggilan alat. Agen tidak sekadar menebak; ia benar-benar menghubungi server MCP BigQuery untuk menjalankan kueri SQL tertentu terhadap tabel pesanan Anda.

2. Logika berurutan: Trace menunjukkan urutan operasi yang jelas. Pertama, mengambil data melalui BigQuery (tanda centang pertama). Setelah memiliki alamat gudang dan pelanggan, Anda melihat beberapa panggilan compute_routes. Agen secara cerdas melakukan "loop" melalui pesanan yang terlambat untuk mendapatkan data jarak dunia nyata dari server MCP Maps.

3. Sintesis akhir: Bagian bawah trace menunjukkan respons final.

Perhatikan datanya:

• ORD-101: Jaraknya 380 mil.
• ORD-103: Jaraknya 352 mil.

Karena kita memberikan logika: "Jika jarak > 500 mil, rekomendasikan Air Shipping, jika tidak Regional Express Ground," agen menerapkan aturan bisnis ini dengan benar pada kedua pesanan dan memformatnya menjadi tabel Markdown yang rapi.

Kesimpulan

Kita baru saja membangun Agen Logistik yang fungsional tanpa menulis satu baris pun kode API kustom untuk BigQuery atau Google Maps. Dengan menggunakan ADK dan MCP, kita telah menciptakan arsitektur yang modular, aman, dan berfokus pada pengembang.

Masa depan AI bukan hanya tentang chatbot yang berbicara, tetapi tentang agen yang mengambil tindakan. Dengan alat ini, kita akhirnya bergerak menuju realitas tersebut.

Tutorial ini dapat menjadi titik awal yang bagus untuk eksperimen Anda dengan Google ADK dan server MCP: 

• Ganti BigQuery dengan dataset lain (atau bahkan server MCP SQLite lokal) untuk melihat betapa mudahnya mengubah sumber data.
• Ganti Maps dengan server MCP lain (misalnya, GKE untuk pemeriksaan kesehatan klaster) untuk membuktikan sifat plug-and-play.
• Tambahkan lebih banyak logika bisnis dalam prompt (perbandingan biaya, draf email) dan uji langsung di UI web ADK.

Jika Anda ingin mempelajari lebih lanjut tentang orkestrasi agen, saya sangat merekomendasikan mendaftar di jalur karier Associate AI Engineer for Developers.