BigQuery MCP ile Google Trendler Analisti Ajanı oluşturma

1. Genel Bakış

Bu codelab'de, Google ADK'yı kullanarak Google Trendler Analisti Ajanı oluşturacaksınız. Bu aracı, Google Trendler herkese açık veri kümesini (bigquery-public-data.google_trends) sorgulayan araçları dinamik olarak keşfetmek ve yürütmek için BigQuery MCP sunucusundan yararlanır.

Neler öğreneceksiniz?

• ADK geliştirme için proje oluşturma
• BigQuery için yönetilen MCP sunucularını etkinleştirme ve kullanma
• MCP araçlarını kullanan bir temsilci oluşturma
• Test için aracıyı yerel olarak çalıştırma
• Aracı Google Cloud Run'a dağıtma

İhtiyacınız olanlar

• Faturalandırmanın etkin olduğu bir Google Cloud projesi
• Chrome gibi bir web tarayıcısı
• Python 3.11 veya sonraki sürümler

Bu codelab, Python ve Google Cloud hakkında bilgi sahibi olan orta düzey geliştiriciler içindir.

Bu codelab'in tamamlanması yaklaşık 15-20 dakika sürer.

Bu kod laboratuvarında oluşturulan kaynakların maliyeti 5 ABD dolarından az olmalıdır.

2. Ortamınızı ayarlama

Google Cloud projesi oluşturma

1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Bu codelab için Google Cloud Shell'i kullanmanızı öneririz. Python ve Google Cloud CLI'ın yüklü olduğu bir terminal ortamı sağlar.

Cloud Shell'i etkinleştirmek için Google Cloud Console'un üst kısmındaki Cloud Shell'i etkinleştir düğmesini tıklayın.

Ortam değişkenlerini ayarlama

Aşağıdaki ortam değişkenlerini ayarlayın.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Not: GOOGLE_GENAI_USE_VERTEXAI=1 ayarı, ADK'yı GEMINI_API_KEY yerine kimlik doğrulama için Cloud IAM'den yararlanarak Vertex AI'ı kullanmaya yönlendirir.

gcloud'un kimliğini doğrulama ve gcloud'u yapılandırma

Google Hesabınızda oturum açın, etkin projenizi ayarlayın ve Uygulama Varsayılan Kimlik Bilgileri'ni yapılandırın.

Cloud Shell'i kullanıyorsanız bu adımı atlayabilirsiniz.

gcloud auth login
gcloud auth application-default login

Not: gcloud auth login, gcloud CLI komutlarının kimliğini doğrularken gcloud auth application-default login, yerel uygulama kodunun kimliğini doğrular.

Google Cloud projesini ayarlayın:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Gerekli API'leri Etkinleştirme

Cloud Run, Artifact Registry, BigQuery ve Vertex AI için gerekli Google Cloud API'lerini etkinleştirin.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

BigQuery için MCP'yi etkinleştirme

Yönetilen MCP sunucuları, projeniz için açıkça etkinleştirilmelidir.

gcloud beta services mcp enable bigquery.googleapis.com

Proje klasörü oluşturma

Öncelikle temsilciniz için bir kök klasör ve temsilci uygulaması için bir dahili klasör oluşturun.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. Aracı kodunu oluşturma

google_trends/__init__.py adlı boş bir dosya oluşturun:

touch google_trends/__init__.py

Ardından, google_trends/agent.py adlı bir dosya oluşturun ve aşağıdaki kodu yapıştırın:

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

4. Temsilciyi çalıştırma

Bu adımda yerel bir Python sanal ortamı ayarlayacak, bağımlılıkları yükleyecek ve aracının makinenizdeki (veya Google Cloud Shell'deki) davranışını doğrulamak için aracı çalıştıracaksınız.

• Uygulamanın kök dizinine (google-trends-agent) gidin.
• Sanal ortam oluşturun:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• Gerekli Python paketlerini yükleyin:

pip install google-auth google-adk

Yeni aracımızı test etmek için ADK Web'i kullanacağız.

Yerel geliştirme ve test için aşağıdaki komutu çalıştırın:

adk web

Google Cloud Shell'de geliştirme ve test için aşağıdaki komutu çalıştırın:

adk web --allow_origins="*"

Bu işlem, ADK web sunucusunu başlatır. Yerel web arayüzünü (genellikle http://localhost:8000 adresinde) kullanarak aracıyla etkileşimde bulunabilirsiniz.

Not: Aracıyı test etmek için daha basit olan adk run google_trends komutunu da kullanabilirsiniz.

Ajanınıza şu istemleri sormayı deneyin:

• ABD'deki en popüler trendleri göster
• Bu ay Fransa'da en çok yükselen trendler neler?
• Geçen hafta Kaliforniya'daki en önemli 3 trend neydi?
• Erişebildiğiniz BigQuery tabloları nelerdir?
• top_trends tablosu hakkında bildiğin her şeyi anlat

5. Cloud Run'a dağıt

Aracı Google Cloud Run'a güvenli bir şekilde dağıtmak için aşağıdaki adımları uygulayın.

İzin Ver

Cloud Run'ın Vertex AI'a erişmek ve BigQuery MCP araçlarını kullanmak için izne ihtiyacı vardır.

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}[e-mail]" \
  --role="roles/bigquery.dataViewer"

Dockerfile'ı oluşturma

Projenizin kök dizininde (google-trends-agent) Dockerfile adlı bir dosya oluşturun ve aşağıdaki içeriği yapıştırın:

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

Aracıyı dağıtma

Aşağıdaki komutu kök dizinden çalıştırın. Bu işlem, aracınızı container mimarisine alır ve Cloud Run'a dağıtır.

Komut çıkışını takip edin. Dağıtım tamamlandığında Hizmet URL'si sağlanır. Temsilcinizle etkileşim kurmak için bu URL'yi kullanırsınız.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

Hızlı Doğrulama

Dağıtım tamamlandığında konsol bir hizmet URL'si çıkarır. Bu URL'yi tarayıcınızda açın. Bu URL, yerel olarak gördüğünüz etkileşimli kullanıcı arayüzünü sağlar ancak artık bulutta çalışır.

Her şeyin sorunsuz şekilde çalıştığından emin olmak için günlükleri de izleyebilirsiniz:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. Temizleme

Devam eden ücretleri önlemek için bu codelab sırasında oluşturulan kaynakları silin.

Cloud Run hizmetini silin:

gcloud run services delete google-trends-agent --region us-west1

Bu codelab için özel olarak bir proje oluşturduysanız projenin tamamını silebilirsiniz:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Bu codelab ile ilgili tüm dosyaları da silebilirsiniz:

deactivate
cd ..
rm -rf google-trends-agent

7. Tebrikler

Tebrikler! Google Trendler Analisti Aracısı'nı başarıyla oluşturup dağıttınız.

Öğrendikleriniz

• Aracı özelliklerini dinamik olarak genişletmek için MCP'yi kullanma
• Google ADK ile LLM temsilcileri oluşturma ve sunma
• Cloud Run'da aracıları dağıtma ve ölçeklendirme

Sonraki adımlar

• Farklı BigQuery veri kümelerini sorgulamak için aracıyı değiştirmeyi deneyin.
• Temsilcinin yeteneklerini genişletmek için daha fazla MCP aracı ekleyin

Referans belgeleri

• ADK Dokümanları
• MCP Araçları Kılavuzu
• BigQuery MCP
• Cloud Run belgeleri