Araç Olarak Veritabanı: ADK, MCP Toolbox ve Cloud SQL ile Agentic RAG

1. Giriş

Yapay zeka ajanlarının faydası, erişebildikleri verilerle sınırlıdır. Gerçek dünyadaki verilerin çoğu veritabanlarında bulunur ve aracıları veritabanlarına bağlamak genellikle bağlantı yönetimi, sorgu mantığı ve yerleştirme işlem hatlarını aracı kodunuza yazmak anlamına gelir. Veritabanı erişimi gerektiren her aracı bu çalışmayı tekrarlar ve her sorgu değişikliği, aracının yeniden dağıtılmasını gerektirir.

Bu codelab'de farklı bir yaklaşım gösterilmektedir. Veritabanı araçlarınızı (standart SQL sorguları, vektör benzerliği araması ve hatta otomatik yerleştirme oluşturma) bir YAML dosyasında beyan edersiniz. Veritabanları için MCP Araç Kutusu, tüm veritabanı işlemlerini bir MCP sunucusu olarak yönetir. Aracı kodunuz minimum düzeyde kalır: Araçları yükleyin, hangisinin çağrılacağına Gemini karar versin.

Ne oluşturacaksınız?

"TechJobs" için Akıllı İş İlanı Asistanı: Geliştiricilerin standart filtreleri (rol, teknoloji yığını) kullanarak teknoloji iş ilanlarına göz atmasına ve "Yapay zeka chatbot'ları üzerinde çalışacağım uzaktan bir iş istiyorum" gibi doğal dil açıklamalarıyla işleri keşfetmesine yardımcı olan, Gemini destekli bir ADK aracısı. Aracı, tüm veritabanı erişimini (vektör araması için otomatik yerleştirme oluşturma dahil) işleyen MCP Toolbox for Databases aracılığıyla Cloud SQL PostgreSQL veritabanından okuma ve veritabanına yazma işlemleri yapar. Sonunda hem araç kutusu hem de aracı Cloud Run'da çalışır.

Neler öğreneceksiniz?

MCP (Model Context Protocol) standardının yapay zeka aracılarına yönelik araç erişimini nasıl standartlaştırdığı ve MCP Toolbox for Databases'in bunu veritabanı işlemlerine nasıl uyguladığı
Bir ADK aracısı ile Cloud SQL PostgreSQL arasında ara katman yazılımı olarak MCP Toolbox for Databases'i ayarlama
Veritabanı araçlarını tools.yaml içinde bildirimsel olarak tanımlayın. Temsilcinizde veritabanı kodu bulunmaz.
ToolboxToolset kullanarak çalışan bir Araç Kutusu sunucusundan araç yükleyen bir ADK aracısı oluşturma
Cloud SQL'in yerleşik embedding() işlevini kullanarak vektör yerleştirmeleri oluşturma ve pgvector ile semantik aramayı etkinleştirme
Yazma işlemlerinde otomatik vektör alımı için valueFromParam özelliğini kullanma
Hem Toolbox sunucusunu hem de ADK aracısını Cloud Run'a dağıtma

Ön koşullar

Deneme faturalandırma hesabına sahip bir Google Cloud hesabı
Python ve SQL hakkında temel düzeyde bilgi
ADK, MCP Toolbox veya pgvector ile ilgili deneyim gerekmez.

2. Ortamınızı ayarlama

Bu adımda Cloud Shell ortamınız hazırlanır, Google Cloud projeniz yapılandırılır ve referans deposu klonlanır.

Cloud Shell'i açma

Tarayıcınızda Cloud Shell'i açın. Cloud Shell, bu codelab için ihtiyacınız olan tüm araçların bulunduğu önceden yapılandırılmış bir ortam sağlar. İstendiğinde Yetkilendir'i tıklayın.

Ardından, terminali açmak için "Görünüm" -> "Terminal"i tıklayın. Arayüzünüz aşağıdaki gibi görünmelidir.

Bu, ana arayüzümüz olacak. Üstte IDE, altta terminal yer alacak.

Çalışma dizininizi ayarlama

Çalışma dizininizi oluşturun. Bu codelab'de yazdığınız tüm kodlar burada bulunur:

mkdir -p ~/build-agent-adk-toolbox-cloudsql
cloudshell workspace ~/build-agent-adk-toolbox-cloudsql && cd ~/build-agent-adk-toolbox-cloudsql

Google Cloud projenizi oluşturun

Konum değişkenlerini içeren .env dosyasını oluşturun:

# For Vertex AI / Gemini API calls
echo "GOOGLE_CLOUD_LOCATION=global" > .env
# For Cloud SQL, Cloud Run, Artifact Registry
echo "REGION=us-central1" >> .env

Proje kurulum komut dosyasını çalışma dizininize indirin:

curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh

Komut dosyasını çalıştırın. Deneme faturalandırma hesabınızı doğrular, yeni bir proje oluşturur (veya mevcut bir projeyi doğrular), proje kimliğinizi geçerli dizindeki bir .env dosyasına kaydeder ve gcloud'de etkin projeyi ayarlar.

bash setup_verify_trial_project.sh && source .env

Komut dosyası:

Etkin bir deneme faturalandırma hesabınız olduğunu doğrulayın.
.env içinde mevcut bir proje olup olmadığını kontrol edin (varsa)
Yeni bir proje oluşturun veya mevcut projeyi yeniden kullanın
Deneme faturalandırma hesabını projenize bağlama
Proje kimliğini .env dosyasına kaydedin.
Projeyi etkin gcloud projesi olarak ayarlayın

Cloud Shell terminal isteminde çalışma dizininizin yanındaki sarı metni kontrol ederek projenin doğru şekilde ayarlandığını doğrulayın. Proje kimliğiniz gösterilmelidir.

Cloud Shell oturumunuz bu codelab sırasında herhangi bir noktada sıfırlanırsa çalışma dizininize geri dönün ve proje yapılandırmanızı geri yüklemek için bash setup_verify_trial_project.sh && source .env komutunu yeniden çalıştırın. Sarı proje kimliği metninin terminal isteminde yeniden göründüğünü onaylayın.

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

Vertex AI API (aiplatform.googleapis.com): Aracınız Gemini modellerini, Araç Kutusu ise vektör araması için yerleştirme API'sini kullanır.
Cloud SQL Admin API (sqladmin.googleapis.com): PostgreSQL örneği sağlarsınız ve yönetirsiniz.
Compute Engine API (compute.googleapis.com): Cloud SQL örnekleri oluşturmak için gereklidir.
Cloud Run, Cloud Build, Artifact Registry: Bu codelab'in ilerleyen bölümlerinde dağıtım adımında kullanılır.

3. Veritabanı örneğini oluşturma

Bu adım, Cloud SQL örneği oluşturma işlemini arka planda ayarlar. Siz eğitime devam ederken sağlama işlemi yapılır.

Örnek oluşturma işlemini başlatma

Veritabanı şifresini .env dosyanıza ekleyin ve dosyayı yeniden yükleyin:

echo "DB_PASSWORD=techjobs-pwd-2025" >> .env
source .env

Cloud SQL örneği oluşturma işlemini başlatın. Bu işlem arka planda çalışır, böylece çalışmaya devam edebilirsiniz:

gcloud sql instances create jobs-instance \
  --database-version=POSTGRES_17 \
  --tier=db-custom-1-3840 \
  --edition=ENTERPRISE \
  --region=$REGION \
  --root-password=$DB_PASSWORD \
  --enable-google-ml-integration \
  --database-flags cloudsql.enable_google_ml_integration=on \
  --quiet &

db-custom-1-3840, ENTERPRISE sürümündeki en küçük ayrılmış çekirdekli Cloud SQL katmanıdır (1 vCPU, 3,75 GB RAM). Daha fazla bilgiyi burada bulabilirsiniz. Vertex AI ML entegrasyonu için özel bir çekirdek gerekir. Paylaşılan çekirdek katmanları (db-f1-micro, db-g1-small) bu entegrasyonu desteklemez.
--root-password, varsayılan postgres kullanıcısının şifresini ayarlar.
--enable-google-ml-integration, Cloud SQL'in Vertex AI ile yerleşik entegrasyonunu etkinleştirir. Bu entegrasyon, embedding() işlevini kullanarak doğrudan SQL'den yerleştirme modellerini çağırmanıza olanak tanır.
&, komutu arka planda çalıştırır.

Bu işlem arka planda çalışır. Ardından, MCP Toolbox ikilisini indirelim. Bu işlemi aynı terminalde yapabilirsiniz.

Toolbox ikilisini indirin

Bu eğitimde MCP Toolbox'ı kullanacağız. Neyse ki bu araç, Linux ortamında kullanıma hazır önceden oluşturulmuş bir ikili dosya ile birlikte gelir. Bu işlem biraz zaman alacağından dosyayı arka planda indirelim.

cd ~/build-agent-adk-toolbox-cloudsql
curl -O https://storage.googleapis.com/genai-toolbox/v0.27.0/linux/amd64/toolbox &

Bu işlemin geçerli sekmede çalışmasına izin verin (işlem zaten arka planda çalıştırılır ancak çıkış yine de gösterilir). Daha iyi odaklanabilmek için Cloud Shell'de yeni bir terminal sekmesi açalım (artı simgesini tıklayın).

Çalışma dizininize tekrar gidin ve önceki kurulum komut dosyasını kullanarak projeyi etkinleştirin.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Bu adımda Python projesi ayarlanır, bağımlılıklar yüklenir ve ADK aracısı dizini oluşturulur.

4. Aracı projesini başlatma

Python projesini oluşturma

uv, Rust ile yazılmış hızlı bir Python paketi ve proje yöneticisidir ( uv dokümanları ). Bu codelab'de hız ve basitlik için kullanılır.

Bir Python projesi başlatın ve gerekli bağımlılıkları ekleyin:

uv init
uv add google-adk==1.25.0 toolbox-adk==0.6.0

google-adk — Gemini SDK dahil olmak üzere Google'ın Agent Development Kit'i
toolbox-adk — Veritabanları için MCP Araç Kutusu'nda ADK entegrasyonu.

Temsilci dizin yapısını oluşturma

ADK, belirli bir klasör düzeni bekler: __init__.py, agent.py ve .env içeren, temsilcinizin adını taşıyan bir dizin. Bu konuda yardımcı olmak için yapıyı hızlıca oluşturmaya yönelik yerleşik bir komut vardır:

uv run adk create jobs_agent \
    --model gemini-2.5-flash \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --region ${GOOGLE_CLOUD_LOCATION}

Dizininiz artık şu şekilde görünmelidir:

build-agent-adk-toolbox-cloudsql/
├── jobs_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env
├── pyproject.toml
├── .env              (project setup — already exists)
└── .venv/

5. İş ilanı veritabanını doldurma

Bu adımda başlangıç verileri yazılır, Cloud SQL örneğinin sağlama işleminin tamamlanması beklenir ve jobs tablosuna 15 iş ilanı ile açıklamalarının yerleştirilmesi yüklenir.

Başlangıç SQL'ini yazma

Cloud Shell Düzenleyici'de iş listeleme içeriğini içeren seed.sql adlı bir dosya oluştururuz. Bu işlem, pgvector destekli jobs tablosunu oluşturur ve teknoloji şirketlerindeki 15 iş ilanını ekler.

İlk olarak, aşağıdaki komutu kullanarak seed.sql dosyasını oluşturun:

cloudshell edit seed.sql

Ardından bu komut dosyalarını dosyaya kopyalayın.

-- seed.sql
-- DISCLAIMER: These job listings are entirely fictional and created for tutorial
-- purposes only. Company names are used for illustrative context — the positions,
-- salaries, and descriptions do not reflect real openings.

CREATE EXTENSION IF NOT EXISTS google_ml_integration;
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS jobs (
    id SERIAL PRIMARY KEY,
    title VARCHAR NOT NULL,
    company VARCHAR NOT NULL,
    role VARCHAR NOT NULL,
    tech_stack VARCHAR NOT NULL,
    salary_range VARCHAR NOT NULL,
    location VARCHAR NOT NULL,
    openings INTEGER NOT NULL,
    description TEXT NOT NULL,
    description_embedding vector(3072)
);

INSERT INTO jobs (title, company, role, tech_stack, salary_range, location, openings, description) VALUES
('Senior Backend Engineer', 'Stripe', 'Backend', 'Go, PostgreSQL, gRPC, Kubernetes', '$180-250K/year', 'San Francisco, Hybrid', 3,
 'Design and build high-throughput microservices powering payment infrastructure for millions of businesses. Optimize Go services for sub-100ms latency at scale, work with PostgreSQL and Redis for data persistence, and deploy on Kubernetes clusters handling billions of API calls.'),

('Machine Learning Engineer', 'Spotify', 'Data/AI', 'Python, TensorFlow, BigQuery, Vertex AI', '$170-230K/year', 'Stockholm, Remote', 2,
 'Build and deploy ML models for music recommendation and personalization systems serving hundreds of millions of listeners. Design feature pipelines in BigQuery, train models using distributed computing, and serve predictions through real-time APIs processing thousands of requests per second.'),

('Frontend Engineer', 'Vercel', 'Frontend', 'React, TypeScript, Next.js', '$140-190K/year', 'Remote', 4,
 'Build developer-facing dashboard interfaces and deployment tools used by millions of developers worldwide. Create responsive, accessible React components for project management, analytics, and real-time deployment monitoring with a focus on developer experience.'),

('DevOps Engineer', 'Datadog', 'DevOps', 'Terraform, GCP, Docker, Kubernetes, ArgoCD', '$160-220K/year', 'New York, Hybrid', 2,
 'Manage cloud infrastructure powering an observability platform used by thousands of engineering teams. Automate deployment pipelines with ArgoCD, manage multi-cloud Kubernetes clusters, and implement infrastructure-as-code with Terraform across production environments.'),

('Mobile Engineer (Android)', 'Grab', 'Mobile', 'Kotlin, Jetpack Compose, GraphQL', '$120-170K/year', 'Singapore, Hybrid', 3,
 'Develop features for a super-app serving millions of users across Southeast Asia. Build modern Android UIs with Jetpack Compose, integrate GraphQL APIs, and optimize app performance for diverse device capabilities and network conditions.'),

('Data Engineer', 'Airbnb', 'Data', 'Python, Apache Spark, Airflow, BigQuery', '$160-210K/year', 'San Francisco, Hybrid', 2,
 'Build data pipelines that process booking, search, and pricing data for a global travel marketplace. Design ETL workflows with Apache Spark and Airflow, maintain data warehouses in BigQuery, and ensure data quality for analytics and machine learning teams.'),

('Full Stack Engineer', 'Revolut', 'Full Stack', 'TypeScript, Node.js, React, PostgreSQL', '$130-180K/year', 'London, Remote', 5,
 'Build the next generation of financial products making banking accessible to millions of users across 35 countries. Develop real-time trading interfaces with React and WebSockets, build Node.js APIs handling market data streams, and design PostgreSQL schemas for financial transactions.'),

('Site Reliability Engineer', 'Cloudflare', 'SRE', 'Go, Prometheus, Grafana, GCP, Terraform', '$170-230K/year', 'Austin, Hybrid', 2,
 'Ensure 99.99% uptime for a global network handling millions of requests per second. Define SLOs, build monitoring dashboards with Prometheus and Grafana, manage incident response, and automate infrastructure scaling across 300+ data centers worldwide.'),

('Cloud Architect', 'Google Cloud', 'Cloud', 'GCP, Terraform, Kubernetes, Python', '$200-280K/year', 'Seattle, Hybrid', 1,
 'Help enterprises modernize their infrastructure on Google Cloud. Design multi-region architectures, lead migration projects from on-premises to GKE, and build reference implementations using Terraform and Cloud Foundation Toolkit.'),

('Backend Engineer (Payments)', 'Square', 'Backend', 'Java, Spring Boot, PostgreSQL, Kafka', '$160-220K/year', 'San Francisco, Hybrid', 3,
 'Build payment processing systems handling millions of transactions for businesses of all sizes. Design event-driven architectures using Kafka, implement idempotent payment flows with Spring Boot, and ensure PCI-DSS compliance across all services.'),

('AI Engineer', 'Hugging Face', 'Data/AI', 'Python, LangChain, Vertex AI, FastAPI, PostgreSQL', '$150-210K/year', 'Paris, Remote', 2,
 'Build AI-powered tools for the largest open-source ML community. Develop RAG pipelines that index and search model documentation, create conversational agents using LangChain, and deploy AI services with FastAPI on cloud infrastructure.'),

('Platform Engineer', 'Coinbase', 'Platform', 'Rust, Kubernetes, AWS, Terraform', '$180-250K/year', 'Remote', 0,
 'Build the infrastructure platform for a leading cryptocurrency exchange. Develop high-performance matching engines in Rust, manage Kubernetes clusters for microservices, and design CI/CD pipelines that enable rapid feature deployment with zero downtime.'),

('QA Automation Engineer', 'Shopify', 'QA', 'Python, Selenium, Cypress, Jenkins', '$110-160K/year', 'Toronto, Hybrid', 3,
 'Design and maintain automated test suites for a commerce platform powering millions of merchants. Build end-to-end test frameworks with Cypress and Selenium, integrate tests into Jenkins CI pipelines, and establish quality gates that prevent regressions in checkout and payment flows.'),

('Security Engineer', 'CrowdStrike', 'Security', 'Python, SIEM, Kubernetes, Penetration Testing', '$170-240K/year', 'Austin, On-site', 1,
 'Protect enterprise customers from cyber threats on a leading endpoint security platform. Conduct penetration testing, design security monitoring with SIEM tools, implement zero-trust networking in Kubernetes environments, and lead incident response for security events.'),

('Product Engineer', 'GitLab', 'Full Stack', 'Go, React, PostgreSQL, Redis, GCP', '$140-200K/year', 'Remote', 4,
 'Own features end-to-end for an all-in-one DevSecOps platform used by millions of developers. Build Go microservices for CI/CD pipelines, create React frontends for code review and project management, and collaborate with product managers to iterate on user-facing features using data-driven development.');

Başlangıç komut dosyası iki PostgreSQL uzantısı yükler:

google_ml_integration: Vertex AI yerleştirme modellerini doğrudan SQL'den çağıran embedding() SQL işlevini sağlar. Bu, jobs_db içinde makine öğrenimi işlevlerini kullanılabilir hale getiren bir veritabanı düzeyinde uzantıdır. Örnek oluşturma sırasında ayarladığınız örnek düzeyindeki işaret (--enable-google-ml-integration), Cloud SQL VM'nin Vertex AI'ye ulaşmasına olanak tanır. Bu uzantı, SQL işlevlerini söz konusu veritabanında kullanılabilir hâle getirir.
vector (pgvector): Yerleştirmeleri depolamak ve sorgulamak için vector veri türünü ve mesafe operatörlerini ekler.

description_embedding sütunu, vector(3072) (3072 boyutlu vektörleri depolayan bir pgvector sütunu) olur. Şu anda NULL'dur. Bir sonraki adımda embedding() işlevini kullanarak yerleştirmeler oluşturup dolduracaksınız.

Veritabanı kurulumunu tamamlama

Önceki adımda başlattığınız Cloud SQL örneği oluşturma işlemi hâlâ devam ediyor ve henüz tamamlanmamış olabilir. Örneğin hazır olduğunu doğrulayın:

gcloud sql instances describe jobs-instance --format="value(state)"

Aşağıdaki çıkışı görmeniz gerekir.

RUNNABLE

Ardından, Cloud SQL örneğinin hizmet hesabına Vertex AI'ı çağırma izni verin. Bu, sonraki adımda kullanacağınız yerleşik embedding() işlevi için gereklidir:

SERVICE_ACCOUNT=$(gcloud sql instances describe jobs-instance --format="value(serviceAccountEmailAddress)")

gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" \
  --quiet

Ardından, iş ilanları için özel bir veritabanı oluşturun:

gcloud sql databases create jobs_db --instance=jobs-instance

Veritabanının oluşturulduğunu onaylayan bir çıkış görmeniz gerekir:

Creating Cloud SQL database...done.                                                                         
Created database [jobs_db].
instance: jobs-instance
name: jobs_db
project: workshop-xxxxxxx

Veritabanını bağlama ve doldurma

Cloud SQL Auth Proxy'yi başlatın (cloud-sql-proxy, Cloud Shell'e önceden yüklenmiştir). Bu, Cloud Shell'den Cloud SQL örneğinize güvenli ve kimliği doğrulanmış bir bağlantı sağlar:

cloud-sql-proxy ${GOOGLE_CLOUD_PROJECT}:${REGION}:jobs-instance --port 5432 &

Proxy başlatılırsa terminalde şu çıkışı görürsünüz:

... Authorizing with Application Default Credentials
... [workshop-xxxxxx:your-location:jobs-instance] Listening on 127.0.0.1:5432
... The proxy has started successfully and is ready for new connections!

Şu anda geçerli terminal, Cloud SQL Proxy'nin günlüğünü sürekli olarak çıkarıyor. Daha iyi odaklanabilmek için Cloud Shell'de yeni bir terminal sekmesi açalım (artı simgesini tıklayın).

Çalışma dizininize tekrar gidin ve önceki kurulum komut dosyasını kullanarak projeyi etkinleştirin.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Ardından, başlangıç komut dosyasını çalıştırın.

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" -f seed.sql

Şuna benzer bir terminal çıkışı görürsünüz:

CREATE EXTENSION
CREATE EXTENSION
CREATE TABLE
INSERT 0 15

Verileri doğrulayalım

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "SELECT title, company, role, openings FROM jobs ORDER BY role, title;"

Birden fazla rolde 15 iş ilanı görürsünüz:

             title              |    company     |   role    | openings
---------------------------------+----------------+-----------+----------
 Senior Backend Engineer         | Stripe         | Backend   |        3
 Backend Engineer (Payments)     | Square         | Backend   |        3
 Cloud Architect                 | Google Cloud   | Cloud     |        1
 ...
(15 rows)

İş tanımları için yerleştirilmiş öğeler oluşturma

jobs tablosundaki description_embedding sütunu şu anda NULL. Cloud SQL'in yerleşik google_ml_integration uzantısı, Python komut dosyası veya harici SDK gerektirmeden Vertex AI'ı doğrudan SQL'den çağıran bir embedding() işlevi sağlar.

Arka planda yerleştirme oluşturma işlemini başlatın. Bu işlem, 15 iş açıklamasının her biri için gemini-embedding-001 modelini kullanarak 3.072 boyutlu bir vektör oluşturmak üzere Vertex AI'ı çağırır:

psql "host=127.0.0.1 port=5432 dbname=jobs_db user=postgres password=$DB_PASSWORD" \
  -c "UPDATE jobs SET description_embedding = embedding('gemini-embedding-001', description)::vector;" &

Bu komut dosyası şunları yapar:

embedding('gemini-embedding-001', description) — Her işin description metnini ileterek doğrudan SQL'den Vertex AI'ın Gemini yerleştirme modelini çağırır. Bu, başlangıç komut dosyasına yüklediğiniz google_ml_integration uzantısıdır.
::vector: Döndürülen kayan nokta dizisini, pgvector'ın vector türüne yayınlar. Böylece, mesafe operatörleriyle depolanabilir ve sorgulanabilir.
UPDATE, 15 satırın tamamında çalışarak her iş açıklaması için 3.072 boyutlu bir yerleştirme oluşturur.
&, komutu arka planda çalıştırır. Böylece Vertex AI yerleştirmeleri işlerken çalışmaya devam edebilirsiniz.

Önceki arka plan işlemi yürütme işlemlerinde olduğu gibi, mevcut terminalde işlemin günlüğü çıkışı yapılır. Daha iyi odaklanabilmek için Cloud Shell'de yeni bir terminal sekmesi açalım (artı simgesini tıklayın).

Çalışma dizininize tekrar gidin ve önceki kurulum komut dosyasını kullanarak projeyi etkinleştirin.

cd ~/build-agent-adk-toolbox-cloudsql
bash setup_verify_trial_project.sh && source .env

Ardından, bir sonraki işleme geçebiliriz.

6. Veritabanları için MCP Toolbox'ı yapılandırma

Bu adımda, Veritabanları için MCP Araç Kutusu tanıtılır, Cloud SQL örneğinize bağlanacak şekilde yapılandırılır ve iki standart SQL sorgu aracı tanımlanır.

ÇMY nedir ve neden Araç Kutusu'nu kullanmalısınız?

MCP (Model Context Protocol), yapay zeka temsilcilerinin harici araçları keşfetme ve bunlarla etkileşime girme şeklini standartlaştıran açık bir protokoldür. Bir istemci-sunucu modeli tanımlar: Aracı, bir MCP istemcisine ev sahipliği yapar ve araçlar MCP sunucuları tarafından kullanıma sunulur. MCP ile uyumlu herhangi bir istemci, MCP ile uyumlu herhangi bir sunucuyu kullanabilir. Aracının her araç için özel entegrasyon koduna ihtiyacı yoktur.

MCP Toolbox for Databases, özellikle veritabanı erişimi için oluşturulmuş açık kaynaklı bir MCP sunucusudur. Bu olmadan, veritabanı bağlantılarını açan, bağlantı havuzlarını yöneten, SQL eklemeyi önlemek için parametreli sorgular oluşturan, hataları işleyen ve tüm bu kodu aracınıza yerleştiren Python işlevleri yazmanız gerekirdi. Veritabanı erişimi gereken her temsilci bu çalışmayı tekrarlar. Bir sorguyu değiştirmek, temsilcinin yeniden dağıtılması anlamına gelir.

Araç kutusu ile bir YAML dosyası yazarsınız. Her araç, parametrelendirilmiş bir SQL ifadesiyle eşlenir. Toolbox, bağlantı havuzunu, parametreli sorguları, kimlik doğrulamayı ve gözlemlenebilirliği yönetir. Araçlar, aracıdan ayrılır. tools.yaml düzenleyip Toolbox'ı yeniden başlatarak sorguyu güncelleyin. Aracı koduna dokunmayın. Aynı araçlar ADK, LangGraph, LlamaIndex veya MCP ile uyumlu herhangi bir çerçevede çalışır.

Araç yapılandırmasını yazma

Şimdi, araç yapılandırmamızı ayarlamak için Cloud Shell Düzenleyici'de tools.yaml adlı bir dosya oluşturmamız gerekiyor.

cloudshell edit tools.yaml

Dosyada çok dokümanlı YAML kullanılır. --- ile ayrılan her blok bağımsız bir kaynaktır. Her kaynağın, ne olduğunu bildiren bir kind (veritabanı bağlantıları için sources, aracı tarafından çağrılabilir işlemler için tools) ve arka ucu belirten bir type (kaynak için cloud-sql-postgres, SQL tabanlı araçlar için postgres-sql) vardır. Bir araç, kaynağına name ile referans verir. Bu sayede Araç Kutusu, hangi bağlantı havuzunun yürütüleceğini bilir. Ortam değişkenleri ${VAR_NAME} söz dizimini kullanır ve başlatma sırasında çözümlenir.

Şimdi aşağıdaki komut dosyalarını önce tools.yaml dosyasına kopyalayalım.

# tools.yaml

# --- Data Source ---
kind: sources
name: jobs-db
type: cloud-sql-postgres
project: ${GOOGLE_CLOUD_PROJECT}
region: ${REGION}
instance: jobs-instance
database: jobs_db
user: postgres
password: ${DB_PASSWORD}

---