Pola Agentik ADK dengan Memori & MCP

1. Yang akan Anda pelajari

Selamat datang di ADK Master Class - Perjalanan Anda ke Sistem Multi-Agen

Anda akan memasuki dunia agen AI yang menarik. Lupakan chatbot sederhana yang hanya menjawab pertanyaan. Kita akan mempelajari Agent Development Kit (ADK) secara mendalam untuk membangun sistem otonom yang canggih yang dapat bernalar, merencanakan, dan menggunakan alat untuk menyelesaikan tugas yang kompleks.

Seluruh codelab ini akan menjadi perjalanan langsung, 1 Repo GitHub ini berisi semua kode dan contoh untuk sesi kita. repo github

Pada akhir tutorial ini, Anda akan dapat:

• Membangun Agen AI Pertama Anda: Mulai dari nol hingga agen yang berfungsi penuh yang dapat memahami kebutuhan pengguna, menggunakan alat seperti Google Penelusuran, dan menghasilkan respons yang mendetail dan bermanfaat.
• Membuat Sistem Multi-Agen: Pelajari pola "Agen sebagai Alat", sebuah konsep revolusioner yang memungkinkan agen mendelegasikan tugas ke agen khusus lainnya, sehingga menciptakan tim ahli AI yang bekerja sama.
• Mengorkestrasi Alur Kerja yang Kompleks: Melampaui delegasi sederhana dan menguasai pola lanjutan seperti Router, Rantai Berurutan, Loop, dan Eksekusi Paralel untuk membangun aplikasi yang kuat, efisien, dan cerdas yang dapat menangani hampir semua permintaan.
• Memberi Memori kepada Agen Anda: Memahami peran penting memori percakapan, yang memungkinkan agen Anda menangani pertanyaan lanjutan, belajar dari masukan, dan mengelola tugas multilangkah dengan lancar.
• Terhubung dengan MCP: Terhubung dengan MCP Toolbox.

Mari kita mulai! 🚀

2. Penyiapan: Mendapatkan Kunci API Anda

Penyiapan Kunci API Google AI Studio

Codelab ini berjalan sepenuhnya pada kunci API Google AI Studio gratis. Tidak diperlukan project Google Cloud, akun penagihan, atau kredit — setiap sesi, termasuk Memori (Sesi 6) dan MCP (Sesi 7), berjalan secara lokal dengan kunci Anda. Setiap peserta didik menggunakan kunci sendiri, sehingga kuota API per orang, tidak dibagikan.

Yang Anda perlukan:

• Python 3.9 atau yang lebih baru (python3 --version untuk memeriksa)
• Akun Google (untuk membuat kunci AI Studio)
• Terminal — komputer lokal atau Cloud Shell berfungsi
• ~10 menit

Untuk mendukung agen AI kami, kita memerlukan kunci Gemini API dari Google AI Studio. Ini adalah cara tercepat untuk memulai.

Langkah 1 — Mendapatkan Kunci Gemini API dari AI Studio (1 menit)

1. Buka https://aistudio.google.com/app/apikey di tab browser baru.
2. Login dengan Akun Google Anda.
3. Klik "Buat kunci API" (kanan atas).
4. Dialog akan terbuka dengan dropdown project:

• Jika Anda sudah membuat project Google sebelumnya: Pilih project tersebut, lalu klik "Buat kunci API di project yang sudah ada"
• Jika TIDAK ada dalam daftar: Klik "Buat Project".

5. Salin kunci API yang ditampilkan. Kunci API dimulai dengan AIza... dan terdiri dari ~40 karakter.

✏️ Tempelkan di tempat yang aman — Anda akan membutuhkannya di Langkah 4 di bawah.

Perlakukan kunci API seperti sandi. Jangan tempelkan di chat publik, screenshot, atau lakukan commit ke repo GitHub publik.

Langkah 2 — Membuat Clone Repositori (1 menit)

👉💻 Buka terminal (atau Cloud Shell) dan buat clone repo tutorial:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Langkah 3 — Membuat Lingkungan Virtual &Menginstal Dependensi

👉💻 Buat dan aktifkan lingkungan virtual bernama .adk_env, lalu instal dependensi:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Anda akan melihat (.adk_env) di awal perintah terminal.

Langkah 4 — 🔥 PENTING: Menambahkan Kunci API Anda

⚠️ Jangan lewati langkah ini! Buat file .env di root folder adk_tutorial. Satu file ini mendukung setiap sesi di codelab ini — sesi Web ADK (1–5) dan sesi Memori dan MCP command line (6–7) semuanya dibaca secara otomatis.

👉💻 Buat file .env dengan kunci Anda (ganti your_actual_api_key_here dengan kunci dari Langkah 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

~/adk_tutorial/.env Anda sekarang akan berisi:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 PENTING: Ganti your_actual_api_key_here dengan kunci API Anda yang sebenarnya dari Langkah 1 (dimulai dengan AIza...).

⚠️ Pastikan GOOGLE_GENAI_USE_VERTEXAI ditetapkan ke FALSE. Hal ini memberi tahu ADK untuk melakukan autentikasi dengan kunci API Google AI Studio, bukan Vertex AI.

✅ Checkpoint: Anda memiliki file .env di ~/adk_tutorial/.env yang berisi kunci AIza..., dan perintah terminal Anda menampilkan (.adk_env). Anda siap membangun agen.

3. Sesi 1: Agen Pertama Anda di Web ADK

Buka Web ADK dengan Menjalankan:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Setelah menjalankan perintah, Anda akan melihat output di terminal yang menunjukkan bahwa Server Web ADK telah dimulai, mirip dengan ini:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Selanjutnya, buka browser Anda ke http://localhost:8000 untuk mengakses UI Dev ADK.

Menjalankan di Cloud Shell, bukan secara lokal? Klik ikon Pratinjau web di toolbar Cloud Shell (biasanya kanan atas), pilih Ubah port, tetapkan port ke 8000, lalu klik "Ubah dan Pratinjau". Cloud Shell akan membuka UI Dev ADK di tab browser baru.

👉 Ritual pemanggilan Anda telah selesai, dan agen kini berjalan. UI Dev ADK di browser Anda adalah koneksi langsung ke Familiar.

Pilih agen pertama Anda Di menu dropdown di bagian atas UI, pilih a_single_agent.

Anda dapat memilih a_single_agent di sini:

Anda dapat melihat pelacakan di sini:

👉 Perintah Pengujian:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Sesi 2: Agen Alur Kerja: Agen Berurutan, Agen Paralel, Agen Loop

Buka UI Web ADK Anda dengan mengikuti langkah-langkah sesi 1.

Agen Paralel

Pilih agen alur kerja paralel Di menu dropdown di bagian atas UI, pilih b2_parallel_agent.

👉 Perintah Pengujian:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Anda dapat memilih b2_parallel_agent di sini:

Anda dapat melihat pelacakan di sini:

Agen Berurutan

Pilih agen alur kerja berurutan Di menu dropdown di bagian atas UI, pilih b1_sequential_agent.

👉 Perintah Pengujian:

Find a good sushi near Standford and tell me how to get there.

Anda dapat memilih b1_sequential_agent di sini:

Anda dapat melihat pelacakan di sini:

Agen Loop

Pilih agen alur kerja loop Di menu dropdown di bagian atas UI, pilih b3_loop_agent.

👉 Perintah Pengujian:

Plan a trip from Sunnyvale to San Francisco today.

Anda dapat memilih b3_loop_agent di sini:

Anda dapat melihat pelacakan di sini:

5. Sesi 3: Agen Kustom

Buka UI Web ADK Anda dengan mengikuti langkah-langkah sesi 1.

Setelah UI Web ADK Anda terbuka, pilih c_custom_agent dari dropdown.

👉 Perintah Pengujian:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Anda dapat memilih c_custom_agent di sini:

Anda dapat melihat pelacakan di sini:

6. Sesi 4: Pola Orkestrator - Agen Perutean

Buka UI Web ADK Anda dengan mengikuti langkah-langkah sesi 1.

Setelah UI Web ADK Anda terbuka, pilih d_routing_agent dari dropdown.

👉 Perintah Pengujian:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Anda dapat memilih d_routing_agent di sini:

Anda dapat melihat pelacakan di sini:

7. Sesi 5: Agen sebagai alat

Buka UI Web ADK Anda dengan mengikuti langkah-langkah sesi 1.

Setelah UI Web ADK Anda terbuka, pilih e_agent_as_tool dari dropdown.

👉 Perintah Pengujian:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Anda dapat memilih e_agent_as_tool di sini:

Anda dapat melihat pelacakan di sini:

8. Sesi 6: Agen Dengan Memori Jangka Panjang

Berjalan sepenuhnya secara lokal. Sesi ini menyimpan memori percakapan dalam database SQLite lokal (di bagian ~/.adk/), sehingga preferensi Anda tetap ada di seluruh proses memulai ulang tanpa memerlukan Google Cloud, penagihan, atau kredit. Agen membaca kunci AI Studio Anda dari ~/adk_tutorial/.env yang Anda buat di Penyiapan.

👉💻 Uji memori jangka panjang Anda dengan membuka folder dan menggunakan runner untuk mengaktifkan agen:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Perintah Pengujian:

I like Art and Italian food.

Kemudian, akhiri sesi dengan menekan Ctrl+C. Mulai ulang sesi:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Perintah Pengujian:

Plan a trip to San Francisco based on my preference.

✅ Agen harus mengingat "Seni dan makanan Italia" dari sesi sebelumnya — itulah memori jangka panjang yang berfungsi di seluruh sesi.

9. Sesi 7: Memberdayakan agen Anda dengan MCP

Berjalan sepenuhnya secara lokal. Sesi ini memulai server MCP Toolbox lokal yang membaca database SQLite lokal (destinations.db) — tidak memerlukan Google Cloud, penagihan, atau kredit. Satu-satunya download eksternal adalah biner MCP Toolbox open source.

Langkah 1: Menyiapkan Database Lokal

👉💻 Dari root repo, buat database contoh:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Tindakan ini akan membuat destinations.db di ~/adk_tutorial/.

⚠️ Database contoh hanya berisi empat kota — Paris, Roma, New York, dan Tokyo (jenis atraksi: Landmark, Museum, Taman). Perintah yang merujuk ke kota lain (misalnya San Francisco atau Sunnyvale) akan menampilkan tidak ada hasil dengan benar, karena baris tersebut tidak ada. Gunakan empat kota di atas saat menguji sesi ini.

Langkah 2: Menginstal dan Menjalankan Server MCP Toolbox

👉💻 Download biner MCP Toolbox untuk sistem operasi Anda:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

setelah selesai mendownload, lalu jalankan

chmod +x toolbox

Tidak yakin Mac mana yang Anda miliki? Jalankan uname -m — arm64 = Apple Silicon, x86_64 = Intel. Di Windows, download .../windows/amd64/toolbox.exe dan jalankan dari PowerShell.

Langkah 3

Di satu terminal Jalankan perintah berikut (biarkan berjalan — agen terhubung ke perintah tersebut di http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

Di terminal lain Jalankan perintah berikut

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Perintah Pengujian (gunakan kota yang ada di database contoh — Paris, Roma, New York, atau Tokyo):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Pemecahan masalah sesi 7

• "Koneksi ditolak" / agen tidak menemukan alat: server Toolbox di terminal pertama tidak berjalan — mulai ulang dan pastikan server tersebut mendengarkan di port 7001.
• Setiap kueri menampilkan hasil kosong: pastikan Anda menjalankan Langkah 1 sehingga ~/adk_tutorial/destinations.db ada, dan perintah Anda menggunakan salah satu dari empat kota (Paris, Roma, New York, Tokyo).
• toolbox: cannot execute binary file di macOS: Anda mendownload build Linux — jalankan kembali Langkah 2 dengan OS=darwin/arm64 (Apple Silicon) atau OS=darwin/amd64 (Intel).