Halaman ini diterjemahkan oleh Cloud Translation API.

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 dalam 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.

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
Project Google Cloud dengan penagihan diaktifkan
Pikiran yang ingin tahu dan semangat untuk belajar

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 ini 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 tugas.

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 membangun 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. Menyiapkan Layanan Google Cloud

Buat Project Google Cloud

Codelab ini mengasumsikan bahwa Anda telah membuat project Google Cloud dengan penagihan diaktifkan. Jika Anda belum memiliki project, ikuti langkah-langkah berikut untuk membuatnya:

Pilih atau Buat Project Google Cloud

Buka Konsol Google Cloud.
Di bagian atas, klik menu dropdown pemilih project (di samping logo Google Cloud)
Pilih project yang ada atau buat project baru.

Aktifkan Penagihan

Pastikan penagihan diaktifkan untuk project Google Cloud yang Anda pilih.
Anda dapat mempelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project dengan mengikuti petunjuk dalam dokumentasi Penagihan Google Cloud.

Mengonfigurasi Cloud Shell

Sekarang, pastikan Anda telah menyiapkan semuanya dengan benar di Cloud Shell, antarmuka command line praktis langsung di dalam Konsol Google Cloud.

Luncurkan Cloud Shell

Di pojok kanan atas Konsol Google Cloud, Anda akan melihat ikon yang terlihat seperti terminal (>_). Klik ikon tersebut untuk mengaktifkan Cloud Shell.

Izinkan Akses

Jika diminta, klik Authorize untuk memberikan izin yang diperlukan kepada Cloud Shell agar dapat berinteraksi dengan project Google Cloud Anda.

Verifikasi Akun Anda:

Setelah Cloud Shell dimuat, mari kita pastikan Anda menggunakan akun Google Cloud yang benar. Jalankan perintah berikut:

gcloud auth list

Anda akan melihat output perintah yang serupa di terminal:

Credentialed Accounts

ACTIVE: *
ACCOUNT: current_account@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Ganti Akun (Jika Perlu):

Jika akun aktif bukan akun yang ingin Anda gunakan untuk Codelab ini, beralihlah ke akun yang benar menggunakan perintah ini, dengan mengganti <your_desired_account@example.com> dengan email Anda yang akan digunakan untuk lab ini:

gcloud config set account <your_desired_account@example.com

Konfirmasi Project Anda

Selanjutnya, mari kita verifikasi bahwa Cloud Shell dikonfigurasi untuk menggunakan Project Google Cloud yang benar. Jalankan:

gcloud config list project

Anda akan melihat daftar konfigurasi. Cari bagian [core], dan pastikan nilai project cocok dengan ID Project Google Cloud yang ingin Anda gunakan untuk Codelab ini:

[core]
project = <current-project-id>

Menetapkan Project Anda (Jika Perlu)

Jika nilai project ID salah, tetapkan ke project yang Anda inginkan menggunakan perintah berikut:

gcloud config set project <your-desired-project-id>

Aktifkan API yang diperlukan

Untuk menggunakan layanan Google Cloud, Anda harus mengaktifkan API masing-masing layanan terlebih dahulu untuk project Anda. Menjalankan perintah di bawah di terminal Cloud Shell akan mengaktifkan semua layanan yang Anda perlukan 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. Karena Agent Development Kit (ADK) memerlukan Python 3.9 atau yang lebih tinggi, kita akan menggunakan alat seperti uv untuk mengelola lingkungan virtual dan memastikan versi Python yang benar digunakan.

uv adalah alat modern, cepat, dan efisien untuk mengelola project dan lingkungan Python, yang menggabungkan fungsi yang biasanya ditemukan di alat seperti pip, venv, pip-tools, dan pipx. Ditulis dalam Rust untuk kecepatan.

Cloud Shell sudah menyediakan uv sehingga kita bisa langsung memulai.

Pastikan uv diinstal dengan benar

uv --version

Membuat folder project baru untuk agen AI Anda

uv init ai-agents-adk
cd ai-agents-adk

Buat lingkungan virtual dengan Python 3.12

uv venv --python 3.12

Instal library Google ADK dalam lingkungan virtual Anda

uv add google-adk

Periksa apakah Anda telah berhasil menginstal paket google-adk

uv pip list | grep google-adk

Jika Anda melihat baris output dengan google-adk dan versinya, Anda dapat melanjutkan ke langkah berikutnya.

5. Buat agen

Setelah lingkungan pengembangan disiapkan dan siap, sekarang saatnya meletakkan dasar untuk agen AI Anda. Agent Development Kit (ADK) menyederhanakan proses ini, hanya memerlukan beberapa file penting untuk menentukan logika dan konfigurasi inti agen Anda.

Ketiga file ini bekerja sama untuk membuat agen Anda dapat ditemukan, dijalankan, dan dikonfigurasi:

agent.py: Ini adalah inti dari agen Anda. File ini berisi kode Python utama yang menentukan perilaku agen Anda, termasuk namanya, model bahasa besar (LLM) yang digunakannya sebagai "otak", dan petunjuk inti yang memandu responsnya.
__init__.py: Di Python, file __init__.py menandai direktori sebagai paket Python. Untuk ADK, hal ini sangat penting karena membantu framework menemukan dan memuat definisi agen Anda dari agent.py. Dalam project ADK sederhana, file ini sering kali berisi satu baris untuk mengimpor modul agent, sehingga membuat agen Anda dapat diakses oleh runner ADK.
.env: File ini (singkatan dari "environment") digunakan untuk menyimpan informasi sensitif dan variabel konfigurasi yang dibutuhkan agen Anda, seperti kunci API, ID project, dan lokasi geografis. Menyimpan detail ini dalam file .env terpisah adalah praktik terbaik untuk keamanan dan portabilitas, karena mencegah hardcode data sensitif secara langsung ke dalam kode Anda. Selain itu, Anda dapat dengan mudah mengubah konfigurasi tanpa mengubah logika agen utama.

Gunakan perintah di bawah untuk membuat file ini dalam folder khusus untuk agen asisten pribadi Anda:

uv run 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

Terakhir, Anda akan diminta untuk mengonfirmasi project ID dan region Google Cloud Anda. Jika nilai yang telah diisi sebelumnya (current-project-id dan current-region) adalah nilai yang ingin Anda gunakan, cukup tekan Enter untuk setiap pertanyaan.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

Anda akan melihat output yang serupa di terminal.

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

Sekarang, klik tombol Open Editor di bagian atas jendela Cloud Shell Anda. Mengklik tombol tersebut akan membuka jendela Editor, yang mempermudah Anda menjelajahi konten file. Proses pengalihan mungkin memerlukan waktu beberapa saat; jika Anda terjebak di layar pemuatan selama lebih dari beberapa menit, coba muat ulang browser Anda.

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). Mari kita jelajahi kontennya.

Jika Anda tidak melihat file .env di folder, buka panel menu di bagian atas, klik Lihat, lalu pilih Tampilkan/Sembunyikan File Tersembunyi. Ini adalah setelan umum karena file .env sering disembunyikan secara default untuk mencegah eksposur yang tidak disengaja.

Mari kita pelajari isi 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="personal_assistant": 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, melakukan penalaran, 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 dengan 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.

6. Menjalankan agen di Terminal

Setelah ketiga file tersedia, Anda siap menjalankan agen langsung dari terminal. Untuk melakukannya, Anda perlu membuka jendela Terminal. Mengklik Terminal di panel menu, lalu memilih New Terminal akan menyelesaikan tugas ini.

Setelah terminal tersedia, Anda dapat memulai agen menggunakan perintah adk run. Karena ini adalah jendela terminal baru dan kita menggunakan uv, Anda harus membuka folder ai-agent-adk terlebih dahulu, lalu menambahkan awalan uv run pada perintah adk run.

Ketik perintah berikut ke terminal:

cd ai-agents-adk
uv run adk run personal_assistant

Jika semuanya disiapkan dengan benar, Anda akan melihat output serupa di terminal.

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

Mulai chat dengan agen. 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.

7. Menjalankan agen di UI 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 Anda masih berada di sesi sebelumnya, cukup ketik exit di terminal untuk menutupnya. Setelah sesi sebelumnya ditutup, ketik perintah berikut di terminal:

uv run 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:

Buka melalui Terminal

Ctrl + Klik atau Cmd + Klik pada URL (misalnya, http://localhost:8000) dari terminal.

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!

8. Pembersihan

Karena codelab ini tidak melibatkan produk yang berjalan lama, cukup hentikan sesi agen aktif Anda (misalnya, instance adk web di terminal) dengan menekan Ctrl + 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.

9. Kesimpulan

Selamat! Anda telah berhasil membuat agen asisten pribadi sederhana menggunakan Agent Development Kit (ADK).

Seperti yang mungkin Anda perhatikan, agen asisten pribadi ini belum terlalu mumpuni (misalnya, agen ini tidak dapat mengakses internet untuk mendapatkan informasi terbaru). Dalam codelab berikutnya dari seri "Membangun Agen AI dengan ADK" ini, Anda akan mempelajari cara melengkapi agen asisten pribadi Anda dengan fungsi dan alat. Sampai jumpa!