إنشاء وكيل محلّل "مؤشرات 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
• الإصدار 3.11 من Python أو إصدار أحدث

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

يستغرق إكمال هذا الدرس التطبيقي حول الترميز من 15 إلى 20 دقيقة تقريبًا.

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

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

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

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

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

لتفعيل Cloud Shell، انقر على الزر تفعيل Cloud Shell في أعلى Google Cloud Console.

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

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

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 CLI، بينما يؤدي gcloud auth application-default login إلى مصادقة الرمز البرمجي للتطبيق المحلي.

اضبط مشروع Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

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

فعِّل واجهات برمجة التطبيقات المطلوبة على 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

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

سنستخدم 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 للخدمة. ستستخدم هذا العنوان للتفاعل مع وكيلك.

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

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

بعد انتهاء عملية النشر، ستعرض وحدة التحكّم عنوان 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 لتوسيع إمكانات الوكيل بشكل ديناميكي
• كيفية إنشاء وكلاء نماذج لغوية كبيرة (LLM) وعرضهم باستخدام Google ADK
• كيفية نشر الوكلاء وتوسيع نطاقهم على Cloud Run

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

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

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

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