Membangun Agen AI dengan Google ADK

1. Pengantar

Dalam codelab ini, Anda akan membangun agen AI pertama Anda langkah demi langkah menggunakan Agent Development Kit (ADK) dan Gemini dari Google. Anda akan membuat agen penulisan blog dasar yang merencanakan dan menulis konten, yang menunjukkan konsep inti penalaran dan tindakan.

Yang akan Anda lakukan

• Siapkan lingkungan pengembangan Anda untuk ADK.
• Buat sistem multi-agen dengan Planner dan Writer.
• Jalankan agen secara lokal dan berinteraksi dengannya melalui UI Web ADK.

Yang Anda butuhkan

• Browser web seperti Chrome.
• Python 3.10 atau yang lebih tinggi diinstal di komputer Anda.
• Kunci API Google AI Studio.

Codelab ini ditujukan bagi developer dari semua level, termasuk pemula.

Estimasi durasi: 30 menit.

2. Panduan visual: Apa yang dimaksud dengan Agen AI?

Sebelum mulai membangun, mari kita pahami secara singkat apa itu agen AI dan pola umum yang mereka ikuti.

Apa yang dimaksud dengan Agen AI?

Pada tingkat yang paling sederhana, agen adalah software yang tidak hanya menjawab, tetapi juga dapat memutuskan dan mengambil tindakan. Alih-alih membuat satu respons seperti chatbot tradisional, chatbot ini akan melihat permintaan Anda, mencari tahu langkah-langkah yang harus dilakukan, mungkin memanggil API, menjalankan kode, melihat hasilnya, lalu memutuskan apa yang harus dilakukan selanjutnya.

Salah satu penjelasan paling jelas berasal dari makalah penelitian ReAct: Synergizing Reasoning and Acting in Language Models. Ide dalam makalah tersebut sederhana tetapi efektif: model bahasa tidak boleh hanya membuat teks dalam satu langkah. Model bahasa dapat melakukan penalaran langkah demi langkah, mengambil tindakan seperti memanggil alat atau API, mengamati hasilnya, lalu memutuskan tindakan yang harus dilakukan selanjutnya.

Siklus penalaran, bertindak, mengamati, dan menyesuaikan tersebut adalah fondasi cara kerja agen AI modern. Selain itu, definisi tersebut sesuai dengan cara Google Cloud mendefinisikannya: sistem dengan kemampuan penalaran, perencanaan, dan memori, dengan otonomi yang cukup untuk beradaptasi dan mengambil keputusan atas nama pengguna.

Tiga Pola Perilaku Agen

Tidak semua agen berperilaku sama. Cara yang berguna untuk memikirkannya adalah dalam tiga pola luas:

1. Agen berurutan: Agen ini berjalan langkah demi langkah seperti jalur perakitan: Langkah 1, lalu Langkah 2, lalu Langkah 3. Mereka dapat diprediksi, tetapi kaku.
2. Agen reaktif: Agen ini memutuskan saat itu juga. Mereka melihat kondisi saat ini dan bertanya, 'Apa yang harus saya lakukan selanjutnya?' Mungkin Alat A sekali, Alat B berikutnya. Agen ini fleksibel, tetapi tidak merencanakan ke depan.
3. Agen deliberatif, atau agen perencanaan: Agen ini berhenti untuk membuat rencana, lalu melaksanakannya. Pikirkan tentang pemesanan perjalanan — Anda tidak hanya membeli tiket pesawat secara acak, Anda memilih tanggal, hotel, mengurutkan langkah-langkah, lalu menyelesaikannya.

Manakah yang 'benar'? Hal ini bergantung pada masalahnya. Untuk alur yang sederhana dan dapat diprediksi, berurutan tidak masalah. Untuk tugas dinamis, reaktif lebih baik. Untuk tujuan multilangkah dengan dependensi, Anda memerlukan agen perencanaan.

Di lab ini, kita akan membangun agen Deliberative/Planning yang pertama-tama membuat kerangka, lalu menulis postingan blog.

3. Sebelum memulai

Buat Akun dan Project Google Cloud

Untuk men-deploy agen Anda ke Google Cloud Run nanti dalam lab ini, Anda memerlukan akun Google Cloud dan project dengan penagihan yang diaktifkan.

1. Login ke Konsol Google Cloud. Buat project baru atau gunakan kembali project yang sudah ada. Jika Anda belum memiliki Akun Google, Anda harus membuatnya.
2. Selanjutnya, Anda harus mengaktifkan penagihan di Konsol Cloud untuk menggunakan resource Cloud. Menjalankan operasi dalam codelab ini seharusnya tidak memerlukan biaya lebih dari beberapa sen. Pengguna baru Google Cloud juga mungkin memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai$300 USD.
3. Catat Project ID Anda (nama unik di semua project Google Cloud). Anda akan memerlukan ini untuk mengonfigurasi dan men-deploy agen.

Mendapatkan Kunci API Google AI Studio

Untuk menggunakan model Gemini, Anda memerlukan kunci API dari Google AI Studio.

1. Buka Google AI Studio.
2. Klik Get API Key.
3. Buat kunci baru atau gunakan kunci yang sudah ada. Salin kunci untuk digunakan nanti.

4. Membuat Struktur Project Agen Penulis Blog

Pada langkah ini, Anda akan menyiapkan direktori dan file untuk menampung kode agen penulisan blog di komputer lokal.

1. Membuat ruang kerja agen penulisan blog

Buka terminal Anda dan jalankan perintah berikut untuk membuat direktori khusus bagi agen penulis blog Anda dan membukanya:

mkdir bloggeragent
cd bloggeragent

2. Lakukan inisialisasi file agen

Framework Google ADK memuat alur kerja agen langsung dari direktori project Anda. Buat file yang diperlukan langsung di root bloggeragent:

touch requirements.txt .env __init__.py agent.py

5. Menginstal Dependensi dan Menyiapkan Lingkungan

Pada langkah ini, Anda akan menyiapkan lingkungan virtual Python, menginstal framework Google ADK, dan mengonfigurasi variabel lingkungan untuk mengautentikasi agen blog Anda dengan model Gemini.

1. Mengonfigurasi persyaratan agen

Buka file requirements.txt di direktori bloggeragent dan tentukan paket yang diperlukan untuk agen penulisan blog dengan menambahkan kode berikut:

google-adk==2.2.0
python-dotenv

2. Buat lingkungan virtual untuk agen

Dari direktori bloggeragent, buat dan aktifkan lingkungan virtual Python untuk mengisolasi paket agen:

python3 -m venv .venv
source .venv/bin/activate

3. Menginstal framework ADK

Instal dependensi yang ditentukan di requirements.txt untuk melengkapi ruang kerja lokal Anda dengan Google ADK:

pip install -r requirements.txt

4. Mengonfigurasi kredensial API agen

Buka file .env yang Anda buat di root project dan tambahkan kunci API Gemini Anda:

GOOGLE_API_KEY=your_api_key

Ganti your_api_key dengan kunci yang Anda salin dari Google AI Studio.

Catatan tentang Nama Model dan Endpoint:

Pemilihan Model: Kode agen di agent.py secara default menggunakan gemini-flash-latest. Seperti yang dijelaskan dalam dokumentasi Google ADK di bagian "Mulai", alias pemilih ini memungkinkan aplikasi Anda menggunakan model Gemini Flash stabil terbaru yang tersedia secara otomatis. Jika ingin menggunakan model lain (seperti model Pro atau model versi tertentu), Anda dapat mengganti default ini dengan menyetel variabel lingkungan MODEL di setelan terminal atau penampung (tidak perlu berada dalam file .env, karena kode membaca variabel lingkungan sistem secara langsung).

Endpoint & Latensi: Secara default, penyiapan ini menggunakan endpoint Google AI Studio global. Untuk workload produksi yang latensinya sangat penting, Anda harus merutekan panggilan AI generatif melalui endpoint Gemini Enterprise regional yang lebih dekat dengan workload Anda (misalnya, us-east1 atau us-west1). Untuk mengetahui detail ketersediaan regional dan tempat model tertentu dihosting, lihat panduan model Gemini Enterprise Agent Platform.

6. Membangun Penulis Blog Multi-Agen

Pada langkah ini, Anda akan menerapkan alur kerja inti sistem agen penulisan blog.

Alih-alih chatbot satu perintah yang sederhana, Anda akan membangun sistem multi-agen yang kompleks yang menggunakan loop koreksi otomatis dan verifikasi kerangka untuk menulis postingan teknis berkualitas tinggi. Hal ini mengikuti pola Deliberatif/Perencanaan yang kita bahas sebelumnya.

Ringkasan Arsitektur

Berikut cara agen spesialis berinteraksi dalam sistem Anda:

Konfigurasi init.py

Buka __init__.py di editor teks Anda dan tambahkan impor berikut untuk mengekspos alur kerja agen ke runner:

from . import agent

Menulis alur kerja agen penulisan blog

Buka agent.py di editor kode Anda dan tambahkan kode berikut yang menentukan Planner, Writer, Pemeriksa Validasi, dan agen Blogger utama:

import os
import sys
from pathlib import Path
import datetime

from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool

# env config
load_dotenv()

MODEL = os.getenv("MODEL", "gemini-flash-latest")

# Sub-Agent: Planner
blog_planner = Agent(
   name="BlogPlanner",
   model=MODEL,
   description="Creates a practical, skimmable outline in Markdown.",
   instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion

If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
   output_key="blog_outline",
)

class OutlineValidationChecker(Agent):
   def __init__(self):
       super().__init__(
           name="OutlineValidationChecker",
           model=MODEL,
           description="Validates that the outline is usable.",
           instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
           output_key="validation_result",
       )

robust_blog_planner = LoopAgent(
   name="RobustBlogPlanner",
   description="Retries planning if validation fails.",
   sub_agents=[blog_planner, OutlineValidationChecker()],
   max_iterations=3,
)

# Sub-Agent: Writer
blog_writer = Agent(
   name="BlogWriter",
   model=MODEL,
   description="Writes a technical blog post from the outline.",
   instruction="""
Write a complete Markdown article from the outline in `blog_outline`.

Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
   output_key="blog_post",
)

class BlogPostValidationChecker(Agent):
   def __init__(self):
       super().__init__(
           name="BlogPostValidationChecker",
           model=MODEL,
           description="Validates the final post.",
           instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
           output_key="validation_result",
       )

robust_blog_writer = LoopAgent(
   name="RobustBlogWriter",
   description="Retries writing if validation fails.",
   sub_agents=[blog_writer, BlogPostValidationChecker()],
   max_iterations=3,
)

# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool  = agent_tool.AgentTool(agent=robust_blog_writer)

# Root Agent: Plan → Write 
root_agent = Agent(
   name="Blogger",
   model=MODEL,
   description="Minimal multi-agent blogger that plans and writes.",
   instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.

Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
   tools=[
       planner_tool, # calls RobustBlogPlanner
       writer_tool,  # calls RobustBlogWriter
   ],
)

Memahami Arsitektur Agen

Mari kita uraikan komponen utama kode yang baru saja Anda tambahkan di agent.py untuk memahami cara kode tersebut menerapkan alur kerja perencanaan dan penulisan multiagen:

1. Sub-Agen BlogPlanner

Agen blog_planner bertanggung jawab atas perencanaan konten. Plugin ini menggunakan topik yang diberikan oleh pengguna dan menghasilkan kerangka terstruktur dalam Markdown (dengan judul, pengantar, 4-6 bagian, dan kesimpulan). Garis batas disimpan ke kamus status bersama dengan kunci "blog_outline".

2. OutlineValidationChecker

Agen OutlineValidationChecker bertindak sebagai gerbang kualitas. Fungsi ini meninjau "blog_outline" yang dihasilkan dalam status. Jika garis batas valid, API akan merespons dengan "ok". Jika tidak, nilai "retry" akan ditampilkan bersama daftar item yang tidak ada.

3. Loop RobustBlogPlanner

Untuk mencegah agen menghasilkan draf yang buruk, kita membungkus perencana dan pemeriksa validasi di dalam LoopAgent yang disebut robust_blog_planner. Jika validasi gagal dan menampilkan "retry", loop akan otomatis menjalankan perencana lagi, hingga 3 kali, sehingga memastikan koreksi mandiri sebelum beralih ke tahap berikutnya.

4. Sub-Agen BlogWriter

Setelah poin-poin utama selesai, agen blog_writer akan membaca "blog_outline" dari status dan membuat artikel teknis lengkap dalam Markdown, yang cocok dengan struktur poin-poin utama dan menyesuaikannya untuk software engineer.

5. Loop BlogPostValidationChecker & RobustBlogWriter

Seperti kerangka, artikel akhir divalidasi oleh BlogPostValidationChecker untuk memastikan semua bagian penting ada dan jelas. Penulis dan pemeriksa berada dalam loop robust_blog_writer, sehingga dapat mengoreksi diri hingga 3 kali jika pemeriksa menemukan masalah.

6. Mengekspos Loop sebagai Alat

Kita membungkus loop perencana (robust_blog_planner) dan loop penulis (robust_blog_writer) sebagai alat (planner_tool dan writer_tool) menggunakan AgentTool. Dengan demikian, agen lain dapat memanggil alur kerja yang kompleks ini seolah-olah alur kerja tersebut adalah alat sederhana.

7. Agen Root Blogger

root_agent (bernama Blogger) mengorkestrasi seluruh alur kerja. Saat diberi topik, petunjuknya akan memandunya untuk:

1. Panggil planner_tool untuk membuat garis batas yang divalidasi.
2. Panggil writer_tool untuk menulis draf berdasarkan kerangka tersebut.
3. Selesaikan dengan membuat 3 judul alternatif dan 2 saran tweet.

Arsitektur loop multi-agen ini memastikan keandalan dengan mendeteksi dan memperbaiki kesalahan pemformatan atau struktural LLM sebelum menampilkan output kepada pengguna.

7. Menjalankan dan Menguji Agen

Sekarang saatnya melihat cara kerja agen Anda.

1. Mulai UI Web ADK

Pastikan Anda berada di direktori utama project bloggeragent di terminal dan lingkungan virtual Anda aktif (source .venv/bin/activate), lalu mulai antarmuka web:

adk web

Jika port 8000 sudah digunakan, Anda dapat menentukan port lain menggunakan --port 8001. Jika perintah adk tidak ditemukan, pastikan lingkungan virtual Anda diaktifkan dan paket diinstal dengan benar.

2. Berinteraksi dengan Agen

1. Buka browser Anda, lalu buka http://127.0.0.1:8000 (atau port yang Anda tentukan).
2. Anda akan melihat UI Web ADK dengan agen Blogger yang dimuat dan tata letak visualnya (menampilkan agen root Blogger yang mengarah ke alat RobustBlogPlanner dan RobustBlogWriter):
3. Ketik topik teknis di kotak pesan, lalu tekan Enter. Berikut beberapa perintah pengujian menarik yang dapat Anda gunakan untuk mengevaluasi agen:
   • How to build an AI agent using planning loops
   • Explain the difference between REST and gRPC in microservices
   • A guide to using Python's asyncio for backend concurrency
   • Why developers should use Docker for local database setups
4. Tonton rekaman aktivitas eksekusi di UI. Anda akan melihat BlogPlanner membuat kerangka, OutlineValidationChecker memvalidasinya, dan BlogWriter menulis draf akhir berdasarkan kerangka tersebut:

8. Men-deploy ke Cloud Run

Setelah memverifikasi bahwa agen berfungsi secara lokal, mari kita deploy ke Google Cloud Run agar orang lain dapat menggunakannya.

Google Cloud Run adalah platform komputasi terkelola yang memungkinkan Anda menjalankan container stateless yang dapat dipanggil melalui permintaan web atau peristiwa Pub/Sub.

1. Prasyarat untuk Deployment

Untuk men-deploy agen penulisan blog ke Cloud Run, Anda harus menginstal dan mengautentikasi Google Cloud CLI (gcloud) di mesin lokal Anda:

1. Instal Google Cloud CLI: Jika Anda belum menginstalnya, ikuti Panduan Pemasangan Google Cloud CLI untuk sistem operasi Anda (macOS, Windows, atau Linux).
2. Mengautentikasi terminal lokal Anda: Setelah diinstal, jalankan perintah berikut di terminal Anda untuk login ke akun Google Cloud Anda:

   gcloud auth login
   

3. Verifikasi autentikasi: Konfirmasi bahwa akun Anda berhasil sedang login dan Anda dapat mengakses resource Google Cloud Anda:

   gcloud auth list
   

Langkah deployment ini memerlukan project Google Cloud dengan penagihan yang diaktifkan. Jika hanya ingin menjalankan dan menguji agen penulisan blog secara lokal, Anda dapat melewati bagian selanjutnya.

2. Menyiapkan Project Google Cloud

Tetapkan project aktif Anda di terminal:

gcloud config set project <YOUR_PROJECT_ID>

Aktifkan layanan Google Cloud yang diperlukan untuk membangun dan men-deploy agen dalam container Anda:

gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com

Karena perintah deployment ADK menggunakan Google Cloud Build untuk mengotomatiskan proses build, Anda harus memberikan izin akun layanan komputasi default untuk menggunakan Cloud Build.

Temukan nomor project Anda dengan menjalankan:

gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"

Jalankan perintah berikut untuk mengikat peran IAM yang diperlukan (ganti dengan project ID Anda dan dengan angka yang ditampilkan dari perintah di atas).

1. Beri Cloud Build izin untuk membangun container Anda:

gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
  --member="serviceAccount:<PROJECT_NUMBER>[e-mail]" \
  --role="roles/cloudbuild.builds.builder"

2. Beri izin akses Gemini Enterprise agar agen yang di-deploy dapat memanggil model Gemini tanpa memerlukan kunci API:

gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
  --member="serviceAccount:<PROJECT_NUMBER>[e-mail]" \
  --role="roles/aiplatform.user"

3. Menyiapkan variabel lingkungan lokal

Untuk menyederhanakan perintah deployment dan mencegah salah ketik, tetapkan project ID Anda sebagai variabel lingkungan di sesi terminal Anda:

export PROJECT_ID="<YOUR_PROJECT_ID>"

4. Men-deploy menggunakan ADK CLI

CLI ADK menyediakan perintah yang disederhanakan untuk men-deploy agen Anda ke Cloud Run.

Pastikan lingkungan virtual Anda aktif dan Anda berada di direktori project bloggeragent, lalu jalankan perintah deployment:

# Deploy using ADK
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=us-east1 \
  --service_name=bloggeragent \
  --with_ui \
  . \
  -- \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global

Selama proses deployment, Anda akan diminta menjawab dua pertanyaan berikut di terminal:

1. Konfirmasi pembuatan repositori:

   Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created.
   
   Do you want to continue (Y/n)?
   

   Ketik Y, lalu tekan Enter.
2. Izinkan akses tanpa autentikasi:

   Allow unauthenticated invocations to [bloggeragent] (y/N)?
   

   Ketik y, lalu tekan Enter (tindakan ini memungkinkan Anda mengakses UI Web ADK secara publik di browser).

Menetapkan variabel lingkungan untuk Cloud Run

Saat menjalankan agen secara lokal, Anda menggunakan file .env untuk mengelola variabel lingkungan. Namun, selama deployment, file .env lokal akan otomatis diabaikan (menggunakan .gcloudignore) untuk mencegah upload rahasia atau konfigurasi lokal. Sebagai gantinya, parameter --set-env-vars (bukan flag) digunakan untuk memasukkan variabel lingkungan (seperti MODEL dan GOOGLE_CLOUD_LOCATION) secara eksplisit ke dalam lingkungan layanan Cloud Run. Autentikasi ditangani secara otomatis oleh akun layanan Cloud Run menggunakan Kredensial Default Aplikasi (ADC), sehingga Anda tidak perlu mengonfigurasi atau mengupload kunci API.

5. Mengakses Agen yang Di-deploy

Setelah deployment selesai, perintah akan menghasilkan URL. Buka URL tersebut di browser Anda untuk mengakses UI Web ADK yang aktif dan dapat diakses secara publik.

9. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.

1. Menghapus Layanan Cloud Run

Hapus layanan bloggeragent yang di-deploy:

gcloud run services delete bloggeragent --region=us-east1 --quiet

2. Menghapus Repositori Artifact Registry

Hapus repositori Docker yang dibuat untuk menyimpan image container yang dibuat:

gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet

3. Hentikan Server Lokal

Untuk menghentikan server ADK lokal, tekan CTRL+C di terminal tempat server berjalan, lalu nonaktifkan lingkungan virtual:

deactivate

10. Selamat

Selamat! Anda telah membangun agen AI pertama menggunakan ADK Google dan Gemini.

Yang telah Anda pelajari

• Konsep inti agen AI (Penalaran dan Tindakan).
• Cara menggunakan Google ADK untuk membangun sistem multi-agen.
• Cara menjalankan dan menguji agen menggunakan UI Web.

Langkah berikutnya

• Coba tambahkan alat ke agen Anda (seperti penelusuran web atau panggilan API).
• Nantikan Video 2, tempat kita akan mengintegrasikan server MCP.

Dokumen referensi

• Dokumentasi ADK Google
• Dokumentasi Gemini