Membangun Agen AI dengan ADK: Memberdayakan dengan Alat

1. Sebelum memulai

HARAP BACA:

Tutorial ini memerlukan Project Google Cloud dengan akun penagihan yang aktif.

Untuk Peserta Workshop Tatap Muka

• Ikuti petunjuk penyiapan dan penagihan khusus yang diberikan oleh instruktur Anda.

Untuk Pengguna yang Belajar Mandiri

• Ikuti langkah-langkah berikut untuk menukarkan uji coba:

1. Buka Jendela Samaran di browser Anda.
2. Buka portal penukaran ini.
3. Login menggunakan akun Gmail pribadi Anda.
4. Ikuti petunjuk langkah demi langkah dari portal.

Selamat datang di bagian kedua dari 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: Fondasi, 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, selangkah lebih dekat untuk diperluas di bagian selanjutnya dari seri ini saat kita mengubahnya menjadi Sistem Multi-Agen (MAS) yang canggih.

Anda juga dapat mengakses codelab ini melalui URL yang disingkat ini: goo.gle/adk-using-tools.

Prasyarat

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

Yang akan Anda pelajari

• Memberi agen Anda keterampilan baru dengan membangun fungsi Python kustom sebagai alat.
• Menghubungkan agen Anda ke informasi real-time menggunakan alat bawaan seperti Google Penelusuran.
• Menyusun 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 akan Anda butuhkan

• Komputer dan Wi-Fi yang berfungsi dengan baik
• Browser, seperti Chrome, untuk mengakses Konsol Google Cloud
• Pikiran yang ingin tahu dan keinginan untuk belajar

2. Pengantar

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

Anggap alat sebagai pemberian akses asisten AI tersebut 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.
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 kemajuan Anda.

Jalur A: Melanjutkan dari Codelab Fondasi

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

Jika Anda tidak melihat (ai-agents-adk) di perintah Cloud Shell, jalankan perintah ini untuk mengaktifkan lingkungan virtual Python:

cd ~/ai-agents-adk
source .venv/bin/activate

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. Mengonfigurasi Layanan Google Cloud
2. Membuat 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 Penukaran Mata Uang

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

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

Anda akan melihat bahwa agen tidak dapat mengambil nilai tukar real-time. Hal ini karena agen saat ini tidak memiliki akses internet dan konektivitas sistem eksternal. Meskipun agen membalas dengan nilai, sulit untuk mempercayai nilai tersebut karena kemungkinan akan menjadi 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 berjalan menggunakan pintasan keyboard Ctrl + C di jendela terminal.

Membuat file custom_functions.py

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

Jalankan perintah ini di terminal untuk membuat file Python bernama custom_functions.py di folder personal_assistant dan juga membukanya di Editor Kode.

cloudshell edit personal_assistant/custom_functions.py

Berikut tampilan struktur folder Anda sekarang:

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

File custom_functions.py ini akan berisi fungsi Python yang bertanggung jawab untuk mengambil data nilai tukar dari API eksternal. Salin dan tempel kode berikut ke dalam file:

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 teks deskriptif dalam tiga tanda kutip ("""..."""). Teks ini disebut docstring. Meskipun merupakan praktik yang baik untuk developer manusia, hal ini penting untuk Agen AI.

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

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

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

Memperbarui 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-3.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 baik untuk kumpulan alat kecil, tetapi seiring bertambahnya alat, kita perlu membuat paket alat.

Setelah perubahan, mulai ulang agen dengan mengetik:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Catatan: Meskipun menjalankan perintah adk web biasanya cukup untuk sebagian besar kasus, untuk memastikan akses yang tepat saat menjalankan server dari terminal Cloud Shell, Anda harus menyertakan flag --allow_origins.

Saat agen 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 sesuai keinginan Anda.

5. Mengintegrasikan dengan Alat Google Penelusuran Bawaan

Setelah agen dapat memberikan nilai tukar, tugas berikutnya adalah mendapatkan prakiraan cuaca bulan depan. Ajukan pertanyaan ini kepada agen, "Berapa prakiraan cuaca di Tokyo, Jepang untuk bulan depan?"

Seperti yang mungkin Anda harapkan, prakiraan cuaca memerlukan informasi real-time yang tidak dimiliki agen kita. Meskipun kita dapat membuat kode fungsi Python baru untuk setiap kasus penggunaan yang memerlukan data real-time, menambahkan semakin banyak alat kustom akan membuat agen menjadi terlalu rumit dan sulit dikelola.

Untungnya, Agent Development Kit (ADK) menyediakan rangkaian Alat Bawaan, termasuk Google Penelusuran yang siap digunakan, sehingga menyederhanakan cara agen kita berinteraksi dengan dunia luar.

Untuk melengkapi agen dengan alat Google Penelusuran, Anda harus menerapkan pola multi-agen. Pertama, Anda membuat agen khusus yang tugasnya hanya melakukan penelusuran Google. Kemudian, Anda menetapkan Agen Google Penelusuran baru ini ke personal_assistant utama kita sebagai alat. Berikut langkah-langkahnya:

Membuat 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.

Jalankan perintah ini di terminal untuk membuat file Python bernama custom_agents.py di folder personal_assistant dan membukanya di Editor Kode:

cloudshell edit personal_assistant/custom_agents.py

Berikut tampilan struktur folder Anda sekarang:

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

File custom_agents.py ini akan berisi kode untuk google_search_agent khusus. Salin kode berikut ke file custom_agents.py:

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-3.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 ini.

Memperbarui 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.agent_tool import AgentTool

from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent


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

Mari kita uraikan pola baru yang canggih dalam kode:

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

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

root_agent telah menjadi orkestrator atau router, yang tugas utamanya adalah memahami permintaan pengguna dan meneruskannya ke alat yang benar, baik fungsi get_fx_rate maupun google_search_agent. Desain terdesentralisasi ini adalah kunci untuk membangun sistem agen yang kompleks dan dapat dipertahankan.

Sekarang, ketik perintah ini di terminal untuk memulai instance:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Setelah agen berjalan, ajukan pertanyaan ini kepada agen lagi, "Berapa prakiraan cuaca di Tokyo, Jepang untuk bulan depan?"

Agen kini menggunakan google_search_agent untuk mendapatkan informasi terbaru

Anda juga dapat mencoba mengajukan pertanyaan tentang nilai tukar saat ini. Agen kini akan dapat menggunakan alat yang tepat untuk pertanyaan yang relevan.

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 kita sedang dibentuk menjadi asisten perjalanan yang hebat. Agen ini dapat menangani penukaran 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 dapat diandalkan.

Untungnya, ADK dirancang agar sangat dapat 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 berjalan (Ctrl + C) dan instal library tambahan ke lingkungan virtual Python saat ini dengan mengetik perintah berikut di Terminal.

uv pip install langchain-community wikipedia

Membuat 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.

Perintah berikut membuat file Python bernama third_party_tools.py di folder personal_assistant dan membukanya di Cloud Editor:

cloudshell edit personal_assistant/third_party_tools.py

Berikut tampilan struktur folder Anda sekarang:

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 dalam file third_party_tools.py:

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."
)

Memperbarui file agent.py

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

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

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-3.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    tools=[
        FunctionTool(get_fx_rate),
        AgentTool(agent=google_search_agent),
        LangchainTool(langchain_wikipedia_tool),
    ]
)

Sekarang, ketik perintah ini di terminal untuk memulai instance:

adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

Saat agen siap, ajukan pertanyaan ini kepada agen, "Beri tahu saya tentang sejarah Kyoto".

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

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

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

7. Membersihkan (Opsional)

Catatan: Anda tidak perlu melakukan langkah ini jika berencana untuk melanjutkan seri ini. Jika Anda mengikuti codelab ini secara langsung dengan instruktur, instruktur Anda akan memberikan petunjuk lebih lanjut tentang apa yang harus dilakukan.

Karena codelab ini tidak melibatkan produk yang berjalan lama, cukup hentikan sesi agen aktif Anda (misalnya, instance adk web di terminal Anda) dengan menekan Ctrl + C di terminal.

Menghapus Folder dan File Project Agen

Jika 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

Menutup Seluruh Project Google Cloud

Jika Anda ingin menutup sepenuhnya project Google Cloud, lihat panduan resmi untuk mengetahui petunjuk mendetail.

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 dasar untuk membangun agen yang mumpuni: menggunakan agen khusus sebagai alat. Dengan membuat google_search_agent khusus dan memberikannya ke root_agent, Anda telah mengambil langkah pertama dari membangun satu agen hingga mengatur sistem multi-agen yang sederhana, tetapi canggih.

Anda kini siap untuk codelab berikutnya (segera hadir) dalam seri ini, yang akan membahas lebih dalam tentang mengatur beberapa agen dan alur kerja. Sampai jumpa!