Membangun Agen AI dengan ADK: Dasar-Dasar

1. Sebelum memulai

Selamat datang di bagian pertama seri "Membangun Agen AI dengan ADK"! Dalam rangkaian codelab praktik ini, Anda akan memulai perjalanan yang menarik untuk membuat agen AI cerdas Anda sendiri menggunakan Agent Development Kit (ADK) Google.

Kita akan mulai dengan hal-hal yang paling mendasar, memandu Anda menyiapkan lingkungan pengembangan dan membuat agen percakapan dasar. Di akhir codelab ini, Anda akan telah membangun AI interaktif pertama Anda, yang siap dikembangkan di bagian selanjutnya dari seri ini saat kita mengubahnya menjadi Sistem Multi-Agen (MAS) yang canggih.

Anda dapat menyelesaikan codelab ini di lingkungan lokal atau di Google Cloud. Untuk mendapatkan pengalaman yang paling konsisten, sebaiknya gunakan Cloud Shell dari lingkungan Google Cloud. Cloud Shell juga menyediakan penyimpanan persisten sebesar 5 GB di direktori $HOME. Hal ini berguna untuk menyimpan skrip, file konfigurasi, atau repositori yang di-clone.

Catatan: Jika Anda memilih untuk bekerja secara lokal, Anda mungkin memerlukan langkah-langkah penyiapan, penginstalan, dan autentikasi tambahan, yang tidak dibahas dalam bagian penyiapan lingkungan di lab ini.

Prasyarat

• Pemahaman tentang konsep AI Generatif
• Kemahiran dasar dalam pemrograman Python
• Pemahaman tentang command line / terminal

Yang akan Anda pelajari

• Cara menyiapkan lingkungan Python
• Cara membuat Agen Asisten Pribadi sederhana menggunakan ADK
• Cara menjalankan, menguji, dan men-debug agen

Yang Anda butuhkan

• Komputer dan Wi-Fi yang berfungsi dengan baik
• Browser, seperti Chrome, untuk mengakses Konsol Google Cloud
• Pikiran yang ingin tahu dan semangat untuk belajar

Menukarkan Akun Penagihan Uji Coba

Catatan: Anda tidak perlu melakukan langkah ini jika sudah memiliki akun penagihan. Jika Anda mengikuti codelab ini secara langsung dengan instruktur, instruktur Anda akan memberikan informasi yang diperlukan.

Untuk menyelesaikan codelab ini, Anda juga memerlukan akun penagihan Google Cloud yang aktif. Jika Anda belum memilikinya, ikuti langkah-langkah berikut untuk menukarkan akun penagihan uji coba:

1. Membuka jendela samaran di browser Anda
2. Buka portal penukaran ini
3. Login menggunakan akun Gmail pribadi Anda
4. Ikuti petunjuk langkah demi langkah dari portal

2. Pengantar

Dunia AI Generatif (GenAI) berkembang pesat, dan Agen AI saat ini menjadi topik hangat. Agen AI adalah program komputer pintar yang dirancang untuk bertindak atas nama Anda, seperti asisten pribadi. Agen dapat memahami lingkungan digitalnya, membuat keputusan, dan mengambil tindakan untuk mencapai sasaran tertentu tanpa kontrol langsung dari manusia. Anggap saja sebagai entitas proaktif dan otonom yang dapat belajar dan beradaptasi untuk menyelesaikan berbagai hal.

Pada intinya, agen AI menggunakan model bahasa besar (LLM) sebagai "otaknya" untuk memahami dan melakukan penalaran. Hal ini memungkinkannya memproses informasi dari berbagai sumber, seperti teks, gambar, dan suara. Kemudian, agen menggunakan pemahaman ini untuk membuat rencana dan menjalankan serangkaian tugas untuk mencapai tujuan yang telah ditentukan sebelumnya.

Anda kini dapat dengan mudah membuat agen AI Anda sendiri, bahkan tanpa keahlian mendalam, berkat framework siap pakai seperti Agent Development Kit (ADK). Kita akan memulai perjalanan ini dengan membuat agen asisten pribadi untuk membantu Anda menyelesaikan tugas. Mari kita mulai!

3. Mengonfigurasi Layanan Google Cloud

Buat project Google Cloud

Mulailah dengan membuat project Google Cloud baru agar aktivitas dari codelab ini hanya diisolasi dalam project baru ini.

1. Buka console.cloud.google.com/projectcreate
2. Masukkan informasi yang diperlukan:

• Nama project - Anda dapat memasukkan nama apa pun yang diinginkan (misalnya, genai-workshop)
• Lokasi - biarkan sebagai Tidak Ada Organisasi
• Akun penagihan - Jika Anda melihat opsi ini, pilih Akun Penagihan Uji Coba Google Cloud Platform. Jangan khawatir jika Anda tidak melihat opsi ini. Lanjutkan saja ke langkah berikutnya.

3. Salin Project ID yang dibuat, Anda akan memerlukannya nanti.

4. Jika semuanya sudah sesuai, klik tombol Buat

Mengonfigurasi Cloud Shell

Setelah project Anda berhasil dibuat, lakukan langkah-langkah berikut untuk menyiapkan Cloud Shell.

1. Luncurkan Cloud Shell

Buka shell.cloud.google.com dan jika Anda melihat pop-up yang meminta Anda untuk memberikan otorisasi, klik Authorize.

2. Tetapkan ID Project

Jalankan perintah berikut di terminal Cloud Shell untuk menetapkan Project ID yang benar. Ganti <your-project-id> dengan Project ID Anda yang sebenarnya, yang disalin dari langkah pembuatan project di atas.

gcloud config set project <your-project-id>

Sekarang Anda akan melihat bahwa project yang benar dipilih di terminal Cloud Shell. Project ID yang dipilih ditandai dengan warna kuning.

3. Mengaktifkan API yang diperlukan

Untuk menggunakan layanan Google Cloud, Anda harus mengaktifkan API masing-masing layanan terlebih dahulu untuk project Anda. Jalankan perintah di bawah di terminal Cloud Shell untuk mengaktifkan layanan untuk Codelab ini:

gcloud services enable aiplatform.googleapis.com

Jika operasi berhasil, Anda akan melihat Operation/... finished successfully tercetak di terminal.

4. Buat lingkungan virtual Python

Sebelum memulai project Python, sebaiknya buat lingkungan virtual. Hal ini mengisolasi dependensi project, sehingga mencegah konflik dengan project lain atau paket Python global sistem.

Catatan: Kita akan menggunakan uv untuk membuat lingkungan virtual, bukan paket venv standar. Ini adalah pengelola project dan paket Python yang sangat cepat yang ditulis dalam Rust.

Jika tertarik, Anda dapat mempelajari lebih lanjut di dokumentasi UV resmi.

1. Buat direktori project dan buka direktori tersebut:

mkdir ai-agents-adk
cd ai-agents-adk

2. Buat dan aktifkan lingkungan virtual:

uv venv --python 3.12
source .venv/bin/activate

Anda akan melihat (ai-agents-adk) yang mengawali perintah terminal, yang menunjukkan bahwa lingkungan virtual aktif.

3. Instal halaman adk

uv pip install google-adk

Catatan: Jika Anda tidak sengaja menutup terminal, Anda harus membuka folder ai-agents-adk dan menjalankan source .venv/bin/activate lagi.

5. Buat agen

Setelah lingkungan Anda siap, saatnya membuat fondasi agen AI Anda. ADK memerlukan beberapa file untuk menentukan logika dan konfigurasi agen Anda:

• agent.py: Berisi kode Python utama agen Anda, yang menentukan nama, LLM yang digunakan, dan petunjuk intinya.
• __init__.py: Menandai direktori sebagai paket Python, membantu ADK menemukan dan memuat definisi agen Anda.
• .env: Menyimpan informasi sensitif dan variabel konfigurasi seperti kunci API, Project ID, dan lokasi.

Perintah ini akan membuat direktori baru bernama personal_assistant yang berisi tiga file penting.

adk create personal_assistant

Setelah perintah dijalankan, Anda akan diminta memilih beberapa opsi untuk mengonfigurasi agen.

Untuk langkah pertama, pilih opsi 1 untuk menggunakan model gemini-2.5-flash, model yang cepat dan efisien serta sempurna untuk tugas percakapan.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)
Choose model (1, 2): 1

Untuk langkah kedua, pilih Vertex AI (opsi 2), platform AI terkelola yang canggih dari Google Cloud, sebagai penyedia layanan backend.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Setelah itu, Anda perlu memverifikasi bahwa Project ID yang ditampilkan dalam tanda kurung [...] telah ditetapkan dengan benar. Jika ya, tekan Enter. Jika tidak, masukkan Project ID yang benar di dialog berikut:

Enter Google Cloud project ID [your-project-id]:

Terakhir, tekan Enter pada pertanyaan berikutnya, untuk menggunakan us-central1 sebagai region untuk codelab ini.

Enter Google Cloud region [us-central1]:

Anda akan melihat output yang serupa di terminal.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

6. Mempelajari kode agen

Untuk melihat file yang dibuat, buka folder ai-agents-adk di Cloud Shell Editor.

• Klik File > Open Folder... di menu atas.
• Cari dan pilih folder ai-agents-adk
• Klik Oke.

Jika panel menu atas tidak muncul, Anda juga dapat mengklik ikon folder dan memilih Buka Folder.

Catatan: Anda dapat menggunakan editor command line seperti Vim, tetapi Anda harus mengetahui perintah untuk keluar dari Vim sendiri.

Setelah jendela Editor dimuat sepenuhnya, buka folder personal-assistant. Anda akan melihat file yang diperlukan seperti yang disebutkan di atas (agent.py, __init__.py, dan .env).

File .env sering disembunyikan secara default. Agar dapat terlihat di Cloud Shell Editor:

• buka menu bar di bagian atas,
• klik Lihat, dan
• Pilih Aktifkan/Nonaktifkan File Tersembunyi.

Jelajahi konten setiap file.

agent.py

File ini membuat instance agen Anda menggunakan class Agent dari library google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: Baris ini mengimpor class Agent yang diperlukan dari library ADK.
• root_agent = Agent(...): Di sini, Anda membuat instance agen AI.
• name="root_agent": ID unik untuk agen Anda. Dengan demikian, ADK akan mengenali dan merujuk agen Anda.
• model="gemini-2.5-flash": Parameter penting ini menentukan Model Bahasa Besar (LLM) mana yang akan digunakan agen Anda sebagai "otak" dasarnya untuk memahami, menalar, dan menghasilkan respons. gemini-2.5-flash adalah model yang cepat dan efisien yang cocok untuk tugas percakapan.
• description="...": Memberikan ringkasan singkat tentang tujuan atau kemampuan agen. Deskripsi lebih ditujukan untuk pemahaman manusia atau untuk agen lain dalam sistem multi-agen agar memahami fungsi agen tertentu ini. Sering digunakan untuk logging, proses debug, atau saat menampilkan informasi tentang agen.
• instruction="...": Ini adalah perintah sistem yang memandu perilaku agen Anda dan menentukan personanya. Hal ini memberi tahu LLM cara bertindak dan tujuan utamanya. Dalam hal ini, perintah menetapkan agen sebagai "asisten yang membantu". Petunjuk ini sangat penting untuk membentuk gaya dan kemampuan percakapan agen.

init.py

File ini diperlukan agar Python mengenali personal-assistant sebagai paket, sehingga ADK dapat mengimpor file agent.py Anda dengan benar.

from . import agent

• from . import agent: Baris ini melakukan impor relatif, yang memberi tahu Python untuk mencari modul bernama agent (yang sesuai dengan agent.py) dalam paket saat ini (personal-assistant). Baris sederhana ini memastikan bahwa saat ADK mencoba memuat agen personal-assistant Anda, ADK dapat menemukan dan menginisialisasi root_agent yang ditentukan dalam agent.py. Meskipun kosong, keberadaan __init__.py-lah yang membuat direktori menjadi paket Python.

.env

File ini menyimpan konfigurasi khusus lingkungan dan kredensial sensitif.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: Memberi tahu ADK bahwa Anda bermaksud menggunakan layanan Vertex AI Google untuk operasi AI Generatif Anda. Hal ini penting untuk memanfaatkan layanan terkelola dan model lanjutan Google Cloud.
• GOOGLE_CLOUD_PROJECT: Variabel ini akan menyimpan ID unik Project Google Cloud Anda. ADK memerlukan hal ini untuk mengaitkan agen Anda dengan resource cloud Anda secara benar dan untuk mengaktifkan penagihan.
• GOOGLE_CLOUD_LOCATION: Menentukan region Google Cloud tempat resource Vertex AI Anda berada (misalnya, us-central1). Menggunakan lokasi yang benar akan memastikan agen Anda dapat berkomunikasi secara efektif dengan layanan Vertex AI di region tersebut.

7. Menjalankan agen di Terminal

Setelah ketiga file tersedia, Anda siap menjalankan agen langsung dari terminal. Untuk melakukannya, jalankan perintah adk run berikut di terminal:

adk run personal_assistant

Jika semuanya disiapkan dengan benar, Anda akan melihat output serupa di terminal. Jangan khawatir tentang peringatan untuk saat ini, selama Anda melihat [user]:, Anda dapat melanjutkan.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

Lanjutkan dan mulai chat dengan agen. Ketik sesuatu seperti "halo. Apa yang bisa kamu lakukan untukku?" dan Anda akan mendapatkan balasan.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

Anda akan melihat bahwa output terkadang diformat dengan Markdown, yang sulit dibaca di terminal. Pada langkah berikutnya, kita akan menggunakan UI Pengembangan untuk pengalaman yang jauh lebih kaya, seperti aplikasi chat.

Pemecahan masalah

Metode API ini memerlukan pengaktifan penagihan

Jika Anda menerima pesan yang bertuliskan {‘message': ‘This API method requires billing to be enabled'}, lakukan hal berikut:

1. Periksa apakah Anda menggunakan Project ID yang benar dalam file .env
2. Buka halaman akun penagihan tertaut dan lihat apakah akun penagihan sudah ditautkan
3. Jika tidak, pilih Akun Penagihan Uji Coba Google Cloud Platform dari opsi

Vertex AI API belum digunakan dalam project

Jika Anda menerima pesan error yang berisi {'message': 'Vertex AI API has not been used in project...'}, aktifkan Vertex AI API dengan mengetik ini di terminal:

gcloud services enable aiplatform.googleapis.com

Jika operasi berhasil, Anda akan melihat Operation/... finished successfully tercetak di terminal.

Error Lainnya

Jika Anda menerima error lain yang tidak disebutkan di atas, coba muat ulang tab Cloud Shell di browser (dan beri otorisasi ulang jika diminta).

8. Menjalankan agen di UI Web Pengembangan

Agent Development Kit juga menawarkan cara mudah untuk meluncurkan agen Anda sebagai aplikasi chat menggunakan UI pengembangannya. Cukup gunakan perintah adk web, bukan adk run.

Jika terminal Anda masih menjalankan adk run, ketik exit untuk menutupnya sebelum mengetik perintah ini:

adk web

Anda akan melihat output yang serupa di terminal:

...
INFO:     Started server process [4978]
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)

Anda memiliki dua opsi untuk mengakses UI pengembangan:

1. Buka melalui Terminal

• Ctrl + Klik atau Cmd + Klik pada link (misalnya, http://localhost:8000) seperti yang ditampilkan di terminal.

2. Buka melalui Pratinjau Web

• Klik tombol Pratinjau Web,
• Pilih Ubah Port.
• Masukkan nomor port (misalnya, 8000)
• Klik Ubah dan Pratinjau

Kemudian, Anda akan melihat UI seperti aplikasi chat muncul di browser. Mulai percakapan dengan asisten pribadi Anda melalui antarmuka ini.

Anda akan melihat bahwa format Markdown kini ditampilkan dengan benar, dan UI ini juga memungkinkan Anda men-debug dan menyelidiki setiap peristiwa pesan, status agen, permintaan pengguna, dan banyak lagi. Selamat chatting!

9. Membersihkan (Opsional)

Catatan: Anda tidak perlu melakukan langkah ini jika berencana untuk melanjutkan seri ini. Jika Anda mengikuti codelab ini secara langsung dengan instruktur, instruktur Anda akan memberikan petunjuk lebih lanjut tentang langkah-langkah yang harus dilakukan.

Karena codelab ini tidak melibatkan produk yang berjalan lama, cukup hentikan sesi agen aktif Anda (misalnya, instance adk web di terminal Anda) dengan menekan Ctrl + C atau Cmd + C di terminal.

Menghapus Folder dan File Project Agen

Jika Anda hanya ingin menghapus kode dari lingkungan Cloud Shell, gunakan perintah berikut:

cd ~
rm -rf ai-agents-adk

Menonaktifkan Vertex AI API

Untuk menonaktifkan Vertex AI API yang diaktifkan sebelumnya, jalankan perintah ini:

gcloud services disable aiplatform.googleapis.com

Menghentikan Seluruh Project Google Cloud

Jika Anda ingin menonaktifkan project Google Cloud sepenuhnya, lihat panduan resmi untuk mengetahui petunjuk selengkapnya.

10. Kesimpulan

Selamat! Anda telah berhasil membuat agen asisten pribadi sederhana menggunakan Agent Development Kit (ADK). Sekarang Anda memiliki dasar dan pemahaman yang kuat tentang komponen inti agen ADK.

Sebagai langkah berikutnya, Anda dapat memperluas kemampuan agen secara signifikan dengan memberinya alat untuk mengakses informasi real-time dan berinteraksi dengan layanan eksternal. Jika Anda ingin melanjutkan perjalanan, codelab berikutnya dalam seri ini, Membangun Agen AI dengan ADK: Memberdayakan dengan Alat, akan memandu Anda melalui proses ini.