ADK: Dari Dasar-Dasar hingga Agen Multi-Alat

1. Pengantar

Mulai dari dasar-dasar dan berlanjut ke pengembangan agen multialat, codelab ini memberikan pengantar komprehensif untuk membangun agen dengan ADK.

Secara sederhana, Agen AI adalah sistem software yang menggunakan Model Bahasa Besar (LLM) sebagai "mesin penalaran" untuk mencapai sasaran dengan melakukan serangkaian tugas secara mandiri.

Jika LLM adalah konsultan yang sangat kompeten yang dapat memberi Anda saran, Agen AI adalah engineer proaktif yang dapat menggunakan alat untuk menjalankan saran tersebut.

LLM vs. Agen

Otak (LLM): Menyediakan penalaran, perencanaan, dan natural language understanding. Ia memutuskan apa yang perlu dilakukan.

Tangan (Alat): Ini adalah API, SDK, dan fungsi kustom yang memungkinkan agen berinteraksi dengan dunia nyata. Lakukan rencana tersebut.

Agent Development Kit (ADK)

Agent Development Kit (ADK) adalah framework khusus yang dirancang untuk menyederhanakan pembuatan, deployment, dan orkestrasi agen AI. Vertex AI Agent menyediakan blok penyusun standar yang diperlukan untuk mengubah Model Bahasa Besar statis menjadi agen dinamis yang mampu mengeksekusi kode, memanggil API, dan mengelola alur kerja multi-langkah.

Agen Multi-alat adalah pengelola yang dapat memilih dan mengurutkan berbagai fungsi khusus—seperti mesin telusur, database, dan kalkulator—untuk memecahkan masalah yang kompleks. Orkestrasi secara cerdas menentukan alat yang akan digunakan untuk setiap langkah dan dapat meneruskan output satu tindakan sebagai input untuk tindakan berikutnya guna mencapai tujuan akhir.

Yang akan Anda build

Dalam codelab ini, Anda akan membangun Agen "Healthy Hints", konsultan nutrisi cerdas yang bertransisi dari penalaran teks sederhana ke alat serbaguna yang canggih. Anda akan memulai dengan membuat agen percakapan dasar yang memahami konsep nutrisi, lalu secara progresif melengkapinya dengan alat Storage SDK untuk mengarsipkan gambar bahan makanan dan alat Vision untuk "membaca" dan menganalisis gambar tersebut. Di akhir lab ini, Anda akan memiliki orkestrator yang berfungsi penuh yang dapat mengambil foto label makanan yang diupload, menyimpannya di bucket cloud untuk pencatatan, dan langsung memberikan "Petunjuk Sehat" untuk setiap bahan.

2. Prasyarat

Project Google Cloud dengan Penagihan diaktifkan
Browser web

Buat project Anda

Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
Pastikan penagihan diaktifkan di project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mengaktifkan Cloud Shell

Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Konsol Google Cloud yang telah dilengkapi dengan bahasa yang diperlukan. Dari Cloud Console, klik Activate Cloud Shell di pojok kanan atas:

Setelah terhubung ke Cloud Shell, Anda akan melihat bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa Anda telah diautentikasi:

gcloud auth list

Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda:

gcloud config list project

Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:

gcloud config set project <YOUR_PROJECT_ID>

Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.

Buka Editor

Untuk codelab ini, kita akan menggunakan editor Cloud bawaan. Di jendela Cloud Shell, klik tombol Open editor di pojok kanan atas. Tindakan ini akan membuka Editor VSCode untuk Anda.

3. Penyiapan ADK

Mari beralih ke Terminal Cloud Shell yang kita aktifkan di bagian sebelumnya:

Buat & Aktifkan Lingkungan Virtual (Direkomendasikan)

Dari Terminal Cloud Shell, buat Lingkungan Virtual:

python -m venv .venv

Aktifkan Lingkungan Virtual:

source .venv/bin/activate

Menginstal ADK

pip install google-adk

4. Kunci Google API

Buat kunci API Google menggunakan AI Studio:

Buka https://aistudio.google.com/ dan dari menu kiri bawah, klik Get API Key

Anda akan melihat jendela Kunci API, klik Buat kunci API di jendela ini:

Anda akan melihat pop-up untuk membuat kunci baru. Beri nama kunci sebagai: healthy-hints-key

Buka dropdown "Pilih project yang diimpor"

Klik Import Project, akan ada jendela samping yang mencantumkan semua project Google Cloud Anda. Pilih project yang ingin Anda kerjakan.

Klik Impor

Dropdown sekarang akan diperbarui dengan project yang baru saja Anda impor. Pilih project dari menu dropdown. Klik Buat Kunci sekarang. Anda akan melihat daftar kunci API yang dibuat. Klik ikon salin kunci API yang baru saja Anda buat.

5. Agen Contoh

Dari Cloud Shell Terminal, buat direktori root untuk agen Anda di lokasi project yang diinginkan:

adk create healthy_hints

Anda dapat memilih model apa pun, tetapi untuk codelab ini, kita akan menggunakan gemini-2.5-flash

Untuk codelab ini, kita akan menggunakan Google AI. Tempelkan kunci API yang Anda buat di langkah sebelumnya.

Mari kita buka folder yang baru saja kita buat. Di menu paling kiri, klik ikon , klik File -> Open Folder. Pilih folder healthy_hints yang baru saja dibuat, yang biasanya berada di folder /home/<username>.
Struktur folder healthy_hints biasanya akan terlihat seperti ini:

Anda akan melihat file .env yang memiliki kunci Google API Anda. Anda dapat menggunakan file ini untuk menetapkan variabel lingkungan apa pun.
File lain bernama agent.py juga dibuat dan itu adalah file agen utama kita. Di sinilah agen root contoh dibuat. Mari kita lihat konten file ini dengan cermat. Pertama, kita mengimpor llm_agent dari ADK. Kemudian, kita menggunakan DSL ADK untuk membuat agen root. Kita menentukan nama model sebagai Gemini-2.5-flash, memberi nama agen, dan memberikan deskripsi yang bagus untuknya. Petunjuk adalah hal terpenting di sini. Di sinilah kita memberi tahu agen apa yang perlu dilakukan dalam bahasa alami.
Agen contoh ini cukup umum, hanya akan menjawab pertanyaan apa pun yang diajukan pengguna.
Sekarang, jalankan agen ini secara lokal. Ada dua cara untuk berinteraksi dengan agen ini : CLI dan Web.
CLI: Jalankan perintah berikut dari luar direktori healthy_hints

adk run healthy_hints

Atau, jika Anda berada di dalam direktori healthy_hints, jalankan perintah berikut:

adk run .

Anda akan melihat output yang serupa:

Silakan tulis "hai" atau pertanyaan apa pun yang Anda miliki. Jawaban dapat berbeda untuk setiap orang, itulah sifat GenAI.

Web: Jalankan perintah berikut dari direktori induk healthy_hints :

adk web

6. Agen Multi-alat

Alat adalah bagian kode modular—biasanya fungsi atau API—yang memungkinkan agen berinteraksi dengan dunia di luar pengetahuan internalnya.

Jenis Alat di ADK

Alat Fungsi: Logika kustom yang Anda tulis sendiri. Misalnya, fungsi yang terhubung ke database spesifik Anda atau "Parser Log" kustom untuk format unik perusahaan Anda.
Alat Bawaan: Kemampuan siap pakai yang disediakan oleh Google atau ADK, seperti Google Penelusuran, Penafsir Kode, atau Mesin RAG Google.
Agents-as-Tools: Dalam sistem "Multi-alat" atau "Multi-agen" tingkat lanjut, satu agen khusus dapat bertindak sebagai alat untuk agen lain. Misalnya, "Agen Penelusuran" dapat menjadi alat yang digunakan oleh "Agen Pengelola Riset".

Dalam codelab ini, kita akan membahas Alat Fungsi. Sekarang, mari kita tingkatkan kemampuan agen kita dan menjadikannya multi-alat.

Mari tambahkan metode get_weather baru di agent.py

def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city for which to retrieve the weather report.

  Returns:
    dict: status and result or error msg.
  """
  if city.lower() == "new york":
    return {
      "status": "success",
      "report": (
          "The weather in New York is sunny with a temperature of 25 degrees"
          " Celsius (77 degrees Fahrenheit)."
      ),
    }
  else:
    return {
      "status": "error",
      "error_message": f"Weather information for '{city}' is not available.",
    }

Mari kita ubah agent.py dan ganti nama, deskripsi, serta petunjuk agen:

root_agent = Agent(
    model='gemini-2.5-flash',
    name='healthy_hints_agent',
    description='Agent to answer questions about the weather in a city.',
    instruction='You are a helpful agent who can answer user questions about the weather in a city.',
    tools=[get_weather],
)

Sejauh ini, kita hanya membuat satu alat. Sekarang, mari kita buat beberapa alat:

Mari buat metode lain bernama get_current_time :

def get_current_time(city: str) -> dict:
  """Returns the current time in a specified city.

  Args:
    city (str): The name of the city for which to retrieve the current time.

  Returns:
    dict: status and result or error msg.
  """

  if city.lower() == "new york":
    tz_identifier = "America/New_York"
  else:
    return {
      "status": "error",
      "error_message": (
        f"Sorry, I don't have timezone information for {city}."
      ),
    }

  tz = ZoneInfo(tz_identifier)
  now = datetime.datetime.now(tz)
  report = (
    f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
  )
  return {"status": "success", "report": report}

Mari kita ubah agen untuk memanggil alat ini juga:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to answer questions about the time and weather in a city.',
  instruction='You are a helpful agent who can answer user questions about the time and weather in a city.',
  tools=[get_weather, get_current_time],
)

Kami telah mengubah deskripsi, petunjuk, dan alat yang sesuai. Sekarang, mari kita jalankan agen yang telah diperbarui ini. Kali ini, agen akan merespons dengan waktu dan cuaca saat ini juga.

7. Integrasi SDK

Sekarang kita tahu cara menggunakan beberapa alat. Mari kita lihat beberapa contoh nyata. Mari kita buat agen saran sehat. Tujuan kita di sini adalah mengupload gambar apa pun yang memiliki daftar bahan, ke agen kita dan agen akan memberi tahu kita tentang setiap bahan yang sehat atau tidak.

Mari buat bucket terlebih dahulu, untuk mengupload gambar, di Google Cloud Storage. Buka tab baru dan buka https://console.cloud.google.com/, lalu di kotak penelusuran, ketik cloud storage. Sekarang, pilih Cloud Storage di bagian Produk & halaman:

Anda akan diarahkan ke halaman ringkasan Google Cloud Storage. Klik tombol Create bucket. Di halaman buat bucket, masukkan nama bucket. Nama dapat berupa apa saja, tetapi untuk codelab ini, kita akan memasukkannya sebagai healthy-hints-bucket-kolkata . Biarkan semuanya seperti apa adanya, lalu klik tombol Create.

Mari buat file baru bernama requirements.txt dan tambahkan google-cloud-storage di dalamnya. Kita akan menggunakan Python Storage SDK untuk mengupload gambar di Storage.

Pertama, instal dependensi:

pip install -r requirements.txt

Anda mungkin perlu mengaktifkan Storage API terlebih dahulu. Jalankan perintah berikut di terminal Anda untuk melakukannya:

gcloud services enable storage.googleapis.com

Sekarang, mari kita tambahkan alat baru untuk mengupload gambar.

def upload_image() -> str:
  storage_client = storage.Client()
  bucket_name = "healthy-hints-bucket-kolkata"
  bucket = storage_client.bucket(bucket_name)
  blob = bucket.blob("ingredirents")
  blob.upload_from_filename(<image-file-path>)

Sekarang, mari kita perbarui agen agar menggunakan alat baru:

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool.',
  tools=[upload_image],
)

Sekarang kita akan menambahkan alat lain untuk membacakan bahan-bahan yang ada di gambar. Mari tambahkan google-cloud-vision di requirements.txt dan instal dependensi baru.

pip install -r requirements.txt

Sekali lagi, Anda mungkin perlu mengaktifkan Vision API terlebih dahulu. Jalankan perintah berikut di terminal Anda untuk melakukannya:

gcloud services enable vision.googleapis.com

Sekarang mari kita tambahkan alat baru read_ingredients :

def read_ingredients() -> str:
  vision_client = vision.ImageAnnotatorClient()

  with io.open("/home/bajajnehaa/healthy_hints/images/Ingredients-list.jpg", 'rb') as image_file:
    content = image_file.read()

  image = vision.Image(content=content)
  response = vision_client.text_detection(image=image)
  texts = response.text_annotations
  return texts[0].description

Sekarang, mari kita perbarui agen untuk menggunakan alat ini

root_agent = Agent(
  model='gemini-2.5-flash',
  name='healthy_hints_agent',
  description='Agent to upload image to Google Cloud Storage, read the list of ingredients from the image and explain if the ingredient is healthy or not',
  instruction='You are a helpful agent who will upload the image to Google Cloud Storage using `upload_image` tool, read the ingredients of the image using `read_ingredients` tool and explain if the ingredient is healthy or not in one line.',
  tools=[upload_image, read_ingredients],
)

8. Kesimpulan

Selamat, Anda telah menyelesaikan codelab Healthy Hints. Anda telah berhasil mengubah AI standar dari generator teks menjadi Agen Multi-alat yang proaktif. Dengan menggunakan ADK untuk mengintegrasikan Vision API dan Cloud Storage SDK, Anda telah memberi agen "mata" untuk membaca label dan "memori" untuk mengarsipkan label tersebut. Anda telah melihat bagaimana agen secara mandiri memutuskan kapan harus menyimpan file dan cara menafsirkan data mentah untuk memberikan saran kesehatan di dunia nyata.

Ke depannya, prinsip-prinsip ini akan berfungsi sebagai cetak biru untuk sistem otomatis apa pun. Baik Anda mengelola infrastruktur cloud maupun membangun asisten pribadi, intinya tetap sama: tentukan alat khusus dan biarkan agen mengatur logikanya. Sebagai langkah berikutnya, coba tambahkan lebih banyak alat seperti "Database Nutrisi" atau "Alat Email" untuk memperluas dampak agen Anda.