Cloud Run'da Gemini ve BigQuery MCP sunucusu ile yapay zeka aracıları oluşturma ve dağıtma

1. Giriş

Neler öğreneceksiniz?

Cloud Run, temel altyapıyı yönetmeden container'a alınmış uygulamaları ve hizmetleri çalıştırmanıza olanak tanıyan, tümüyle yönetilen sunucusuz bir bilgi işlem platformudur.

Agent Development Kit (ADK), kurumsal ölçekte güvenilir yapay zeka ajanları oluşturmanıza, hatalarını ayıklamanıza ve dağıtmanıza olanak tanıyan açık kaynaklı bir ajan geliştirme çerçevesidir.

BigQuery, devasa veri kümelerini depolamanıza, sorgulamanıza ve analiz etmenize olanak tanıyan, tümüyle yönetilen ve sunucusuz bir kurumsal veri ambarıdır.

Model Bağlam Protokolü (MCP), büyük dil modellerinin (LLM'ler) ve yapay zeka uygulamalarının ya da ajanlarının harici veri kaynaklarına bağlanma şeklini standartlaştırır. MCP sunucuları, arka uç hizmetlerinden güncellenmiş veriler almak ve işlem yapmak için araçlarını, kaynaklarını ve istemlerini kullanmanıza olanak tanır. BigQuery MCP Server, yapay zeka aracılarınıza BigQuery'deki verileri analiz etmenin doğrudan ve güvenli bir yolunu sunar. Bu tamamen yönetilen MCP sunucusu, yönetim ek yükünü ortadan kaldırarak akıllı aracıları geliştirmeye odaklanmanızı sağlar.

2. Kurulum ve Gereksinimler

Varsayılan projeyi ve Cloud Run bölgesini ayarlayarak başlayın:

# set the project
gcloud config set project YOUR_PROJECT_ID

YOUR_PROJECT_ID kısmını Google Cloud proje kimliğinizle değiştirin.

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

CLOUD-RUN-REGION değerini Cloud Run tarafından desteklenen bölgelerden biriyle değiştirin.

Bu codelab boyunca kullanılacak ortam değişkenleri aşağıda verilmiştir. Bunları bir ortam dosyasına kaydedip "kaynak" olarak kullanabilirsiniz. Proje kimliğinizin ve isteğe bağlı olarak bölgenin değerini doğru şekilde ayarladığınızdan emin olun.

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

Bu Codelab için gerekli API'leri etkinleştirin. API değişikliklerinin geçerlilik kazanması 2-3 dakika sürebilir.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Agent Development Kit'i kullanarak veri temsilcisi oluşturma

Ajanın kodunu yazma

Cloud Shell Terminal'den veya yerel terminalinizden, yapay zeka aracılı uygulamanız için bir kök dizin oluşturun:

mkdir data_agent

Cloud Shell Düzenleyici'yi veya başka bir metin düzenleyiciyi açın ve data_agent dizininde agent.py dosyasını oluşturun:

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

ADK'nın dağıtılması için __init__.py ve requirements.txt da gerekir:

  • __init__.py, aracı için bir içe aktarma işlemine sahip olmalıdır.
  • requirements.txt Python bağımlılıklarını listeleyin: google-adk Agent Development Kit için ve mcp Model Bağlam Protokolü istemcisi için.

Bu komutlar, __init__.py ve requirements.txt oluşturmanıza yardımcı olur:

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

Son klasör yapısı şu şekilde görünmelidir:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Temsilciyi yerel olarak deneme

Agent Development Kit, adk CLI aracını içerir. Bu araç, ajanlarınızı test etmek için kullanılan etkileşimli bir terminal arayüzüdür. Bu, hızlı testler, komut dosyası oluşturulmuş etkileşimler ve CI/CD ardışık düzenleri için kullanışlıdır. Sunduğu özelliklerden biri, adk web - ADK Web Arayüzü'dür. Bu arayüz, aracılarınızı etkileşimli olarak geliştirip hatalarını ayıklamanın basit bir yoludur. ADK Web, üretim dağıtımlarında kullanılmak üzere tasarlanmamıştır ancak aracı denemeyi çok kolaylaştırır.

Bu komut, 8080 numaralı bağlantı noktasında yerel bir web sunucusu başlatan adk web uygulamasını başlatır.

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

Hizmet başlatıldıktan sonra yerel ADK web sayfasını açın: http://localhost:8080/.

Google Cloud Shell kullanıyorsanız Web Önizlemesi Web Önizlemesi düğmesini tıklayın ve "8080 numaralı bağlantı noktasında önizle" menü öğesini seçin.

ADK Web Kullanıcı Arayüzü'nde, aracının erişebildiği veriler hakkında soru sorun:

What data do you have?

Temsilci, citibike veri kümesini keşfetmek için BigQuery MCP araçlarını kullanacak. Citibike veri kümesindeki mevcut tablolar ve alanlar hakkında genel bir bakış sunar.

4. Aracıyı Cloud Run'a dağıtma

Bu komut, ADK KSA'yı kullanarak aracıyı Cloud Run'a dağıtır.

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

Temsilciyi deneyin

Aracı dağıtımımız için --with_ui seçeneğini kullandık. Ajanı ADK Web Arayüzü ile dağıttı.

  1. Temsilci URL'sini web tarayıcısında açın. adk deploy komutu döndürdü. Ayrıca gcloud run services komutunu çalıştırarak da URL'yi alabilirsiniz:
gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'
  1. Aracıdan, mevcut Citibike verileri hakkında akıl yürütmesini isteyin:
We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

Aracı, BigQuery MCP sunucusunu kullanarak Citibike veri kümesini keşfetmeli, birkaç SQL sorgusu çalıştırmalı ve 3 Citibike istasyonunun listesini döndürmelidir.

5. Tebrikler!

Codelab'i tamamladığınız için tebrik ederiz.

Cloud Run belgelerini incelemenizi öneririz.

İşlediğimiz konular

  • Agent Development Kit ve Gemini ile yapay zeka temsilcisi oluşturma
  • Aracı, BigQuery MCP sunucusuna bağlama
  • Aracıyı Cloud Run'a dağıtma

6. Temizleme

Bu eğiticide kullanılan kaynaklar için Google Cloud hesabınızın ücretlendirilmesini istemiyorsanız projeyi veya tek tek kaynakları silebilirsiniz.

1. seçenek: Hizmeti silme

Cloud Run hizmetini silme

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

2. seçenek: Projeyi silme

Projenin tamamını silmek için Kaynakları Yönet'e gidin, 2. adımda oluşturduğunuz projeyi seçin ve Sil'i tıklayın. Projeyi silerseniz Cloud SDK'nızda projeleri değiştirmeniz gerekir. gcloud projects list komutunu çalıştırarak kullanılabilir tüm projelerin listesini görüntüleyebilirsiniz. Komut satırını kullanmaya devam etmek istiyorsanız şu komutu da kullanabilirsiniz:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}