1. Pengantar

Terakhir Diperbarui: 22-06-2026
Membangun Agen Perjalanan Sederhana dengan ADK
Selamat datang di workshop Python(*) ADK ini, yang dilengkapi dengan semua yang Anda butuhkan, berkat Gemini CLI.
Codelab ini dibagi menjadi dua 🏅 pencapaian:
- Alur pembelajaran yang umum dan sederhana: penyiapan + kepuasan instan.
- Jalur yang dipersonalisasi tempat Anda memilih quest untuk diselesaikan dengan bantuan Gemini CLI
Bagian kedua membuat codelab ini cocok untuk hackathon (dan hadiah untuk solusi paling kreatif!)
Milestone 1: Agen pertama Anda dengan ADK dan Gemini CLI
Tujuan pencapaian ini adalah membangun agen perjalanan sederhana dengan ADK langkah demi langkah. Untuk melakukannya, pertama-tama kita perlu menyiapkan Gemini CLI agar dapat membantu kita membuat kode dengan ADK. Dengan begitu, shell lokal Anda dapat memilih Python ADK versi terbaru, memahami kode dan dokumennya, serta memberikan kode terbaru/terbaik untuk digunakan sesuai tujuan Anda.
Ini adalah bagian yang dipandu secara manual, tempat kita membuat aplikasi yang berfungsi penuh melalui penambahan kecil dan sederhana. Proses ini biasanya memerlukan waktu sekitar satu jam (ditambah waktu penginstalan).
Tonggak Pencapaian 2: Memperluas agen Anda
Setelah itu, kami akan memberikan selusin opsi (dengan berbagai tingkat kesulitan) untuk memperluas aplikasi sesuai keinginan Anda. Hal ini memungkinkan Anda menjelajahi berbagai aspek (UI, Operasi, Interaksi agen yang kompleks, ..)
Yang akan Anda build
Dalam codelab ini, Anda akan membangun aplikasi Agen Perjalanan menggunakan ADK dan Gemini CLI. Aplikasi Anda akan:
- Menghubungkan ke API Airbnb melalui MCP Airbnb.
- Menelusuri informasi terbaru secara online (cuaca, tanggal, ..)
- Menjalankan alat kustom.
- Buat gambar apartemen/kamar menggunakan NanoBanana.
Gemini CLI akan memandu Anda melakukan semua ini: menulis/meninjau kode dan menemukan dokumentasi terbaru di mirror lokal repositori ADK (dalam Python, atau bahasa favorit Anda).
Yang akan Anda pelajari
- Cara membuat dan men-deploy aplikasi dengan ADK
- Cara menggunakan Gemini CLI untuk membuat kode aplikasi berdasarkan dokumen lokal.
- Cara berinteraksi dengan server MCP untuk terhubung ke sumber data eksternal real-time, seperti ini:
Yang Anda butuhkan
- Komputer yang memungkinkan Anda menginstal paket (misalnya,
npm install ..) - Kemampuan coding dasar dalam Python, TypeScript, Go, atau Java.
- IDE semacam (Antigravity, vscode, IntelliJ, vim) sangat dianjurkan.
Mengapa ADK + Gemini CLI?
Beberapa dari Anda mungkin bertanya-tanya: Mengapa saya perlu menggunakan ADK (SDK pembuat agen) bersama dengan asisten kode agentic lokal (seperti Gemini CLI)? Alasannya adalah kedua alat ini sangat canggih, tetapi interaksinya tidak mudah; banyak orang telah mencoba menggunakan keduanya secara bersamaan dan gagal (sebagian besar karena masalah "loop dalam loop"). Codelab ini mencoba membagikan beberapa tips tentang cara memungkinkan koeksistensi ini.
2. Mempersiapkan
Pilih salah satu opsi berikut: Penyiapan lingkungan mandiri jika Anda ingin menjalankan codelab ini di komputer Anda sendiri, atau; Mulai Cloud Shell jika Anda ingin menjalankan codelab ini sepenuhnya di cloud.
Penyiapan lingkungan mandiri
- Login ke Konsol Google Cloud dan buat project baru atau gunakan kembali project yang sudah ada. Jika belum memiliki akun Gmail atau Google Workspace, Anda harus membuatnya.



- Project name adalah nama tampilan untuk peserta project ini. String ini adalah string karakter yang tidak digunakan oleh Google API. Anda dapat memperbaruinya kapan saja.
- Project ID bersifat unik di semua project Google Cloud dan tidak dapat diubah (tidak dapat diubah setelah ditetapkan). Konsol Cloud otomatis membuat string unik; biasanya Anda tidak mementingkan kata-katanya. Di sebagian besar codelab, Anda harus merujuk Project ID-nya (umumnya diidentifikasi sebagai
PROJECT_ID). Jika tidak suka dengan ID yang dibuat, Anda dapat membuat ID acak lainnya. Atau, Anda dapat mencobanya sendiri, dan lihat apakah ID tersebut tersedia. ID tidak dapat diubah setelah langkah ini dan tersedia selama durasi project. - Sebagai informasi, ada nilai ketiga, Project Number, yang digunakan oleh beberapa API. Pelajari lebih lanjut ketiga nilai ini di dokumentasi.
- Selanjutnya, Anda harus mengaktifkan penagihan di Konsol Cloud untuk menggunakan resource/API Cloud. Menjalankan operasi dalam codelab ini tidak akan memakan banyak biaya, bahkan mungkin tidak sama sekali. Guna mematikan resource agar tidak menimbulkan penagihan di luar tutorial ini, Anda dapat menghapus resource yang dibuat atau menghapus project-nya. Pengguna baru Google Cloud memenuhi syarat untuk mengikuti program Uji Coba Gratis senilai $300 USD.
Mulai Cloud Shell
Meskipun Google Cloud dapat dioperasikan dari jarak jauh menggunakan laptop Anda, dalam codelab ini, Anda akan menggunakan Google Cloud Shell, lingkungan command line yang berjalan di Cloud.
Dari Konsol Google Cloud, klik ikon Cloud Shell di toolbar kanan atas:

Hanya perlu waktu beberapa saat untuk penyediaan dan terhubung ke lingkungan. Jika sudah selesai, Anda akan melihat tampilan seperti ini:

Mesin virtual ini berisi semua alat pengembangan yang Anda perlukan. Layanan ini menawarkan direktori beranda tetap sebesar 5 GB dan beroperasi di Google Cloud, sehingga sangat meningkatkan performa dan autentikasi jaringan. Semua pekerjaan Anda dalam codelab ini dapat dilakukan di browser. Anda tidak perlu menginstal apa pun.
3. Prasyarat (Penginstalan)
Untuk tutorial ini, Anda perlu menginstal:
1. Python dan uv
python dan uv (pengelola paket untuk Python). Hal ini diperlukan untuk ADK. Pastikan Anda telah menginstal uv:
$ curl -LsSf https://astral.sh/uv/install.sh | sh
Mengapa uv? Meskipun Anda dapat menggunakan pengelola Python mana pun yang Anda inginkan, penggunaan uv akan memastikan penyiapan ENV/PATH untuk Python akan sama bagi Anda dan Gemini CLI, sehingga pengalaman shell Anda akan sebagian besar sama dengan Gemini CLI. Misalnya, jika Anda menggunakan virtualenv, Gemini CLI akan dipaksa untuk melakukan hal-hal seperti "source .env/venv/bin/activate && my-original-command" untuk meniru lingkungan Anda.
2. Gemini CLI
Untuk gemini CLI, temukan petunjuk penginstalan di sini: https://github.com/google-gemini/gemini-cli .
# Note: This requires having npm or npx installed. npm install -g @google/gemini-cli
- Di Mac, Anda dapat menggunakan
brewsesuai dengan dokumen resmi. - Di Windows, Anda dapat menggunakan
chocolateyatau cukup mendownload file yang dapat dieksekusi dari https://nodejs.org/en/download
Untuk langkah 4 (nanti), Anda juga harus menginstal npx. npm dan npx akan muncul secara alami sebagai bagian dari Gemini CLI. Jika belum, minta bantuan Gemini CLI di sini.

Authentication
Anda memerlukan Project Google Cloud dengan Vertex AI yang diaktifkan, atau Kunci API Google AI Studio.
Opsi A (Direkomendasikan untuk Workshop): Ekspor Kunci API Anda:
export GOOGLE_API_KEY="your-api-key"
Opsi B (Vertex AI): Lakukan autentikasi dengan gcloud:
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" export GOOGLE_GENAI_USE_VERTEXAI=true gcloud auth application-default login
Menyiapkan lingkungan kerja Anda
Anda akan membuat solusi SENDIRI di bagian mysolution/, jadi mari kita buat folder dan dua file yang kita perlukan.
Sekarang, Anda dapat membuka IDE (Visual Studio Code, IntelliJ, RubyMine, ..) dan membuka folder.
# 1. Find an empty directory, and download this repo. git clone https://github.com/palladius/adk-gemini-cli-workshop cd adk-gemini-cli-workshop/ # 2. Create your solution empty skeleton mkdir -p mysolution/ touch mysolution/__init__.py mysolution/agent.py # 3. This installs ADK and MCP via `uv` by reading pyproject.toml uv init uv sync # 4. Call Gemini CLI gemini # This runs Gemini CLI under the adk-gemini-cli-workshop/ folder. # Login with your GMail account.
uv sync tidak mutlak diperlukan, tetapi jika gagal, Anda tahu bahwa Anda perlu memperbaiki penginstalan Python atau uv. Tindakan ini akan menginstal adk dan skrip berguna lainnya ke dalam folder ./.venv/bin/.
Untuk menguji penyiapan, Anda cukup menjalankan make test-step1 dan memastikan bahwa Anda tidak mendapatkan 403 PERMISSION DENIED.
Solusi yang tersedia
Semua kode terdapat di 📂 steps/. Anda dapat menyalin kode dari sana.
Codelab ini tidak membahas cara menulis kode ADK yang baik, melainkan cara menyiapkan lingkungan Anda agar kode yang BAIK ditulis secara otomatis sesuai arahan Anda.
- Menginstal perangkat lunak
- mengonfigurasi/membuatnya berfungsi, dan
- memasuki Feedback Loop yang benar
Inilah yang benar-benar ingin kami sampaikan kepada Anda di sini. Anda juga dapat menguji semuanya sekaligus melalui $ make web-4steps.
4. Langkah 1: Agen Dasar

Mari kita mulai dengan membuat agen dasar yang dapat melakukan percakapan.
Edit file bernama mysolution/__init__.py dengan menambahkan konten berikut:
from .agent import root_agent
Semudah itu. Dengan begitu, ADK dapat mengetahui lokasi kode Anda: di agent.py.
Edit file bernama mysolution/agent.py dengan menambahkan konten berikut:
from google.adk.agents import Agent
root_agent = Agent(
name="travel_basic",
model="gemini-2.5-flash",
instruction="You are a helpful travel assistant." +
"You can help with general travel advice based on your knowledge.",
)
Menguji agen
Hal ini berlaku untuk semua langkah. ADK memungkinkan Anda menguji agen dengan dua cara: CLI dan Web.
- CLI paling cocok untuk pengujian cepat dan otomatis
- Web adalah yang terbaik untuk melihat secara visual apa yang terjadi, menggunakan mikrofon (!), dan memecahkan masalah.
Tips: untuk tujuan latihan ini, agar dapat menyelesaikan apa pun (kecuali pengujian unit), gunakan Web. Luar biasa! Gunakan CLI hanya untuk pengujian otomatis.
Perintah yang baik dan menguji langkah 1-2-3-4 dengan benar dapat berupa perintah berikut (perintah "lakmus" yang cerdas):
Halo, saya ingin memesan hotel di Paris untuk besok malam, sendirian, satu malam, di pusat kota Paris. Idealnya dekat dengan Gare de Lyon. Anggaran: di bawah 200eur per malam.
- Beri tahu saya YYYYMMDD dan Hari dalam Seminggu untuk besok.
- Beri tahu saya hotel mana yang Anda lihat untuk besok (minimal 3). I want to see: > price, address, some rating (in form of XX/YY, eg "4.7/5" - from Google Hotels, Booking or Airbnb), # reviews. Berikan dalam format TABEL. Idealnya, nama hotel harus ditautkan ke semacam URL hotel (jangan repot-repot menambahkan kolom URL). Pastikan link tersebut sah (berfungsi dan halaman mengarah ke info tentang hotel).
Ini adalah perintah cerdas karena menguji waktu dan hotel, serta akan gagal secara berbeda di langkah 1, 2, 3, dan hanya akan berhasil sepenuhnya di langkah 4. Tentu saja, Anda dapat menggunakan perintah apa pun yang Anda inginkan.
Jalankan dari bash (CLI):
# 1. If ADK was installed: adk run mysolution/ # ... but if you get: -bash: adk: command not found" # 2. Call ADK cli script through UV to avoid python install nightmares. uv run adk run mysolution/
Coba gunakan "perintah litmus" di atas.
Gemini mungkin gagal mengetahui tanggal tertentu. Kita perlu mengajarinya untuk mengetahui tanggal.
Untuk web, Anda dapat melakukan hal ini:
uv run adk web .: Tindakan ini akan menjalankan semua agen di folder ini. Anda ingin mengarahkannya ke subfolder "mysolution/"- pilih
mysolution/di kanan atas (Lihat gambar di samping) - Ajukan pertanyaan Anda dalam teks atau melalui mikrofon, yang mirip dengan "perintah lakmus".

Perhatikan bahwa Anda perlu memanggil adk web dari folder atas, sesuai dengan versi CLI.

Berikut adalah kemungkinan solusinya, dengan semi-halusinasi tanggal. Perhatikan bahwa 3 dari 5 link pemesanan berfungsi. Lumayan.
5. Langkah 2: Tambahkan alat now()

Tambahkan fungsi ini ke agent.py tepat sebelum definisi root_agent:
from datetime import datetime
def now() -> dict:
"""Returns the current date and time."""
my_datetime = ... # Ask Gemini CLI to help you!
return {
"status": "success",
"current_time": my_datetime
}
Perbarui definisi agen untuk menyertakan alat:
# file XXX.py
root_agent = Agent(
name="..",
model="..",
instruction="..",
tools=[now] # <== This is the only line you want to add.
)
Jalankan lagi dan ajukan pertanyaan yang sama. Sekarang, agen akan mengetahui tanggal (baik), dan tidak jelas tentang hotel (buruk).
Anda juga dapat mengujinya dengan perintah seperti ini:
# Let's pretend we're in Milan. This should call the tool # and respond correctly (possibly with some TZ math issues) echo "What time is it in Milan?" | uv run adk run mysolution/
6. Langkah 3: Ayo mulai fokus: google_search
google_search. Hal ini memungkinkan agen kami mengakses informasi real-time dari web.

Tugas Anda adalah mengubah agen dari Langkah 2. Alih-alih menggunakan alat now, Anda akan mengimpor dan menggunakan alat google_search dari library ADK.
# Full Code: `steps/step03_search/agent.py`
# Remember to REMOVE the now() tool here. See above why.
from google.adk.agents import Agent
from google.adk.tools import google_search
root_agent = Agent(
name="travel_agent",
model="gemini-2.5-flash",
tools=[google_search],
instruction="""You are a travel agent.
Your job is to help the user plan a trip.
You have access to a search engine.
If you don't know the answer, you can use the search engine.
When you are done, reply with "DONE".""",
)
Cara Menjalankan
Sama seperti langkah 1.
Khusus pakar. Untuk integrasi yang lebih lanjut (menggunakan google_search dan now bersama-sama), periksa kode di steps/step03b_search_and_tool/agent.py dan jalankan dengan make run-step3b. Tindakan ini sepenuhnya bersifat opsional.
7. Langkah 4: Alat yang lebih canggih: MCP

Setelah kita melihat alat kustom dan bawaan, mari kita beralih ke sesuatu yang lebih canggih: pola Model-as-a-Tool menggunakan Model Context Protocol (MCP).
Agar langkah ini tetap berfokus pada kemampuan MCP yang canggih, kita akan sekali lagi mengganti alat sebelumnya (google_search). Kita akan memperkenalkan kembali alat now sederhana untuk dijalankan bersama alat airbnb_mcp. Hal ini menunjukkan cara agen dapat menggunakan beberapa alat yang kompatibel (dalam hal ini, FunctionTool dan MCPToolset) untuk melakukan tugas yang kompleks.
# Full Code: steps/step04_mcp/agent.py
# ... Imports as before
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters
def now() -> dict:
# ... as before
# Configure the Airbnb MCP Toolset
airbnb_mcp = MCPToolset(
connection_params=StdioConnectionParams(
server_params=StdioServerParameters(
command='npx',
args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
),
)
)
root_agent = Agent(
name="travel_mcp",
model="gemini-2.5-flash",
instruction="You are a helpful travel assistant. You can find accommodation using Airbnb, and have access to the current time.",
tools=[now, airbnb_mcp],
)
Cara Menjalankan
Langkah ini memerlukan penginstalan npx di sistem Anda. Untuk sisanya, ini sama seperti di atas.
Peringatan/Error
- Jika Anda mendapatkan error pembatasan
robots.txt, Anda dapat menerapkan patch pada MCP dengan perintah abaikan robots. Baca dokumentasi untuk mengetahui detail selengkapnya: https://github.com/openbnb-org/mcp-server-airbnb - Jika Anda mendapatkan error
timeout(5 detik terlalu singkat bagi Airbnb untuk mendapatkan respons), lihat dokumentasi ADK tentang cara meningkatkan waktu tunggu, misalnya, menjadi 30 detik. Atau.. gunakan Gemini CLI untuk melakukannya. Perhatikan bahwa pada 3dec25m, Cloud Shell memberikan error waktu tunggu, saya memperbaiki error waktu tunggu, dan masih mendapatkan error, hingga saya memaksanya ke versi sebelumnya:args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].
8. 🏅 Pencapaian 1 Selesai!
🏅 Selamat! 🏅 Anda sekarang menjadi pakar ADK! Anda telah menyelesaikan bagian pertama workshop dan berhasil membangun serta menguji agen AI dengan alat kustom, alat bawaan, dan alat MCP lanjutan. Sekarang Anda siap membangun agen Anda sendiri yang luar biasa dengan Agent Development Kit Google.
Anda kini memiliki agen perjalanan fungsional yang mengetahui waktu dan dapat menelusuri web. Tidak ada lagi batasan.
Sekarang saatnya menambahkan fungsi tambahan dengan "Gemini CLI".
9. 🏅 Milestone 2: melakukan vibe coding dengan ADK melalui Gemini CLI
Sekarang kita memasuki bagian workshop yang menarik.
- pastikan Anda telah
git commitkode di tempat yang aman. Anda dapat melakukan fork pada kode asli, atau membuat cabang: jangan khawatir, Gemini CLI sangat membantu Anda di sini. - Temukan 💡 ide untuk diterapkan. Anda dapat memeriksa ide di bawah, menemukan ide sendiri, atau meminta Gemini untuk melihat dokumentasi di rag/ dan mengusulkan beberapa ide cerdas.
- Ikuti prasyarat untuk memastikan Gemini dapat membaca dokumen ADK, lalu Anda siap menggunakannya.
💡 Ide
- 🟢 [mudah] Apakah Anda menguasai banyak bahasa? Apakah Anda ingin memberikan
goataujavaatauTypeScript? Merefaktorisasi kode yang ada sangatlah mudah. Pastikan untuk mendownload ADK yang tepat dan minta Gemini CLI untuk melakukan penerjemahan. - 🟢 [mudah] Tambahkan emoji atau tentukan beberapa format output yang Anda sukai (misalnya, tabel dengan emoji hotel, diikuti dengan harga, diikuti dengan emoji bintang 1-5 berdasarkan 🌕🌕🌕🌗🌑 untuk melakukan setengahnya juga!).
- 🟢 [mudah] Ubah perintah untuk mengajarinya hal-hal yang secara khusus Anda cari atau hindari (boleh membawa hewan peliharaan, tidak di lantai dasar, tenang, dekat dengan transportasi umum, ..) dan uji. Maybe add a personal rating like "a YOUR_NAME-rating from 1-10" based on the above, and sort by that rating.
- 🟢 [easy] Any Operator in the room? Deploy ke Cloud Run. Atau ke Vertex AI Agent Engine. Tahukah Anda bahwa Anda dapat mengintegrasikan agen ini dan memanggilnya langsung dari Gemini Enterprise baru?
- 🟢 [mudah] Integrasikan
adk rundengan 🍌 NanoBanana MCP. Memerlukan Kunci Gemini API. Di sini, Anda dapat membuat gambar, tetapi tidak dapat memvisualisasikannya. Lihat di bawah untuk varian yang lebih sulit. - 🟡 [sedang] Buat sub-agen yang melakukan
HotelSearchdan buatBudgetAgentatauLocationAgentyang dapat menggandakan dan melakukan iterasi pada hotel dengan mempertimbangkan kebutuhan lokasi Anda, misalnya "tidak lebih dari X km dari LOKASI". Jika API tidak mengizinkan hal ini, mungkin akan ada beberapa interaksi bolak-balik yang dibantu oleh GoogleSearch. Catatan: Gemini CLI dapat membantu Anda. - 🟡 [sedang] Terapkan
AirbnbReviewAgentyang akan memeriksa ulasan dan meringkas poin positif dan negatif dalam beberapa poin berkode warna, untuk 1 atau N hotel yang dihasilkan dari penelusuran. Anda sudah memiliki 2 komponen (GoogleSearch dan MCP Airbnb), lalu Anda perlu menghubungkannya ke Agen utama dan mungkin membuat semacam protokol agar keduanya dapat berkomunikasi. - 🟡 [sedang] Integrasikan dengan A2A. Jadikan agen A2A. Sekali lagi, minta bantuan Gemini CLI.
- 🔴 [complex] Anda dapat berintegrasi dengan Flights atau fungsi MCP lainnya untuk membuat agen perjalanan multifungsi yang beragam.
- 🔴 [kompleks] Integrasikan web ADK dengan 🍌 NanoBanana MCP. Tugas ini lebih sulit daripada tugas di atas, dan Anda dapat menemukan beberapa tips di https://github.com/palladius/ai-friendly-agents/issues/11 . Penulis memerlukan waktu 3 jam untuk berinteraksi dengan Gemini CLI, Gemini3, dan kami berdua membaca dokumen/kode dari
rag/.
Mencari inspirasi lebih lanjut?
- Lihat tutorial ADK resmi untuk mendapatkan beberapa ide.
- Minta Gemini CLI untuk menemukan ide dengan melihat dokumentasi di bagian
rag/: perintah yang mungkin adalah:Is there a feature in here which seems very succulent to you? Give me 3 proposals and let's implement together the one I choose.
Prasyarat untuk "RAG" ADK
Untuk melakukan vibe coding pada suatu fungsi, sebaiknya download seluruh ADK python ADK (catatan: ini dapat disesuaikan dengan sangat mudah ke bahasa favorit Anda, seperti Java atau Go!)
Kode berada di bagian ./rag dan dapat didownload dengan ./download-adk.sh.
Karena folder rag tercantum dalam file .gitignore, pastikan .gemini/settings.json Anda berisi hal berikut:
{
"context": {
"includeDirectories": ["rag"]
}
}
Mengapa demikian? Kita ingin Gemini dapat membaca file tersebut, sekaligus memastikan file tersebut diabaikan dengan aman oleh git. Secara teknis, Anda juga dapat memperlihatkan semua file .gitignore dengan menetapkan context.fileFiltering.respectGitIgnore ke false, tetapi tindakan ini akan membuka banyak sampah node_modules/ dan __pycache__/ - jadi penyertaan folder eksplisit adalah opsi yang lebih disukai.
10. Langkah berikutnya
Fakta menarik: Workshop ini dibuat dengan bantuan Gemini CLI. Jika Anda penasaran, Anda dapat menemukan cara saya melakukannya dengan melihat GEMINI.md dan WORKSHOP_PLAN.md di folder ini.
Pelajaran yang diperoleh
Kita telah mempelajari cara menyambungkan ADK dengan Gemini CLI
Bacaan tambahan
- Lihat dua codelab Antigravity resmi ini:
- Lihat tutorial ADK resmi untuk mendapatkan beberapa ide.
