Alat Membuat Agen: Dari Nol hingga Asisten dengan ADK

1. Pengantar

Di lab ini, Anda akan membangun agen dengan Agent Development Kit (ADK). Anda akan mempelajari cara membuat agen asisten bug software menggunakan ADK dan berbagai jenis alat. Anda akan memulai dengan agen dasar dan secara progresif menambahkan alat untuk meningkatkan kemampuannya, termasuk alat fungsi, alat bawaan, alat pihak ketiga, dan alat Model Context Protocol (MCP).

Yang akan Anda pelajari

• Cara menyiapkan project Python untuk pengembangan ADK.
• Cara membuat agen ADK dasar.
• Cara menerapkan dan menggunakan Alat Fungsi.
• Cara mengintegrasikan Alat Bawaan seperti Google Penelusuran.
• Cara memanfaatkan Alat Pihak Ketiga dari framework seperti LangChain dalam ADK.
• Cara menggunakan Alat MCP untuk berinteraksi dengan database (Cloud SQL) dan API.

2. Ringkasan

Bayangkan Anda adalah seorang manajer proyek di QuantumRoast, sebuah perusahaan mesin kopi global.

Anda membantu rekan tim Anda menavigasi berbagai roadmap engineering, perubahan strategi yang tiba-tiba (sekarang kami menjual matcha!), dan tiket masuk dari pelanggan — mulai dari sistem invoice yang bermasalah hingga mesin kopi yang mengeluarkan suara bernada tinggi 24/7.

Pada hari biasa, Anda membuka sekitar lima puluh tab browser: sistem tiket internal, email, chat, GitHub, Google Penelusuran, StackOverflow, dan lainnya. Anda menyukai pekerjaan dan rekan kerja Anda, tetapi terkadang Anda merasa kewalahan.

Bagaimana jika ada alat bantu yang dapat kami buat untuk membantu Anda membuat dan memilah tiket software, serta melakukan debug pada masalah? Agen AI memungkinkan hal ini.

Agent Development Kit (ADK)

Agent Development Kit (ADK) adalah framework fleksibel dan modular untuk mengembangkan dan men-deploy agen AI. Meskipun dioptimalkan untuk Gemini dan ekosistem Google, ADK bersifat agnostik terhadap model, agnostik terhadap deployment, dan dibuat agar kompatibel dengan framework lain. ADK dirancang agar pengembangan agen terasa lebih seperti pengembangan software, sehingga memudahkan developer membuat, men-deploy, dan mengatur arsitektur agentic yang berkisar dari tugas sederhana hingga alur kerja yang kompleks.

ADK sepenuhnya bersifat open source di repositori GitHub adk-python.

Jika Anda ingin mengajukan masalah, memiliki permintaan fitur, atau ingin berkontribusi, Anda dapat melakukannya di GitHub.

ADK adalah framework yang akan kita gunakan untuk membangun asisten bug software QuantumRoast.

Alat 101

Agen AI menggunakan model, bukan hanya logika hard code, untuk memecahkan masalah. Namun, lebih dari sekadar penalaran berbasis LLM, agen AI memiliki kemampuan unik untuk mengumpulkan data eksternal dan kemudian mengambil tindakan atas nama pengguna. Daripada memberi tahu Anda cara menyelesaikan masalah, agen AI dapat membantu Anda menyelesaikannya. Bagaimana kami melakukannya? Dengan alat.

Alat adalah kemampuan yang membantu agen AI berinteraksi dengan dunia. Alat dapat berupa apa saja: fungsi inline, database yang dihosting, API pihak ketiga , atau bahkan agen lain. Framework Agen AI seperti Agent Development Kit (ADK) memiliki dukungan bawaan untuk alat, yang mendukung berbagai jenis alat yang akan kita bahas sebentar lagi.

Namun, bagaimana agen mengetahui tidak hanya kapan harus memanggil alat tertentu, tetapi juga cara memanggilnya? Model agen memainkan beberapa peran penting di sini.

Yang pertama adalah pemilihan alat. Kami memberi agen kami daftar alat dan beberapa petunjuk tentang cara menggunakannya. Saat pengguna memberikan perintah kepada agen, model agen akan membantu memutuskan alat mana yang akan dipanggil, dan alasannya, untuk membantu pengguna.

Langkah utama kedua adalah panggilan fungsi. Panggilan fungsi sedikit keliru karena model tidak benar-benar memanggil alat, tetapi bersiap untuk memanggilnya dengan memformat isi permintaan yang kemudian digunakan framework untuk memanggil alat.

Terakhir, model ini membantu menafsirkan respons dari alat tersebut — misalnya, daftar bug terbuka dari database— dan memutuskan apakah akan mengambil tindakan lebih lanjut, atau merespons pengguna dengan informasi tersebut.

Untuk melihat semua ini dalam tindakan, saatnya membangun agen asisten bug QuantumRoast menggunakan ADK Python.

3. Sebelum memulai

Penyiapan Project Google Cloud

1. Jika belum memiliki Akun Google, Anda harus membuat Akun Google.
   • Gunakan akun pribadi, bukan akun kantor atau sekolah. Akun kantor dan sekolah mungkin memiliki batasan yang mencegah Anda mengaktifkan API yang diperlukan untuk lab ini.
2. Login ke Konsol Google Cloud.
3. Aktifkan penagihan di Konsol Cloud.
   • Menyelesaikan lab ini akan dikenai biaya kurang dari $1 USD untuk resource Cloud.
   • Anda dapat mengikuti langkah-langkah di akhir lab ini untuk menghapus resource agar tidak dikenai biaya lebih lanjut.
   • Pengguna baru memenuhi syarat untuk mengikuti Uji Coba Gratis senilai$300 USD.
4. Buat project baru atau pilih untuk menggunakan kembali project yang ada.

Buka Cloud Shell Editor

1. Buka Cloud Shell Editor
2. Jika terminal tidak muncul di bagian bawah layar, buka terminal:
   • Klik menu tiga garis
   • Klik Terminal
   • Klik New Terminal
3. Di terminal, tetapkan project Anda dengan perintah ini (ganti YOUR_PROJECT_ID):
   • Format:

     gcloud config set project YOUR_PROJECT_ID
     

   • Contoh:

     gcloud config set project lab-project-id-example
     

   • Jika Anda tidak dapat mengingat project ID Anda:
     • Anda dapat mencantumkan semua ID project Anda dengan:

       gcloud projects list | awk '/PROJECT_ID/{print $2}'
       

     
4. Jika diminta untuk memberikan otorisasi, klik Authorize untuk melanjutkan.
5. Anda akan melihat pesan ini:

   Updated property [core/project].
   

   Jika Anda melihat WARNING dan diminta Do you want to continue (Y/N)?, berarti Anda kemungkinan telah memasukkan ID project dengan salah. Tekan N, tekan Enter, lalu coba jalankan perintah gcloud config set project lagi.
6. Di terminal, tetapkan variabel lingkungan PROJECT_ID yang akan digunakan pada langkah selanjutnya.

   export PROJECT_ID=$(gcloud config get project)
   

Mengaktifkan API

Di terminal, jalankan perintah berikut untuk mengaktifkan Google Cloud API yang diperlukan:

gcloud services enable sqladmin.googleapis.com \
   compute.googleapis.com \
   cloudresourcemanager.googleapis.com \
   secretmanager.googleapis.com \
   servicenetworking.googleapis.com \
   aiplatform.googleapis.com \
   run.googleapis.com \
   artifactregistry.googleapis.com \
   cloudbuild.googleapis.com

Membuat instance Cloud SQL for PostgreSQL

QuantumRoast memiliki database tiket bug yang menyimpan semua tiket internal. Mari kita siapkan dengan membuat instance Cloud SQL untuk PostgreSQL.

gcloud sql instances create software-assistant \
   --database-version=POSTGRES_16 \
   --tier=db-custom-1-3840 \
   --region=us-central1 \
   --edition=ENTERPRISE \
   --enable-google-ml-integration \
   --database-flags cloudsql.enable_google_ml_integration=on \
   --root-password=admin

Tunggu hingga instance dibuat (mungkin perlu waktu beberapa menit).

Kita menggunakan sandi database admin untuk tujuan codelab ini. Namun, untuk lingkungan produksi, sebaiknya gunakan sandi yang lebih aman.

Setelah dibuat, Anda dapat melihat instance di Konsol Cloud di sini.

Membuat Database Cloud SQL

Buat database SQL (tickets-db), dan berikan akses akun layanan Cloud SQL ke Vertex AI (agar kita dapat membuat penyematan untuk melakukan penelusuran kesamaan).

gcloud sql databases create tickets-db --instance=software-assistant

SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe software-assistant --format="value(serviceAccountEmailAddress)")
echo $SERVICE_ACCOUNT_EMAIL

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" --role="roles/aiplatform.user"

Menyiapkan tabel tickets

Dari Cloud Console (Cloud SQL), buka Cloud SQL Studio untuk instance software-assistant.

Login ke databasetickets-db menggunakan pengguna postgres dan admin sebagai sandi.

Buka tab Editor baru.

Kemudian, tempel kode SQL berikut untuk menyiapkan tabel dan membuat penyematan vektor. Tekan tombol Run untuk menjalankan perintah.

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector CASCADE;
GRANT EXECUTE ON FUNCTION embedding TO postgres;

CREATE TABLE tickets (
    ticket_id SERIAL PRIMARY KEY,             -- PostgreSQL's auto-incrementing integer type (SERIAL is equivalent to INT AUTO_INCREMENT)
    title VARCHAR(255) NOT NULL,              -- A concise summary or title of the bug/issue.
    description TEXT,                         -- A detailed description of the bug.
    assignee VARCHAR(100),                    -- The name or email of the person/team assigned to the ticket.
    priority VARCHAR(50),                     -- The priority level (e.g., 'P0 - Critical', 'P1 - High').
    status VARCHAR(50) DEFAULT 'Open',        -- The current status of the ticket (e.g., 'Open', 'In Progress', 'Resolved'). Default is 'Open'.
    creation_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, -- Timestamp when the ticket was first created. 'WITH TIME ZONE' is recommended for clarity and compatibility.
    updated_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP  -- Timestamp when the ticket was last updated. Will be managed by a trigger.
);

Tabel tickets telah dibuat, klik Clear untuk menghapus kueri lama.

Sekarang, masukkan data sampel dan tekan tombol Run sekali lagi.

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Login Page Freezes After Multiple Failed Attempts', 'Users are reporting that after 3 failed login attempts, the login page becomes unresponsive and requires a refresh. No specific error message is displayed.', '[e-mail]', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Dashboard Sales Widget Intermittent Data Loading Failure', 'The "Sales Overview" widget on the main dashboard intermittently shows a loading spinner but no data. Primarily affects Chrome browser users.', '[e-mail]', 'P1 - High', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Broken Link in Footer - Privacy Policy', 'The "Privacy Policy" hyperlink located in the website footer leads to a 404 "Page Not Found" error.', '[e-mail]', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('UI Misalignment on Mobile Landscape View (iOS)', 'On specific iOS devices (e.g., iPhone 14 models), the top navigation bar shifts downwards when the device is viewed in landscape orientation, obscuring content.', '[e-mail]', 'P2 - Medium', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Critical XZ Utils Backdoor Detected in Core Dependency (CVE-2024-3094)', 'Urgent: A sophisticated supply chain compromise (CVE-2024-3094) has been identified in XZ Utils versions 5.6.0 and 5.6.1. This malicious code potentially allows unauthorized remote SSH access by modifying liblzma. Immediate investigation and action required for affected Linux/Unix systems and services relying on XZ Utils.', '[e-mail]', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Database Connection Timeouts During Peak Usage', 'The application is experiencing frequent database connection timeouts, particularly during peak hours (10 AM - 12 PM EDT), affecting all users and causing service interruptions.', '[e-mail]', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Export to PDF Truncates Long Text Fields in Reports', 'When generating PDF exports of reports containing extensive text fields, the text is abruptly cut off at the end of the page instead of wrapping or continuing to the next page.', '[e-mail]', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Search Filter "Date Range" Not Applying Correctly', 'The "Date Range" filter on the search results page does not filter records accurately; results outside the specified date range are still displayed.', '[e-mail]', 'P2 - Medium', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Typo in Error Message: "Unathorized Access"', 'The error message displayed when a user attempts an unauthorized action reads "Unathorized Access" instead of "Unauthorized Access."', '[e-mail]', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Intermittent File Upload Failures for Large Files', 'Users are intermittently reporting that file uploads fail without a clear error message or explanation, especially for files exceeding 10MB in size.', '[e-mail]', 'P1 - High', 'Open');

Di QuantumRoast, kita mungkin ingin mengetahui kapan bug/tiket terakhir diperbarui.

Untuk melakukannya, kita dapat membuat pemicu untuk memperbarui kolom updated_time setiap kali data diperbarui.

Klik Clear, lalu tempel SQL berikut untuk menerapkan pemicu.

Tekan tombol Run untuk menjalankan.

CREATE OR REPLACE FUNCTION update_updated_time_tickets()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_time = NOW();  -- Set the updated_time to the current timestamp
    RETURN NEW;                -- Return the new row
END;
$$ language 'plpgsql';        

CREATE TRIGGER update_tickets_updated_time
BEFORE UPDATE ON tickets
FOR EACH ROW                  -- This means the trigger fires for each row affected by the UPDATE statement
EXECUTE PROCEDURE update_updated_time_tickets();

Buat embedding vektor dari kolom description. Tindakan ini akan memberi agen kita kemampuan untuk melakukan penelusuran kesamaan di database kita. Misalnya, "Apakah ada masalah terbuka terkait halaman beranda situs?".

ALTER TABLE tickets ADD COLUMN embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005',description)) STORED;

Sekarang Anda dapat membuat kueri database untuk memverifikasi bahwa database sudah siap.

SELECT * FROM tickets;

Anda akan melihat 10 baris yang ditampilkan yang menyerupai berikut ini:

Sekarang Anda siap untuk melanjutkan ke bagian yang menyenangkan, yaitu kode.

4. Penyiapan Project Python

Sebelum mulai membuat agen, kita harus memastikan penyiapan project Python sudah benar. Kita akan melakukannya semua di Cloud Shell.

Pertama, buat folder quantum-roast dan cd ke dalamnya:

mkdir quantum-roast && cd quantum-roast

Setelah memiliki folder untuk project, sekarang saatnya melakukan inisialisasi project dan membuat file yang sesuai yang akan kita butuhkan.

Kita akan menggunakan uv (pengelola paket dan project Python yang sangat cepat) yang sudah diinstal sebelumnya di Cloud Shell untuk mengelola project dan dependensi kita. Uv akan membantu kita menyiapkan beberapa file serta mengelola lingkungan virtual, dependensi, dll. Jadi, kita tidak perlu melakukannya.

Lakukan inisialisasi project baru dengan uv init:

uv init --description "QuantumRoast Software Bug Assistant with ADK" --bare --python 3.10

Setelah menjalankan perintah, kita akan memiliki file pyproject.toml untuk project kita. Untuk memverifikasi, jalankan cat pyproject.toml di terminal Cloud Shell:

cat pyproject.toml

Berikut yang akan terlihat sebagai output:

[project]
name = "quantum-roast"
version = "0.1.0"
description = "QuantumRoast Software Bug Assistant with ADK"
requires-python = ">=3.10"
dependencies = []

Saatnya menambahkan google-adk (ADK) sebagai dependensi ke project kita menggunakan uv add.

uv add google-adk==1.11.0

Tindakan ini akan menambahkan google-adk ke daftar dependencies di pyproject.toml kita.

ADK mengharapkan struktur project tertentu untuk mendapatkan hasil terbaik.

quantum-roast/
    software_bug_assistant/
        __init__.py
        agent.py
        .env

Buat folder software_bug_assistant dan file di dalamnya:

mkdir software_bug_assistant && touch software_bug_assistant/__init__.py \
software_bug_assistant/agent.py \
software_bug_assistant/tools.py \
software_bug_assistant/.env

Verifikasi pembuatan file menggunakan ls:

ls -a software_bug_assistant/

Anda akan melihat berikut ini:

__init__.py	 .  ..	 .env	 agent.py    tools.py

Saatnya mengisi file .env dengan variabel lingkungan yang diperlukan agar ADK dapat memanggil model Gemini dengan benar. Kita akan mengakses Gemini melalui Vertex API.

echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_LOCATION=us-central1" >> software_bug_assistant/.env

Untuk memverifikasi bahwa .env telah diisi dengan benar, jalankan perintah berikut:

cat software_bug_assistant/.env

Anda akan melihat hal berikut dengan your-project-id sebagai project ID Anda:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

Sekarang kita siap untuk mulai membuat agen ADK.

5. Agen ADK Dasar

Mari kita siapkan agen dasar ADK yang dapat kita tambahkan alatnya satu per satu selama workshop ini untuk membuat asisten bug yang canggih.

Buka agent.py di Cloud Shell Editor:

cloudshell edit software_bug_assistant/agent.py

Tempelkan kode berikut ke agent.py dan simpan file Ctrl + s:

from google.adk.agents import Agent

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[],
)

Jalankan agen yang baru dibuat dengan memulai UI dev ADK (adk web). Melakukannya dengan uv run akan otomatis membuat lingkungan virtual dengan ADK yang terinstal.

Menggunakan flag --port 8080 akan memulai adk web di port default Cloud Shell.

Flag --reload_agents memungkinkan perubahan hot-reloading setiap kali kita memperbarui agen. Dengan cara ini, kita dapat membiarkan ADK berjalan saat mengembangkan berbagai jenis alat dan perubahan akan otomatis diterapkan.

uv run adk web --port 8080 --reload_agents

Di konsol, Anda akan melihat keberhasilan peluncuran Server Web ADK.

INFO:     Started server process [1557]
INFO:     Waiting for application startup.

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

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

Buka Pratinjau Web Cloud Shell untuk melihat UI.

Anda akan melihat UI web ADK.

Lanjutkan dan coba mulai chat dengan agen ADK.

Tanyakan kepada agen What day is it today?.

Anda akan melihat dari respons bahwa agen tidak dapat menjawab pertanyaan dasar ini. Ingat bahwa LLM adalah sistem terisolasi, yang dilatih dengan data sebelumnya. Mereka tidak memiliki konteks real-time tentang peristiwa terbaru atau bahkan tanggal saat ini... kecuali jika Anda memberi mereka alat.

Saatnya menerapkan jenis alat pertama ADK, yaitu Function Tool.

Biarkan Pratinjau Web tetap terbuka, kita akan kembali ke agen di setiap langkah lab.

6. Alat Fungsi

Jenis alat ADK pertama dan paling sederhana adalah alat fungsi. Sesuai namanya, ini adalah fungsi Python yang dipanggil oleh agen.

Alat fungsi cukup canggih karena memungkinkan Anda menulis kode kustom agar dipanggil oleh agen sebagai alat, seperti melakukan perhitungan, memanggil API, membuat kueri database. Fungsi ini bisa sederhana atau kompleks, sepenuhnya terserah Anda.

ADK juga mendukung fungsi asinkron yang berjalan lama. Dirancang untuk tugas yang memerlukan waktu pemrosesan yang signifikan tanpa memblokir eksekusi agen.

Di QuantumRoast, kita ingin menentukan fungsi dasar untuk mendapatkan tanggal hari ini, agar nanti dalam lab ini kita dapat menangani kueri seperti, "tunjukkan bug dari minggu lalu" atau "hari ini hari apa?" (hal ini terjadi pada kita semua).

Biarkan terminal web ADK tetap berjalan. Karena kita menggunakan --reload_agents, kita dapat membiarkan agen berjalan dan agen akan otomatis mengambil alat baru saat kita menambahkannya. 😊

File tools.py dalam folder /software_bug_assistant adalah tempat kita akan mengatur semua alat yang kita buat di seluruh lab ini.

Buka terminal BARU dengan mengklik ikon +.

Sekarang di terminal baru, tetapkan PROJECT_ID dan buka tools.py:

cd quantum-roast
export PROJECT_ID=$(gcloud config get project)
cloudshell edit software_bug_assistant/tools.py

Sekarang tentukan fungsi get_current_date yang akan digunakan sebagai alat Fungsi.

from datetime import datetime

# ----- Example of a Function tool -----
def get_current_date() -> dict:
    """
    Get the current date in the format YYYY-MM-DD
    """
    return {"current_date": datetime.now().strftime("%Y-%m-%d")}

Fungsi kini telah ditentukan. Saatnya meneruskannya sebagai alat kepada agen.

Buka agent.py di Cloud Shell Editor:

cloudshell edit software_bug_assistant/agent.py

Kita ingin mengimpor fungsi get_current_date dari tools.py dan meneruskan fungsi ke argumen tools agen.

agent.py yang diupdate akan terlihat seperti berikut:

from google.adk.agents import Agent

from .tools import get_current_date

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date],
)

Sekarang, jika Anda kembali ke tab Pratinjau Web yang menjalankan UI Web ADK dan meminta What day is it today? lagi...

Agen dapat berhasil memberi tahu tanggal dengan memanggil Alat Fungsi get_current_date. 🎉

Saatnya mempelajari jenis alat ADK berikutnya.

7. Alat Bawaan

Jenis alat ADK lainnya adalah alat bawaan. Ini adalah alat yang berfungsi dengan fitur model unggulan Google, seperti eksekusi kode di dalam model itu sendiri. Kita dapat melampirkan alat bawaan Google Penelusuran ke agen asisten bug untuk memberikan konteks yang relevan kepada agen dengan memberinya akses untuk menelusuri web. Hal ini akan memungkinkan agen mengumpulkan informasi terbaru tentang bug atau kerentanan yang sudah diketahui.

Buka file tools.py untuk menambahkan dukungan bagi alat bawaan Google Penelusuran.

cloudshell edit software_bug_assistant/tools.py

Tambahkan kode berikut ke bagian bawah tools.py:

# ----- Built-in Tool Imports -----
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

# ----- Example of a Built-in Tool -----
search_agent = Agent(
    model="gemini-2.5-flash",
    name="search_agent",
    description="A specialist in Google Search.",
    instruction="""
    You're a specialist in Google Search.
    """,
    tools=[google_search],
)

search_tool = AgentTool(search_agent)

Di sini, kita sebenarnya membungkus alat Google Penelusuran tersebut dalam agennya sendiri dengan petunjuk sistemnya sendiri, sehingga secara efektif menggunakan agen sebagai alat.

Sekarang kita dapat mengimpor dan meneruskan search_tool ke agen root di agent.py:

cloudshell edit software_bug_assistant/agent.py

Anda dapat mengganti agent.py dengan kode berikut untuk menyertakan search_tool:

from google.adk.agents import Agent

from .tools import get_current_date, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool],
)

Simpan file dan kembali ke tab yang menjalankan UI Web ADK.

Jika Anda tidak sengaja menutup terminal yang menjalankan ADK Web UI, Anda dapat memulainya kembali dengan menjalankan uv run adk web --port 8080 --reload_agents.

Di QuantumRoast, kami ingin memastikan situs dan software kami terlindungi dari Common Vulnerabilities and Exposures (CVE), yaitu kerentanan keamanan siber publik. Kita dapat menggunakan alat Google Penelusuran baru agen kita untuk menelusuri web guna menemukan CVE yang baru ditemukan.

Jalankan kueri berikut: Do a web search for 5 of the most recent CVEs?.

Agen kita harus memanggil search_agent untuk menelusuri web.

Agen kami kini berhasil membuka kemampuan untuk menelusuri web melalui alat bawaan ADK untuk Google Penelusuran. 🎉

Lanjut ke jenis alat ADK berikutnya.

8. Alat Pihak Ketiga

ADK dirancang agar sangat mudah diperluas, sehingga Anda dapat mengintegrasikan alat dari framework Agen AI pihak ketiga lainnya seperti CrewAI dan LangChain dengan lancar. Interoperabilitas ini sangat penting karena memungkinkan waktu pengembangan yang lebih cepat dan kemampuan untuk menggunakan kembali alat yang ada.

Untuk menghubungkan agen bug kami ke data Tanya Jawab StackOverflow yang canggih, kami dapat mengambil dari library alat LangChain yang ekstensif, khususnya alat StackExchange API Wrapper. ADK mendukung alat pihak ketiga seperti LangChain, sehingga penambahan alat ini ke agen ADK kami hanya memerlukan beberapa baris kode.

Pertama, kita harus menambahkan dependensi baru untuk LangChain dan StackOverflow (langchain-community dan stackapi) ke project:

uv add langchain-community==0.3.27 stackapi==0.3.1

Buka file tools.py untuk menambahkan dukungan bagi alat LangChain StackExchange.

cloudshell edit software_bug_assistant/tools.py

Tambahkan kode berikut ke bagian bawah tools.py:

# ----- Example of a Third-Party Tool -----
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import StackExchangeTool
from langchain_community.utilities import StackExchangeAPIWrapper

stack_exchange_tool = StackExchangeTool(api_wrapper=StackExchangeAPIWrapper())
langchain_tool = LangchainTool(stack_exchange_tool)

Sekarang kita dapat mengimpor dan meneruskan langchain_tool ke agen root di agent.py:

cloudshell edit software_bug_assistant/agent.py

Anda dapat mengganti agent.py dengan kode berikut untuk menyertakan langchain_tool:

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool],
)

Simpan file dan kembali ke tab yang terbuka dengan ADK Web UI.

Jika Anda tidak sengaja menutup terminal yang menjalankan ADK Web UI, Anda dapat memulainya kembali dengan menjalankan uv run adk web --port 8080 --reload_agents.

Coba tanyakan sesuatu kepada agen tentang CVE sebelumnya, "Are there similar issues on stack exchange?" atau sesuatu yang baru seperti "Our database queries with SQLAlchemy seem to be timing out, is there anything on StackExchange relevant to this?".

Agen kita kini telah berhasil memanfaatkan alat LangChain di ADK untuk membuat kueri StackOverflow. 🥳

Saatnya membahas jenis alat ADK berikutnya... Alat MCP

9. Alat MCP (Database)

MCP adalah singkatan dari Model Context Protocol. Ini adalah protokol terbuka yang diperkenalkan oleh Anthropic pada tahun 2024. MCP menyediakan lapisan abstraksi antara agen AI dan "backend" alat Anda (API, database).

MCP memiliki beberapa spesifikasi unik. Tidak seperti HTTP standar, MCP menyediakan koneksi dua arah yang stateful antara klien dan server. API ini memiliki cara sendiri untuk menentukan alat dan pesan error khusus alat. Penyedia alat kemudian dapat membuat Server MCP di atas API mereka, yang mengekspos satu atau beberapa alat bawaan untuk developer dan pengguna. Kemudian, framework agen dapat menginisialisasi Klien MCP di dalam aplikasi agen, untuk menemukan dan memanggil alat tersebut.

Di QuantumRoast, kami memiliki database Cloud SQL untuk PostgreSQL untuk bug software internal. Kita ingin membuat alat ADK agar agen kita dapat melakukan kueri tertentu pada database kita.

Cara termudah untuk melakukannya adalah dengan MCP Toolbox for Databases , server MCP open source untuk database. Toolbox mendukung lebih dari 15 database, salah satunya adalah Cloud SQL.

Toolbox menyediakan:

• Pengembangan yang disederhanakan: Integrasikan alat ke agen Anda dengan kurang dari 10 baris kode, gunakan kembali alat di antara beberapa agen atau framework, dan deploy versi baru alat dengan lebih mudah.
• Performa yang lebih baik: Praktik terbaik seperti penggabungan koneksi, autentikasi, dan lainnya.
• Keamanan yang ditingkatkan: Autentikasi terintegrasi untuk akses yang lebih aman ke data Anda
• Kemampuan observasi menyeluruh: Metrik dan pelacakan langsung dengan dukungan bawaan untuk OpenTelemetry.

ADK memiliki dukungan untuk alat MCP Toolbox for Database yang mempercepat integrasi.

Men-deploy Server MCP Toolbox for Databases ke Cloud Run

Pertama, kita akan men-deploy Server MCP Toolbox for Databases ke Cloud Run dan mengarahkannya ke instance Cloud SQL kita.

Toolbox memerlukan file YAML untuk konfigurasi, tempat Anda menguraikan sumber database dan alat yang akan dikonfigurasi.

Buat file tools.yaml untuk deployment.

cloudshell edit tools.yaml

Tempelkan konten berikut ke tools.yaml:

sources:
  postgresql:
    kind: cloud-sql-postgres
    project: ${PROJECT_ID}
    region: us-central1
    instance: software-assistant
    database: tickets-db
    user: postgres
    password: admin

tools:
  search-tickets:
    kind: postgres-sql
    source: postgresql
    description: Search for similar tickets based on their descriptions.
    parameters:
      - name: query
        type: string
        description: The query to perform vector search with.
    statement: |
      SELECT ticket_id, title, description, assignee, priority, status, (embedding <=> embedding('text-embedding-005', $1)::vector) as distance
      FROM tickets
      ORDER BY distance ASC
      LIMIT 3;
  get-ticket-by-id:
    kind: postgres-sql
    source: postgresql
    description: Retrieve a ticket's details using its unique ID.
    parameters:
      - name: ticket_id
        type: string
        description: The unique ID of the ticket.
    statement: SELECT * FROM tickets WHERE ticket_id = $1;
  get-tickets-by-assignee:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on assignee (email).
    parameters:
      - name: assignee
        type: string
        description: The email of the assignee.
    statement: SELECT * FROM tickets WHERE assignee ILIKE '%' || $1 || '%';
  update-ticket-priority:
    kind: postgres-sql
    source: postgresql
    description: Update the priority of a ticket based on its ID.
    parameters:
      - name: priority
        type: string
        description: The priority of the ticket. Can be one of 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'.
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET priority = $1 WHERE ticket_id = $2;
  update-ticket-status:
    kind: postgres-sql
    source: postgresql
    description: Update the status of a ticket based on its ID.
    parameters:
      - name: status
        type: string
        description: The new status of the ticket (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET status = $1 WHERE ticket_id = $2;
  get-tickets-by-status:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their current status.
    parameters:
      - name: status
        type: string
        description: The status of the tickets to retrieve (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
    statement: SELECT * FROM tickets WHERE status ILIKE '%' || $1 || '%';
  get-tickets-by-priority:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their priority.
    parameters:
      - name: priority
        type: string
        description: The priority of the tickets to retrieve (e.g., 'P0 - Critical', 'P1 - High', 'P2 - Medium', 'P3 - Low').
    statement: SELECT * FROM tickets WHERE priority ILIKE '%' || $1 || '%';
  create-new-ticket:
    kind: postgres-sql
    source: postgresql
    description: Create a new software ticket.
    parameters:
      - name: title
        type: string
        description: The title of the new ticket.
      - name: description
        type: string
        description: A detailed description of the bug or issue.
      - name: assignee
        type: string
        description: (Optional) The email of the person to whom the ticket should be assigned.
      - name: priority
        type: string
        description: (Optional) The priority of the ticket. Can be 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'. Default is 'P3 - Low'.
      - name: status
        type: string
        description: (Optional) The initial status of the ticket. Default is 'Open'.
    statement: INSERT INTO tickets (title, description, assignee, priority, status) VALUES ($1, $2, $3, COALESCE($4, 'P3 - Low'), COALESCE($5, 'Open')) RETURNING ticket_id;
  get-tickets-by-date-range:
    kind: postgres-sql
    source: postgresql
    description: Retrieve tickets created or updated within a specific date range.
    parameters:
      - name: start_date
        type: string
        description: The start date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: end_date
        type: string
        description: The end date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: date_field
        type: string
        description: The date field to filter by ('creation_time' or 'updated_time').
    statement: SELECT * FROM tickets WHERE CASE WHEN $3 = 'creation_time' THEN creation_time ELSE updated_time END BETWEEN $1::timestamp AND $2::timestamp;

toolsets:
  tickets_toolset:
    - search-tickets
    - get-ticket-by-id
    - get-tickets-by-assignee
    - get-tickets-by-status
    - get-tickets-by-priority
    - get-tickets-by-date-range
    - update-ticket-priority
    - update-ticket-status
    - create-new-ticket

File YAML menentukan 9 alat yang terkait dengan database tiket QuantumRoast.

Saatnya mengonfigurasi akun layanan untuk layanan Toolbox Cloud Run, memberikan izin untuk mengakses Cloud SQL dan Secret Manager, serta membuat secret Secret Manager untuk file tools.yaml kita.

Secret Manager adalah tempat kita akan menyimpan file tools.yaml karena berisi kredensial Cloud SQL yang sensitif.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudsql.client

gcloud secrets create tools --data-file=tools.yaml

Saatnya men-deploy MCP Toolbox for Databases ke Cloud Run. Kita akan menggunakan versi rilis terbaru dari image container MCP Toolbox.

gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --set-env-vars="PROJECT_ID=$PROJECT_ID" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --allow-unauthenticated

Tunggu hingga deployment selesai...

Pastikan Toolbox berjalan dengan membuat kueri log Cloud Run:

gcloud run services logs read toolbox --region us-central1 --limit 10

Anda akan melihat:

2025-08-20 18:03:55 2025-08-20T18:03:55.465847801Z INFO "Initialized 1 sources."
2025-08-20 18:03:55 2025-08-20T18:03:55.466152914Z INFO "Initialized 0 authServices."
2025-08-20 18:03:55 2025-08-20T18:03:55.466374245Z INFO "Initialized 9 tools."
2025-08-20 18:03:55 2025-08-20T18:03:55.466477938Z INFO "Initialized 2 toolsets."
2025-08-20 18:03:55 2025-08-20T18:03:55.467492303Z INFO "Server ready to serve!"

Simpan URL Cloud Run untuk layanan Toolbox sebagai variabel lingkungan agar agen ADK tahu tempat menemukannya.

export MCP_TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format "value(status.url)")
echo MCP_TOOLBOX_URL=$MCP_TOOLBOX_URL >> software_bug_assistant/.env

Memperbarui Agen QuantumRoast

Kedua, kita harus menambahkan dependensi untuk MCP Toolbox for Databases SDK (toolbox-core) ke project kita:

uv add toolbox-core==0.5.0

Buka file tools.py untuk menambahkan dukungan bagi alat MCP Toolbox.

cloudshell edit software_bug_assistant/tools.py

Tambahkan kode berikut ke bagian bawah tools.py:

# ----- Example MCP Toolbox for Databases tools -----
import os
from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = os.getenv("MCP_TOOLBOX_URL", "http://127.0.0.1:5000")

# Initialize Toolbox client
toolbox = ToolboxSyncClient(TOOLBOX_URL)
# Load all the tools from toolset
toolbox_tools = toolbox.load_toolset("tickets_toolset")

Sekarang kita dapat mengimpor dan meneruskan toolbox_tools ke agen root di agent.py:

cloudshell edit software_bug_assistant/agent.py

Anda dapat mengganti agent.py dengan kode berikut untuk menyertakan toolbox_tools:

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools],
)

Simpan file dan kembali ke tab yang terbuka dengan ADK Web UI.

Jika Anda tidak sengaja menutup terminal yang menjalankan ADK Web UI, Anda dapat memulainya kembali dengan menjalankan uv run adk web --port 8080 --reload_agents.

Sekarang Anda dapat mengajukan pertanyaan tentang tiket yang disimpan di database tiket internal Cloud SQL kami.

Ajukan pertanyaan seperti salah satu pertanyaan berikut:

• I am seeing an issue with database timeouts, has anyone else seen a similar issue?
• How many bugs are assigned to [e-mail]? Show a table.
• Can you bump the priority of ticket with ID 6 to to P0 - Critical priority
• Create a new ticket (biarkan agen memandu Anda dalam pembuatan bug)

Agen ADK kami kini telah berhasil mengkueri database kami melalui alat MCP Toolbox for Databases.🚀

10. Opsional: Alat MCP (API)

Bagaimana cara menghubungkan agen ADK kita ke alat MCP yang tidak memiliki SDK sendiri seperti MCP Toolbox for Database?

ADK mendukung alat MCP generik melalui class MCPToolset. Class MCPToolset adalah mekanisme utama ADK untuk mengintegrasikan alat dari server MCP.

MCPToolset dapat digunakan untuk terhubung ke server MCP lokal atau jarak jauh. Di QuantumRoast, kita ingin menghubungkan agen kita ke server MCP jarak jauh GitHub — untuk memanggil API GitHub dengan mudah. Dengan demikian, agen kami dapat mengambil informasi tentang masalah dari repositori software publik atau bahkan codebase kami sendiri. Server MCP GitHub mengekspos berbagai bagian fungsi GitHub, mulai dari masalah dan permintaan pull, hingga notifikasi dan keamanan kode.

Token Akses Pribadi (PAT) GitHub

Untuk mengautentikasi dengan server MCP GitHub, Anda memerlukan Token Akses Pribadi GitHub.

Untuk mendapatkannya, ikuti langkah-langkah berikut:

1. Buka setelan Developer GitHub Anda.
2. Klik "Personal access tokens" -> "Tokens (classic)".
3. Klik "Buat token baru" -> "Buat token baru (klasik)".
4. Beri nama deskriptif untuk token Anda.
5. Tetapkan tanggal habis masa berlaku untuk token Anda.
6. Penting: Demi keamanan, berikan cakupan yang paling terbatas yang diperlukan untuk token Anda. Untuk akses hanya baca ke repositori, cakupan repo:status, public_repo, dan read:user sering kali sudah cukup. Hindari memberikan izin admin atau akses repositori penuh kecuali benar-benar diperlukan.
7. Klik Generate token.
8. Salin token yang dihasilkan.

Di terminal Cloud Shell, jalankan perintah berikut untuk menetapkan PAT GitHub agar dapat digunakan oleh agen. Ganti YOUR_GITHUB_PAT dengan PAT yang Anda buat.

export GITHUB_PAT=YOUR_GITHUB_PAT

Memperbarui Agen QuantumRoast

Untuk asisten bug kami, kami hanya akan mengekspos beberapa alat GitHub hanya baca, untuk memungkinkan karyawan QuantumRoast menemukan masalah terkait dependensi open source, untuk melihat apakah hal itu dapat membantu menemukan penyebab utama bug yang mereka lihat di sistem tiket internal. Kita akan menggunakan MCPToolset ADK dengan tool_filter untuk menyiapkannya. tool-filter hanya mengekspos alat GitHub yang kita butuhkan, yang tidak hanya menyembunyikan alat yang tidak ingin kita akses oleh pengguna (misalnya: tindakan repositori yang sensitif), tetapi juga melindungi model agen agar tidak kewalahan saat mencoba memilih alat yang tepat untuk tugas tersebut.

Buka file tools.py untuk menambahkan dukungan bagi alat GitHub.

cloudshell edit software_bug_assistant/tools.py

Tambahkan kode berikut ke bagian bawah tools.py:

# ----- Example MCP Tools with MCPToolset (GitHub) -----
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://api.githubcopilot.com/mcp/",
        headers={
            "Authorization": "Bearer " + os.getenv("GITHUB_PAT"),
        },
    ),
    # Read only tools
    tool_filter=[
        "search_repositories",
        "search_issues",
        "list_issues",
        "get_issue",
        "list_pull_requests",
        "get_pull_request",
    ],
)

Perhatikan juga bagaimana kita perlu memberikan Token Akses Pribadi (PAT) GitHub ke definisi MCPToolset, sama seperti cara Anda memberikan token autentikasi saat menyiapkan klien API standar dalam kode Anda. PAT ini hanya memiliki cakupan untuk mengakses data repositori publik, tanpa cakupan terkait tindakan pengguna atau repositori yang sensitif.

Sekarang kita dapat mengimpor dan meneruskan mcp_tools ke agen root di agent.py:

cloudshell edit software_bug_assistant/agent.py

Anda dapat mengganti agent.py dengan kode berikut untuk menyertakan mcp_tools:

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, mcp_tools, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools, mcp_tools],
)

Simpan file dan kembali ke tab yang terbuka dengan ADK Web UI.

Jika Anda tidak sengaja menutup terminal yang menjalankan ADK Web UI, Anda dapat memulainya kembali dengan menjalankan uv run adk web --port 8080 --reload_agents.

Sekarang, kita memiliki serangkaian alat MCP GitHub yang dapat dipanggil oleh agen kita. Layanan QuantumRoast mengandalkan utilitas XZ, alat kompresi data. Sistem tiket bug internal kami melacak CVE (kerentanan keamanan) dari tahun lalu, yang dapat kami lacak kembali ke repositori GitHub XZ Utils menggunakan alat StackOverflow dan Google Penelusuran. Kemudian, kita dapat menggunakan salah satu alat MCP GitHub, search_issues, untuk menentukan kapan dan bagaimana CVE tersebut di-patch:

Tanyakan hal berikut kepada agen:

• Find the official XZ Utils GitHub repository
• Search the repository for issues related to CVE-2024-3094

Anda akan melihat alat GitHub dipanggil oleh agen.

Agen QuantumRoast ADK kini dapat berinteraksi dengan alat server MCP GitHub. 🤩

11. Selamat

Selamat! Anda telah berhasil membuat agen asisten bug QuantumRoast menggunakan Agent Development Kit (ADK) dan mengintegrasikan berbagai jenis alat untuk meningkatkan kemampuannya. Anda memulai dengan agen dasar dan secara progresif menambahkan Alat Fungsi, Alat Bawaan, Alat Pihak Ketiga, dan Alat MCP.

Yang telah kita bahas

• Cara menyiapkan project Python untuk pengembangan ADK.
• Cara membuat agen ADK dasar.
• Cara menerapkan dan menggunakan Alat Fungsi.
• Cara mengintegrasikan Alat Bawaan seperti Google Penelusuran.
• Cara memanfaatkan Alat Pihak Ketiga dari framework seperti LangChain dalam ADK.
• Cara menggunakan Alat MCP untuk berinteraksi dengan database (Cloud SQL) dan API.

Pembersihan

Anda dapat menghapus project Cloud untuk menghindari biaya tambahan.

Meskipun Cloud Run tidak mengenakan biaya saat layanannya tidak digunakan, Anda mungkin tetap ditagih atas penyimpanan image container di Artifact Registry. Menghapus project Cloud akan menghentikan penagihan untuk semua resource yang digunakan dalam project tersebut.

Jika Anda ingin, hapus project:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

Anda juga dapat menghapus resource yang tidak diperlukan dari disk cloudshell. Anda dapat:

1. Hapus direktori project codelab:

   rm -rf ~/quantum-roast
   

2. Peringatan! Tindakan berikutnya ini tidak dapat diurungkan. Jika ingin menghapus semua yang ada di Cloud Shell untuk mengosongkan ruang penyimpanan, Anda dapat menghapus seluruh direktori beranda. Berhati-hatilah agar semua yang ingin Anda simpan disimpan di tempat lain.

   sudo rm -rf $HOME