1. Giriş
Bu codelab'de, Veritabanları için MCP Aracı Kutusu'nu kullanan Agent Development Kit (ADK)'yi kullanarak bir aracı oluşturacaksınız.
Codelab'de aşağıdaki gibi adım adım bir yaklaşım uygulayacaksınız:
- Oteller veritabanı ve örnek verileri içeren bir PostgreSQL için Cloud SQL veritabanı hazırlayın.
- Verilere erişim sağlayan veritabanları için MCP Aracı Kutusu'nu ayarlayın.
- Kullanıcıdan gelen sorguları yanıtlamak için MCP Aracı Kutusu'nu kullanacak bir Temsilci Geliştirme Kiti (ADK) kullanarak bir temsilci tasarlayın ve geliştirin.
- Veritabanları için Temsilci ve MCP Aracı Kutusu'nu yerel olarak ve Cloud Run hizmeti aracılığıyla Google Cloud'da test etme seçeneklerini keşfedin.
Yapacaklarınız
- Bir konumdaki oteller hakkındaki kullanıcı sorgularını yanıtlayacak veya otellere isme göre arama yapacak bir temsilci tasarlayın, oluşturun ve dağıtın.
Neler öğreneceksiniz?
- PostgreSQL için Cloud SQL veritabanı oluşturma ve örnek veri ile doldurma.
- PostgreSQL için Cloud SQL veritabanı örneğinde veritabanları için MCP Aracı Kutusu'nu kurun.
- Kullanıcı sorgularını yanıtlamak için Agent Development Kit'i (ADK) kullanarak bir temsilci tasarlayın ve geliştirin.
- Yerel ortamda veritabanları için aracıyı ve MCP araç kutusunu test edin.
- (İsteğe bağlı) Google Cloud'da Veritabanları için Aracı ve MCP Aracı Kutusu'nu 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 kod laboratuvarının örnek uygulamasında Python kullanılır. Ancak sunulan kavramları anlamak için Python bilgisine sahip olmanız gerekmez.
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. Projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğinizi öğrenin .
- Google Cloud'da çalışan ve bq ile önceden yüklenmiş 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ğrulanıp doğrulanmadığını ve projenin proje kimliğinize ayarlanıp ayarlanmadığını kontrol edin:
gcloud auth list
- gcloud komutunun projeniz hakkında bilgi sahibi olduğunu onaylamak için Cloud Shell'de aşağıdaki komutu çalıştırın.
gcloud config list project
- Projeniz ayarlanmadıysa 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ğıdakine benzer bir mesaj görürsünüz:
Operation "operations/..." finished successfully.
gcloud komutunun alternatifi, her ürünü arayarak veya bu bağlantıyı kullanarak konsoldan geçmektir.
Atlanan bir API varsa 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 verilerini depolamak için bir PostgreSQL için Google Cloud SQL örneği kullanacağız. PostgreSQL için Cloud SQL, Google Cloud Platform'da PostgreSQL ilişkisel veritabanlarınızı oluşturmanıza, sürdürmenize, yönetmenize ve yönetmenize yardımcı olan, tümüyle yönetilen bir veritabanı hizmetidir.
Cloud Shell'de örneği oluşturmak için aşağıdaki komutu çalıştırın:
gcloud sql instances create hoteldb-instance \
--database-version=POSTGRES_15 \
--cpu=2 \
--memory=8GiB \
--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, NAME, DATABASE_VERSION, LOCATION gibi Cloud SQL örneği bilgilerinizle birlikte komutun tamamlandığını belirten bir çıkış görürsünüz.
4. Oteller veritabanını hazırlama
Şimdi otel temsilcimiz için bazı örnek veriler oluşturacağız.
Cloud Console'daki Cloud SQL sayfasını ziyaret edin.hoteldb-instance hazır ve oluşturulmuş olarak gösterilir. Aşağıda gösterildiği gibi örneğin adını (hoteldb-instance) tıklayın:
Cloud SQL sol menüsünden, aşağıda gösterildiği gibi Cloud SQL Studio menü seçeneğini ziyaret edin:
Bu işlem, birkaç SQL komutu vereceğimiz Cloud SQL Studio'da oturum açmanızı ister. Veritabanı seçeneği için postgres'ı seçin. Hem Kullanıcı hem de Şifre için kullanılacak değer postgres olmalıdır. 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 yürütü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, otel 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-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');
Aşağıda gösterildiği gibi bir SELECT SQL çalıştırarak verileri doğrulayalım:
SELECT * FROM hotels;
Oteller tablosunda aşağıdaki gibi bir dizi kayıt görürsünüz:
Cloud SQL örneği oluşturma işlemini tamamladık ve örnek verilerimizi oluşturduk. Bir sonraki bölümde, veritabanları için MCP Aracı Kutusu'nu ayarlayacağız.
5. Veritabanları için MCP Araç Kutusu'nu ayarlama
Veritabanları için MCP Araç Kutusu, veritabanları için açık kaynak bir MCP sunucusudur. Kurumsal düzeyde ve üretim kalitesinde tasarlanmıştır. Bağlantı havuzu oluşturma, kimlik doğrulama ve daha birçok karmaşıklığı ele alarak araçları daha kolay, daha hızlı ve daha güvenli bir şekilde geliştirmenize olanak tanır.
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 kısa 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 ve daha fazlası 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 destek içeren kullanıma hazır metrikler ve izleme.
Araç Kutusu, uygulamanızın orkestrasyon ç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 sunarak 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ğıtmadan bu araçları güncelleyebilirsiniz.
Veritabanları için MCP Araç Kutusu tarafından desteklenen veritabanlarından birinin Cloud SQL olduğunu ve önceki bölümde bu veritabanı için temel hazırlığı yaptığımızı görebilirsiniz.
Araç Kutusu'nu yükleme
Cloud Shell Terminal'i açın ve mcp-toolbox adlı bir klasör oluşturun.
mkdir mcp-toolbox
Aşağıda gösterilen komutu kullanarak mcp-toolbox klasörüne gidin:
cd mcp-toolbox
Veritabanları için MCP Aracı Kutusu'nun ikili sürümünü aşağıdaki komut dosyasını kullanarak yükleyin:
export VERSION=0.3.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. 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
Araç Kutusu'nu yapılandırmanın birincil yolu tools.yaml dosyasıdır. Aynı klasörde (mcp-toolbox) tools.yaml adlı bir dosya oluşturun. Aşağıda bu dosyanın içeriği gösterilmektedir.
Cloud Shell'de bulunan nano düzenleyiciyi kullanabilirsiniz. nano komutu şu şekildedir: "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.
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
Dosyayı kısaca anlayalım:
Sources, bir aracın etkileşim kurabileceği farklı veri kaynaklarınızı temsil eder. Kaynak, bir aracın etkileşim kurabileceği bir veri kaynağını temsil eder.Sourcesöğesini tools.yaml dosyanızın sources bölümünde bir harita olarak tanımlayabilirsiniz. Kaynak yapılandırmaları genellikle veritabanına bağlanmak ve veritabanı ile etkileşimde bulunmak için gereken tüm bilgileri içerir. Bizim durumumuzda, kimlik bilgileriyle PostgreSQL için Cloud SQL örneğimizi işaret eden tek bir kaynak yapılandırdık. Daha fazla bilgi için Kaynaklar bölümüne bakın.Tools, bir aracının yapabileceği işlemleri (ör. bir kaynağa okuma ve yazma) tanımlar. Araçlar, temsilcinizin yapabileceği bir işlemi (ör. SQL ifadesi çalıştırma) temsil eder.Toolsöğesini tools.yaml dosyanızın tools bölümünde harita olarak tanımlayabilirsiniz. Genellikle bir aracın işlem yapması için bir kaynak gerekir. Bizim durumumuzda,search-hotels-by-namevesearch-hotels-by-locationolmak üzere iki araç tanımlıyoruz ve SQL ile parametrelerin yanı sıra aracın üzerinde çalıştığı kaynağı belirtiyoruz. Daha fazla bilgi için Araçlar referansına bakın.- Son olarak, birlikte yüklemek istediğiniz araç gruplarını tanımlamanıza olanak tanıyan
Toolsetsimgesini de kullanabilirsiniz. Bu, temsilciye 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 mcp-toolbox klasöründen aşağıdaki komutu ç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 belirten bir çıkış görmeniz gerekir. Aşağıda örnek bir çıkış verilmiştir:
./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!"
MCP Toolbox sunucusu varsayılan olarak 5000 bağlantı noktasında çalışır. Bunu test etmek için Cloud Shell'i kullanalım.
Cloud Shell'de aşağıdaki gibi 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ın, ardından Değiştir ve Önizle'yi tıklayın.
Bu işlem sonucunda aşağıdaki çıkışı alırsınız:
Tarayıcı URL'sinde, URL'nin sonuna aşağıdakileri ekleyin:
/api/toolset
Bu işlem, şu anda yapılandırılmış araçları gösterir. Aşağıda örnek bir çıkış gösterilmektedir:
{
"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": []
}
]
}
}
}
Veritabanları için MCP Aracı Kiti'nde, araçları doğrulama ve test etme için kullanabileceğiniz Python'a özgü bir yöntem açıklanmaktadır. Bu yöntemle ilgili dokümanlar burada yer almaktadır. Bu bölümü atlayıp doğrudan bu araçları kullanacak olan sonraki bölümdeki Temsilci Geliştirme Kiti'ne (ADK) geçeceğiz.
6. Temsilcimizi Agent Development Kit (ADK) ile yazma
Temsilci Geliştirme Kiti'ni (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, venv kullanarak aşağıdaki gibi bir sanal Python ortamı oluşturalım:
python -m venv .venv
Sanal ortamı aşağıdaki şekilde etkinleştirin:
source .venv/bin/activate
ADK ve veritabanları için MCP Toolbox paketlerini aşağıdaki gibi yükleyin:
pip install google-adk toolbox-core
Artık adk yardımcı programını aşağıdaki gibi çağırabilirsiniz.
adk
Komutların listesi gösterilir.
$ 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.
İlk temsilci uygulamamızı oluşturma
Şimdi adk aracını kullanarak aşağıda gösterildiği gibi, uygulama adı **(hotel-agent-app)**olan adk create komutunu kullanarak Otel Aracısı Uygulamamız için bir yapı oluşturacağız.
adk create hotel-agent-app
Adımları uygulayıp aşağıdakileri seçin:
- Kök aracı için model seçmek üzere Gemini modeli.
- Arka uç için Vertex AI'ı seçin.
- Varsayılan Google proje kimliğiniz ve bölgeniz gösterilir. Varsayılan değeri seçin.
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
Temsilci için varsayılan şablonun ve gerekli dosyaların oluşturulduğu klasörü gözlemleyin.
İlk olarak .env dosyasını açın. İç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'yi 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 ifade içeren __init__.py dosyası vardır.
from . import agent
Son olarak agent.py dosyasına göz atalım. İçerikleri aşağıda görebilirsiniz:
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',
)
Bu, ADK ile yazabileceğimiz en basit aracıdır. ADK dokümanları sayfasında belirtildiği gibi, temsilciler belirli hedeflere ulaşmak için bağımsız olarak hareket etmek üzere tasarlanmış, kendi kendine yeten bir yürütme birimidir. Temsilciler görevleri gerçekleştirebilir, kullanıcılarla etkileşim kurabilir, harici araçları kullanabilir ve diğer temsilcilerle koordinasyon sağlayabilir.
Daha açık belirtmek gerekirse, genellikle Temsilci olarak adlandırılan LLMAgent, doğal dili anlamak, mantık yürütmek, plan yapmak, yanıt oluşturmak ve nasıl devam edileceğine veya hangi araçların kullanılacağına dinamik olarak karar vermek için temel motor olarak Büyük Dil Modelleri'ni (LLM'ler) kullanır. Bu sayede esnek, dile odaklı görevler için idealdir. LLM temsilcileri hakkında daha fazla bilgiye buradan ulaşabilirsiniz.
agent.py için kodu aşağıdaki şekilde değiştirelim:
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.',
)
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)'te olduğunuzdan emin olun.
adk web
Aşağıda örnek bir yürütme gösterilmektedir:
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)
Son bağlantıyı tıkladığınızda, temsilciyi test etmek için bir web konsolu açılır. Aşağıda gösterildiği gibi tarayıcıda aşağıdaki ekranın açıldığını göreceksiniz:
Sol üstte hotel-agent-app'in tanımlandığını görebilirsiniz. Artık temsilciyle sohbet etmeye başlayabilirsiniz. Şehirlerle ilgili birkaç istem sağlayın. Aşağıda örnek bir görüşme gösterilmektedir:
Cloud Shell terminalinde çalışan işlemi kapatabilirsiniz (Ctrl-C).
Aracısı test etmenin alternatif bir yolu, my-agents klasöründen aşağıdaki gibi verilen adk run komutunu kullanmaktır.
adk run hotel-agent-app
Komutu deneyin ve komut satırı (terminal) üzerinden müşteri temsilcisiyle sohbet edin. Görüşmeyi kapatmak için exit yazın.
7. Temsilcimizi Araçlar'a bağlama
Artık bir aracıyı nasıl yazacağımızı ve yerel olarak nasıl test edeceğimizi biliyoruz. Bu temsilciyi Araçlar'a bağlayacağız. ADK bağlamında bir araç, yapay zeka aracısına sağlanan ve temel metin oluşturma ve akıl yürütme özelliklerinin ötesinde işlemler gerçekleştirmesini ve dünyayla etkileşim kurmasını sağlayan belirli bir kapasiteyi temsil eder.
Bizim durumumuzda, Temsilcimizi veritabanları için MCP Araç Kutusu'nda yapılandırdığımız araçlarla donatacağız.
agent.py dosyasını aşağıdaki kodla değiştirin:
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,
)
Artık veritabanları için MCP Aracı Kutusu ile yapılandırılmış PostgreSQL veritabanımızdan gerçek verileri alacak olan aracıyı test edebiliriz.
Bunun için aşağıdaki sırayı uygulayın:
Cloud Shell'deki bir terminalde, Veritabanları için MCP Aracı Kutusu'nu başlatın. Daha önce test ettiğimiz gibi, 5000 numaralı bağlantı noktasında yerel olarak çalışıyor olabilir. Aksi takdirde, sunucuyu başlatmak için mcp-toolbox klasöründen aşağıdaki komutu ç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 belirten bir çıkış görmeniz gerekir. Aşağıda örnek bir çıkış verilmiştir:
./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!"
MCP sunucusu başarıyla başlatıldıktan sonra, başka bir terminalde, aşağıda gösterilen adk run (my-agents klasöründen) komutunu kullanarak daha önce yaptığımız gibi aracıyı 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.
Temsilcinin artık veritabanları için MCP Araç Kutusu'nda yapılandırdığımız iki aracı (search-hotels-by-name ve search-hotels-by-location) kullandığını ve bize doğru seçenekleri sunduğunu görebilirsiniz. Ardından, verileri PostgreSQL örneği veritabanından sorunsuz bir şekilde alıp yanıtı uygun şekilde biçimlendirebilir.
Bu işlemle, Agent Development Kit (ADK)'i kullanarak geliştirdiğimiz ve veritabanları için MCP Aracı Kutusu'nda yapılandırdığımız araçlarla desteklenen otel temsilcimizin yerel geliştirme ve test süreci tamamlanır.
8. (İsteğe bağlı) Veritabanları ve Aracısı için MCP Aracı Kutusu'nu 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ğıtabilirsiniz.
MCP Toolbox sunucusunu Cloud Run'da barındırma
Öncelikle MCP Toolbox sunucusuyla başlayıp bunu Cloud Run'da barındırabiliriz. Bu sayede, diğer uygulamalarla ve/veya temsilci uygulamalarıyla entegre edebileceğimiz herkese açık bir uç nokta elde ederiz. Bu uygulamayı Cloud Run'da barındırmayla ilgili talimatlar burada verilmiştir. Şimdi önemli adımları inceleyeceğiz.
Yeni bir Cloud Shell Terminal'i başlatın veya mevcut bir Cloud Shell Terminal'i kullanın. toolbox ikili dosyası ve tools.yaml dosyasının bulunduğu mcp-toolbox klasörüne gidin.
Aşağıdaki komutları çalıştırın (her komut için bir açıklama sağlanmıştır):
PROJECT_ID değişkenini Google Cloud proje kimliğinizi işaret edecek ş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'a dağıtacağımız Toolbox hizmetinin kimliği olarak kullanılacak 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 emin oluruz.
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. Araç Kutusu'nu Cloud Run'a yüklememiz gerektiğinden, araç kutusu için en son container görüntüsünü kullanacağız ve bunu IMAGE değişkeninde 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 yönelik tanıdık dağıtım komutunun 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 sunucusunu Cloud Run'a dağıtma işlemini başlatır. Dağıtım başarılı olduğunda aşağıdakine benzer 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 adresini tarayıcıda ziyaret edebilirsiniz. Daha önce gördüğümüz "Merhaba Dünya" mesajı gösterilir. Ayrıca, kullanılabilen araçları görmek için aşağıdaki URL'yi de ziyaret edebilirsiniz:
SERVICE URL/api/toolset
Google Cloud Console'dan Cloud Run'u da ziyaret edebilirsiniz. Cloud Run'daki hizmet listesinde Toolbox hizmetini göreceksiniz.
Not: Otel temsilcinizi 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ğıdaki yerine:
toolbox = ToolboxSyncClient("http://127.0.0.1:5000")
Aşağıda verilen Cloud Run hizmetinin Hizmet URL'si ile değiştirin:
toolbox = ToolboxSyncClient("CLOUD_RUN_SERVICE_URL")
Daha önce gördüğümüz gibi adk run veya adk web kullanarak temsilci uygulamasını test edin.
Otel temsilcisi uygulamasını Cloud Run'a dağıtma
İlk adım, my-agents/hotel-agent-app/agent.py dosyasında yukarıdaki talimatlara göre yerel ana makine yerine Cloud Run'da çalışan Toolbox hizmet URL'sini işaret edecek şekilde değişiklik yaptığınızdan 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 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 verilen adk deploy cloud_run komutu aracılığıyla aracı uygulamasını 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" yazın.
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 temsilcisi uygulamasının Cloud Run'a dağıtım sürecini başlatır. Kaynakları yükler, bir Docker kapsayıcısına paketler, bunu Artifact Registry'ye gönderir ve ardından hizmeti Cloud Run'a 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/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
Dağıtım başarılı olduğunda, Hizmet URL'si için bir değer sağlanır. Daha sonra, yerel kurulumda gördüğümüz gibi otel temsilcisiyle sohbet etmenize olanak tanıyan aynı web uygulamasını görüntülemek için tarayıcıda bu değere erişebilirsiniz.
9. Tebrikler
Tebrikler. Veritabanları için MCP Aracı Kutusu'nu kullanan Temsilci Geliştirme Kiti'ni (ADK) kullanarak başarıyla bir temsilci oluşturdunuz.