ساخت و استقرار عامل‌های هوش مصنوعی با Gemini و سرور BigQuery MCP در Cloud Run

۱. مقدمه

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

• نحوه ایجاد یک عامل هوش مصنوعی با استفاده از کیت توسعه عامل (ADK) با Gemini در پلتفرم عامل .
• نحوه دسترسی به داده‌های ساختاریافته در BigQuery با استفاده از سرور BigQuery MCP به عوامل هوش مصنوعی.

Cloud Run یک پلتفرم محاسباتی کاملاً مدیریت‌شده و بدون سرور است که به شما امکان می‌دهد برنامه‌ها و سرویس‌های کانتینرشده را بدون مدیریت هیچ زیرساخت زیربنایی اجرا کنید.

کیت توسعه عامل (ADK) یک چارچوب توسعه عامل متن‌باز است که به شما امکان می‌دهد عامل‌های هوش مصنوعی قابل اعتمادی را در مقیاس سازمانی بسازید، اشکال‌زدایی کنید و مستقر کنید.

بیگ‌کوئری (BigQuery) یک انبار داده سازمانی کاملاً مدیریت‌شده و بدون سرور است که به شما امکان می‌دهد مجموعه داده‌های عظیم را ذخیره، پرس‌وجو و تجزیه و تحلیل کنید.

پروتکل زمینه مدل (MCP) نحوه اتصال مدل‌های زبانی بزرگ (LLM) و برنامه‌های کاربردی یا عامل‌های هوش مصنوعی به منابع داده خارجی را استاندارد می‌کند. سرورهای MCP به شما امکان می‌دهند از ابزارها، منابع و اعلان‌های آنها برای انجام اقدامات و دریافت داده‌های به‌روز شده از سرویس backend آنها استفاده کنید. سرور MCP BigQuery به عامل‌های هوش مصنوعی شما روشی مستقیم و ایمن برای تجزیه و تحلیل داده‌ها در BigQuery می‌دهد. این سرور MCP کاملاً مدیریت‌شده، سربار مدیریتی را حذف می‌کند و شما را قادر می‌سازد تا بر توسعه عامل‌های هوشمند تمرکز کنید.

۲. تنظیمات و الزامات

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

از تنظیم پروژه پیش‌فرض و منطقه Cloud Run شروع کنید:

# set the project
gcloud config set project YOUR_PROJECT_ID

به جای YOUR_PROJECT_ID ، شناسه پروژه گوگل کلود خود را وارد کنید.

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

CLOUD-RUN-REGION را با یکی از مناطقی که توسط Cloud Run پشتیبانی می‌شود، جایگزین کنید.

در اینجا متغیرهای محیطی که در سراسر این آزمایشگاه کد استفاده خواهند شد، آورده شده است. می‌توانید این موارد را در یک فایل محیطی ذخیره کرده و آن را "source" کنید. مطمئن شوید که مقدار شناسه پروژه و در صورت تمایل، منطقه را به درستی تنظیم کرده‌اید.

# 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

توجه: ذخیره این قطعه کد به عنوان یک فایل اسکریپت و استفاده مجدد از آن در آینده، در مواردی که جلسه Cloud Shell بازنشانی می‌شود، مفید است. آن را با نام env.sh ذخیره کنید و source env.sh را اجرا کنید تا متغیرهای محیطی هنگام اجرای مراحل بعدی تنظیم شوند. env.sh به سیستم‌های کنترل نسخه اختصاص ندهید .

API های مورد نیاز برای این Codelab را فعال کنید. تغییرات API ممکن است 2-3 دقیقه طول بکشد تا اعمال شوند.

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

۳. با استفاده از کیت توسعه عامل، یک عامل داده ایجاد کنید

نوشتن کد عامل

از ترمینال Cloud Shell یا ترمینال محلی خود، یک دایرکتوری ریشه برای برنامه agentic خود ایجاد کنید:

mkdir data_agent

ویرایشگر Cloud Shell یا ویرایشگر متن دیگری را باز کنید و agent.py در دایرکتوری data_agent ایجاد کنید:

data_agent/
    agent.py

عامل.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 همچنین برای استقرار به __init__.py و requirements.txt نیاز دارد:

• __init__.py باید یک import برای عامل داشته باشد.
• requirements.txt وابستگی‌های پایتون را فهرست می‌کند: google-adk برای کیت توسعه عامل، و mcp برای کلاینت پروتکل زمینه مدل.

این دستورات به شما کمک می‌کنند تا __init__.py و requirements.txt را ایجاد کنید:

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

ساختار پوشه نهایی باید به شکل زیر باشد:

data_agent/
    __init__.py
    agent.py
    requirements.txt

عامل را به صورت محلی امتحان کنید

کیت توسعه عامل (Agent Development Kit) با ابزار adk CLI - یک رابط ترمینال تعاملی برای آزمایش عامل‌های شما - ارائه می‌شود. این ابزار برای آزمایش سریع، تعاملات اسکریپت‌نویسی شده و خطوط لوله CI/CD مفید است. یکی از ویژگی‌هایی که ارائه می‌دهد adk web - رابط وب ADK - است که روشی ساده برای توسعه و اشکال‌زدایی تعاملی عامل‌های شما محسوب می‌شود. ADK Web برای استفاده در استقرارهای تولید در نظر گرفته نشده است، اما امتحان کردن عامل را بسیار ساده می‌کند.

توجه: قبل از اجرای این دستور، مطمئن شوید که دایرکتوری فعلی شما دارای دایرکتوری data_agent در آن است (با دستور ls ).

این دستور adk web را اجرا می‌کند که یک وب سرور محلی را روی پورت ۸۰۸۰ راه‌اندازی می‌کند.

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

پس از شروع سرویس، صفحه وب محلی ADK را باز کنید: http://localhost:8080/.

اگر از Google Cloud Shell استفاده می‌کنید ، روی پیش‌نمایش وب کلیک کنید. دکمه را فشار دهید، و گزینه "پیش‌نمایش روی پورت ۸۰۸۰" را انتخاب کنید.

در رابط کاربری وب ADK، از نماینده در مورد داده‌هایی که به آنها دسترسی دارد، سوال کنید:

What data do you have?

این عامل از ابزارهای BigQuery MCP برای کاوش در مجموعه داده‌های Citibike استفاده خواهد کرد. این کار به شما یک نمای کلی از جداول و فیلدهای موجود در مجموعه داده‌های Citibike ارائه می‌دهد.

۴. عامل را در Cloud Run مستقر کنید

این دستور، عامل را با استفاده از ADK CLI در Cloud Run مستقر می‌کند.

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 \
      --labels dev-tutorial=codelab-cloud-run-adk-gemini-bq-mcp \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}

عامل را امتحان کنید

ما از گزینه --with_ui برای استقرار عامل خود استفاده کردیم. این گزینه عامل را با رابط وب ADK مستقر می‌کند.

1. آدرس اینترنتی عامل را در مرورگر وب باز کنید. دستور adk deploy آن را برگرداند، و همچنین می‌توانید با اجرای دستور gcloud run services آدرس اینترنتی را بازیابی کنید:

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

2. از نماینده بخواهید که در مورد داده‌های موجود سیتی‌بایک توضیح دهد:

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

عامل باید مجموعه داده‌های Citibike را با استفاده از سرور BigQuery MCP بررسی کند، چند کوئری SQL اجرا کند و لیستی از ۳ ایستگاه citibike را برگرداند.

۵. تبریک می‌گویم!

تبریک می‌گویم که آزمایشگاه کد را تمام کردید!

توصیه می‌کنیم مستندات Cloud Run را بررسی کنید.

آنچه ما پوشش داده‌ایم

• نحوه ایجاد یک عامل هوش مصنوعی با کیت توسعه عامل و Gemini
• نحوه اتصال عامل به سرور BigQuery MCP.
• نحوه استقرار عامل در Cloud Run.

۶. تمیز کردن

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

گزینه ۱: حذف سرویس

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

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

گزینه ۲: حذف پروژه

برای حذف کل پروژه، به مدیریت منابع بروید، پروژه‌ای را که در مرحله ۲ ایجاد کرده‌اید انتخاب کنید و حذف را انتخاب کنید. اگر پروژه را حذف کنید، باید پروژه‌ها را در Cloud SDK خود تغییر دهید. می‌توانید با اجرای gcloud projects list لیست تمام پروژه‌های موجود را مشاهده کنید. اگر می‌خواهید از خط فرمان استفاده کنید، می‌توانید از این دستور نیز استفاده کنید:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}