GENAI129

Ringkasan

Dalam lab ini, Anda akan menunjukkan kemampuan Anda dalam membuat agen menggunakan Agent Development Kit (ADK), men-deploy agen tersebut ke Agent Runtime, dan menggunakannya dari aplikasi web.

Tujuan

Di lab ini, Anda akan:

• Membangun agen dengan Agent Development Kit (ADK) yang terdiri atas agen root dan sub-agen
• Mendukung agen dengan alat Agent Search dan fungsi Python yang digunakan sebagai alat
• Menyimpan output agen dalam status sesi dan mengambil nilai dari status sesi untuk instruksi agen berikutnya
• Men-deploy agen Anda ke Agent Runtime
• Mengkueri agen yang di-deploy ke Agent Runtime

Materi pembelajaran terkait

Jika Anda mencari referensi yang akan membantu Anda mengembangkan keterampilan yang diperlukan untuk menyelesaikan lab ini dengan sukses, pertimbangkan untuk meninjau bagian yang relevan dari referensi berikut:

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 Konsol Google Cloud

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: Penggunaan akun Google Cloud sendiri untuk lab ini mungkin dikenai biaya tambahan.

7. Klik untuk melanjutkan ke halaman berikutnya:

   • Setujui persyaratan dan ketentuan.
   • Jangan tambahkan opsi pemulihan atau autentikasi 2 langkah (karena ini akun sementara).
   • Jangan daftar 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.

Skenario Tantangan

Seorang rekan kerja Anda mulai mengembangkan agen, Paint Agent, untuk membantu pengguna:

• memilih produk cat berdasarkan lembar data produk cat Cymbal Shops
• memilih warna dari lini produk yang dipilih
• menentukan jumlah cat yang dibutuhkan berdasarkan dimensi ruangan
• menghitung harga berdasarkan opsi yang dipilih

Namun, rekan kerja Anda mengalami kebuntuan dalam menangani bug dan dia keluar dari perusahaan.

Anda adalah ML Engineer baru di Cymbal Shops. Anda ditugasi menyelesaikan deployment Paint Agent. Berikut struktur agen tersebut:

Tugas 1. Membuat aplikasi Agent Search untuk info produk cat

Dalam tugas ini, Anda akan men-deploy penyimpanan data Agent Search. Penyimpanan data ini akan mengimpor lembar data yang menjelaskan cat Cymbal Shops (yang dapat Anda lihat pratinjaunya di jendela Samaran di https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf). Lembar data ini akan berfungsi sebagai sumber data dasar untuk kueri pengguna tentang cat Anda.

Penyimpanan data dan aplikasi penelusuran memungkinkan agen menemukan konten organisasi Anda dengan cepat. Selanjutnya, model ini dapat menggunakan informasi tersebut untuk memberikan respons yang sesuai kepada pengguna berdasarkan data Anda.

1. Di Konsol Google Cloud, buka Agent Platform > Agents > Search.

2. Buat aplikasi Agent Search dengan konfigurasi berikut:

   Kolom	Nilai
   App type	Custom search (general)
   App name	Paint Search
   Company name	Cymbal Shops
   Location	global

3. Buat penyimpanan data Agent Search dengan konfigurasi berikut:

   Kolom	Nilai
   Data source	Cloud Storage
   Data type	Documents
   Folder or File	File
   File to import	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   Location	global
   Data store name	Cymbal Paint
   Document parser	Layout Parser
   Enable table annotation	Enabled
   Include ancestor headings in chunks	Enabled

4. Pilih Pricing Model sebagai General baik untuk Aplikasi Anda maupun Penyimpanan data.

Klik Periksa progres saya untuk memverifikasi tujuan. Membuat penyimpanan data dan aplikasi penelusuran.

Tugas 2. Menginstal ADK dan menyiapkan lingkungan Anda

Di lingkungan lab ini, Agent Platform API telah diaktifkan untuk Anda. Jika mengikuti langkah-langkah ini di project Anda sendiri, Anda dapat mengaktifkannya dengan membuka Agent Platform dan mengikuti dialog untuk mengaktifkannya.

Menyiapkan tab Cloud Shell Editor

1. Klik Activate Cloud Shell () di kolom judul Konsol Google Cloud.

   Catatan: Sebagai alternatif, pilih tab browser konsol, lalu tekan G, lalu S untuk membuka terminal Cloud Shell.

2. Klik Continue.

3. Jika diminta untuk memberikan otorisasi pada Cloud Shell, klik Authorize.

4. Di pojok kanan atas panel Cloud Shell Terminal, klik tombol Open in new window .

5. Klik ikon pensil 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 siswa Qwiklab 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 Cloud Shell Terminal.

Mendownload dan menginstal ADK serta contoh kode untuk lab ini

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

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab . 2> /dev/null

2. Perbarui variabel lingkungan PATH, lalu instal ADK dan persyaratan lab lainnya dengan menjalankan perintah berikut di Terminal Cloud Shell.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1

3. Salin perintah berikut ke file teks. Ubah nilai SEARCH_ENGINE_ID dari YOUR_ID menjadi ID mesin telusur yang baru saja Anda buat (akan terlihat seperti paint-search_1756... dan dapat ditemukan dalam daftar Aplikasi di Agent Platform > Agents > Search):

   cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. Jalankan perintah yang telah Anda edit di Terminal Cloud Shell untuk membuat file .env dengan autentikasi model dan variabel konfigurasi. [Catatan: Untuk melihat file tersembunyi (ditandai dengan file yang diawali dengan titik), Anda dapat menggunakan menu Cloud Shell Editor untuk mengaktifkan View > Toggle Hidden Files]

5. Salin file .env ke direktori agen untuk memberikan konfigurasi autentikasi yang diperlukan agen Anda setelah di-deploy:

   cp .env paint_agent/.env

Tugas 3. Men-debug Paint Agent

Rekan kerja Anda telah mulai mengerjakan Paint Agent, tetapi mengalami kendala. Anda harus melanjutkan pekerjaannya, termasuk memperbaiki bug yang dia tinggalkan, untuk menyelesaikan dan men-deploy agen.

1. Di Terminal Cloud Shell, jalankan versi agen saat ini dengan:

   adk run paint_agent

2. Saat perintah [user]: muncul, masukkan:

   hello

   Jika agen tersebut menindaklanjuti dengan bertanya apakah Anda ingin mempelajari lebih lanjut cat Cymbal Shops, balas:

   yes

   Output yang diharapkan akan diakhiri dengan:

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   Pada langkah-langkah berikutnya, Anda akan menyelesaikan error ini.

3. Buka file adk_challenge_lab/paint_agent/agent.py, lalu periksa daftar sub-agen dan alat yang digunakan oleh root_agent. Perhatikan bahwa sub-agen juga dicakup. Proses transfer ke sub-agen akan memanggil alat implisit transfer_to_agent.

4. Alat root_agent tidak berupa alat penelusuran; oleh karena itu, setidaknya salah satu sub-agen harus memanggil alat penelusuran. Jelajahi sub-agen yang ditemukan di direktori sub_agents untuk menemukan alat penelusuran yang digunakan (dalam kasus ini VertexAiSearchTool):

   Uji pengetahuan: (jawaban akan terungkap seiring progres Anda):

5. Meskipun alat penelusuran tidak dapat digabungkan dengan alat non-penelusuran lainnya dalam satu agen (bahkan dengan menggunakannya di sub-agen seperti yang terlihat di sini), ADK menyediakan alat bernama AgentTool yang dapat menggabungkan agen terpisah yang menggunakan alat penelusuran. Kemudian, agen sebagai alat tersebut dapat digunakan dengan alat lainnya.

   Kembali ke file root_agent adk_challenge_lab/paint_agent/agent.py, tambahkan AgentTool() ke daftar alat root_agent. Berikan argumen berikut ke AgentTool():

   • agent harus disetel ke search_agent (sub-agen yang menggunakan alat penelusuran yang Anda temukan di atas).
   • skip_summarization harus disetel ke False karena Anda ingin agen melaporkan hasil yang ditampilkan oleh alat penelusuran.

6. Hapus sub-agen tersebut dari daftar sub_agents.

7. Simpan file dengan mengklik tombol Save.

   Catatan: Lanjutkan hanya setelah penyimpanan data Anda dibuat dan dokumen Anda diindeks. Anda dapat memantau status ini di penyimpanan data Agent Platform > Agents > Search > Data Stores > Cymbal Paint pada tab Documents.

   Dalam praktiknya, Anda akan mendapatkan output yang lebih andal jika menunggu beberapa menit setelah status menampilkan "Ready" sebelum mengkueri agen Anda.

8. Di terminal Cloud Shell, jalankan kembali agen dengan:

   adk run paint_agent

   Anda sekarang dapat melakukan percakapan dengan agen dan mendapatkan informasi tentang cat Cymbal Shops.

9. Minta agen untuk memberi tahu Anda harga cat EcoGreens dan Forever Paint.

   
   

   Klik Periksa progres saya untuk memverifikasi tujuan. Men-debug agen Anda.

10. Setelah selesai melakukan percakapan dengan agen melalui antarmuka command line, ketik exit untuk mengakhiri percakapan.

Tugas 4. Menyimpan dan memanfaatkan status bersama

root_agent Anda mengimpor dan menggunakan alat set_session_value dari adk_challenge_lab/paint_agent/tools.py. Tujuannya adalah mengumpulkan informasi seperti SELECTED_PAINT dan COVERAGE_RATE dari pengguna, menyimpannya dalam sesi itu, dan menggunakannya dalam multi-turn chat. Namun, hal ini belum sepenuhnya diterapkan.

1. Perbarui fungsi set_session_value di file adk_challenge_lab/paint_agent/tools.py untuk menyimpan pasangan key-value di kamus state ToolContext.

2. Perbarui respons fungsi untuk menampilkan pesan status f"stored '{value}' in '{key}'".

3. Buka file agent.py yang terkait dengan coverage_calculator_agent (sub-agen room_planner, yang merupakan sub-agen root_agent Anda).

4. Perhatikan bahwa instruksinya tidak memuat nilai dari kamus status dengan benar. Perbarui instruksi untuk mengganti istilah dalam ALL CAPS (huruf besar semua) agar menggunakan templating kunci ADK untuk memuat nilai status ke dalam instruksi. Gunakan sintaksis opsional (misalnya {SELECTED_PAINT?}) untuk memastikan agen tidak mengalami error jika dipanggil sebelum kunci status diisi.

5. Uji agen Anda dengan:

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

6. Pilih paint_agent.

7. Sekarang Anda dapat melakukan percakapan berikut dengan agen Anda:

   Anda	Respons Agen
   hello	[Menawarkan untuk membagikan informasi tentang cat Cymbal Shops]
   yes	[Membagikan informasi tentang produk cat, misalnya Project Paint, EcoGreens, SureCoverage, Forever Paint.]
   I'd like to use EcoGreens	[Tab State akan menampilkan nilai status yang telah diperbarui. Bertanya berapa banyak ruangan dan nama setiap ruangan.]
   Just one room, my office	[Meminta Anda memilih warna untuk kantor Anda.]
   Deep Ocean	[Meminta Anda memberikan dimensi ruangan.]
   3m by 4m. 3m high. 1 door, 2 windows.	[Mengonfirmasi jumlah lapisan.]
   Two coats.	[Menghitung bahwa Anda memerlukan cakupan sebesar 74 meter persegi.]

   Catatan: Untuk memastikan gambar produk ditampilkan dengan benar, aktifkan Cookie pihak ketiga untuk domain ini di setelan browser Anda dan muat ulang halaman.

8. Setelah selesai melakukan percakapan dengan agen, Anda dapat menutup tab browser UI Dev.

   Klik Periksa progres saya untuk memverifikasi tujuan. Menetapkan dan memanfaatkan status sesi

9. Pilih panel Terminal Cloud Shell, lalu tekan CTRL+C untuk mematikan server.

Tugas 5. Men-deploy ke Agent Runtime

1. Di Terminal Cloud Shell, pastikan Anda berada di direktori adk_challenge_lab:

   cd ~/adk_challenge_lab

2. Deploy agen Anda ke Agent Runtime menggunakan perintah adk deploy agent_engine. Anda harus menyertakan direktori agen sebagai argumen posisi akhir (misalnya, . jika Anda saat ini berada di direktori tersebut). Gunakan argumen berikut:

   Parameter	Argumen
   --display_name	"Paint Agent"

   Catatan: Perintah deployment dapat memerlukan waktu 5—10 menit untuk diselesaikan.

3. Saat agen di-deploy, berikan peran IAM Agent Platform User dan Discovery Engine User ke akun layanan .

4. Perhatikan bahwa saat deployment selesai, nama resource agen yang di-deploy akan tercetak di konsol.

   Klik Periksa progres saya untuk memverifikasi tujuan. Men-deploy ke Agent Runtime

Tugas 6. Mengkueri agen yang di-deploy

1. Dalam file adk_challenge_lab/chainlit_ui/app.py, temukan dan perbarui baris berikut dengan nama resource agen yang di-deploy untuk memuat agen jarak jauh Anda:

   agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')

2. Jalankan UI dengan perintah berikut:

   cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

   Output yang diharapkan:

   2025-08-25 12:30:00 - Your app is available at http://localhost:8000

3. Klik link http://localhost:8000 untuk membukanya di tab browser baru.

4. Lakukan percakapan berikut dengan agen yang di-deploy:

   Anda	Respons Agen
   hello	[Menawarkan untuk membagikan informasi tentang cat Cymbal Shops]
   yes	[Membagikan informasi tentang produk cat, misalnya Project Paint, EcoGreens, SureCoverage, Forever Paint ]
   I'd like to use Forever Paint	[Bertanya berapa banyak ruangan dan nama setiap ruangan]
   Two rooms. The living room and a baby's room.	[Meminta Anda memilih warna untuk ruang tamu dan kamar bayi.]
   "Sunlight through a canvas tent" for the baby's room and "Coffee Cream" for the living room.	[Meminta Anda memberikan dimensi ruangan]
   The living room is 5m by 4m. 2.5m high. 1 door, 3 windows.	[Menanyakan jumlah lapisan cat.]
   Two coats.	[Meminta dimensi untuk kamar bayi.]
   The baby's room is 3m by 3m. 2.5m high. 1 door, 1 window.	[Memberikan perkiraan untuk satu lapisan dan mengonfirmasi jumlah lapisan.]
   Always two coats.	[Menghitung bahwa Anda memerlukan cakupan sebesar 77 meter persegi untuk ruang keluarga dan 53 meter persegi untuk kamar bayi.]

5. Jika Anda ingin memulai percakapan baru dengan agen, klik ikon Create a New Chat di kiri atas.

   Klik Periksa progres saya untuk memverifikasi tujuan. Mengonfigurasi frontend untuk mengkueri agen Anda

Selamat!

Di lab ini, Anda telah:

• Membangun agen dengan Agent Development Kit (ADK) yang terdiri dari agen root dan sub-agen
• Mendukung agen dengan alat Agent Search dan fungsi Python yang digunakan sebagai alat
• Menyimpan output agen dalam kamus status sesi dan mengambil nilai dari kamus status sesi tersebut untuk instruksi agen berikutnya
• Men-deploy agen Anda ke Agent Runtime
• Mengkueri agen yang di-deploy ke Agent Runtime

Sertifikasi dan pelatihan Google Cloud

...membantu Anda mendapatkan manfaat optimal dari teknologi Google Cloud. Kelas kami mencakup keterampilan teknis dan praktik terbaik untuk membantu Anda memahami dengan cepat dan melanjutkan proses pembelajaran. Kami menawarkan pelatihan tingkat dasar hingga lanjutan dengan opsi on demand, live, dan virtual agar dapat disesuaikan dengan jadwal Anda yang sibuk. Sertifikasi membantu Anda memvalidasi dan membuktikan keterampilan serta keahlian Anda dalam teknologi Google Cloud.

Manual Terakhir Diperbarui: 2 Juli 2026

Lab Terakhir Diuji: 2 Juli 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.