با BigQuery MCP یک تحلیلگر گوگل ترندز بسازید

۱. مرور کلی

در این آزمایشگاه کد، شما با استفاده از Google ADK یک عامل تحلیلگر Google Trends خواهید ساخت. این عامل از سرور BigQuery MCP برای کشف و اجرای پویای ابزارهایی که مجموعه داده‌های عمومی Google Trends ( bigquery-public-data.google_trends ) را جستجو می‌کنند، استفاده می‌کند.

آنچه یاد خواهید گرفت

  • نحوه راه‌اندازی یک پروژه برای توسعه ADK.
  • نحوه فعال‌سازی و استفاده از سرورهای مدیریت‌شده MCP برای BigQuery.
  • چگونه یک عامل بسازیم که از ابزارهای MCP استفاده کند.
  • نحوه اجرای عامل به صورت محلی برای آزمایش.
  • نحوه استقرار عامل در Google Cloud Run.

آنچه نیاز دارید

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • یک مرورگر وب مانند کروم
  • پایتون ۳.۱۱+

این آزمایشگاه کد برای توسعه‌دهندگان سطح متوسط ​​است که با پایتون و گوگل کلود آشنایی دارند.

تکمیل این آزمایشگاه کد تقریباً ۱۵ تا ۲۰ دقیقه طول می‌کشد.

منابع ایجاد شده در این آزمایشگاه کد باید کمتر از ۵ دلار هزینه داشته باشند.

۲. محیط خود را آماده کنید

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

تنظیم متغیرهای محیطی

متغیرهای محیطی زیر را تنظیم کنید.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

توجه : تنظیم GOOGLE_GENAI_USE_VERTEXAI=1 ADK را به استفاده از Vertex AI هدایت می‌کند و به جای GEMINI_API_KEY ، از Cloud IAM برای احراز هویت استفاده می‌کند.

احراز هویت و پیکربندی gcloud

وارد حساب گوگل خود شوید، پروژه فعال خود را تنظیم کنید و اعتبارنامه‌های پیش‌فرض برنامه را پیکربندی کنید.

gcloud auth login
gcloud auth application-default login

نکته : gcloud auth login دستورات رابط خط فرمان gcloud را احراز هویت می‌کند، در حالی که gcloud auth application-default login کد برنامه محلی را احراز هویت می‌کند.

پروژه Google Cloud را تنظیم کنید:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

فعال کردن API های لازم

APIهای مورد نیاز Google Cloud را برای Cloud Run، Artifact Registry، BigQuery و Vertex AI فعال کنید.

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

فعال کردن MCP برای BigQuery

سرورهای مدیریت‌شده‌ی MCP باید به‌طور صریح برای پروژه‌ی شما فعال باشند.

gcloud beta services mcp enable bigquery.googleapis.com

ایجاد پوشه پروژه

با ایجاد یک پوشه ریشه برای عامل خود و یک پوشه داخلی برای پیاده‌سازی عامل شروع کنید.

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

۳. کد عامل را ایجاد کنید

یک فایل خالی با نام google_trends/__init__.py ایجاد کنید:

touch google_trends/__init__.py

سپس، یک فایل با نام google_trends/agent.py ایجاد کنید و کد زیر را در آن قرار دهید:

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)

۴. عامل را اجرا کنید

در این مرحله، شما یک محیط مجازی محلی پایتون راه‌اندازی می‌کنید، وابستگی‌ها را نصب می‌کنید و عامل را اجرا می‌کنید تا رفتار آن را روی دستگاه خود (یا Google Cloud Shell) تأیید کنید.

  • به دایرکتوری ریشه برنامه ( google-trends-agent ) بروید.
  • ایجاد یک محیط مجازی: 
python -m venv mcp_demo_env
source mcp_demo_env/bin/activate
  • بسته‌های پایتون مورد نیاز را نصب کنید: 
pip install google-auth google-adk

ما از ADK Web برای آزمایش عامل جدید خود استفاده خواهیم کرد.

برای توسعه و آزمایش محلی، دستور زیر را اجرا کنید: 

adk web

برای توسعه و آزمایش در Google Cloud Shell، دستور زیر را اجرا کنید: 

adk web --allow_origins="*"

این کار سرور وب ADK را اجرا می‌کند. شما می‌توانید با استفاده از رابط وب محلی (معمولاً در http://localhost:8000 ) با عامل تعامل داشته باشید.

نکته : شما همچنین می‌توانید از دستور ساده‌تر adk run google_trends برای آزمایش عامل استفاده کنید.

۵. استقرار در Cloud Run

برای استقرار ایمن عامل در Google Cloud Run، این مراحل را دنبال کنید.

اعطای مجوزها

Cloud Run برای دسترسی به Vertex AI و استفاده از ابزارهای BigQuery MCP به مجوز نیاز دارد. 

# 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}-compute@developer.gserviceaccount.com" \
  --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}-compute@developer.gserviceaccount.com" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

ایجاد فایل داکر

در ریشه پروژه خود ( google-trends-agent )، فایلی با نام Dockerfile ایجاد کنید و محتوای زیر را در آن قرار دهید: 

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"]

عامل را مستقر کنید

دستور زیر را از دایرکتوری ریشه اجرا کنید. این کار عامل شما را در Cloud Run کانتینرایز و مستقر می‌کند.

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

تأیید سریع

پس از اتمام استقرار، کنسول یک URL سرویس (Service URL) را نمایش می‌دهد. این URL را در مرورگر خود باز کنید؛ همان رابط کاربری تعاملی که به صورت محلی مشاهده کردید را ارائه می‌دهد، اما اکنون در فضای ابری اجرا می‌شود!

همچنین می‌توانید لاگ‌ها را رصد کنید تا مطمئن شوید همه چیز به درستی کار می‌کند: 

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

۶. تمیز کردن

برای جلوگیری از هزینه‌های جاری، منابع ایجاد شده در طول این آزمایش کد را حذف کنید.

سرویس Cloud Run را حذف کنید: 

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

اگر پروژه‌ای را به‌طور خاص برای این آزمایشگاه کد ایجاد کرده‌اید، می‌توانید کل پروژه را حذف کنید: 

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

همچنین می‌توانید تمام فایل‌های مربوط به این codelab را حذف کنید: 

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

۷. تبریک

تبریک! شما با موفقیت یک Google Trends Analyst Agent ساختید و مستقر کردید.

آنچه آموخته‌اید

  • نحوه استفاده از MCP برای گسترش قابلیت‌های عامل به صورت پویا
  • نحوه ساخت و ارائه خدمات به نمایندگان LLM با Google ADK
  • نحوه استقرار و مقیاس‌بندی عامل‌ها در Cloud Run

مراحل بعدی

  • سعی کنید عامل را برای پرس‌وجو از مجموعه داده‌های مختلف BigQuery تغییر دهید
  • ابزارهای MCP بیشتری را برای گسترش قابلیت‌های عامل اضافه کنید

اسناد مرجع