إنشاء وكيل محلّل "مؤشرات Google" باستخدام BigQuery MCP

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيل تحليل مؤشرات Google باستخدام Google ADK. يستفيد هذا الوكيل من خادم BigQuery MCP لاكتشاف الأدوات التي تستعلم عن مجموعة البيانات المتاحة للجميع في "مؤشرات Google" (bigquery-public-data.google_trends) وتنفيذها بشكل ديناميكي.

أهداف الدورة التعليمية

• كيفية إعداد مشروع لتطوير حزمة ADK
• كيفية تفعيل خوادم MCP المُدارة واستخدامها في BigQuery
• كيفية إنشاء وكيل يستخدم أدوات MCP
• كيفية تشغيل الوكيل محليًا لإجراء الاختبار
• كيفية نشر الوكيل على Google Cloud Run

المتطلبات

• مشروع Google Cloud تم تفعيل الفوترة فيه
• متصفّح ويب، مثل Chrome
• ‫Python 3.11 أو إصدار أحدث

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين المتوسطي الخبرة الذين لديهم بعض المعرفة بلغة Python وGoogle Cloud.

يستغرق إكمال هذا الدرس العملي حوالي 15 إلى 20 دقيقة.

يجب أن تكون تكلفة الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز أقل من 5 دولارات أمريكية.

2. إعداد البيئة

إنشاء مشروع على Google Cloud

1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
2. تأكَّد من تفعيل الفوترة لمشروعك على Cloud. كيفية التحقّق من تفعيل الفوترة في مشروع

ننصحك باستخدام Google Cloud Shell في هذا الدرس العملي. توفّر هذه الخدمة بيئة طرفية مع تثبيت Python وGoogle Cloud CLI مسبقًا.

لتفعيل Cloud Shell، انقر على الزر تفعيل Cloud Shell في أعلى "وحدة تحكّم Google Cloud".

ضبط متغيرات البيئة

اضبط متغيرات البيئة التالية.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

ملاحظة: يؤدي ضبط GOOGLE_GENAI_USE_VERTEXAI=1 إلى توجيه حزمة تطوير الوكلاء (ADK) لاستخدام Vertex AI، والاستفادة من Cloud IAM للمصادقة بدلاً من GEMINI_API_KEY.

المصادقة على gcloud وإعدادها

سجِّل الدخول إلى حساب Google، واضبط مشروعك النشط، واضبط "بيانات الاعتماد التلقائية للتطبيق".

يمكنك تخطّي هذه الخطوة إذا كنت تستخدم Cloud Shell.

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}

تفعيل واجهات برمجة التطبيقات اللازمة

فعِّل واجهات Google Cloud APIs المطلوبة لكلّ من 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

3- إنشاء رمز الوكيل

أنشئ ملفًا فارغًا باسم 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)

4. تشغيل الوكيل

في هذه الخطوة، ستُعدّ بيئة Python افتراضية محلية، وتثبّت التبعيات، وتشغّل الوكيل للتحقّق من سلوكه على جهازك (أو Google Cloud Shell).

• انتقِل إلى الدليل الجذر للتطبيق (google-trends-agent).
• أنشئ بيئة افتراضية:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

• ثبِّت حِزم Python المطلوبة:

pip install google-auth google-adk[mcp]

سنستخدم ADK Web لاختبار الوكيل الجديد.

للتطوير والاختبار على الجهاز، شغِّل الأمر التالي:

adk web

للتطوير والاختبار داخل Google Cloud Shell، نفِّذ الأمر التالي:

adk web --allow_origins="*"

سيؤدي ذلك إلى بدء خادم الويب ADK. يمكنك التفاعل مع البرنامج باستخدام واجهة الويب المحلية (عادةً على http://localhost:8000).

ملاحظة: يمكنك أيضًا استخدام الأمر adk run google_trends الأبسط لاختبار الوكيل.

جرِّب توجيه الطلبات التالية إلى الوكيل:

• أريد الاطّلاع على أهم المواضيع الرائجة في الولايات المتحدة
• ما هي أبرز المواضيع الرائجة في فرنسا هذا الشهر؟
• ما هي أهم 3 مؤشرات في كاليفورنيا خلال الأسبوع الماضي؟
• ما هي جداول BigQuery التي لديك إذن بالوصول إليها؟
• أريد معرفة كل المعلومات المتوفرة لديك عن جدول top_trends

5- النشر على 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}[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

في جذر مشروعك (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.

تتبَّع نتائج الأمر. بعد انتهاء عملية النشر، سيتم توفير عنوان URL للخدمة. ستستخدم عنوان URL هذا للتفاعل مع وكيلك.

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

التحقّق السريع

بعد انتهاء عملية النشر، ستعرض وحدة التحكّم عنوان URL للخدمة. افتح عنوان URL هذا في متصفّحك، وسيوفّر لك واجهة المستخدم التفاعلية نفسها التي رأيتها محليًا، ولكنها ستعمل الآن على السحابة الإلكترونية.

يمكنك أيضًا مراقبة السجلات للتأكّد من أنّ كل شيء يعمل بسلاسة:

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

6. تنظيف

لتجنُّب تحصيل رسوم مستمرة، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس التطبيقي حول الترميز.

احذف خدمة Cloud Run:

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

إذا أنشأت مشروعًا خصيصًا لهذا الدرس التطبيقي حول الترميز، يمكنك حذف المشروع بأكمله باتّباع الخطوات التالية:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

يمكنك أيضًا حذف جميع الملفات ذات الصلة بهذا الدرس العملي:

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

7. تهانينا

تهانينا! لقد نجحت في إنشاء ونشر "وكيل محلّل مؤشرات Google".

ما تعلّمته

• كيفية استخدام MCP لتوسيع إمكانات الوكيل بشكل ديناميكي
• كيفية إنشاء وكلاء نماذج لغوية كبيرة وتقديمهم باستخدام Google ADK
• كيفية نشر الوكلاء وتوسيع نطاقهم على Cloud Run

الخطوات التالية

• محاولة تعديل الوكيل لطلب البحث في مجموعات بيانات BigQuery مختلفة
• إضافة المزيد من أدوات MCP لتوسيع إمكانات الوكيل

المستندات المرجعية

• مستندات ADK
• دليل أدوات MCP
• BigQuery MCP
• مستندات Cloud Run