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 ADK, menggunakan alat yang disediakan oleh server MCP yang ada untuk meningkatkan alur kerja ADK. Selain itu, Anda akan melihat 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:

• 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 Model Context Protocol.

Penyiapan dan persyaratan

Sebelum mengklik tombol Start Lab (Mulai Lab)

Baca petunjuk ini. Lab memiliki timer dan Anda tidak dapat menjedanya. Timer, yang dimulai saat Anda mengklik Start Lab (Mulai Lab), menampilkan lamanya resource Cloud akan tersedia untuk Anda.

Lab praktis Qwiklabs ini memungkinkan Anda melakukan aktivitas lab sendiri di lingkungan cloud nyata, bukan di lingkungan demo atau simulasi. Yaitu dengan cara memberi Anda kredensial sementara yang baru yang digunakan untuk login dan mengakses Google Cloud Platform selama durasi lab.

Yang diperlukan

Untuk menyelesaikan lab ini, Anda memerlukan:

• Akses ke browser internet standar (disarankan browser Chrome).
• Waktu untuk menyelesaikan lab.

Catatan: Jika Anda sudah memiliki project atau akun GCP pribadi, jangan gunakan project atau akun tersebut untuk lab ini.

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. Di jendela Konsol Google Cloud yang aktif, buka Cloud Shell dengan menekan tombol G, lalu tombol S di keyboard Anda. Atau, Anda dapat mengklik tombol Activate Cloud Shell () di kanan atas Konsol Cloud.

2. Klik Continue.

3. Saat 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. Di Terminal Cloud Shell, masukkan perintah berikut untuk membuka Cloud Shell Editor ke direktori utama Anda:

   cloudshell workspace ~

6. Tutup panel tutorial atau Gemini tambahan yang muncul di sisi kanan layar untuk meluangkan lebih banyak ruang jendela bagi editor kode Anda.

7. Selama sisa lab ini, Anda dapat bekerja di jendela ini sebagai IDE dengan Cloud Shell Editor dan Terminal Cloud Shell.

Mendownload dan menginstal ADK serta contoh kode untuk lab ini

1. Instal ADK dengan menjalankan perintah berikut di Terminal Cloud Shell.

   Catatan: Anda akan menentukan versi untuk memastikan bahwa versi ADK yang Anda instal sesuai dengan versi yang digunakan di lab ini. Anda dapat melihat nomor versi terbaru dan catatan rilis di repositori adk-python. sudo python3 -m pip install google-adk==1.5.0

2. Tempel perintah berikut ke Terminal Cloud Shell untuk menyalin file dari bucket Cloud Storage, dan mengekstraknya, sehingga akan membuat direktori project dengan kode untuk lab ini:

   gcloud storage cp gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

3. Instal persyaratan lab tambahan dengan:

   python3 -m pip install -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 adk web

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

Di sub-bagian ini, Anda akan membuat kunci API baru bernama GOOGLE_MAPS_API_KEY.

1. Buka tab browser yang menampilkan 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.

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

5. Klik Close di kotak dialog.

   Kunci yang baru dibuat akan diberi nama API Key 1 secara default. Pilih kunci, ganti namanya menjadi GOOGLE_MAPS_API_KEY, lalu klik Save.

   

Menentukan Agen Anda dengan MCPToolset untuk Google Maps

Di sub-bagian ini, Anda akan mengonfigurasi agen untuk menggunakan MCPToolset untuk Google Maps, sehingga agen dapat memberikan rute dan informasi berbasis lokasi dengan lancar.

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

2. Buka direktori adk_mcp_tools/google_maps_mcp_agent.

3. Tempelkan perintah berikut dalam file teks biasa, lalu perbarui nilai YOUR_ACTUAL_API_KEY dengan kunci Google Maps API yang Anda buat dan simpan pada 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={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

4. Salin dan tempel perintah yang telah diperbarui ke Terminal Cloud Shell untuk menjalankannya dan tulis file .env yang akan memberikan detail autentikasi untuk direktori agen ini.

5. Salin file .env ke direktori agen lain yang akan Anda gunakan di lab ini dengan menjalankan perintah berikut:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

6. Selanjutnya, tambahkan kode berikut di tempat yang ditunjukkan dalam file agent.py untuk menambahkan alat Google Maps ke agen Anda. Dengan demikian, agen Anda dapat menggunakan MCPToolset untuk Google Maps guna memberikan rute atau informasi berbasis lokasi.

   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. Dari direktori project adk_mcp_tools, luncurkan UI Dev Agent Development Kit dengan perintah berikut:

   adk web

   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)

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

9. Tab browser baru akan terbuka dengan UI Dev ADK. Dari dropdown Select an agent di sebelah kiri, pilih google_maps_mcp_agent dari dropdown.

10. 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:

    

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

    

12. Perhatikan bahwa grafik 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.

    

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

14. Setelah Anda selesai mengajukan pertanyaan kepada agen ini, tutup tab browser UI dev.

15. 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. Pola ini memungkinkan Anda 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 tab Cloud Shell Editor Anda, lalu pilih direktori adk_mcp_tools/adk_mcp_server.

2. File Python bernama adk_server.py telah disiapkan dan diberi komentar untuk Anda. 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

3. Klik file agent.py di direktori adk_mcp_server.

4. Update jalur ke file adk_server.py Anda.

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

5. Selanjutnya, tambahkan kode berikut di tempat yang ditunjukkan dalam file agent.py untuk menambahkan MCPToolset ke agen Anda. Agen ADK bertindak sebagai klien ke server MCP. Agen ADK ini akan 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 ) ],

6. 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:

   

7. Buka tab Terminal Cloud Shell baru dengan mengklik tombol di bagian atas jendela Terminal Cloud Shell.

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

   cd ~/adk_mcp_tools adk web

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

10. Dari Select an agent dropdown di sebelah kiri, pilih adk_mcp_server dari dropdown.

11. Buat kueri ke agen dengan:

    Muat konten dari https://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 akan menerima permintaan call_tool, menjalankan 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 akhir lab ini, Anda telah mempelajari cara mengintegrasikan alat Model Context Protocol (MCP) eksternal ke dalam agen ADK menggunakan class MCPToolset. Anda telah menemukan cara terhubung ke server MCP, menggunakan alatnya dalam agen, dan mengekspos alat ADK seperti load_web_page melalui server MCP kustom. Dengan keterampilan ini, Anda dapat memperluas agen ADK dengan layanan eksternal yang andal, sehingga meningkatkan alur kerja pengembangan web Anda.

Manual Terakhir Diperbarui pada 6 Oktober 2025

Lab Terakhir Diuji pada 6 Oktober 2025

Hak cipta 2020 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.