1. Pengantar
Dalam codelab ini, Anda akan membuat agen menggunakan Agent Development Kit (ADK) yang memanfaatkan MCP Toolbox for Databases.
Selama mengikuti codelab, Anda akan menggunakan pendekatan langkah demi langkah sebagai berikut:
- Sediakan database Cloud SQL untuk PostgreSQL yang akan memiliki database hotel dan data sampel.
- Siapkan MCP Toolbox for Databases, yang menyediakan akses ke data.
- Desain dan Kembangkan Agen menggunakan Agent Development Kit (ADK) yang akan memanfaatkan MCP Toolbox untuk menjawab kueri dari pengguna.
- Jelajahi opsi untuk menguji Agen dan MCP Toolbox for Databases secara lokal dan di Google Cloud melalui layanan Cloud Run.
Yang akan Anda lakukan
- Merancang, Membangun, dan Men-deploy Agen yang akan menjawab kueri pengguna tentang hotel di suatu lokasi atau menelusuri hotel berdasarkan nama.
Yang akan Anda pelajari
- Menyediakan dan mengisi database Cloud SQL untuk PostgreSQL dengan data sampel.
- Siapkan MCP Toolbox for Databases untuk instance database Cloud SQL for PostgreSQL.
- Desain dan kembangkan Agen menggunakan Agent Development Kit (ADK) untuk menjawab kueri pengguna.
- Uji Agent dan MCP Toolbox for Databases di lingkungan lokal.
- (Opsional) Deploy Agen dan MCP Toolbox for Databases di Google Cloud.
Yang Anda butuhkan
- Browser web Chrome
- Akun Gmail
- Project Cloud dengan penagihan diaktifkan
Codelab ini, yang dirancang untuk developer dari semua level (termasuk pemula), menggunakan Python dalam aplikasi contohnya. Namun, pengetahuan Python tidak diperlukan dan kemampuan membaca kode dasar akan cukup untuk memahami konsep yang disajikan.
2. Sebelum memulai
Membuat project
- Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
- Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project .
- Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan bq. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
- Setelah terhubung ke Cloud Shell, Anda dapat memeriksa bahwa Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:
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>
- Aktifkan API yang diperlukan melalui perintah yang ditampilkan di bawah. Proses ini mungkin memerlukan waktu beberapa menit, jadi harap bersabar.
gcloud services enable cloudresourcemanager.googleapis.com \
servicenetworking.googleapis.com \
run.googleapis.com \
cloudbuild.googleapis.com \
cloudfunctions.googleapis.com \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com
Jika perintah berhasil dieksekusi, Anda akan melihat pesan yang mirip dengan yang ditampilkan di bawah:
Operation "operations/..." finished successfully.
Alternatif untuk perintah gcloud adalah melalui konsol dengan menelusuri setiap produk atau menggunakan link ini.
Jika ada API yang terlewat, Anda dapat mengaktifkannya kapan saja selama pelaksanaan.
Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.
3. Membuat instance Cloud SQL
Kita akan menggunakan instance Google Cloud SQL untuk PostgreSQL guna menyimpan data hotel. Cloud SQL untuk PostgreSQL adalah layanan database terkelola sepenuhnya yang membantu Anda menyiapkan, memelihara, mengelola, dan mengatur database relasional PostgreSQL di Google Cloud Platform.
Jalankan perintah berikut di Cloud Shell untuk membuat instance:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Perintah ini memerlukan waktu sekitar 3-5 menit untuk dijalankan. Setelah perintah berhasil dieksekusi, Anda akan melihat output yang menunjukkan bahwa perintah telah selesai, beserta informasi instance Cloud SQL Anda seperti NAME, DATABASE_VERSION, LOCATION, dll.
4. Menyiapkan database Hotel
Sekarang, tugas kita adalah membuat beberapa data contoh untuk Agen Hotel.
Buka halaman Cloud SQL di konsol Cloud.Anda akan melihat hoteldb-instance siap dan dibuat. Klik nama instance (hoteldb-instance) seperti yang ditunjukkan di bawah:
Dari menu kiri Cloud SQL, buka opsi menu Cloud SQL Studio seperti yang ditunjukkan di bawah:
Anda akan diminta untuk login ke Cloud SQL Studio tempat kami akan memberikan beberapa perintah SQL. Pilih postgres untuk opsi Database dan untuk opsi Pengguna dan Sandi, nilai yang akan digunakan adalah postgres. Klik AUTHENTICATE.
Pertama, buat tabel hotel sesuai dengan skema di bawah. Di salah satu panel Editor di Cloud SQL Studio, jalankan SQL berikut:
CREATE TABLE hotels(
id INTEGER NOT NULL PRIMARY KEY,
name VARCHAR NOT NULL,
location VARCHAR NOT NULL,
price_tier VARCHAR NOT NULL,
checkin_date DATE NOT NULL,
checkout_date DATE NOT NULL,
booked BIT NOT NULL
);
Sekarang, isi tabel hotel dengan data contoh. Jalankan SQL berikut:
INSERT INTO hotels(id, name, location, price_tier, checkin_date, checkout_date, booked)
VALUES
(1, 'Hilton Basel', 'Basel', 'Luxury', '2024-04-20', '2024-04-22', B'0'),
(2, 'Marriott Zurich', 'Zurich', 'Upscale', '2024-04-14', '2024-04-21', B'0'),
(3, 'Hyatt Regency Basel', 'Basel', 'Upper Upscale', '2024-04-02', '2024-04-20', B'0'),
(4, 'Radisson Blu Lucerne', 'Lucerne', 'Midscale', '2024-04-05', '2024-04-24', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-01', '2024-04-23', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-02', '2024-04-27', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-09', '2024-04-24', B'0'),
(9, 'Courtyard Zurich', 'Zurich', 'Upscale', '2024-04-03', '2024-04-13', B'0'),
(10, 'Comfort Inn Bern', 'Bern', 'Midscale', '2024-04-04', '2024-04-16', B'0');
Mari kita validasi data dengan menjalankan SQL SELECT seperti yang ditunjukkan di bawah ini:
SELECT * FROM hotels;
Anda akan melihat sejumlah data dalam tabel hotel seperti yang ditunjukkan di bawah:
Kita telah menyelesaikan proses penyiapan instance Cloud SQL dan telah membuat data sampel. Di bagian berikutnya, kita akan menyiapkan MCP Toolbox for Databases.
5. Menyiapkan MCP Toolbox for Databases
MCP Toolbox for Databases adalah server MCP open source untuk database. Alat ini dirancang dengan mempertimbangkan kualitas produksi dan tingkat perusahaan. Hal ini memungkinkan Anda mengembangkan alat dengan lebih mudah, cepat, dan aman dengan menangani kompleksitas seperti penggabungan koneksi, autentikasi, dan lainnya.
Toolbox membantu Anda membangun alat AI Generatif yang memungkinkan agen Anda mengakses data dalam database Anda. 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 siap pakai dengan dukungan bawaan untuk OpenTelemetry.
Toolbox berada di antara framework orkestrasi aplikasi dan database Anda, menyediakan bidang kontrol yang digunakan untuk mengubah, mendistribusikan, atau memanggil alat. Hal ini menyederhanakan pengelolaan alat Anda dengan memberi Anda lokasi terpusat untuk menyimpan dan memperbarui alat, sehingga Anda dapat membagikan alat di antara agen dan aplikasi serta memperbarui alat tersebut tanpa perlu men-deploy ulang aplikasi Anda.
Anda dapat melihat bahwa salah satu database yang didukung oleh MCP Toolbox for Databases adalah Cloud SQL dan kita telah menyediakannya di bagian sebelumnya.
Menginstal Toolbox
Buka Terminal Cloud Shell dan buat folder bernama mcp-toolbox.
mkdir mcp-toolbox
Buka folder mcp-toolbox melalui perintah yang ditampilkan di bawah:
cd mcp-toolbox
Instal versi biner MCP Toolbox for Databases melalui skrip yang diberikan di bawah. Perintah di bawah ini adalah untuk Linux, tetapi jika Anda menggunakan Mac atau Windows, pastikan Anda mendownload biner yang benar. Lihat halaman rilis untuk Sistem Operasi dan Arsitektur Anda, lalu download biner yang benar.
export VERSION=0.8.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Sekarang kita memiliki versi biner toolbox yang siap digunakan. Langkah berikutnya adalah mengonfigurasi toolbox dengan sumber data dan konfigurasi lainnya.
Mengonfigurasi tools.yaml
Cara utama untuk mengonfigurasi Toolbox adalah melalui file tools.yaml. Buat file bernama tools.yaml di folder yang sama, yaitu mcp-toolbox, yang isinya ditampilkan di bawah.
Anda dapat menggunakan editor nano yang tersedia di Cloud Shell. Perintah nano adalah sebagai berikut: "nano tools.yaml".
Jangan lupa untuk mengganti nilai YOUR_PROJECT_ID dengan ID Project Google Cloud Anda.
sources:
my-cloud-sql-source:
kind: cloud-sql-postgres
project: YOUR_PROJECT_ID
region: us-central1
instance: hoteldb-instance
database: postgres
user: postgres
password: "postgres"
tools:
search-hotels-by-name:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on name.
parameters:
- name: name
type: string
description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';
search-hotels-by-location:
kind: postgres-sql
source: my-cloud-sql-source
description: Search for hotels based on location. Result is sorted by price from least to most expensive.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: |
SELECT *
FROM hotels
WHERE location ILIKE '%' || $1 || '%'
ORDER BY
CASE price_tier
WHEN 'Midscale' THEN 1
WHEN 'Upper Midscale' THEN 2
WHEN 'Upscale' THEN 3
WHEN 'Upper Upscale' THEN 4
WHEN 'Luxury' THEN 5
ELSE 99 -- Handle any unexpected values, place them at the end
END;
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Mari kita pahami file ini secara singkat:
Sourcesmewakili berbagai sumber data yang dapat berinteraksi dengan alat. Sumber merepresentasikan sumber data yang dapat berinteraksi dengan alat. Anda dapat menentukanSourcessebagai peta di bagian sumber file tools.yaml. Biasanya, konfigurasi sumber akan berisi informasi apa pun yang diperlukan untuk terhubung dan berinteraksi dengan database. Dalam kasus ini, kita telah mengonfigurasi satu sumber yang mengarah ke instance Cloud SQL untuk PostgreSQL dengan kredensial. Untuk mengetahui informasi selengkapnya, lihat referensi Sumber.Toolsmenentukan tindakan yang dapat dilakukan agen – seperti membaca dan menulis ke sumber. Alat merepresentasikan tindakan yang dapat dilakukan agen Anda, seperti menjalankan pernyataan SQL. Anda dapat menentukanToolssebagai peta di bagian alat pada file tools.yaml. Biasanya, alat akan memerlukan sumber untuk ditindaklanjuti. Dalam kasus ini, kita menentukan dua alat:search-hotels-by-namedansearch-hotels-by-locationserta menentukan sumber yang sedang dioperasikannya, bersama dengan SQL dan parameter. Untuk mengetahui informasi selengkapnya, lihat referensi Alat.- Terakhir, ada
Toolset, yang memungkinkan Anda menentukan grup alat yang ingin dimuat bersama. Hal ini dapat berguna untuk menentukan berbagai grup berdasarkan agen atau aplikasi. Dalam kasus ini, kita memiliki satu set alat bernamamy_first_toolset, yang berisi dua alat yang telah kita tentukan.
Menjalankan MCP Toolbox for Databases Server
Jalankan perintah berikut (dari folder mcp-toolbox) untuk memulai server:
./toolbox --tools-file "tools.yaml"
Idealnya, Anda akan melihat output bahwa Server telah dapat terhubung ke sumber data kami dan telah memuat toolset dan alat. Contoh output diberikan di bawah:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Server MCP Toolbox berjalan secara default di port 5000. Jika Anda mendapati bahwa port 5000 sudah digunakan, Anda dapat menggunakan port lain (misalnya 7000) sesuai perintah yang ditunjukkan di bawah. Sebagai gantinya, gunakan 7000, bukan port 5000 dalam perintah berikutnya.
./toolbox --tools-file "tools.yaml" --port 7000
Mari kita gunakan Cloud Shell untuk mengujinya.
Klik Pratinjau Web di Cloud Shell seperti yang ditunjukkan di bawah:
Klik Ubah port dan tetapkan port ke 5000 seperti yang ditunjukkan di bawah, lalu klik Ubah dan Pratinjau.
Ini akan menghasilkan output berikut:
Di URL browser, tambahkan berikut ini ke bagian akhir URL:
/api/toolset
Tindakan ini akan memunculkan alat yang saat ini dikonfigurasi. Contoh output ditampilkan di bawah:
{
"serverVersion": "0.3.0+container.12222fe27ae070f2689a0632d60fda45412d1f97",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location.",
"parameters": [
{
"name": "location",
"type": "string",
"description": "The location of the hotel.",
"authSources": []
}
]
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"description": "The name of the hotel.",
"authSources": []
}
]
}
}
}
MCP Toolkit for Databases menjelaskan cara Pythonic bagi Anda untuk memvalidasi dan menguji alat, yang didokumentasikan di sini. Kita akan melewatinya dan langsung membahas Agent Development Kit (ADK) di bagian berikutnya yang akan menggunakan alat ini.
6. Menulis Agen dengan Agent Development Kit (ADK)
Menginstal Agent Development Kit (ADK)
Buka tab terminal baru di Cloud Shell dan buat folder bernama my-agents sebagai berikut. Buka juga folder my-agents.
mkdir my-agents
cd my-agents
Sekarang, mari kita buat lingkungan Python virtual menggunakan venv sebagai berikut:
python -m venv .venv
Aktifkan lingkungan virtual sebagai berikut:
source .venv/bin/activate
Instal paket ADK dan MCP Toolbox for Databases beserta dependensi langchain sebagai berikut:
pip install google-adk toolbox-core
Sekarang Anda dapat memanggil utilitas adk sebagai berikut.
adk
Daftar perintah akan ditampilkan.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--help Show this message and exit.
Commands:
api_server Starts a FastAPI server for agents.
create Creates a new app in the current folder with prepopulated agent template.
deploy Deploys agent to hosted environments.
eval Evaluates an agent given the eval sets.
run Runs an interactive CLI for a certain agent.
web Starts a FastAPI server with Web UI for agents.
Membuat Aplikasi Agen pertama kita
Sekarang kita akan menggunakan adk untuk membuat scaffolding bagi Aplikasi Agen Hotel melalui perintah adk create dengan nama aplikasi **(hotel-agent-app)**seperti yang diberikan di bawah.
adk create hotel-agent-app
Ikuti langkah-langkahnya dan pilih opsi berikut:
- Model Gemini untuk memilih model agen root.
- Pilih Vertex AI untuk backend.
- Project ID dan region Google default Anda akan ditampilkan. Pilih default itu sendiri.
Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2
You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai
Enter Google Cloud project ID [gcp-experiments-349209]:
Enter Google Cloud region [us-central1]:
Agent created in /home/romin/hotel-agent-app:
- .env
- __init__.py
- agent.py
Amati folder tempat template default dan file yang diperlukan untuk Agen telah dibuat.
Yang pertama adalah file .env. Isinya ditampilkan di bawah:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Nilai tersebut menunjukkan bahwa kita akan menggunakan Gemini melalui Vertex AI bersama dengan nilai masing-masing untuk Project ID dan lokasi Google Cloud.
Kemudian, kita memiliki file __init__.py yang menandai folder sebagai modul dan memiliki satu pernyataan yang mengimpor agen dari file agent.py.
from . import agent
Terakhir, mari kita lihat file agent.py. Isinya ditampilkan di bawah:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Ini adalah Agen paling sederhana yang dapat Anda tulis dengan ADK. Dari halaman dokumentasi ADK, Agen adalah unit eksekusi mandiri yang dirancang untuk bertindak secara mandiri guna mencapai tujuan tertentu. Agen dapat melakukan tugas, berinteraksi dengan pengguna, menggunakan alat eksternal, dan berkoordinasi dengan agen lain.
Secara khusus, LLMAgent, yang umumnya diberi alias sebagai Agent, menggunakan Model Bahasa Besar (LLM) sebagai mesin intinya untuk memahami bahasa alami, melakukan penalaran, membuat rencana, menghasilkan respons, dan secara dinamis memutuskan cara melanjutkan atau alat yang akan digunakan, sehingga ideal untuk tugas yang fleksibel dan berfokus pada bahasa. Pelajari lebih lanjut Agen LLM di sini.
Mari kita ubah kode untuk agent.py sebagai berikut:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.0-flash-001',
name='hotel_agent',
description='A helpful assistant that answers questions about a specific city.',
instruction='Answer user questions about a specific city to the best of your knowledge. Do not answer questions outside of this.',
)
Menguji Aplikasi Agen secara lokal
Dari jendela terminal yang ada, berikan perintah berikut. Pastikan Anda berada di folder induk (my-agents) yang berisi folder hotel-agent-app.
adk web
Contoh eksekusi ditampilkan di bawah:
INFO: Started server process [5015]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
Klik link terakhir dan konsol web akan muncul untuk menguji Agen. Anda akan melihat tampilan berikut diluncurkan di browser seperti yang ditunjukkan di bawah:
Perhatikan bahwa di kiri atas, aplikasi agen hotel telah diidentifikasi. Sekarang Anda dapat mulai berkomunikasi dengan Agen. Berikan beberapa perintah yang menanyakan tentang kota. Contoh percakapan ditampilkan di bawah ini:
Anda dapat mematikan proses yang berjalan di terminal Cloud Shell (Ctrl-C).
Cara alternatif untuk menguji Agen adalah melalui perintah adk run seperti yang diberikan di bawah dari folder my-agents.
adk run hotel-agent-app
Coba perintahnya dan Anda dapat berkomunikasi dengan Agen melalui command line (terminal). Ketik exit untuk menutup percakapan.
7. Menghubungkan Agen ke Alat
Sekarang kita tahu cara menulis Agen dan mengujinya secara lokal. Kita akan menghubungkan Agen ini ke Alat. Dalam konteks ADK, Alat merepresentasikan kemampuan spesifik yang diberikan kepada agen AI, sehingga memungkinkannya melakukan tindakan dan berinteraksi dengan dunia di luar kemampuan inti pembuatan teks dan penalaran.
Dalam kasus ini, kita akan melengkapi Agen kita dengan Alat yang telah kita konfigurasi di Toolbox MCP untuk Database.
Ubah file agent.py dengan kode berikut. Perhatikan bahwa kita menggunakan port default 5000 dalam kode, tetapi jika Anda menggunakan nomor port alternatif, gunakan nomor tersebut.
from google.adk.agents import Agent
from toolbox_core import ToolboxSyncClient
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
# Load single tool
# tools = toolbox.load_tool('search-hotels-by-location')
# Load all the tools
tools = toolbox.load_toolset('my_first_toolset')
root_agent = Agent(
name="hotel_agent",
model="gemini-2.0-flash",
description=(
"Agent to answer questions about hotels in a city or hotels by name."
),
instruction=(
"You are a helpful agent who can answer user questions about the hotels in a specific city or hotels by name. Use the tools to answer the question"
),
tools=tools,
)
Sekarang kita dapat menguji Agen yang akan mengambil data sebenarnya dari database PostgreSQL yang telah dikonfigurasi dengan MCP Toolbox for Databases.
Untuk melakukannya, ikuti urutan berikut:
Di salah satu terminal Cloud Shell, luncurkan MCP Toolbox for Databases. Anda mungkin sudah menjalankannya secara lokal di port 5000 seperti yang kita uji sebelumnya. Jika tidak, jalankan perintah berikut (dari folder mcp-toolbox) untuk memulai server:
./toolbox --tools_file "tools.yaml"
Idealnya, Anda akan melihat output bahwa Server telah dapat terhubung ke sumber data kami dan telah memuat toolset dan alat. Contoh output diberikan di bawah:
./toolbox --tools-file "tools.yaml"
2025-04-23T14:32:29.564903079Z INFO "Initialized 1 sources."
2025-04-23T14:32:29.565009291Z INFO "Initialized 0 authServices."
2025-04-23T14:32:29.565070176Z INFO "Initialized 2 tools."
2025-04-23T14:32:29.565120847Z INFO "Initialized 2 toolsets."
2025-04-23T14:32:29.565510068Z INFO "Server ready to serve!"
Setelah server MCP berhasil dimulai, di terminal lain, luncurkan Agen seperti yang telah kita lakukan sebelumnya melalui perintah adk run (dari folder my-agents) yang ditunjukkan di bawah. Anda juga dapat menggunakan perintah adk web jika mau.
$ adk run hotel-agent-app/
Log setup complete: /tmp/agents_log/agent.20250423_170001.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent hotel_agent, type exit to exit.
user: what can you do for me?
[hotel_agent]: I can help you find hotels in a specific city or search for hotels by name.
user: I would like to search for hotels
[hotel_agent]: Great, do you have a specific city or hotel name in mind?
user: Yes a specific city
[hotel_agent]: Great, which city are you interested in?
user: Basel
[hotel_agent]: OK. I found three hotels in Basel: Hilton Basel, Hyatt Regency Basel, and Holiday Inn Basel.
Perhatikan bahwa Agen kini menggunakan dua alat yang telah kita konfigurasi di MCP Toolbox for Databases (search-hotels-by-name dan search-hotels-by-location) dan memberikan opsi yang benar kepada kita. Kemudian, aplikasi dapat mengambil data dari database instance PostgreSQL secara lancar dan memformat respons dengan tepat.
Dengan demikian, pengembangan dan pengujian lokal Agen Hotel yang kami buat menggunakan Agent Development Kit (ADK) dan didukung oleh alat yang kami konfigurasi di MCP Toolbox for Databases telah selesai.
8. (Opsional) Men-deploy MCP Toolbox for Databases and Agent ke Cloud Run
Di bagian sebelumnya, kita menggunakan terminal Cloud Shell untuk meluncurkan server MCP Toolbox dan menguji alat dengan Agent. Aplikasi ini berjalan secara lokal di lingkungan Cloud Shell.
Anda memiliki opsi untuk men-deploy server MCP Toolbox dan Agen ke layanan Google Cloud yang dapat menghosting aplikasi ini untuk kami.
Menghosting server MCP Toolbox di Cloud Run
Pertama, kita dapat memulai dengan server MCP Toolbox dan menghostingnya di Cloud Run. Kemudian, kita akan mendapatkan endpoint publik yang dapat diintegrasikan dengan aplikasi lain dan/atau aplikasi Agen. Petunjuk untuk menghostingnya di Cloud Run diberikan di sini. Sekarang kita akan membahas langkah-langkah utamanya.
Luncurkan Terminal Cloud Shell baru atau gunakan Terminal Cloud Shell yang ada. Buka folder mcp-toolbox, tempat biner toolbox dan tools.yaml berada.
Jalankan perintah berikut (penjelasan diberikan untuk setiap perintah):
Tetapkan variabel PROJECT_ID untuk mengarah ke Project ID Google Cloud Anda.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Selanjutnya, pastikan layanan Google Cloud berikut diaktifkan di project.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Mari buat akun layanan terpisah yang akan bertindak sebagai identitas untuk layanan Toolbox yang akan kita deploy di Google Cloud Run. Kami juga memastikan bahwa akun layanan ini memiliki peran yang benar, yaitu kemampuan untuk mengakses Secret Manager dan berkomunikasi dengan Cloud SQL.
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
Kita akan mengupload file tools.yaml sebagai secret dan karena kita harus menginstal Toolbox di Cloud Run, kita akan menggunakan Image container terbaru untuk toolbox dan menyetelnya di variabel IMAGE.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Langkah terakhir dalam perintah deployment yang sudah dikenal ke Cloud Run:
gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated
Tindakan ini akan memulai proses men-deploy Toolbox Server dengan tools.yaml yang dikonfigurasi ke Cloud Run. Setelah deployment berhasil, Anda akan melihat pesan yang mirip dengan berikut ini:
Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.
OK Creating Revision...
OK Routing traffic...
OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app
Sekarang Anda dapat membuka Service URL yang tercantum di atas di browser. Pesan "Hello World" yang kita lihat sebelumnya akan ditampilkan. Selain itu, Anda juga dapat membuka URL berikut untuk melihat alat yang tersedia:
SERVICE URL/api/toolset
Anda juga dapat membuka Cloud Run dari konsol Google Cloud dan Anda akan melihat layanan Toolbox tersedia dalam daftar layanan di Cloud Run.
Catatan: Jika Anda masih ingin menjalankan Agen Hotel secara lokal dan tetap terhubung ke layanan Cloud Run yang baru di-deploy, Anda hanya perlu melakukan satu perubahan pada file my-agents/hotel-agent-app/agent.py.
Daripada berikut ini:
toolbox = ToolboxTool("http://127.0.0.1:5000")
Ubah ke URL Layanan layanan Cloud Run seperti yang diberikan di bawah:
toolbox = ToolboxTool("CLOUD_RUN_SERVICE_URL")
Uji Aplikasi Agen menggunakan adk run atau adk web seperti yang telah kita lihat sebelumnya.
Men-deploy Aplikasi Agen Hotel di Cloud Run
Langkah pertama adalah memastikan bahwa Anda telah melakukan perubahan di my-agents/hotel-agent-app/agent.py seperti yang diinstruksikan di atas untuk mengarah ke URL layanan Toolbox yang berjalan di Cloud Run, bukan host lokal.
Di sesi Terminal Cloud Shell baru atau Terminal yang ada, pastikan Anda berada di lingkungan virtual Python yang benar yang kita siapkan sebelumnya.
Pertama, mari kita buat file requirements.txt di folder my-agents/hotel-agent-app seperti yang ditunjukkan di bawah:
google-adk
toolbox-core
Buka folder my-agents dan tetapkan variabel lingkungan berikut terlebih dahulu:
export GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=us-central1
export AGENT_PATH="hotel-agent-app/"
export SERVICE_NAME="hotels-service"
export APP_NAME="hotels-app"
export GOOGLE_GENAI_USE_VERTEXAI=True
Terakhir, deploy Aplikasi Agen ke Cloud Run melalui perintah cloud_run adk deploy seperti yang diberikan di bawah. Jika Anda diminta untuk mengizinkan pemanggilan yang tidak diautentikasi ke layanan, berikan "y" sebagai nilai untuk saat ini.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Tindakan ini akan memulai proses men-deploy Aplikasi Agen Hotel ke Cloud Run. Tindakan ini akan mengupload sumber, mengemasnya ke dalam Container Docker, mengirimkannya ke Artifact Registry, lalu men-deploy layanan di Cloud Run. Proses ini mungkin memerlukan waktu beberapa menit, jadi harap bersabar.
Anda akan melihat pesan yang mirip dengan yang di bawah ini:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250424_045623
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250424_045623/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_GOOGLE_CLOUD_PROJECT] region [us-central1]
| Building and deploying... Uploading sources.
| Uploading sources...
OK Building and deploying... Done.
OK Uploading sources...
OK Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds;region=us-central1/b02f5a74-6da6-4367-aaba-0c8aa098edf5?project=415458962931].
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00002-cpm] has been deployed and is serving 100 percent of traffic.
Service URL: https://hotels-service-<SOME_ID>.us-central1.run.app
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250424_045623
Setelah deployment berhasil, Anda akan diberi nilai untuk URL Layanan, yang kemudian dapat Anda akses di browser untuk melihat Aplikasi Web yang sama yang memungkinkan Anda melakukan chat dengan Agen Hotel, seperti yang kita lihat sebelumnya dalam penyiapan lokal.
9. Pembersihan
Agar tidak menimbulkan biaya berkelanjutan pada akun Google Cloud Anda, penting untuk menghapus resource yang kita buat selama workshop ini. Kita akan menghapus instance Cloud SQL dan secara opsional, jika Anda telah men-deploy Toolbox dan Aplikasi Hotel ke Cloud Run, kita juga akan menghapus layanan tersebut.
Pastikan variabel lingkungan berikut ditetapkan dengan benar, sesuai dengan project dan region Anda:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Dua perintah berikut akan menghapus layanan Cloud Run yang telah kita deploy:
gcloud run services delete toolbox --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
gcloud run services delete hotels-service --platform=managed --region=${REGION} --project=${PROJECT_ID} --quiet
Perintah berikut akan menghapus instance Cloud SQL:
gcloud sql instances delete hoteldb-instance
10. Selamat
Selamat, Anda telah berhasil membuat agen menggunakan Agent Development Kit (ADK) yang memanfaatkan MCP Toolbox for Databases.