1. Giriş
Bu codelab'de, Agent Development Kit (ADK)'yi kullanarak MCP Toolbox for Databases'i kullanan bir aracı oluşturacaksınız.
Bu codelab'de aşağıdaki gibi adım adım bir yaklaşım kullanacaksınız:
- Oteller veritabanını ve örnek verileri içeren bir PostgreSQL için Cloud SQL veritabanı sağlayın.
- Verilere erişim sağlayan MCP Toolbox for Databases'i kurun.
- Kullanıcının sorgularını yanıtlamak için MCP Araç Kutusu'nu kullanacak bir aracı, Aracı Geliştirme Kiti (ADK) ile tasarlayıp geliştirin.
- Cloud Run hizmeti aracılığıyla Agent ve MCP Toolbox for Databases'i yerel olarak ve Google Cloud'da test etme seçeneklerini keşfedin.
Yapacaklarınız
- Bir konumdaki otellerle ilgili kullanıcı sorgularını yanıtlayacak veya otelleri ada göre arayacak bir aracı tasarlayın, oluşturun ve dağıtın.
Neler öğreneceksiniz?
- PostgreSQL için Cloud SQL veritabanı sağlama ve örnek verilerle doldurma
- Cloud SQL for PostgreSQL veritabanı örneği için MCP Toolbox for Databases'i kurun.
- Kullanıcı sorgularını yanıtlamak için Agent Development Kit'i (ADK) kullanarak bir aracı tasarlayın ve geliştirin.
- Yerel ortamda veritabanları için Agent ve MCP Toolbox'ı test edin.
- (İsteğe bağlı) Google Cloud'da veritabanları için aracı ve MCP Toolbox'ı dağıtın.
Gerekenler
- Chrome web tarayıcısı
- Gmail hesabı
- Faturalandırmanın etkin olduğu bir Cloud projesi
Her seviyeden geliştirici (yeni başlayanlar dahil) için tasarlanan bu codelab'de örnek uygulamada Python kullanılmaktadır. Ancak Python bilgisi gerekmez ve sunulan kavramları anlamak için temel düzeyde kod okuma becerisi yeterli olacaktır.
2. Başlamadan önce
Proje oluşturma
- Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
- Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Faturalandırmanın projede etkin olup olmadığını kontrol etmeyi öğrenin .
- bq'nun önceden yüklendiği, Google Cloud'da çalışan bir komut satırı ortamı olan Cloud Shell'i kullanacaksınız. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
- Cloud Shell'e bağlandıktan sonra aşağıdaki komutu kullanarak kimliğinizin doğrulanmış olduğunu ve projenin proje kimliğinize ayarlandığını kontrol edin:
gcloud auth list
- gcloud komutunun projeniz hakkında bilgi sahibi olduğunu doğrulamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
- Projeniz ayarlanmamışsa ayarlamak için aşağıdaki komutu kullanın:
gcloud config set project <YOUR_PROJECT_ID>
- Aşağıda gösterilen komutu kullanarak gerekli API'leri etkinleştirin. Bu işlem birkaç dakika sürebilir. Lütfen bekleyin.
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
Komut başarıyla yürütüldüğünde aşağıda gösterilene benzer bir mesaj görürsünüz:
Operation "operations/..." finished successfully.
Gcloud komutuna alternatif olarak, her ürünü arayarak veya bu bağlantıyı kullanarak konsolu kullanabilirsiniz.
Herhangi bir API atlanırsa uygulama sırasında istediğiniz zaman etkinleştirebilirsiniz.
gcloud komutları ve kullanımı için belgelere bakın.
3. Cloud SQL örneği oluşturma
Otel verilerimizi depolamak için Google Cloud SQL for PostgreSQL örneğini kullanacağız. PostgreSQL için Cloud SQL, Google Cloud Platform'da PostgreSQL ilişkisel veritabanlarınızı kurmanıza, yönetmenize ve bakımını yapmanıza yardımcı olan, tümüyle yönetilen bir veritabanı hizmetidir.
Örneği oluşturmak için Cloud Shell'de aşağıdaki komutu çalıştırın:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--tier db-g1-small \
--region=us-central1 \
--edition=ENTERPRISE \
--root-password=postgres
Bu komutun yürütülmesi yaklaşık 3-5 dakika sürer. Komut başarıyla yürütüldüğünde, komutun tamamlandığını belirten bir çıkışın yanı sıra Cloud SQL örneği bilgileriniz (ör. NAME, DATABASE_VERSION, LOCATION) gösterilir.
4. Oteller veritabanını hazırlama
Şimdi görevimiz, otel temsilcimiz için bazı örnek veriler oluşturmak olacak.
Cloud Console'da Cloud SQL sayfasını ziyaret edin.hoteldb-instance hazır ve oluşturulmuş olmalıdır. Aşağıda gösterildiği gibi örneğin adını (hoteldb-instance) tıklayın:
Cloud SQL sol menüsünde, aşağıda gösterildiği gibi Cloud SQL Studio menü seçeneğini ziyaret edin:
Bu işlem, Cloud SQL Studio'da oturum açmanızı ister. Burada birkaç SQL komutu vereceğiz. Veritabanı seçeneği için postgres'ı, hem Kullanıcı hem de Şifre için kullanılacak değer olarak postgres'ı seçin. AUTHENTICATE simgesini tıklayın.
Öncelikle aşağıdaki şemaya göre otel tablosunu oluşturalım. Cloud SQL Studio'daki Düzenleyici bölmelerinden birinde aşağıdaki SQL'i çalıştırın:
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
);
Şimdi de oteller tablosunu örnek verilerle dolduralım. Aşağıdaki SQL'i yürütün:
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');
Aşağıda gösterildiği gibi bir SELECT SQL'i çalıştırarak verileri doğrulayalım:
SELECT * FROM hotels;
Aşağıda gösterildiği gibi, oteller tablosunda bir dizi kayıt görmeniz gerekir:
Cloud SQL örneği oluşturma sürecini tamamladık ve örnek verilerimizi oluşturduk. Bir sonraki bölümde, MCP Toolbox for Databases'i kuracağız.
5. Veritabanları için MCP Araç Kutusu'nu ayarlama
Veritabanları için MCP Araç Kutusu, veritabanları için açık kaynaklı bir MCP sunucusudur. Kurumsal düzeyde ve üretim kalitesinde olacak şekilde tasarlanmıştır. Bağlantı havuzu oluşturma ve kimlik doğrulama gibi karmaşık işlemleri yöneterek araçları daha kolay, daha hızlı ve daha güvenli bir şekilde geliştirmenizi sağlar.
Araç kutusu, temsilcilerinizin veritabanınızdaki verilere erişmesine olanak tanıyan üretken yapay zeka araçları oluşturmanıza yardımcı olur. Araç kutusu şunları sağlar:
- Basitleştirilmiş geliştirme: Araçları 10 satırdan daha az kodla aracınıza entegre edin, araçları birden fazla aracı veya çerçeve arasında yeniden kullanın ve araçların yeni sürümlerini daha kolay dağıtın.
- Daha iyi performans: Bağlantı havuzu oluşturma, kimlik doğrulama gibi en iyi uygulamalar.
- Gelişmiş güvenlik: Verilerinize daha güvenli erişim için entegre kimlik doğrulama
- Uçtan uca gözlemlenebilirlik: OpenTelemetry için yerleşik destekle kullanıma hazır metrikler ve izleme.
Araç kutusu, uygulamanızın düzenleme çerçevesi ile veritabanınız arasında yer alır ve araçları değiştirmek, dağıtmak veya çağırmak için kullanılan bir kontrol düzlemi sağlar. Araçları depolamak ve güncellemek için merkezi bir konum sağlayarak araçlarınızın yönetimini basitleştirir. Böylece, araçları temsilciler ve uygulamalar arasında paylaşabilir ve uygulamanızı yeniden dağıtmanıza gerek kalmadan bu araçları güncelleyebilirsiniz.
MCP Toolbox for Databases tarafından desteklenen veritabanlarından birinin Cloud SQL olduğunu ve bunu önceki bölümde sağladığımızı görebilirsiniz.
Araç Kutusu'nu yükleme
Cloud Shell Terminali'ni açın ve mcp-toolbox adlı bir klasör oluşturun.
mkdir mcp-toolbox
Aşağıdaki komutu kullanarak mcp-toolbox klasörüne gidin:
cd mcp-toolbox
Aşağıdaki komut dosyası aracılığıyla MCP Toolbox for Databases'in ikili sürümünü yükleyin. Aşağıdaki komut Linux içindir. Mac veya Windows kullanıyorsanız doğru ikili dosyayı indirdiğinizden emin olun. İşletim sisteminiz ve mimariniz için yayınlar sayfasına göz atın ve doğru ikili dosyayı indirin.
export VERSION=0.13.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
Artık araç kutusunun ikili sürümünü kullanabiliriz. Bir sonraki adım, araç kutusunu veri kaynaklarımız ve diğer yapılandırmalarla yapılandırmaktır.
tools.yaml dosyasını yapılandırma
Toolbox'ı yapılandırmanın birincil yolu tools.yaml dosyasıdır. Aynı klasörde (ör.mcp-toolbox) tools.yaml adlı bir dosya oluşturun. Bu dosyanın içeriği aşağıda gösterilmiştir.
Cloud Shell'de bulunan nano düzenleyiciyi kullanabilirsiniz. Nano komutu şöyledir: "nano tools.yaml".
YOUR_PROJECT_ID değerini Google Cloud proje kimliğinizle değiştirmeyi unutmayın.
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
Dosyayı kısaca açıklayalım:
Sources, bir aracın etkileşimde bulunabileceği farklı veri kaynaklarınızı temsil eder. Kaynak, bir aracın etkileşimde bulunabileceği bir veri kaynağını temsil eder.Sourcesöğesini tools.yaml dosyanızın kaynaklar bölümünde harita olarak tanımlayabilirsiniz. Genellikle bir kaynak yapılandırması, veritabanına bağlanmak ve veritabanıyla etkileşim kurmak için gereken tüm bilgileri içerir. Bizim durumumuzda, kimlik bilgileriyle PostgreSQL için Cloud SQL örneğimize işaret eden tek bir kaynak yapılandırdık. Daha fazla bilgi için Kaynaklar referansına bakın.Tools, bir aracının yapabileceği işlemleri (ör. bir kaynağı okuma ve kaynağa yazma) tanımlar. Araç, aracınızın gerçekleştirebileceği bir işlemi (ör. SQL ifadesi çalıştırma) temsil eder.Toolsöğesini tools.yaml dosyanızın araçlar bölümünde harita olarak tanımlayabilirsiniz. Genellikle bir aracın işlem yapması için bir kaynak gerekir. Bizim durumumuzdasearch-hotels-by-namevesearch-hotels-by-locationolmak üzere iki araç tanımlıyor, SQL ve parametrelerle birlikte üzerinde işlem yapılan kaynağı belirtiyoruz. Daha fazla bilgi için Araçlar referansına bakın.- Son olarak,
Toolsetvar. Bu özellik, birlikte yüklemek istediğiniz araç gruplarını tanımlamanıza olanak tanır. Bu, aracıya veya uygulamaya göre farklı gruplar tanımlamak için yararlı olabilir. Bizim durumumuzda, tanımladığımız iki aracı içerenmy_first_toolsetadlı tek bir araç setimiz var.
Veritabanı Sunucusu için MCP Araç Kutusu'nu çalıştırma
Sunucuyu başlatmak için aşağıdaki komutu (mcp-toolbox klasöründen) çalıştırın:
./toolbox --tools-file "tools.yaml"
İdeal olarak, sunucunun veri kaynaklarımıza bağlanabildiğini ve araç setini ve araçları yüklediğini gösteren bir çıktı görmeniz gerekir. Aşağıda örnek bir çıktı verilmiştir:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
MCP Toolbox Server varsayılan olarak 5000 bağlantı noktasında çalışır. 5000 bağlantı noktasının zaten kullanıldığını görürseniz aşağıdaki komutta gösterildiği gibi başka bir bağlantı noktası (ör. 7000) kullanabilirsiniz. Lütfen sonraki komutlarda 5000 bağlantı noktası yerine 7000 bağlantı noktasını kullanın.
./toolbox --tools-file "tools.yaml" --port 7000
Bunu test etmek için Cloud Shell'i kullanalım.
Aşağıda gösterildiği gibi Cloud Shell'de Web Önizlemesi'ni tıklayın:
Bağlantı noktasını değiştir'i tıklayın ve bağlantı noktasını aşağıda gösterildiği gibi 5000 olarak ayarlayıp Değiştir ve Önizle'yi tıklayın.
Bu işlem sonucunda aşağıdaki çıkış elde edilir:
Tarayıcı URL'sine, URL'nin sonuna aşağıdakileri ekleyin:
/api/toolset
Bu işlem, şu anda yapılandırılmış araçları gösterir. Örnek bir çıkış aşağıda gösterilmektedir:
{
"serverVersion": "0.13.0+binary.linux.amd64.1a6dfe8d37d0f42fb3fd3f75c50988534dbc1b85",
"tools": {
"search-hotels-by-location": {
"description": "Search for hotels based on location. Result is sorted by price from least to most expensive.",
"parameters": [
{
"name": "location",
"type": "string",
"required": true,
"description": "The location of the hotel.",
"authSources": []
}
],
"authRequired": []
},
"search-hotels-by-name": {
"description": "Search for hotels based on name.",
"parameters": [
{
"name": "name",
"type": "string",
"required": true,
"description": "The name of the hotel.",
"authSources": []
}
],
"authRequired": []
}
}
}
Veritabanları için MCP Araç Kutusu kullanıcı arayüzü üzerinden araçları test etme
Araç Kutusu, parametreleri değiştirerek, başlıkları yöneterek ve çağrıları yürüterek araçlarla doğrudan etkileşim kurmak için görsel bir arayüz (Araç Kutusu kullanıcı arayüzü) sağlar. Tüm bunlar basit bir web kullanıcı arayüzünde yapılır.
Bunu test etmek isterseniz Toolbox sunucusunu başlatmak için kullandığımız önceki komutu --ui seçeneğiyle çalıştırabilirsiniz.
Bunu yapmak için, çalışıyor olabilecek MCP Toolbox for Databases Server'ın önceki örneğini kapatın ve aşağıdaki komutu verin:
./toolbox --tools-file "tools.yaml" --ui
İdeal olarak, sunucunun veri kaynaklarımıza bağlanabildiğini ve araç setini ve araçları yüklediğini gösteren bir çıktı görmeniz gerekir. Aşağıda örnek bir çıktı verilmiştir. Bu çıktıda, Araç Kutusu kullanıcı arayüzünün çalışır durumda olduğu belirtilir.
2025-09-08T02:44:11.561572538Z INFO "Initialized 1 sources."
2025-09-08T02:44:11.561966395Z INFO "Initialized 0 authServices."
2025-09-08T02:44:11.562060934Z INFO "Initialized 2 tools."
2025-09-08T02:44:11.562105678Z INFO "Initialized 2 toolsets."
2025-09-08T02:44:11.568209923Z INFO "Server ready to serve!"
2025-09-08T02:44:11.568259411Z INFO "Toolbox UI is up and running at: http://localhost:5000/ui"
Kullanıcı arayüzü URL'sini tıklayın ve URL'nin sonunda /ui olduğundan emin olun. Bu işlem, aşağıdaki gibi bir kullanıcı arayüzü gösterir:
Yapılandırılmış araçları görüntülemek için soldaki Araçlar seçeneğini tıklayın. Aşağıda gösterildiği gibi, bizim durumumuzda bu araçlardan ikisi (search-hotels-by-name ve search-hotels-by-location) olmalıdır:
Araçlardan birini (search-hotels-by-location) tıklamanız yeterlidir. Bu işlem, gerekli parametre değerlerini girerek aracı test edebileceğiniz bir sayfa açar. Ardından, sonucu görmek için Aracı Çalıştır'ı tıklayın. Örnek bir çalıştırma aşağıda gösterilmektedir:
Veritabanları için MCP Araç Seti, araçları doğrulamanız ve test etmeniz için Python'a özgü bir yöntem de açıklar. Bu yöntem burada belgelenmiştir. Bu konuyu atlayıp doğrudan bu araçları kullanacak olan bir sonraki bölümdeki Agent Development Kit'e (ADK) geçeceğiz.
6. Agent Development Kit (ADK) ile aracımızı yazma
Agent Development Kit'i (ADK) yükleme
Cloud Shell'de yeni bir terminal sekmesi açın ve aşağıdaki gibi my-agents adlı bir klasör oluşturun. my-agents klasörüne de gidin.
mkdir my-agents
cd my-agents
Şimdi de venv kullanarak aşağıdaki şekilde sanal bir Python ortamı oluşturalım:
python -m venv .venv
Sanal ortamı aşağıdaki şekilde etkinleştirin:
source .venv/bin/activate
ADK ve MCP Toolbox for Databases paketlerini langchain bağımlılığıyla birlikte aşağıdaki şekilde yükleyin:
pip install google-adk toolbox-core
Artık adk yardımcı programını aşağıdaki şekilde çağırabilirsiniz.
adk
Komutların listesi gösterilir.
$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...
Agent Development Kit CLI tools.
Options:
--version Show the version and exit.
--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.
İlk Temsilci Uygulamamızı Oluşturma
Şimdi, aşağıdaki gibi bir uygulama adı **(hotel-agent-app)**ile adk create komutunu kullanarak Otel Acentesi Uygulamamız için bir iskelet oluşturmak üzere adk kullanacağız.
adk create hotel-agent-app
Adımları uygulayın ve aşağıdakileri seçin:
- Kök aracı için model seçmeye yönelik Gemini modeli.
- Arka uç için Vertex AI'ı seçin.
- Varsayılan Google proje kimliğiniz ve bölgeniz gösterilir. Varsayılanı seçin.
Choose a model for the root agent:
1. gemini-2.5-flash
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 [YOUR_PROJECT_ID]:
Enter Google Cloud region [us-central1]:
Agent created in <YOUR_HOME_FOLDER>/my-agents/hotel-agent-app:
- .env
- __init__.py
- agent.py
Varsayılan şablonun ve Agent için gerekli dosyaların oluşturulduğu klasörü inceleyin.
İlk olarak .env dosyası. İçeriği aşağıda gösterilmiştir:
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION
Değerler, Google Cloud projesi kimliği ve konumuna ilişkin ilgili değerlerle birlikte Vertex AI üzerinden Gemini'ı kullanacağımızı gösterir.
Ardından, klasörü modül olarak işaretleyen ve aracıyı agent.py dosyasından içe aktaran tek bir ifadeye sahip olan __init__.py dosyası gelir.
from . import agent
Son olarak, agent.py dosyasına göz atalım. İçerikler aşağıda gösterilmektedir:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
)
Bu, ADK ile yazabileceğiniz en basit aracıdır. ADK dokümanları sayfasında belirtildiği gibi, Temsilci, belirli hedeflere ulaşmak için bağımsız hareket edecek şekilde tasarlanmış, kendi kendine yeterli bir yürütme birimidir. Temsilciler görevleri yerine getirebilir, kullanıcılarla etkileşimde bulunabilir, harici araçları kullanabilir ve diğer temsilcilerle koordineli çalışabilir.
Özellikle, genellikle Agent olarak bilinen bir LLMAgent, doğal dili anlamak, akıl yürütmek, plan yapmak, yanıt oluşturmak ve nasıl devam edeceğine veya hangi araçları kullanacağına dinamik olarak karar vermek için çekirdek motoru olarak Büyük Dil Modelleri'ni (LLM'ler) kullanır. Bu nedenle, esnek ve dil odaklı görevler için idealdir. LLM Temsilcileri hakkında daha fazla bilgiyi burada bulabilirsiniz.
agent.py için kodu aşağıdaki gibi değiştirelim:
from google.adk.agents import Agent
root_agent = Agent(
model='gemini-2.5-flash',
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.',
)
Temsilci uygulamasını yerel olarak test etme
Mevcut terminal penceresinden aşağıdaki komutu verin. hotel-agent-app klasörünü içeren üst klasör (my-agents) içinde olduğunuzdan emin olun.
adk web
Aşağıda örnek bir yürütme gösterilmektedir:
INFO: Started server process [1478]
INFO: Waiting for application startup.
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
Son bağlantıyı tıkladığınızda, aracı test etmek için bir web konsolu açılır. Tarayıcıda aşağıdaki gibi bir ekran görmeniz gerekir:
Sol üstte hotel-agent-app simgesinin tanımlandığını göreceksiniz. Artık temsilciyle sohbet etmeye başlayabilirsiniz. Şehirlerle ilgili birkaç istem girin. Örnek bir görüşme aşağıda gösterilmektedir:
Cloud Shell terminalinde çalışan işlemi kapatabilirsiniz (Ctrl-C).
Aracıyı test etmenin alternatif bir yolu da my-agents klasöründen aşağıdaki gibi adk run komutunu kullanmaktır.
adk run hotel-agent-app
Komutu deneyin. Komut satırı (terminal) üzerinden Agent ile etkileşim kurabilirsiniz. Görüşmeyi kapatmak için exit yazın.
7. Temsilcimizi Araçlara Bağlama
Artık bir aracı yazmayı ve yerel olarak test etmeyi biliyoruz. Bu temsilciyi Araçlar'a bağlayacağız. ADK bağlamında Araç, bir yapay zeka aracısına sağlanan belirli bir özelliği temsil eder. Bu özellik, aracının temel metin oluşturma ve muhakeme yeteneklerinin ötesinde işlemler gerçekleştirmesine ve dünyayla etkileşim kurmasına olanak tanır.
Bu örnekte, aracımızı şimdi MCP Toolbox for Databases'de yapılandırdığımız araçlarla donatacağız.
agent.py dosyasını aşağıdaki kodla değiştirin. Kodda varsayılan bağlantı noktası olan 5000'in kullanıldığını unutmayın. Alternatif bir bağlantı noktası numarası kullanıyorsanız lütfen bunu kullanın.
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.5-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,
)
Artık, MCP Toolbox for Databases ile yapılandırılmış PostgreSQL veritabanımızdan gerçek verileri getirecek olan aracı test edebiliriz.
Bunun için aşağıdaki sırayı izleyin:
Cloud Shell'in bir terminalinde, Veritabanları için MCP Araç Kutusu'nu başlatın. Daha önce test ettiğimiz gibi, yerel olarak 5000 numaralı bağlantı noktasında çalışıyor olabilir. Aksi takdirde, sunucuyu başlatmak için aşağıdaki komutu (mcp-toolbox klasöründen) çalıştırın:
./toolbox --tools_file "tools.yaml"
İdeal olarak, sunucunun veri kaynaklarımıza bağlanabildiğini ve araç setini ve araçları yüklediğini gösteren bir çıktı görmeniz gerekir. Aşağıda örnek bir çıktı verilmiştir:
2025-09-05T12:56:28.490964335Z INFO "Initialized 1 sources."
2025-09-05T12:56:28.491127294Z INFO "Initialized 0 authServices."
2025-09-05T12:56:28.491184521Z INFO "Initialized 2 tools."
2025-09-05T12:56:28.491223782Z INFO "Initialized 2 toolsets."
2025-09-05T12:56:28.497457533Z INFO "Server ready to serve!"
MCP sunucusu başarıyla başlatıldıktan sonra başka bir terminalde, daha önce yaptığımız gibi aşağıdaki adk run (my-agents klasöründen) komutuyla aracı başlatın. Dilerseniz adk web komutunu da kullanabilirsiniz.
$ 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.
Aracının artık Veritabanları için MCP Araç Kutusu'nda (search-hotels-by-name ve search-hotels-by-location) yapılandırdığımız iki aracı kullandığını ve bize doğru seçenekleri sunduğunu fark edin. Ardından, verileri PostgreSQL örneği veritabanından sorunsuz bir şekilde alabilir ve yanıtı buna göre biçimlendirebilir.
Bu işlem, Agent Development Kit (ADK) kullanılarak oluşturulan ve MCP Toolbox for Databases'te yapılandırılan araçlarla desteklenen otel aracımızın yerel geliştirme ve test sürecini tamamlar.
8. (İsteğe bağlı) Veritabanları için MCP Toolbox ve Agent'ı Cloud Run'a dağıtma
Önceki bölümde, MCP Toolbox sunucusunu başlatmak için Cloud Shell terminalini kullandık ve araçları aracıyla test ettik. Bu işlem, Cloud Shell ortamında yerel olarak çalıştırılıyordu.
Hem MCP Toolbox sunucusunu hem de aracıyı, bu uygulamaları bizim için barındırabilecek Google Cloud hizmetlerine dağıtma seçeneğiniz vardır.
Cloud Run'da MCP Araç Kutusu sunucusunu barındırma
İlk olarak MCP Toolbox sunucusuyla başlayıp Cloud Run'da barındırabiliriz. Bu durumda, diğer uygulamalar ve/veya aracı uygulamalarıyla entegre edebileceğimiz herkese açık bir uç nokta elde ederiz. Bunu Cloud Run'da barındırma talimatları burada verilmiştir. Şimdi temel adımları inceleyelim.
Yeni bir Cloud Shell terminali başlatın veya mevcut bir Cloud Shell terminalini kullanın. mcp-toolbox ikili programının ve toolbox dosyasının bulunduğu tools.yaml klasörüne gidin.
Aşağıdaki komutları çalıştırın (her komut için açıklama sağlanmıştır):
PROJECT_ID değişkenini Google Cloud proje kimliğinizi gösterecek şekilde ayarlayın.
export PROJECT_ID="YOUR_GOOGLE_CLOUD_PROJECT_ID"
Ardından, projede aşağıdaki Google Cloud hizmetlerinin etkinleştirildiğini doğrulayın.
gcloud services enable run.googleapis.com \
cloudbuild.googleapis.com \
artifactregistry.googleapis.com \
iam.googleapis.com \
secretmanager.googleapis.com
Google Cloud Run'da dağıtacağımız Toolbox hizmetinin kimliği olarak hareket edecek ayrı bir hizmet hesabı oluşturalım. Ayrıca bu hizmet hesabının doğru rollere (ör. Secret Manager'a erişme ve Cloud SQL ile iletişim kurma) sahip olduğundan da emin oluyoruz.
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
tools.yaml dosyasını gizli olarak yükleyeceğiz. Toolbox'ı Cloud Run'a yüklememiz gerektiğinden Toolbox için en son container görüntüsünü kullanıp bunu IMAGE değişkenine ayarlayacağız.
gcloud secrets create tools --data-file=tools.yaml
export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
Cloud Run'a dağıtım için kullanılan komutun son adımı:
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
Bu işlem, yapılandırılmış tools.yaml ile Toolbox Sunucusu'nun Cloud Run'a dağıtılması sürecini başlatır. Dağıtım başarılı olduğunda aşağıdaki gibi bir mesaj görürsünüz:
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
Artık yukarıda listelenen Service URL tarayıcıda ziyaret edebilirsiniz. Daha önce gördüğümüz "Hello World" mesajı görüntülenir. Ayrıca, mevcut araçları görmek için aşağıdaki URL'yi de ziyaret edebilirsiniz:
SERVICE URL/api/toolset
Google Cloud Console'dan Cloud Run'ı da ziyaret edebilirsiniz. Bu durumda, Cloud Run'daki hizmetler listesinde Toolbox hizmetini görürsünüz.
Not: Otel aracınızı yerel olarak çalıştırmaya devam etmek ve yeni dağıtılan Cloud Run hizmetine bağlanmak istiyorsanız my-agents/hotel-agent-app/agent.py dosyasında tek bir değişiklik yapmanız yeterlidir.
Aşağıdakiler yerine:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Aşağıda belirtildiği gibi Cloud Run hizmetinin hizmet URL'si olarak değiştirin:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Daha önce gördüğümüz gibi adk run veya adk web kullanarak Agent Application'ı test edin.
Otel aracısı uygulamasını Cloud Run'da dağıtma
İlk adım, yukarıda belirtildiği gibi my-agents/hotel-agent-app/agent.py içinde değişikliği yaparak Cloud Run'da çalışan ve yerel ana makine olmayan Toolbox hizmeti URL'sini işaret ettiğinizden emin olmaktır.
Yeni bir Cloud Shell terminalinde veya mevcut bir terminal oturumunda, daha önce ayarladığımız doğru Python sanal ortamında olduğunuzdan emin olun.
Öncelikle, aşağıdaki resimde gösterildiği gibi my-agents/hotel-agent-app klasöründe bir requirements.txt dosyası oluşturalım:
google-adk
toolbox-core
my-agents klasörüne gidin ve önce aşağıdaki ortam değişkenlerini ayarlayalım:
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
Son olarak, aşağıda belirtildiği gibi adk deploy cloud_run komutuyla Agent Application'ı Cloud Run'a dağıtalım. Hizmete kimliği doğrulanmamış çağrıların gönderilmesine izin vermeniz istenirse lütfen şimdilik değer olarak "y" girin.
adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH
Bu işlem, Otel Aracı Uygulaması'nın Cloud Run'a dağıtılma sürecini başlatır. Kaynakları yükler, Docker container'ına paketler, Artifact Registry'ye gönderir ve ardından hizmeti Cloud Run'da dağıtır. Bu işlem birkaç dakika sürebilir. Lütfen bekleyin.
Aşağıdakine benzer bir mesaj görürsünüz:
Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250905_132636
Copying agent source code...
Copying agent source code completed.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250905_132636/Dockerfile
Deploying to Cloud Run...
Building using Dockerfile and deploying container to Cloud Run service [hotels-service] in project [YOUR_PROJECT_ID] region [us-central1]
- Building and deploying... Uploading sources.
- Uploading sources...
. Building Container...
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/d1f7e76b-0587-4bb6-b9c0-bb4360c07aa0?project=415
458962931]. f
OK Creating Revision...
OK Routing traffic...
Done.
Service [hotels-service] revision [hotels-service-00003-hrl] has been deployed and is serving 100 percent of traffic.
Service URL: <YOUR_CLOUDRUN_APP_URL>
INFO: Display format: "none"
Cleaning up the temp folder: /tmp/cloud_run_deploy_src/20250905_132636
Başarılı dağıtımın ardından, hizmet URL'si için bir değer sağlanır. Bu değere tarayıcıdan erişerek, daha önce yerel kurulumda gördüğümüz gibi otel temsilcisiyle sohbet etmenize olanak tanıyan aynı web uygulamasına erişebilirsiniz.
9. Temizleme
Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu atölye çalışması sırasında oluşturduğumuz kaynakları silmeniz önemlidir. Cloud SQL örneğini sileceğiz. Ayrıca, Toolbox ve Hotels uygulamasını Cloud Run'a dağıttıysanız bu hizmetleri de sileceğiz.
Projenize ve bölgenize göre aşağıdaki ortam değişkenlerinin doğru şekilde ayarlandığından emin olun:
export PROJECT_ID="YOUR_PROJECT_ID"
export REGION="YOUR_REGION"
Aşağıdaki iki komut, dağıttığımız Cloud Run hizmetlerini siler:
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
Aşağıdaki komut, Cloud SQL örneğini siler:
gcloud sql instances delete hoteldb-instance
10. Tebrikler
Tebrikler! Veritabanları için MCP Araç Kutusu'nu kullanan Agent Development Kit (ADK) ile başarıyla bir aracı oluşturdunuz.