GENAI124

Ringkasan

Di lab ini, Anda akan mempelajari Model Context Protocol (MCP), yakni sebuah standar terbuka yang memungkinkan integrasi yang lancar antara layanan, sumber data, alat, dan aplikasi eksternal. Anda akan mempelajari cara mengintegrasikan MCP ke dalam agen Agent Development Kit (ADK), menggunakan alat yang disediakan oleh server MCP yang ada untuk meningkatkan alur kerja ADK. Selain itu, Anda akan menemukan cara mengekspos alat ADK seperti load_web_page melalui server MCP yang dibangun khusus, sehingga memungkinkan integrasi yang lebih luas dengan klien MCP.

Apa itu Model Context Protocol (MCP)?

Model Context Protocol (MCP) adalah standar terbuka yang dirancang untuk menstandarkan cara Model Bahasa Besar (LLM) seperti Gemini dan Claude berkomunikasi dengan aplikasi, sumber data, dan alat eksternal. Anggap saja sebagai mekanisme koneksi universal yang menyederhanakan cara LLM mendapatkan konteks, menjalankan tindakan, dan berinteraksi dengan berbagai sistem.

MCP mengikuti arsitektur klien-server, yang menentukan cara data (resource), template interaktif (perintah), dan fungsi yang dapat ditindaklanjuti (alat) diekspos oleh server MCP dan digunakan oleh klien MCP (yang dapat berupa aplikasi host LLM atau agen AI).

Lab ini mencakup dua pola integrasi utama:

• Menggunakan Server MCP yang ada dalam ADK: Agen ADK bertindak sebagai klien MCP, yang memanfaatkan alat yang disediakan oleh server MCP eksternal.
• Mengekspos Alat ADK melalui Server MCP: Membangun server MCP yang menggabungkan alat ADK, sehingga dapat diakses oleh klien MCP mana pun.

Tujuan

Di lab ini, Anda akan mempelajari cara melakukan tugas-tugas berikut:

• Menggunakan agen ADK sebagai klien MCP untuk berinteraksi dengan alat dari server MCP yang ada.
• Mengonfigurasi dan men-deploy server MCP Anda sendiri untuk mengekspos alat ADK ke klien lain.
• Menghubungkan agen ADK dengan alat eksternal melalui komunikasi MCP standar.
• Mengaktifkan interaksi yang lancar antara LLM dan alat menggunakan MCP.

Penyiapan dan persyaratan

Sebelum mengklik tombol Start Lab

Baca petunjuk ini. Lab memiliki timer dan Anda tidak dapat menjedanya. Timer yang dimulai saat Anda mengklik Start Lab akan menampilkan durasi ketersediaan resource Google Cloud untuk Anda.

Lab interaktif ini dapat Anda gunakan untuk melakukan aktivitas lab di lingkungan cloud sungguhan, bukan di lingkungan demo atau simulasi. Untuk mengakses lab ini, Anda akan diberi kredensial baru yang bersifat sementara dan dapat digunakan untuk login serta mengakses Google Cloud selama durasi lab.

Untuk menyelesaikan lab ini, Anda memerlukan:

• Akses ke browser internet standar (disarankan browser Chrome).

• Waktu untuk menyelesaikan lab. Ingat, setelah dimulai, lab tidak dapat dijeda.

Cara memulai lab dan login ke Google Cloud Console

1. Klik tombol Start Lab. Jika Anda perlu membayar lab, dialog akan terbuka untuk memilih metode pembayaran. Di sebelah kiri ada panel Lab Details yang berisi hal-hal berikut:

   • Tombol Open Google Cloud console
   • Waktu tersisa
   • Kredensial sementara yang harus Anda gunakan untuk lab ini
   • Informasi lain, jika diperlukan, untuk menyelesaikan lab ini

2. Klik Open Google Cloud console (atau klik kanan dan pilih Open Link in Incognito Window jika Anda menjalankan browser Chrome).

   Lab akan menjalankan resource, lalu membuka tab lain yang menampilkan halaman Sign in.

   Tips: Atur tab di jendela terpisah secara berdampingan.

   Catatan: Jika Anda melihat dialog Choose an account, klik Use Another Account.

3. Jika perlu, salin Username di bawah dan tempel ke dialog Sign in.

   {{{user_0.username | "Username"}}}

   Anda juga dapat menemukan Username di panel Lab Details.

4. Klik Next.

5. Salin Password di bawah dan tempel ke dialog Welcome.

   {{{user_0.password | "Password"}}}

   Anda juga dapat menemukan Password di panel Lab Details.

6. Klik Next.

   Penting: Anda harus menggunakan kredensial yang diberikan lab. Jangan menggunakan kredensial akun Google Cloud Anda. Catatan: Menggunakan akun Google Cloud sendiri untuk lab ini dapat dikenai biaya tambahan.

7. Klik halaman berikutnya:

   • Setujui persyaratan dan ketentuan.
   • Jangan tambahkan opsi pemulihan atau autentikasi 2 langkah (karena ini akun sementara).
   • Jangan mendaftar uji coba gratis.

Setelah beberapa saat, Konsol Google Cloud akan terbuka di tab ini.

Catatan: Untuk mengakses produk dan layanan Google Cloud, klik Navigation menu atau ketik nama layanan atau produk di kolom Search.

Tugas 1. Menginstal ADK dan menyiapkan lingkungan Anda

Di lingkungan lab ini, Vertex AI API, Routes API, dan Directions API telah diaktifkan untuk Anda.

Menyiapkan tab Cloud Shell Editor

1. Dari Konsol Google Cloud, klik tombol Activate Cloud Shell () di kanan atas Konsol Cloud.
2. Klik Continue.
3. Jika diminta untuk memberikan otorisasi pada Cloud Shell, klik Authorize.
4. Di pojok kanan atas panel terminal Cloud Shell, klik tombol Open in new window ().
5. Klik ikon Open Editor () di bagian atas panel untuk melihat file.
6. Di bagian atas menu navigasi sebelah kiri, klik ikon Explorer () untuk membuka file explorer Anda.
7. Klik tombol Open Folder.
8. Di dialog Open Folder yang terbuka, klik OK untuk memilih folder beranda akun peserta kursus Anda.
9. Tutup panel Gemini atau tutorial tambahan yang muncul di sisi kanan layar agar ruang jendela bagi editor kode Anda lebih besar.
10. Di sepanjang lab, Anda dapat memanfaatkan jendela ini sebagai IDE dengan Cloud Shell Editor dan terminal Cloud Shell.

Mendownload dan menginstal ADK serta contoh kode untuk lab ini

Di bagian ini, Anda akan menjalankan perintah berikut di terminal Cloud Shell.

1. Jalankan perintah berikut di terminal Cloud Shell untuk menyalin direktori project dari Cloud Storage:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

2. Jalankan perintah berikut untuk menginstal Agent Development Kit (ADK) dan dependensi lain yang diperlukan untuk menjalankan aplikasi contoh:

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.22.1 -r adk_mcp_tools/requirements.txt

Klik Periksa progres saya untuk memverifikasi tujuan. Menginstal ADK dan menyiapkan lingkungan Anda

Tugas 2. Menggunakan server MCP Google Maps dengan agen ADK (ADK sebagai klien MCP) di UI Dev ADK

Bagian ini menunjukkan cara mengintegrasikan alat dari server MCP Google Maps eksternal ke dalam agen ADK Anda. Ini adalah pola integrasi paling umum saat agen ADK Anda perlu menggunakan kemampuan yang disediakan oleh layanan yang ada yang mengekspos antarmuka MCP. Anda akan melihat cara menambahkan class MCPToolset langsung ke daftar tools agen, sehingga memungkinkan koneksi yang lancar ke server MCP, penemuan alatnya, dan membuatnya tersedia untuk digunakan agen Anda. Contoh ini terutama berfokus pada interaksi dalam lingkungan pengembangan adk web.

MCPToolset

Class MCPToolset adalah mekanisme utama ADK untuk mengintegrasikan alat dari server MCP. Jika Anda menyertakan instance MCPToolset dalam daftar tools agen, instance tersebut akan otomatis menangani interaksi dengan server MCP yang ditentukan. Berikut caranya:

• Pengelolaan Koneksi: Saat inisialisasi, MCPToolset akan membuat dan mengelola koneksi ke server MCP. Hal ini dapat berupa proses server lokal (menggunakan StdioServerParameters untuk menjalankan komunikasi melalui input/output standar) atau server jarak jauh (menggunakan SseServerParams untuk Peristiwa yang Dikirim Server). Toolset ini juga menangani penghentian normal koneksi ini saat agen atau aplikasi dihentikan.
• Penemuan & Adaptasi Alat: Setelah terhubung, MCPToolset akan mengkueri server MCP untuk alat yang tersedia (melalui metode MCP list_tools). Kemudian, toolset akan mengonversi skema alat MCP yang ditemukan ini menjadi instance BaseTool yang kompatibel dengan ADK.
• Eksposur ke Agen: Alat yang diadaptasi ini kemudian akan dibuat tersedia untuk LlmAgent Anda seolah-olah alat tersebut adalah alat ADK native.
• Membuat Proxy Panggilan Alat: Saat LlmAgent Anda memutuskan untuk menggunakan salah satu alat ini, MCPToolset akan membuat proxy panggilan secara transparan (menggunakan metode MCP call_tool) ke server MCP, mengirimkan argumen yang diperlukan, dan menampilkan respons server kembali ke agen.
• Pemfilteran (Opsional): Anda dapat menggunakan parameter tool_filter saat membuat MCPToolset untuk memilih subset alat tertentu dari server MCP, bukan mengekspos semuanya ke agen Anda.

Mendapatkan kunci API dan mengaktifkan API

Server MCP Google Maps memerlukan kunci API untuk berkomunikasi dengan layanan Google Maps. Di langkah ini, Anda akan membuat kunci API baru bernama GOOGLE_MAPS_API_KEY dan membatasinya ke Directions API dan Routes API untuk keamanan.

1. Buka tab browser Konsol Google Cloud (bukan Cloud Shell Editor Anda).

2. Anda dapat menutup panel terminal Cloud Shell di tab browser ini untuk mendapatkan area konsol yang lebih luas.

3. Telusuri Credentials di kotak penelusuran di bagian atas halaman. Pilih dari hasil.

4. Di halaman Credentials, klik Create credentials di bagian atas halaman, lalu pilih API key.

5. Untuk Name, ketik GOOGLE_MAPS_API_KEY

6. Untuk APIs that can be accessed using this key, pilih API berikut:

   • Directions API
   • Routes API

7. Klik Create.

   Dialog API key created akan menampilkan kunci API yang baru dibuat. Pastikan untuk menyalin dan menyimpan kunci ini secara lokal untuk digunakan nanti di lab.

8. Klik Close di kotak dialog.

   

Menentukan Agen Anda dengan MCPToolset untuk Google Maps

Sekarang Anda akan mengonfigurasi agen untuk menggunakan alat Google Maps. Dengan menambahkan MCPToolset, Anda memungkinkan agen menemukan dan memanggil Maps API secara dinamis saat diperlukan.

1. Tempelkan perintah berikut ke dalam dokumen teks biasa di komputer Anda, lalu perbarui nilai YOUR_ACTUAL_API_KEY dengan kunci Google Maps API yang Anda buat dan simpan di langkah sebelumnya:

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. Salin dan tempel perintah yang telah diperbarui ke terminal Cloud Shell, lalu jalankan untuk menulis file .env, yang memberikan detail autentikasi untuk direktori agen ini.

3. Salin file .env ke direktori agen lain untuk penggunaan selanjutnya di lab ini dengan menjalankan perintah berikut:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

4. Di panel file explorer Cloud Shell Editor, temukan folder adk_mcp_tools. Klik untuk membukanya.

5. Buka direktori adk_mcp_tools/google_maps_mcp_agent.

6. Buka agent.py dan tambahkan kode berikut setelah komentar ## Add the MCPToolset (di baris baru setelah baris 53) untuk mengonfigurasi koneksi agen ke server MCP Google Maps:

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. Simpan file dengan mengklik tombol Save.

8. Dari direktori project adk_mcp_tools, luncurkan UI Dev Agent Development Kit dengan perintah berikut:

   adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents

   Output:

   INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

9. Untuk melihat antarmuka web di tab yang baru, klik link http://127.0.0.1:8000 di output terminal.

10. Tab browser baru akan terbuka dengan UI Dev ADK. Dari drop-down Select an agent di sebelah kiri, pilih google_maps_mcp_agent.

11. Mulai percakapan dengan agen dan jalankan perintah berikut:

    Dapatkan rute dari GooglePlex ke SFO. Catatan: Jika panggilan API Anda kehabisan waktu saat pertama kali Anda menggunakannya, klik + New Session di kanan atas UI Dev ADK dan coba lagi. Apa rute dari Paris, Prancis ke Berlin, Jerman?

    Output:

    

12. Klik ikon agen di samping balon chat agen dengan tanda petir, yang menunjukkan panggilan fungsi. Tindakan ini akan membuka pemeriksa Peristiwa untuk peristiwa ini.

    

    Perhatikan bahwa graf agen menunjukkan beberapa alat yang berbeda, yang diidentifikasi oleh emoji kunci pas (🔧). Meskipun Anda hanya mengimpor satu MCPToolset, set alat tersebut dilengkapi dengan berbagai alat yang tercantum di sini, seperti maps_place_details dan maps_directions.

    

    Di tab Event, Anda dapat melihat struktur permintaan. Anda dapat menggunakan tanda panah di bagian atas pemeriksa Peristiwa untuk menjelajahi pemikiran, panggilan fungsi, dan respons agen.

13. Setelah Anda selesai mengajukan pertanyaan kepada agen ini, tutup tab browser UI Dev.

14. Kembali ke panel terminal Cloud Shell dan tekan CTRL+C untuk menghentikan server.

Klik Periksa progres saya untuk memverifikasi tujuan. Membuat kunci API dan men-deploy agen ADK

Tugas 3. Membangun server MCP dengan alat ADK (server MCP yang mengekspos ADK)

Di bagian ini, Anda akan mempelajari cara mengekspos alat load_web_page ADK melalui server MCP yang dibangun khusus. Dengan pola ini, Anda dapat menggabungkan alat ADK yang ada dan membuatnya dapat diakses oleh aplikasi klien MCP standar mana pun.

Membuat skrip Server MCP dan menerapkan logika server

1. Kembali ke Cloud Shell Editor Anda, lalu pilih direktori adk_mcp_tools/adk_mcp_server.

2. Buka file Python bernama adk_server.py. File ini berisi logika untuk server MCP kustom Anda. Tinjau kode untuk memahami cara kode ini menggabungkan dan menyajikannya sebagai alat ADK.

   Luangkan waktu untuk meninjau file tersebut. Baca komentar untuk memahami cara kode menggabungkan alat dan menyajikannya sebagai server MCP. Perhatikan cara kode ini memungkinkan klien MCP mencantumkan alat yang tersedia serta memanggil alat ADK secara asinkron, dengan menangani permintaan dan respons dalam format yang sesuai dengan MCP.

Menguji Server MCP kustom dengan Agen ADK

1. Buka agent.py di direktori adk_mcp_server.

2. Di baris 31, perbarui nilai PATH_TO_YOUR_MCP_SERVER_SCRIPT ke jalur berikut agar agen dapat terhubung ke skrip server kustom Anda:

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

3. Selanjutnya, tambahkan kode berikut di baris 55, yaitu setelah tempat yang bertuliskan ## Add the MCPToolset below: dalam file agent.py, untuk menambahkan MCPToolset ke agen Anda. Agen ADK bertindak sebagai klien ke server MCP. Agen ADK ini menggunakan MCPToolset untuk terhubung ke skrip adk_server.py Anda.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

4. Simpan file dengan mengklik tombol Save.

5. Untuk menjalankan server MCP, mulai skrip adk_server.py dengan menjalankan perintah berikut di terminal Cloud Shell:

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Output:

   

6. Buka tab terminal Cloud Shell yang baru dengan mengklik tombol di bagian atas jendela terminal Cloud Shell.

7. Di terminal Cloud Shell, dari direktori project adk_mcp_tools, luncurkan UI Dev Agent Development Kit dengan perintah berikut:

   export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents Catatan: `PATH` telah ditambahkan ke perintah ini untuk meresetnya, karena terminal Cloud Shell yang baru dapat menghasilkan error jika Anda menjalankan perintah lainnya tanpa perintah ini. Biasanya, ini adalah error `adk web` tidak ditemukan.

8. Untuk melihat antarmuka web di tab yang baru, klik link http://127.0.0.1:8000 di output terminal.

9. Dari Select an agent drop-down di sebelah kiri, pilih adk_mcp_server.

10. Berikan perintah kepada agen dengan hal berikut:

    Muat konten dari http://example.com.

    Output:

    

    Yang terjadi di sini:

    • Agen ADK (web_reader_mcp_client_agent) menggunakan MCPToolset untuk terhubung ke adk_server.py Anda.
    • Server MCP menerima permintaan call_tool, mengeksekusi alat load_web_page ADK, dan menampilkan hasilnya.
    • Agen ADK kemudian akan menyampaikan informasi ini. Anda akan melihat log dari UI Web ADK (dan terminalnya) serta dari terminal adk_server.py di tab terminal Cloud Shell tempatnya berjalan.

    Hal ini menunjukkan bahwa alat ADK dapat dienkapsulasi dalam server MCP, sehingga dapat diakses oleh berbagai klien yang kompatibel dengan MCP, termasuk agen ADK.

Selamat!

Di lab ini, Anda telah mempelajari cara mengintegrasikan alat Model Context Protocol (MCP) eksternal ke dalam agen Agent Development Kit (ADK) menggunakan class MCPToolset. Anda menemukan cara terhubung ke server MCP, menggunakan alatnya dalam agen, dan mengekspos alat ADK seperti load_web_page melalui server MCP kustom. Dengan keahlian ini, Anda dapat memperluas agen ADK dengan layanan eksternal yang andal, sehingga meningkatkan alur kerja pengembangan web Anda.

Manual Terakhir Diperbarui pada 21 April 2026

Lab Terakhir Diuji pada 21 April 2026

Hak cipta 2026 Google LLC. Semua hak dilindungi undang-undang. Google dan logo Google adalah merek dagang dari Google LLC. Semua nama perusahaan dan produk lain mungkin adalah merek dagang masing-masing perusahaan yang bersangkutan.