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

1. Giriş

Bu Codelab'de, Gemini 3.0 Pro tarafından desteklenen bir ADK aracısı oluşturacaksınız. Aracı, demografi, fiyatlandırma ve satış verileri için BigQuery'ye, gerçek dünyadaki konum analizi ve doğrulama için de Google Haritalar'a güvenli bir şekilde erişmek üzere iki uzak (Google tarafından barındırılan) MCP sunucusundaki araçlarla donatılacak.

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

Yapacaklarınız

Verileri ayarlama: BigQuery'de temel fırın veri kümesini oluşturun.
Aracı geliştirin: Aracı Geliştirme Kitini (ADK) kullanarak akıllı bir aracı oluşturun.
Araçları Entegre Edin: MCP sunucusu aracılığıyla aracıya 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ırma özelliği etkinleştirilmiş 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. Faturalandırmanın bir projede 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ı onaylamak 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 Haritalar 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 projenizde 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

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.0 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ı (API anahtarları gibi) içerir.

1. MCP Araç Setini Başlatma:

Ş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 kurar.

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 Authorization ü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-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-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ı: Aracıya, hem BigQuery'den (veriler için) hem de Haritalar'dan (konum analizi için) elde edilen analizleri birleştirmesi için özel talimatlar verilir.
Araçlar: Hem maps_toolset hem de bigquery_toolset, temsilciye atanır ve her iki hizmetin özelliklerine erişmesini sağlar.

Aracı, 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:

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

Sunucu başladıktan sonra, ADK Web Arayüzü'nü başlatmak için sağlanan URL'yi tıklayarak aracınızla sohbet edebilirsiniz.

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. En yüksek sabah yaya trafiği puanına sahip posta kodunu bulun."

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 çalışırken 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 olduğu bir semte ihtiyacım var. En yüksek "sabah" yaya trafiği puanına sahip posta kodunu bulun.
"Doygunluk olup olmadığını görmek için o posta kodundaki "Fırınlar"ı arayabilir misin? Çok fazla varsa "Specialty Coffee" (Ö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 tahmini toplam geliri hesaplayın (18 ABD doları kullanalım)."
"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."

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ı! Aracı Geliştirme Kiti'ni (ADK) kullanarak başarıyla bir Konum Bilgisi Aracısı oluşturdunuz.

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ş mantığına sahip güçlü bir araç oluşturdunuz.

Başarılarınız:

Kod Olarak Altyapı: Google Cloud CLI araçlarını kullanarak bir veri yığını sağladınız.
MCP entegrasyonu: Karmaşık API sarmalayıcıları yazmadan bir yapay zeka aracısı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.