Membangun Agen AI dengan ADK: Memberdayakan dengan Alat

1. Sebelum memulai

Selamat datang di bagian kedua seri "Membangun Agen AI dengan ADK". Dalam codelab praktis ini, Anda akan melengkapi agen AI dasar dengan berbagai alat.

Untuk memulai, panduan ini menyediakan dua jalur: satu untuk mereka yang melanjutkan dari codelab 'Membangun Agen AI dengan ADK: Dasar-Dasar', dan satu lagi untuk mereka yang memulai dari awal. Kedua jalur akan memastikan Anda memiliki kode agen dasar yang diperlukan untuk memulai.

Di akhir codelab ini, Anda akan melengkapi agen asisten pribadi Anda dengan alat untuk berbagai tujuan, satu langkah lebih dekat untuk dikembangkan di bagian selanjutnya dalam seri ini saat kita mengubahnya menjadi Sistem Multi-Agen (MAS) yang canggih.

Prasyarat

• Pemahaman tentang konsep AI Generatif
• Kemahiran dasar dalam pemrograman Python
• Menyelesaikan codelab Membangun Agen AI dengan ADK: Dasar-Dasar atau yang serupa

Yang akan Anda pelajari

• Berikan keterampilan baru kepada agen Anda dengan membuat fungsi Python kustom sebagai alat.
• Hubungkan agen Anda ke informasi real-time menggunakan alat bawaan seperti Google Penelusuran.
• Susun agen multi-alat dengan membuat sub-agen khusus untuk tugas yang kompleks.
• Mengintegrasikan alat dari framework AI populer seperti LangChain untuk memperluas kemampuan dengan cepat.

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

Agen dasar yang dibuat dengan ADK memiliki kemampuan LLM yang canggih, tetapi juga memiliki batasan: agen ini tidak dapat mengakses informasi yang dibuat setelah tanggal pelatihannya, dan tidak dapat berinteraksi dengan layanan eksternal. Model ini seperti asisten cerdas yang sangat pintar, tetapi terkunci di perpustakaan tanpa telepon atau internet. Agar agen benar-benar bermanfaat, kita perlu memberinya alat.

Anggap saja alat ini memberikan akses asisten AI ke dunia luar: kalkulator, browser web, atau akses ke database perusahaan tertentu. Di ADK, alat adalah bagian kode modular yang memungkinkan agen melakukan tindakan tertentu seperti mencari data real-time atau memanggil API eksternal. Penggunaan alat memperluas kemampuannya jauh melampaui percakapan sederhana.

ADK menawarkan tiga kategori alat:

1. Alat Fungsi: Alat kustom yang Anda kembangkan untuk memenuhi persyaratan unik aplikasi Anda, seperti fungsi dan agen yang telah ditentukan sebelumnya.
2. Alat Bawaan: Alat siap pakai yang disediakan oleh framework untuk operasi umum, seperti Google Penelusuran dan Eksekusi Kode.
3. Alat Pihak Ketiga: Library eksternal populer seperti Serper dan alat dari LangChain dan CrewAI.

Untuk mempelajari lebih lanjut cara menggunakan Alat dengan Agen ADK, lihat dokumentasi resmi. Dalam codelab ini, kita akan menambahkan alat untuk mengubah agen sederhana kita menjadi asisten perjalanan pribadi yang mumpuni. Mari kita mulai!

3. Mulai: Agen Dasar Anda

Sebelum dapat melengkapi agen dengan alat, Anda memerlukan agen dasar untuk digunakan. Pilih jalur yang paling sesuai dengan progres Anda.

Jalur A: Melanjutkan dari Codelab Dasar

Jika Anda baru saja menyelesaikan codelab " Membangun Agen AI dengan ADK: Dasar-Dasar", Anda sudah siap. Anda dapat terus bekerja di direktori project ai-agents-adk yang ada.

Jalur B: Memulai dari Awal

Jika Anda memulai codelab ini secara langsung, selesaikan 4 langkah ini untuk menyiapkan lingkungan dan membuat agen awal yang diperlukan.

1. Menyiapkan Layanan Google Cloud
2. Buat lingkungan virtual Python
3. Membuat agen
4. Menjalankan agen di UI Pengembangan

Setelah menyelesaikan langkah-langkah tersebut, Anda siap memulai perjalanan pembelajaran.

4. Membangun Alat Kustom untuk Pertukaran Mata Uang

Pada tahap ini, Anda seharusnya sudah tahu cara membangun agen AI sederhana menggunakan ADK dan menjalankannya di UI Pengembangan.

Bayangkan Anda sedang bersiap untuk melakukan perjalanan ke Jepang bulan depan dan perlu memeriksa nilai tukar mata uang saat ini. Tanyakan kepada agen "Berapa nilai tukar dari dolar Singapura ke yen Jepang?"

Anda akan melihat bahwa agen tidak dapat mengambil nilai tukar real-time. Hal ini karena saat ini agen tidak memiliki akses internet dan konektivitas sistem eksternal. Meskipun agen membalas dengan suatu nilai, sulit untuk memercayai nilai tersebut karena kemungkinan besar merupakan halusinasi.

Untuk mengatasi hal ini, kita akan menerapkan fungsi Python untuk mengambil nilai tukar melalui REST API dan mengintegrasikannya sebagai Alat Fungsi untuk agen.

Hentikan proses agen yang sedang berjalan menggunakan pintasan keyboard Ctrl + C (untuk Windows/Linux) atau Cmd + C (untuk macOS) di jendela terminal.

Buat file custom_functions.py**:**

Catatan: Sebelum melanjutkan, pastikan Anda berada di direktori yang benar (ai-agents-adk). Jalankan perintah pwd (print working directory) di terminal Anda untuk mengonfirmasi lokasi Anda saat ini.

Buat file Python bernama custom_functions.py di folder personal_assistant dengan mengetik perintah ini di terminal.

touch personal_assistant/custom_functions.py

Berikut tampilan struktur folder Anda:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    └── custom_functions.py

Buka custom_functions.py di Code Editor. File ini akan berisi fungsi Python yang bertanggung jawab untuk mengambil data nilai tukar dari API eksternal.

Salin dan tempel kode berikut di dalamnya:

import requests

# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
        """
        Fetches the current exchange rate between two currencies.

        Args:
                base: The base currency (e.g., "SGD").
                target: The target currency (e.g., "JPY").

        Returns:
                The exchange rate information as a json response,
                or None if the rate could not be fetched.
        """
        base_url = "https://hexarate.paikama.co/api/rates/latest"
        api_url = f"{base_url}/{base}?target={target}"

        response = requests.get(api_url)
        if response.status_code == 200:
                return response.json()

Catatan: Perhatikan baik-baik teks deskriptif dalam tiga tanda kutip ("""..."""). Ini disebut docstring. Meskipun merupakan praktik yang baik bagi developer manusia, hal ini sangat penting bagi Agen AI.

LLM yang mendasari agen membaca nama fungsi dan docstring ini untuk memahami fungsi alat, arti argumennya (base dan target dalam kasus ini), dan kapan alat tersebut harus digunakan.

Docstring yang jelas dan deskriptif adalah faktor terpenting bagi agen untuk menggunakan alat Anda dengan benar.

Sekarang, edit file agent.py: impor fungsi get_fx_rate dan tetapkan sebagai FunctionTool.

Perbarui file agent.py**:**

Salin blok kode ini dan ganti konten file agent.py yang ada:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool

from .custom_functions import get_fx_rate

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',
    tools=[FunctionTool(get_fx_rate)]
)

Catatan: Impor relatif diperlukan untuk mengimpor fungsi dari file Python lain karena ADK menjalankan folder agen sebagai modul Python. Pendekatan ini cocok untuk sekumpulan kecil alat, tetapi seiring berkembangnya alat, kita perlu membuat paket alat.

Setelah perubahan, mulai ulang agen dengan mengetik:

uv run adk web

Saat agen sudah aktif, ajukan pertanyaan yang sama lagi, "Berapa nilai tukar dari dolar Singapura ke yen Jepang?"

Kali ini, Anda akan melihat nilai tukar sebenarnya yang diberikan oleh alat get_fx_rate.

Jangan ragu untuk mengajukan pertanyaan terkait penukaran mata uang yang Anda inginkan.

5. Melakukan Integrasi dengan Alat Penelusuran Google Bawaan

Setelah agen dapat memberikan nilai tukar, tugas berikutnya adalah mendapatkan prakiraan cuaca untuk bulan depan. Ajukan pertanyaan ini kepada agen, "What is the weather forecast in Tokyo, Japan for next month?" (Apa ramalan cuaca di Tokyo, Jepang untuk bulan depan?)

Seperti yang mungkin Anda duga, perkiraan cuaca memerlukan informasi real-time yang tidak dimiliki agen kami. Meskipun kita dapat membuat kode fungsi Python baru untuk setiap bagian data real-time yang diperlukan, penambahan alat kustom yang terus bertambah dengan cepat membuat agen menjadi terlalu rumit dan sulit dikelola.

Untungnya, Agent Development Kit (ADK) menyediakan serangkaian Alat Bawaan, termasuk Google Penelusuran yang siap digunakan, sehingga menyederhanakan cara agen kami berinteraksi dengan dunia luar. Mari tambahkan alat Google Penelusuran ke agen kita.

Untuk melakukannya, Anda perlu mengedit file agent.py sebagai:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import google_search

from .custom_functions import get_fx_rate

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',
    tools=[
        FunctionTool(get_fx_rate), 
        google_search,
    ]
)

Setelah mengedit file, mulai ulang instance adk web. Jika Anda lupa,

1. Klik terminal, tekan Ctrl + C atau Cmd + C untuk menghentikan instance
2. uv run adk web untuk memulai instance
3. Coba ajukan pertanyaan yang sama: "Bagaimana ramalan cuaca di Tokyo, Jepang untuk bulan depan?"

Peringatan: Hal ini akan menyebabkan error dan memang disengaja. ADK dirancang sedemikian rupa sehingga setiap agen yang menggunakan alat bawaan tidak dapat menggunakan alat lain jenis apa pun secara bersamaan.

Pendekatan yang direkomendasikan adalah menggunakan pola multi-agen: buat agen khusus yang satu-satunya tugasnya adalah melakukan penelusuran Google. Kemudian, kami menetapkan Agen Google Penelusuran baru ini ke personal_assistant utama kami sebagai alat.

Buat file custom_agents.py

Catatan: Sebelum melanjutkan, pastikan Anda berada di direktori yang benar (ai-agents-adk). Jalankan perintah pwd (print working directory) di terminal untuk mengonfirmasi lokasi Anda saat ini.

Sekarang, buat file Python bernama custom_agents.py di folder personal_assistant.

touch personal_assistant/custom_agents.py

Sekarang struktur folder Anda akan terlihat seperti ini:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    └── custom_agents.py

File ini akan berisi kode untuk google_search_agent khusus. Salin kode berikut ke file custom_agents.py menggunakan Editor Kode.

from google.adk.agents import Agent
from google.adk.tools import google_search


# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

Setelah file dibuat, perbarui file agent.py seperti yang ditunjukkan di bawah.

Perbarui file agent.py

Salin blok kode ini dan ganti konten file agent.py yang ada:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

Mari kita uraikan pola baru yang canggih dalam kode:

• Agen Pakar Baru: Kami telah menentukan agen yang benar-benar baru, google_search_agent. Perhatikan deskripsinya yang spesifik dan bahwa satu-satunya alatnya adalah google_search. Ini adalah spesialis penelusuran.
• agent_tool.AgentTool: Ini adalah wrapper khusus dari ADK. Agent ini mengambil seluruh agen (google_search_agent kami) dan mengemasnya agar terlihat dan bertindak seperti alat standar.
• Lebih Cerdas **root_agent**: root_agent kami kini memiliki alat baru: agent_tool.AgentTool(agent=google_search_agent). Model ini tidak tahu cara menelusuri web, tetapi tahu bahwa ia memiliki alat yang dapat didelegasikan untuk tugas penelusuran.

Perhatikan bahwa kolom petunjuk telah hilang dari root_agent. Petunjuknya kini didefinisikan secara implisit oleh alat yang tersedia.

root_agent telah menjadi pengelola atau perute, yang tugas utamanya adalah memahami permintaan pengguna dan meneruskannya ke alat yang tepat, baik fungsi get_fx_rate maupun google_search_agent. Desain terdesentralisasi ini penting untuk membangun sistem agen yang kompleks dan mudah dikelola.

Sekarang, mulai ulang

adk web

instance dan ajukan pertanyaan ini lagi kepada agen, "Bagaimana ramalan cuaca di Tokyo, Jepang untuk bulan depan?"

Agen kini menggunakan google_search_agent untuk mendapatkan informasi terbaru

Anda juga dapat mencoba mengajukan pertanyaan terkait penukaran saat ini. Sekarang, agen akan dapat menggunakan alat yang tepat untuk pertanyaan masing-masing.

Jangan ragu untuk mengajukan pertanyaan lain yang memerlukan informasi real-time kepada agen dan amati cara agen menangani kueri menggunakan alat yang tersedia.

6. Memanfaatkan Alat Wikipedia LangChain

Agen kami akan menjadi asisten perjalanan yang hebat. Perusahaan ini dapat menangani pertukaran mata uang dengan alat get_fx_rate dan mengelola logistik dengan alat google_search_agent. Namun, perjalanan yang menyenangkan bukan hanya tentang logistik, tetapi juga tentang memahami budaya dan sejarah tujuan Anda.

Meskipun google_search_agent dapat menemukan fakta budaya dan sejarah, informasi dari sumber khusus seperti Wikipedia sering kali lebih terstruktur dan andal.

Untungnya, ADK dirancang agar sangat mudah diperluas, sehingga Anda dapat mengintegrasikan alat dari framework Agen AI lain seperti CrewAI dan LangChain dengan lancar. Interoperabilitas ini sangat penting karena memungkinkan waktu pengembangan yang lebih cepat dan memungkinkan Anda menggunakan kembali alat yang ada. Untuk kasus penggunaan ini, kita akan memanfaatkan alat Wikipedia dari LangChain.

Pertama, hentikan proses agen yang sedang berjalan (Ctrl + C atau Cmd + C) dan instal library tambahan ke lingkungan virtual Python saat ini dengan mengetik perintah berikut di Terminal.

uv add langchain-community
uv add wikipedia

Buat file third_party_tools.py

Catatan: Sebelum melanjutkan, pastikan Anda berada di direktori yang benar (ai-agents-adk). Jalankan perintah pwd (print working directory) di terminal untuk mengonfirmasi lokasi Anda saat ini.

Sekarang, buat file Python bernama third_party_tools.py di folder personal_assistant.

touch personal_assistant/third_party_tools.py

Sekarang struktur folder Anda akan terlihat seperti ini:

ai-agents-adk/
└── personal_assistant/
    ├── .env
    ├── __init__.py
    ├── agent.py
    ├── custom_functions.py
    ├── custom_agents.py
    └── third_party_tools.py

File ini akan berisi implementasi untuk alat Wikipedia LangChain. Salin kode berikut ke third_party_tools.py menggunakan Cloud Editor:

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
    api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)

# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
    "Provides deep historical and cultural information on landmarks, concepts, and places."
    "Use this for 'tell me about' or 'what is the history of' type questions."
)

Perbarui file agent.py

Sekarang, perbarui file agent.py dengan konten di bawah:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import agent_tool
from google.adk.tools import langchain_tool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool


root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

Sekarang, mulai ulang instance adk web dan ajukan pertanyaan ini kepada agen, "Tell me about the history of Kyoto".

Agen mengidentifikasi ini dengan benar sebagai kueri historis dan menggunakan alat Wikipedia barunya. Dengan mengintegrasikan alat pihak ketiga dan memberikan peran tertentu, Anda telah membuat agen Anda jauh lebih cerdas dan berguna untuk tujuan perencanaan perjalanannya.

Untuk melihat secara tepat bagaimana agen membuat pilihan ini, Anda dapat menggunakan pemeriksa peristiwa di adk web UI. Klik tab Acara, lalu klik acara functionCall terbaru.

Pemeriksa menampilkan daftar semua alat yang tersedia dan menandai tool_code untuk alat yang dijalankan oleh agen.

7. Membersihkan (Opsional)

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

Menonaktifkan Seluruh Project Google Cloud

Jika Anda ingin menonaktifkan project Google Cloud sepenuhnya, lihat panduan resmi untuk mengetahui petunjuk selengkapnya.

8. Kesimpulan

Selamat! Anda telah berhasil melengkapi agen asisten pribadi dengan fungsi kustom dan akses Google Penelusuran real-time. Baca dokumentasi resmi ini tentang penggunaan alat dengan Google ADK.

Yang lebih penting lagi, Anda telah mempelajari pola arsitektur mendasar untuk membangun agen yang mumpuni: menggunakan agen khusus sebagai alat. Dengan membuat google_search_agent khusus dan memberikannya kepada root_agent, Anda telah mengambil langkah pertama dari membangun satu agen hingga mengatur sistem multi-agen yang sederhana, tetapi efektif.

Sekarang Anda sudah siap untuk codelab berikutnya dalam seri ini, yang akan membahas lebih dalam cara mengoordinasikan beberapa agen dan alur kerja. Sampai jumpa!