Google ADK Eğitimi: Bir MCP Sunucusu Lojistik Aracısı Oluşturma

Bugün gelişmiş yapay zeka ajanları inşa etmenin en büyük engeli model değil, entegrasyondur. Bir ajanın on farklı kurumsal araca erişmesini istiyorsanız, genellikle on farklı API sarmalayıcısı yazmanız gerekir. Deneyimlerime göre bu, sarmalayıcı yorgunluğuna ve devasa bir bakım yüküne yol açıyor. Her API değiştiğinde ajanınız bozuluyor.

Çözüm, Google Agent Development Kit (ADK) ile Model Context Protocol (MCP) arasındaki iş birliğinde yatıyor. Yapay zekayı bir çalışan olarak düşünürsek, ADK "beyin"dir (mantığı ve hafızayı orkestre eder), MCP ise "elleri" temsil eder (herhangi bir aracı alıp kullanmanın standartlaştırılmış yolu).

Bu eğitimde, ADK kullanarak gerçek bir lojistik kurtarma ajanı oluşturacağız. Ajan şunları yapacak:

1. BigQuery’de yüksek öncelikli gecikmiş siparişleri sorgulamak. 
2. Google Maps MCP sunucusunu kullanarak depodan müşteriye gerçek sürüş mesafesini hesaplamak. 
3. Uzun mesafeli gönderiler için hava taşımacılığına yükseltme gibi bir kurtarma eylemi önermek.

Tüm bunlar, tek bir satır özel API kodu yazmadan gerçekleşir. Ajan araçları otomatik olarak keşfeder ve kullanır.

Google Cloud’a yeni misiniz? Faturalandırma, projeler ve temel hizmetleri kapsamak için ücretsiz Introduction to GCP kursuyla başlamanızı öneririm.

Google ADK Nedir?

Google Agent Development Kit (ADK), Google’ın yapay zeka ajanları oluşturmak, test etmek ve dağıtmak için sunduğu açık kaynaklı, kod odaklı bir çerçevedir. LangChain gibi çerçeveler zincirlere odaklanırken, ADK icra için tasarlanmıştır. Ajanların nasıl düşündüğüne, araç setlerini nasıl kullandığına ve üretim ortamlarında nasıl çalıştığına dair standart bir yapı sunar.

İşte temel kavramlar:

• Ajanlar: Modeli (ör. Gemini 2.0 Flash) ve belirli talimat setiyle tanımlanan çekirdek varlık.
• Araç setleri: Yetenekler koleksiyonu. Araçları elle tanımlamak yerine ADK’yi bir MCP sunucusuna yönlendiriyoruz ve o araçları otomatik olarak "öğreniyor".
• Çalıştırıcılar (Runners): Konuşma durumunu ve yinelemeli "düşünce-eylem-gözlem" döngüsünü yöneten yürütme motoru.

Bu kod odaklı yaklaşımı kullanmak, sürüm kontrolü, test ve CI/CD’yi tıpkı normal yazılımda yaptığımız gibi kullanmamıza olanak tanır. Ayrıca derin Google entegrasyonu sunar; yani, yönetilen MCP sunucuları BigQuery veya Maps için neredeyse hiç dağıtım gerektirmez.

“Büyük üç” bulut sağlayıcısını ve hizmetlerini karşılaştırmak için AWS vs. Azure vs. Google Cloud rehberimize mutlaka göz atın.

Google ADK Entegrasyon Mimarisi ve Mantık Akışı

Lojistik kurtarma ajanımız bir iş problemini çözmek için net bir akıl yürütme yolunu izler. Akışı anlamak, daha sonra istem talimatlarını yazmaya başladığınızda yardımcı olur.

Akıl yürütme döngüsü şu adımları izler:

1. Ajan, status='Delayed' ve priority='High' olan satırları bulmak için BigQuery MCP’yi çağırır. 

2. Dönen her sipariş için ajan, depo ve müşteri adreslerini çıkarır. 

3. Ajan, sürüş mesafesini hesaplamak için her sipariş için Google Maps MCP’yi çağırır. 

4. Ajan iş mantığını uygular (ör. 500 mil üzeri mesafe hava taşımacılığı demektir) ve önerilerin bulunduğu bir markdown tablosu sunar.

MCP Sunucularını Kurma

Kodlamaya başlamadan önce, temel bulut altyapısını hazırlamamız ve MCP sunucularını hazır hale getirmemiz gerekir. Deneyimlerime göre bu aşamada IAM izinlerini doğru ayarlamak en önemli kısımdır.

Adım 1: Google Cloud CLI’yı başlatma 

Önce Google Cloud CLI’yı kurduğunuzdan emin olun. Başlamak için, terminalinizi açın ve yerel ortamınızı Google hesabınıza bağlamak üzere aşağıdaki komutu çalıştırın:

gcloud initAltyapı:

Bunu çalıştırdığınızda, otomatik olarak bir tarayıcı penceresi açılır. Google hesabınızla oturum açmanız istenir. Oturum açtıktan sonra, CLI’ın kaynaklarınızı yönetmesine izin vermek için Allow’a tıklayın. 

Terminale geri döndüğünüzde, komut istemi sizden varsayılan bir proje seçmenizi isteyecektir. Halihazırda oluşturduysanız projenin kimliğini seçin ya da terminalde yeni bir proje oluşturun.

Adım 2: Faturalandırmayı ayarlama

API hizmetlerini kullanmak için faturalandırmayı ayarlamanız gerekir. Bununla birlikte Google Cloud, Compute, GKE ve Maps gibi hizmetleri denemeniz için 90 gün boyunca 300 $ ücretsiz kredi verir ve bu ücretsiz krediler bu eğitimdeki örnek için fazlasıyla yeterlidir. Yalnızca kullandıkça ödeyi veya ön ödemeyi açarsanız ücretlendirilirsiniz. Faturalandırmayı ayarlamak için:

1. Google Console faturalandırma sayfasına gidin ve gcloud için kullandığınız hesapla oturum açın.

2. Bir faturalandırma hesabınız yoksa oluşturun (ödeme yöntemi eklemek gerekir, ancak önce ücretsiz kredi uygulanır).

3. Faturalandırma hesabını projenize bağlayın: Billing → Link a project → projenizi seçin veya şunu çalıştırın:

gcloud billing projects link YOUR_PROJECT_ID --billing-account=BILLING_ACCOUNT_IDAltyapı:

Adım 3: Çekirdek API’leri ve MCP hizmetlerini etkinleştirme

Sırada birincil ürün API’lerini etkinleştirmemiz gerekiyor. Bunlar, ajanın BigQuery ve Maps gibi ham veri hizmetlerine ulaşmasını sağlar.

gcloud services enable bigquery.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com
gcloud services enable mapstools.googleapis.comAltyapı:

Şimdi, Yönetilen MCP Uç Noktalarını etkinleştirmeliyiz. Bunları, normal API’lerin üzerine oturan çevirmen arayüzleri olarak düşünmenin faydalı olduğunu gördüm. 

Önce, proje kimliğinizi ve hesap e-postanızı ortam değişkenlerine kaydedelim. Bu, sonraki her komut için bunları elle yazmamızı önler:

export PROJECT_ID=$(gcloud config get-value project)
export USER_EMAIL=$(gcloud config get-value account)Altyapı:

Bu değişkenler ayarlandıktan sonra, belirli projeniz için beta MCP özelliklerini açmak üzere aşağıdaki komutları çalıştırın. Bu komutlar, ajanın çağırması için uzak MCP uç noktalarını hazırlaması için Google’a talimat verir:

gcloud beta services mcp enable bigquery.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable mapstools.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable container.googleapis.com --project=$PROJECT_ID
gcloud beta services mcp enable compute.googleapis.com --project=$PROJECT_IDAltyapı:

Adım 3: IAM ve Maps Anahtarlarını yapılandırma 

MCP, "çift katmanlı" bir güvenlik modeli kullanır. MCP sunucusuyla konuşmak için izin gerekir ve gerçek verilere (ör. bir tablodaki satırlar) erişmek için ayrı bir izin gerekir. Bunu gcloud CLI veya Google Cloud Console arayüzünü kullanarak yapabilirsiniz.

IAM Seçenek A: gcloud CLI kullanma 

Hesabınıza MCP kullanma ve BigQuery ile etkileşim kurma izni vermek için şu üç komutu çalıştırın:

# MCP Çevirmen ile konuşma izni
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/mcp.toolUser"

# BigQuery işlerini çalıştırma ve verileri görüntüleme izinleri
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.jobUser"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="user:$USER_EMAIL" --role="roles/bigquery.dataViewer"Altyapı:

IAM Seçenek B: Google Cloud Console’u (UI) kullanma

Görsel bir arayüzü tercih ediyorsanız, tarayıcıda şu adımları izleyebilirsiniz:

1. Google Cloud Console’unuzda IAM & Admin sayfasına gidin.
2. Listede e-posta adresinizi bulun ve Üyeyi Düzenle (kalem) simgesine tıklayın.
3. Başka Bir Rol Ekle’ye tıklayın ve MCP Tool Userı arayın.
4. Aynı işlemi BigQuery Data Viewer ve BigQuery Job Userı eklemek için tekrarlayın.
5. Kaydet’e tıklayın.

Bir Maps API anahtarı oluşturun

Son olarak, bir Maps API anahtarı oluşturun. Oturum açma bilgilerinizi kullanan BigQuery’den farklı olarak Maps MCP sunucusu, faturalandırma ve kota takibi için bu anahtarı kullanır: 

gcloud alpha services api-keys create --display-name="Maps-MCP-Key"Altyapı:

Adım 4: MCP Inspector ile sunucuları yerelde doğrulama

Python kodumuzu yazmadan önce, MCP Inspector kullanarak bir sağlamlık kontrolü yapmalıyız. Node.js ile gelen npx komutunu kullanacağız. 

Amacı, bir paketi (örneğin inspector) bilgisayarınıza kalıcı olarak kurmadan hemen çalıştırmanıza izin vermektir. Bunu terminalinizde çalıştırın:

npx @modelcontextprotocol/inspectorAltyapı:

Bu, tarayıcınızda bir web arayüzü başlatacaktır (genellikle http://localhost:3000). Aşağıdaki kurulum listesindeki belirli seçimleri, Google’ın sunucularının yerel bir taklidini değil Uzaktan Yönetilen sürümünü test ettiğimizden emin olmak için yaptım:

1. Taşıma türü: Streamable HTTP. Bunu seçiyoruz çünkü Google’ın yönetilen bulut sunucuları için kullandığı üretim standart protokoldür.

2. URL: https://mapstools.googleapis.com/mcp girin. Bu, Google’ın Maps MCP’sine doğrudan giriş kapısıdır.

3. Bağlantı Türü: Proxy aracılığıyla. Bu kritik bir seçimdir. "Proxy" seçilerek, inspector yerel gcloud oturum açmanızı kullanarak tüm karmaşık güvenlik el sıkışmalarını otomatik olarak halleder.

4. Özel Üstbilgiler: X-Goog-Api-Key ekleyin ve 3. Adımda aldığınız anahtarı yapıştırın.

5. Connect’e tıklayın.

Bağlandı durumunu şimdi yeşil olarak görmelisiniz. Sunucunun sunduğu tüm yeteneklerin bir listesini görmek için List Tools düğmesine tıklayın. Listede compute_routes görürseniz, altyapınız mükemmel şekilde yapılandırılmış demektir.

Ajanlarınız için BigQuery, Maps ve diğer Google hizmetlerinin nasıl kullanılacağına daha derinlemesine bir bakış için Google MCP Sunucuları üzerine bu eğitimi mutlaka inceleyin.

Google ADK ile Bir MCP Sunucusu Ajanı Oluşturma

Altyapı hazır olduğuna göre, şimdi yerel geliştirme ortamımıza geçebiliriz. Proje dosyalarımızı düzenleyerek başlayacağız.

Adım 1: Proje yapısını ve bağımlılıkları ayarlama

Başlamak için projeniz için bir klasör oluşturun ve bir sanal ortam ayarlayın.

mkdir my-agents
cd my-agents
python -m venv .venv
source .venv/bin/activateAltyapı:

Yukarıdaki son komut macOS veya Linux kullanıcıları içindir; Windows kullanıyorsanız bunun yerine .venv\Scripts\activate kullanın.

Sonraki adımda, google-adk paketini destekleyici kitaplıklarıyla birlikte kurabilirsiniz.

pip install google-adk google-generativeai python-dotenv httpx  google-authAltyapı:

Yapmanız gereken bir şey daha var: kök klasörünüzde, önceki adımda oluşturduğunuz PROJECT_ID ve MAPS_API_KEY’i saklamak için bir .env dosyası oluşturun.

Adım 2: MCP araç setlerini yapılandırma

tools.py adlı bir betikte, "veri almak" için kod yazmıyoruz. Bunun yerine, veri almayı bilen bir sunucuya bağlanmak için kod yazıyoruz. 

Araçları mantıktan ayırmanın projeyi hata ayıklamayı çok daha kolay hale getirdiğini gördüm. Uzak Google Cloud uç noktalarıyla konuştuğumuz için kimlik doğrulama üstbilgilerini yönetmek üzere StreamableHTTPConnectionParams kullanıyoruz.

import os
import google.auth
import google.auth.transport.requests
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams 

# --- BigQuery Toolset ---
def get_bigquery_mcp_toolset():   
    credentials, project_id = google.auth.default(
        scopes=["https://www.googleapis.com/auth/bigquery"]
    )
    credentials.refresh(google.auth.transport.requests.Request())
        
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://bigquery.googleapis.com/mcp",
            headers={
                "Authorization": f"Bearer {credentials.token}",
                # 'x-goog-user-project' is vital for BigQuery billing
                "x-goog-user-project": project_id,
                "Content-Type": "application/json"
            }
        )
    )

# --- Maps Toolset ---
def get_maps_mcp_toolset():
    maps_api_key = os.getenv('MAPS_API_KEY')
    
    return MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url="https://mapstools.googleapis.com/mcp",
            headers={
                "X-Goog-Api-Key": maps_api_key,
                "Content-Type": "application/json"
            }
        )
    )Altyapı:

Adım 3: Ajanın görevini tanımlama

Şimdi "beyni" inşa ediyoruz. Deneyimlerime göre burada Gemini Flash modellerinden birini kullanmak en iyi seçim, çünkü araç çağırmada son derece hızlılar. 

Ajanı agent.py dosyasındaki talimatlar aracılığıyla standart bir işletim prosedürü ile donatıyoruz. Ajanın kafasının karışmasını önlemek için nasıl net, dört adımlı bir hattı kullandığımıza dikkat edin.

from .tools import get_maps_mcp_toolset, get_bigquery_mcp_toolset
from google.adk.agents import LlmAgent

# We're giving the agent a very structured 'Instruction' set. 
# Think of this as the SOP (Standard Operating Procedure) for your agent.
root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='logistics_recovery_agent',
    instruction="""
      You are an expert Retail Operations Recovery Agent. 
      Your job is to find high-priority problems and solve them using the tools provided.

      Step 1: Use 'execute_sql' to find orders where status is 'Delayed' and priority is 'High'.
      Step 2: For every result, pull the warehouse and customer addresses.
      Step 3: Call the Maps 'compute_routes' tool to find the exact drive distance.
      Step 4: Use this logic: If distance > 500 miles, recommend 'Air Shipping'. 
            Otherwise, recommend 'Regional Express Ground'.
    
      Output the final result as a clean Markdown table.
    """,
    # We simply drop our toolsets here. 
    # ADK handles the complexity of deciding which tool to call when.
    tools=[get_maps_mcp_toolset(), get_bigquery_mcp_toolset()]
)Altyapı:

Adım 4: Ajan döngüsünü çalıştırma 

Ajanı çalıştırmak için runner’ı kullanıyoruz. Bu bileşen, ajanın neleri hallettiğini ve sırada ne yapması gerektiğini bilmesi için konuşma durumunu takip eder.

from google.adk.runners import Runner
from google.genai import types

async def main():
    # The Runner acts as the host for our agent.
    runner = Runner(app_name="logistics_app", agent=root_agent)

    # Wrap the user input in the standard GenAI Content format
    user_input = "Identify high-priority delayed orders and suggest recovery shipping methods."
    content = types.Content(role="user", parts=[types.Part(text=user_input)])

    print("--- Starting Smart Logistics Agent ---")
    
    # We use run_async to stream the 'events' (Thoughts and Tool Calls)
    async for event in runner.run_async(user_id="admin_user", new_message=content):
        # We only want to print the text part of the response to the console
        if hasattr(event, 'content') and event.content.parts:
            print(event.content.parts[0].text)Altyapı:

Arka planda neler oluyor?

runner.run_async çağrıldığında, ADK yinelemeli bir döngü başlatır:

1. Gemini düşünür: "Önce gecikmiş siparişleri görmem gerekiyor."

2. ADK eyleme geçer: BigQuery MCP araç setinizden execute_sql aracını çağırır.

3. Gözlem: Araç, sipariş verilerini döndürür.

4. Gemini düşünür: "Şimdi bu iki sipariş için mesafelere ihtiyacım var."

5. ADK eyleme geçer: Maps MCP aracını iki kez çağırır.

6. Son Yanıt: Gemini tüm verileri görür, sizin "500 mil" mantığınızı uygular ve tabloyu biçimlendirir.

Google ADK Ajanımızı Web Konsolunda Test Etme

Terminal günlükler için harika olsa da ADK, ajanın içsel akıl yürütmesini görselleştiren yerleşik bir web konsolu içerir. Bunun hata ayıklama için en faydalı araç olduğunu gördüm.

Arayüzü adk web komutunu çalıştırarak başlatın. Sunucu başladıktan sonra tarayıcınızı http://127.0.0.1:8000 adresine açın. "Yüksek öncelikli gecikmiş siparişleri belirleyin ve kurtarma gönderim yöntemleri önerin." komutunu gönderebileceğiniz temiz, sohbet benzeri bir arayüz göreceksiniz.

Yürütme izini analiz etme

ADK konsolu, ajanın bulut altyapınızla tam olarak nasıl etkileşime girdiğine dair şeffaf bir "iz" sağlar.

Adım adım inceleyelim:

1. Arayüz el sıkışmaları: execute_sql ve compute_routes etiketli simgelere dikkat edin. İzde, şimşek simgesi bir araç çağrısını gösterir. Ajan sadece tahmin etmedi; siparişler tablonuzda belirli bir SQL sorgusunu çalıştırmak için BigQuery MCP sunucusuna fiilen ulaştı.

2. Sıralı mantık: İz, net bir işlem sırası gösterir. İlk olarak BigQuery aracılığıyla verileri çeker (ilk onay işareti). Depo ve müşteri adresleri eline geçince birden fazla compute_routes çağrısı görürsünüz. Ajan, gecikmiş siparişler arasında akıllıca "döngü" yaparak gerçek dünya mesafe verilerini Maps MCP sunucusundan alır.

3. Nihai sentez: İzin en altında nihai yanıtı görürsünüz.

Verilere bakın:

• ORD-101: Mesafe 380 mil.
• ORD-103: Mesafe 352 mil.

Ajana şu mantığı verdiğimiz için: "Mesafe > 500 mil ise Air Shipping öner, değilse Regional Express Ground öner"; ajan bu iş kuralını her iki siparişe de doğru şekilde uyguladı ve bunları güzel bir Markdown tablosuna biçimlendirdi.

Sonuç

BigQuery veya Google Maps için tek bir satır özel API kodu yazmadan işlevsel bir Lojistik Ajanı oluşturduk. ADK ve MCP kullanarak modüler, güvenli ve geliştirici odaklı bir mimari kurduk.

Yapay zekanın geleceği sadece konuşan sohbet botları değil, eyleme geçen ajanlardır. Bu araçlarla nihayet o gerçeğe doğru ilerliyoruz.

Bu eğitim, Google ADK ve MCP sunucularıyla denemeleriniz için harika bir başlangıç noktası olabilir: 

• Veri kaynaklarını değiştirmenin ne kadar kolay olduğunu görmek için BigQuery’i farklı bir veri setiyle (hatta yerel bir SQLite MCP sunucusuyla) değiştirin.
• Tak-çalıştır doğasını kanıtlamak için Maps’i başka bir MCP sunucusuyla (ör. küme sağlık kontrolleri için GKE) değiştirin.
• İsteminize daha fazla iş mantığı ekleyin (maliyet karşılaştırması, e‑posta taslağı) ve bunu ADK web arayüzünde canlı olarak test edin.

Ajan orkestrasyonu hakkında daha fazla bilgi edinmek istiyorsanız, Associate AI Engineer for Developers kariyer yoluna kaydolmanızı şiddetle tavsiye ederim.