BigQuery ve Google Haritalar için MCP sunucularıyla bir Konum Zekası ADK Aracısı oluşturma

1. Giriş

Bu codelab'de, Gemini 3.1 Pro destekli bir ADK ajanı oluşturacaksınız. Ajan, demografi, fiyatlandırma ve satış verileri için BigQuery'ye güvenli bir şekilde erişmek üzere iki uzak (Google tarafından barındırılan) MCP sunucusundaki araçlarla, gerçek dünya konum analizi ve doğrulama için ise Google Haritalar'daki araçlarla donatılacak.

Ajan, kurgusal fırın veri kümesiyle ilgili işletme sorunlarını çözmek için kullanıcı ile Google Cloud hizmetleri arasındaki istekleri düzenler.

Yapacaklarınız

Verileri ayarlama: BigQuery'de temel fırın veri kümesini oluşturun.
Ajanı geliştirin: Agent Development Kit'i (ADK) kullanarak akıllı bir ajan oluşturun.
Araçları entegre edin: MCP sunucusu aracılığıyla ajana BigQuery ve Haritalar işlevlerini ekleyin.
Pazarı analiz edin: Pazar trendlerini ve doygunluğunu değerlendirmek için temsilciyle etkileşime geçin.

Gerekenler

Chrome gibi bir web tarayıcısı
Faturalandırmanın etkin olduğu bir Google Cloud projesi veya bir Gmail hesabı.

Bu Codelab, yeni başlayanlar da dahil olmak üzere her seviyeden geliştiriciye yöneliktir. ADK geliştirme için Google Cloud Shell'deki komut satırı arayüzünü ve Python kodunu kullanacaksınız. Python uzmanı olmanız gerekmez ancak kodu nasıl okuyacağınızla ilgili temel bilgiler, kavramları anlamanıza yardımcı olur.

2. Başlamadan önce

Google Cloud projesi 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. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın:

Cloud Shell'e bağlandıktan sonra Cloud Shell'de kimlik doğrulamanızı doğrulamak için şu komutu çalıştırın:

gcloud auth list

Projenizin gcloud ile kullanılacak şekilde yapılandırıldığını doğrulamak için aşağıdaki komutu çalıştırın:

gcloud config get project

Projenin beklendiği gibi olduğunu onaylayın ve ardından proje kimliğinizi ayarlamak için aşağıdaki komutu çalıştırın:

export PROJECT_ID=$(gcloud config get project)

3. Kodu Al

Depoyu Klonlama

Depoyu Cloud Shell ortamınıza klonlayın:

git clone https://github.com/google/mcp.git

Demo dizinine gidin:

cd mcp/examples/launchmybakery

Kimlik doğrulama

Google Cloud hesabınızla kimliğinizi doğrulamak için aşağıdaki komutu çalıştırın. Bu, ADK'nın BigQuery'ye erişmesi için gereklidir.

gcloud auth application-default login

Kimlik doğrulama sürecini tamamlamak için talimatları uygulayın.

4. Ortamı ve BigQuery'yi yapılandırma

Kurulum Komut Dosyalarını Çalıştırma

Ortam kurulumu komut dosyasını çalıştırın. Bu komut dosyası, BigQuery ve Google Haritalar API'lerini etkinleştirir ve Proje Kimliğiniz ile Maps API Anahtarınızı içeren bir .env dosyası oluşturur.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

BigQuery kurulum komut dosyasını çalıştırın. Bu komut dosyası, Cloud Storage paketi oluşturma, veri yükleme ve BigQuery veri kümesi ile tablolarını sağlama işlemlerini otomatikleştirir.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

Komut dosyası tamamlandıktan sonra mcp_bakery veri kümesi oluşturulmalı ve aşağıdaki tablolarla doldurulmalıdır:

Demografi: Posta koduna göre nüfus sayımı verileri ve nüfus özellikleri.
bakery_prices: Çeşitli fırın ürünleri için rakip fiyatlandırması ve ürün ayrıntıları.
sales_history_weekly: Mağazaya ve ürüne göre haftalık satış performansı (miktar ve gelir).
foot_traffic: Posta koduna ve günün saatine göre tahmini yaya trafiği puanları.

Google Cloud projenizdeki BigQuery konsolunu ziyaret ederek veri kümesinin ve tabloların oluşturulduğunu doğrulayın:

5. ADK'yı yükleme

Altyapı hazır olduğuna göre şimdi sanal bir Python ortamı oluşturalım ve ADK için gerekli paketleri yükleyelim.

Sanal ortam oluşturun:

python3 -m venv .venv

Sanal ortamı etkinleştirin:

source .venv/bin/activate

ADK'yı yükleyin:

pip install google-adk==1.28.0

Temsilci dizinine gidin:

cd adk_agent/

6. ADK uygulamasını inceleme

Cloud Shell Düzenleyici'yi açmak ve klonlanan depoyu mcp/examples/launchmybakery dizininde görüntülemek için Cloud Shell'de Open Editor (Düzenleyiciyi Aç) düğmesini tıklayın.

Aracı kodu, adk_agent/ dizininde zaten sağlanmıştır. Çözüm yapısını inceleyelim:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

mcp_bakery_app içindeki önemli dosyalar:

agent.py: Temsilciyi, araçlarını ve modeli (Gemini 3.1 Pro Önizleme) tanımlayan temel mantık.
tools.py: Özel araç tanımlarını içerir.
.env: Proje yapılandırmanızı ve kurulum komut dosyası tarafından oluşturulan gizli anahtarları (ör. API anahtarları) içerir.

1. MCP Araç Setini İlk Kullanıma Hazırlama:

Şimdi MCP araç setlerinin nasıl başlatıldığını anlamak için Düzenleyici'de adk_agent/mcp_bakery_app/tools.py dosyasını açın.

Ajanımızın BigQuery ve Google Haritalar ile iletişim kurabilmesi için Model Context Protocol (MCP) istemcilerini yapılandırmamız gerekir.

Kod, StreamableHTTPConnectionParams kullanarak Google'ın uzak MCP sunucularıyla güvenli bağlantılar oluşturur.

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


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())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

Haritalar Araç Seti: API anahtarınızı kullanarak Haritalar MCP sunucusuna bağlantıyı yapılandırır.
BigQuery Araç Seti: Bu işlev, BigQuery MCP sunucusuna bağlantıyı yapılandırır. Cloud kimlik bilgilerinizi otomatik olarak almak için google.auth'u kullanır, bir OAuth Bearer jetonu oluşturur ve bunu Yetkilendirme üstbilgisine yerleştirir.

2. Aracı tanımı:

Şimdi, temsilcinin nasıl tanımlandığını görmek için Düzenleyici'de adk_agent/mcp_bakery_app/agent.py dosyasını açın.

LlmAgent, gemini-3.1-pro-preview modeliyle başlatılır.

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.1-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

Sistem Talimatları: Ajan, hem BigQuery'den (veriler için) hem de Haritalar'dan (konum analizi için) elde edilen bilgileri birleştirmesi için belirli talimatlar alır.
Araçlar: Hem maps_toolset hem de bigquery_toolset, temsilciye atanır ve her iki hizmetin özelliklerine erişim izni verilir.

Müşteri temsilcisi, depoda tanımlanan talimatlara ve araçlara uyar. Talimatlarda değişiklik yaparak bunun aracının davranışını nasıl etkilediğini görebilirsiniz.

7. Temsilcinizle sohbet edin.

Cloud Shell'deki terminale dönün ve adk_agent dizinine gitmek için şu komutu çalıştırın (daha önce yapmadıysanız):

cd adk_agent/

ADK web arayüzünü başlatmak için aşağıdaki komutu çalıştırın. Bu komut, sohbet uygulamasını barındırmak için basit bir web sunucusu başlatır:

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

Sunucu başlatıldıktan sonra Cloud Shell'de aşağıdakileri görürsünüz:

+-----------------------------------------------------------------------------+
| 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)

ADK kullanıcı arayüzüne erişmek için iki seçeneğiniz vardır:

1. seçenek: Yerel bağlantıyı tıklayın Cloud Shell terminalinizde görünen http://127.0.0.1:8000 bağlantısını tıklayın.

2. seçenek: Web Önizleme'yi kullanma

Cloud Shell'in sağ üst köşesindeki Web Önizlemesi düğmesini tıklayın.
Bağlantı noktasını değiştir'i seçin.
Bağlantı noktası numarası olarak 8000 girin ve Change and Preview'u (Değiştir ve Önizle) tıklayın.

ADK kullanıcı arayüzünün nasıl açılacağını gösteren ekran görüntüsü

Web kullanıcı arayüzünde aşağıdaki soruları sorarak Agent ile etkileşim kurun. İlgili araçların çağrıldığını görmeniz gerekir.

Bölgeyi bul (makro): "Los Angeles'ta fırın açmak istiyorum. Sabah saatlerinde en yüksek yaya trafiği puanına sahip posta kodunu bul."

Temsilci, BigQuery'deki foot_traffic tablosunu sorgulamak için get_table_info ve execute_sql gibi araçları kullanmalıdır.

Konumu (Mikro) Doğrulama: "Doygunluk olup olmadığını görmek için o posta kodunda "Fırınlar"ı arayabilir misin?"

Temsilci, bu soruyu yanıtlamak için Haritalar araç setindeki search places araçlarını kullanmalıdır.

Hemen deneyin! ADK temsilcinizi nasıl kullanacağınızı görmek için aşağıdaki örnek sorulara göz atın:

"Los Angeles'ta dördüncü fırınımı açmak istiyorum. Erken saatlerde hareketliliğin başladığı bir mahalle istiyorum. En yüksek "sabah" yaya trafiği puanına sahip posta kodunu bul.
"Doygunluk olup olmadığını görmek için o posta kodundaki "Fırınlar"ı arayabilir misin? Çok fazla varsa "Özel Kahve" dükkanlarını kontrol et. Böylece, yaya trafiğinden yararlanmak için kendimi bu dükkanların yakınına konumlandırabilirim.
"Tamam ve bunu premium bir marka olarak konumlandırmak istiyorum. Los Angeles metropol bölgesinde "ekşi mayalı ekmek" için alınan maksimum fiyat nedir?"
Şimdi de Aralık 2025 için gelir tahmini istiyorum. Satış geçmişime bak ve "Ekşi Mayalı Ekmek" için en iyi performans gösteren mağazamdan veri al. Satacağım miktarı tahmin etmek için Aralık 2025'e yönelik bir tahmin çalıştır. Ardından, bulduğumuz premium fiyatın biraz altında bir fiyat kullanarak (18 ABD doları) tahmini toplam geliri hesaplayın."
"Kiramı ödeyeceğim. Son olarak, lojistiği doğrulayalım. Önerilen bölgeye en yakın "Restaurant Depot"u bulun ve günlük stok yenileme için sürüş süresinin 30 dakikadan kısa olduğundan emin olun."

Aracınızı test etmeyi bitirdiğinizde Cloud Shell terminalinizde Ctrl+C tuşuna basarak ADK web arayüzünü sonlandırabilirsiniz.

8. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu Codelab sırasında oluşturulan kaynakları silin.

Temizleme komut dosyasını çalıştırın. Bu komut dosyası, kurulum sırasında oluşturulan BigQuery veri kümesini, Cloud Storage paketini ve API anahtarlarını siler.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. Tebrikler

Görev Tamamlandı! Agent Development Kit'i (ADK) kullanarak konum bazlı bilgi ajanı oluşturmayı başardınız.

BigQuery'deki "kurumsal" verileriniz ile Google Haritalar'daki gerçek dünya konum bağlamı arasındaki boşluğu doldurarak Model Context Protocol (MCP) ve Gemini tarafından desteklenen, karmaşık işletme muhakemesi yapabilen güçlü bir araç oluşturdunuz.

Başarılarınız:

Kod Olarak Altyapı: Google Cloud KSA araçlarını kullanarak bir veri yığını sağladınız.
MCP Entegrasyonu: Karmaşık API sarmalayıcıları yazmadan bir yapay zeka ajanını iki farklı uzak MCP sunucusuna (BigQuery ve Haritalar) bağladınız.
Birleşik Akıl Yürütme: Bir işletme sorununu çözmek için iki farklı alandaki analizleri stratejik olarak birleştirebilen tek bir temsilci oluşturdunuz.