Membuat Agen Perjalanan menggunakan MCP Toolbox untuk Database dan Agent Development Kit (ADK)
Tentang codelab ini
1. Pengantar
Dalam codelab ini, Anda akan mem-build agen menggunakan Agent Development Kit (ADK) yang menggunakan MCP Toolbox for Databases.
Melalui codelab ini, 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 untuk Database, yang memberikan akses ke data.
- Buat Desain dan Kembangkan Agen menggunakan Agent Development Kit (ADK) yang akan menggunakan MCP Toolbox untuk menjawab kueri dari pengguna.
- Jelajahi opsi untuk menguji Agen dan MCP Toolbox untuk Database secara lokal dan di Google Cloud melalui layanan Cloud Run.
Yang akan Anda lakukan
- Buat Desain, Build, dan 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 untuk PostgreSQL.
- Buat desain dan kembangkan Agen menggunakan Agent Development Kit (ADK) untuk menjawab kueri pengguna.
- Uji Agen dan MCP Toolbox untuk Database di lingkungan lokal.
- (Opsional) Deploy Agen dan MCP Toolbox untuk Database 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 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 Aktifkan Cloud Shell di bagian atas konsol Google Cloud.
- Setelah terhubung ke Cloud Shell, Anda akan memeriksa apakah Anda sudah diautentikasi dan project 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. Tindakan 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
Setelah perintah berhasil dieksekusi, Anda akan melihat pesan yang mirip dengan yang ditampilkan di bawah ini:
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 proses penerapan.
Baca dokumentasi untuk mempelajari perintah gcloud dan penggunaannya.
3. Membuat instance Cloud SQL
Kita akan menggunakan instance Google Cloud SQL untuk PostgreSQL untuk 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 \
--cpu=2 \
--memory=8GiB \
--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 seperti NAME, DATABASE_VERSION, LOCATION, dll.
4. Menyiapkan database Hotel
Tugas kita sekarang adalah membuat beberapa contoh data 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 Pengguna dan Sandi, nilai yang akan digunakan adalah postgres. Klik AUTHENTICATE.
Pertama-tama, mari kita buat tabel hotel sesuai dengan skema yang diberikan 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, mari kita 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-22', '2024-04-20', 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-24', '2024-04-05', B'0'),
(5, 'Best Western Bern', 'Bern', 'Upper Midscale', '2024-04-23', '2024-04-01', B'0'),
(6, 'InterContinental Geneva', 'Geneva', 'Luxury', '2024-04-23', '2024-04-28', B'0'),
(7, 'Sheraton Zurich', 'Zurich', 'Upper Upscale', '2024-04-27', '2024-04-02', B'0'),
(8, 'Holiday Inn Basel', 'Basel', 'Upper Midscale', '2024-04-24', '2024-04-09', 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 di 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 untuk Database.
5. Menyiapkan MCP Toolbox untuk Database
MCP Toolbox for Databases adalah server MCP open source untuk database. Server ini dirancang dengan mempertimbangkan kualitas produksi dan tingkat perusahaan. Dengan demikian, Anda dapat mengembangkan alat dengan lebih mudah, lebih cepat, dan lebih aman dengan menangani kompleksitas seperti penggabungan koneksi, autentikasi, dan lainnya.
Toolbox membantu Anda membuat alat AI Generatif yang memungkinkan agen mengakses data di database Anda. Toolbox menyediakan:
- Pengembangan yang disederhanakan: Mengintegrasikan alat ke agen Anda dalam kurang dari 10 baris kode, menggunakan kembali alat di antara beberapa agen atau framework, dan men-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, yang menyediakan platform kontrol yang digunakan untuk mengubah, mendistribusikan, atau memanggil alat. Alat ini menyederhanakan pengelolaan alat dengan menyediakan lokasi terpusat untuk menyimpan dan mengupdate alat, sehingga Anda dapat membagikan alat antar-agen dan aplikasi serta mengupdate alat tersebut tanpa harus men-deploy ulang aplikasi.
Anda dapat melihat bahwa salah satu database yang didukung oleh MCP Toolbox for Databases adalah Cloud SQL dan kami 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 MCP Toolbox for Databases versi biner melalui skrip yang diberikan di bawah ini:
export VERSION=0.3.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Sekarang kita memiliki toolbox versi biner 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 kontennya 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.
parameters:
- name: location
type: string
description: The location of the hotel.
statement: SELECT * FROM hotels WHERE location ILIKE '%' || $1 || '%';
toolsets:
my_first_toolset:
- search-hotels-by-name
- search-hotels-by-location
Mari kita pahami file ini secara singkat:
Sourcesmewakili berbagai sumber data Anda yang dapat berinteraksi dengan alat. Sumber mewakili sumber data yang dapat berinteraksi dengan alat. Anda dapat menentukanSourcessebagai peta di bagian sumber file tools.yaml. Biasanya, konfigurasi sumber akan berisi informasi 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 informasi selengkapnya, lihat referensi Sumber.Toolsmenentukan tindakan yang dapat dilakukan agen – seperti membaca dan menulis ke sumber. Alat mewakili 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 menjadi sasarannya, beserta SQL dan parameter. Untuk informasi selengkapnya, lihat referensi Alat.- Terakhir, kita memiliki
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 yang disebutmy_first_toolset, yang berisi dua alat yang telah kita tentukan.
Menjalankan Server MCP Toolbox for Databases
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 rangkaian alat dan alat. Contoh output diberikan di bawah ini:
./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. 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.
Tindakan ini akan menampilkan output berikut:
Di URL browser, tambahkan kode berikut ke bagian akhir URL:
/api/toolset
Tindakan ini akan menampilkan alat yang saat ini dikonfigurasi. Contoh output ditampilkan di bawah ini:
{
"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 untuk memvalidasi dan menguji alat, yang didokumentasikan di sini. Kita akan melewatinya dan langsung menggunakan 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 virtual Python 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 sebagai berikut:
pip install google-adk toolbox-core
Sekarang Anda dapat memanggil utilitas adk sebagai berikut.
adk
Tindakan ini akan menampilkan daftar perintah.
$ 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 untuk 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 hal berikut:
- Model Gemini untuk memilih model agen root.
- Pilih Vertex AI untuk backend.
- ID Project Google dan region default Anda akan ditampilkan. Pilih setelan 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 beserta 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 otonom guna mencapai sasaran tertentu. Agen dapat melakukan tugas, berinteraksi dengan pengguna, menggunakan alat eksternal, dan berkoordinasi dengan agen lain.
Secara khusus, LLMAgent, yang biasanya memiliki alias sebagai Agen, menggunakan Model Bahasa Besar (LLM) sebagai mesin intinya untuk memahami bahasa alami, penalaran, perencanaan, menghasilkan respons, dan memutuskan secara dinamis cara melanjutkan atau alat yang akan digunakan, sehingga ideal untuk tugas yang fleksibel dan berfokus pada bahasa. Pelajari Agen LLM lebih lanjut 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 ini:
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 ini:
Perhatikan bahwa di kiri atas, hotel-agent-app telah diidentifikasi. Sekarang Anda dapat mulai berkomunikasi dengan Agen. Berikan beberapa perintah yang menanyakan tentang kota. Contoh percakapan ditampilkan di bawah ini:
Anda dapat menonaktifkan 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 perintah tersebut 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 mewakili kemampuan tertentu yang diberikan kepada agen AI, sehingga dapat melakukan tindakan dan berinteraksi dengan dunia di luar kemampuan penalaran dan pembuatan teks intinya.
Dalam kasus ini, kita akan melengkapi Agen dengan Alat yang telah dikonfigurasi di MCP Toolbox untuk Database.
Ubah file agent.py dengan kode berikut:
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 untuk Database.
Untuk melakukannya, ikuti urutan ini:
Di satu terminal Cloud Shell, luncurkan MCP Toolbox untuk Database. 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 rangkaian alat dan alat. Contoh output diberikan di bawah ini:
./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 ditampilkan 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 konfigurasikan di MCP Toolbox untuk Database (search-hotels-by-name dan search-hotels-by-location) dan memberikan opsi yang benar kepada kita. Kemudian, aplikasi ini dapat mengambil data dari database instance PostgreSQL dengan lancar dan memformat respons yang sesuai.
Tindakan ini akan menyelesaikan pengembangan dan pengujian lokal Agen Hotel yang kita buat menggunakan Agent Development Kit (ADK) dan yang didukung oleh alat yang kita konfigurasikan di MCP Toolbox untuk Database.
8. (Opsional) Men-deploy MCP Toolbox untuk Database dan Agen ke Cloud Run
Di bagian sebelumnya, kita menggunakan terminal Cloud Shell untuk meluncurkan server MCP Toolbox dan menguji alat dengan Agen. 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-tama, kita dapat memulai dengan server MCP Toolbox dan menghostingnya di Cloud Run. Tindakan ini akan memberi kita 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 dalam project.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Mari kita 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 menetapkannya dalam 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 deployment Server Toolbox 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 mengunjungi Service URL yang tercantum di atas di browser. Halaman ini akan menampilkan pesan "Hello World" yang kita lihat sebelumnya. 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 akan melihat layanan Toolbox yang tersedia dalam daftar layanan di Cloud Run.
Catatan: Jika ingin tetap menjalankan Agen Hotel secara lokal dan 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 hal berikut:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Ubah menjadi URL Layanan layanan Cloud Run seperti yang diberikan di bawah:
toolbox = ToolboxSyncClient("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 pada 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 Terminal Cloud Shell baru atau sesi Terminal yang ada, pastikan Anda berada di lingkungan virtual Python yang benar yang telah 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 mari kita 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, mari kita 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, harap 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 deployment 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. Tindakan ini mungkin memerlukan waktu beberapa menit, jadi harap bersabar.
Anda akan melihat pesan yang mirip dengan pesan 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 berhasil di-deploy, Anda akan diberi nilai untuk URL Layanan, yang kemudian dapat diakses di browser untuk melihat Aplikasi Web yang sama yang memungkinkan Anda melakukan chat dengan Agen Hotel, seperti yang kita lihat sebelumnya di penyiapan lokal.
9. Selamat
Selamat, Anda telah berhasil mem-build agen menggunakan Agent Development Kit (ADK) yang menggunakan MCP Toolbox untuk Database.