تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إنشاء وكلاء مستندين إلى الذكاء الاصطناعي ونشرهم باستخدام Gemini وخادم BigQuery MCP في Cloud Run

1. مقدمة

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

كيفية إنشاء وكيل ذكاء اصطناعي باستخدام حزمة تطوير الوكلاء (ADK) مع Gemini في "منصة الوكلاء"
كيفية منح "وكلاء الذكاء الاصطناعي" إذن الوصول إلى البيانات المنظَّمة في BigQuery باستخدام خادم BigQuery MCP

‫Cloud Run هي منصة حوسبة مُدارة بالكامل بدون خادم تتيح لك تشغيل التطبيقات والخدمات في حاويات بدون إدارة أي بنية تحتية أساسية.

حزمة تطوير الوكلاء (ADK) هي إطار عمل مفتوح المصدر لتطوير الوكلاء يتيح لك إنشاء وكلاء ذكاء اصطناعي موثوقين وتصحيح أخطائهم ونشرهم على مستوى المؤسسة.

‫BigQuery هو مستودع مُدار بالكامل لبيانات المؤسسات يعمل بدون خادم ويتيح لك تخزين مجموعات البيانات الضخمة وطلب البحث فيها وتحليلها.

يضع بروتوكول سياق النموذج (MCP) معيارًا لطريقة ربط النماذج اللغوية الكبيرة وتطبيقات أو وكلاء الذكاء الاصطناعي بمصادر البيانات الخارجية. تتيح لك خوادم MCP استخدام أدواتها ومواردها وطلباتها لاتّخاذ إجراءات والحصول على بيانات محدّثة من خدمتها الخلفية. يوفّر خادم BigQuery MCP لوكلاء الذكاء الاصطناعي طريقة مباشرة وآمنة لتحليل البيانات في BigQuery. يزيل خادم MCP المُدار بالكامل عبء الإدارة، ما يتيح لك التركيز على تطوير وكلاء أذكياء.

2. الإعداد والمتطلبات

ابدأ بتحديد المشروع التلقائي ومنطقة Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

استبدِل YOUR_PROJECT_ID برقم تعريف مشروع Google Cloud.

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

استبدِل CLOUD-RUN-REGION بإحدى المناطق التي يتيحها Cloud Run.

في ما يلي متغيرات البيئة التي سيتم استخدامها في هذا الدرس التطبيقي. يمكنك حفظ هذه المتغيرات في ملف بيئة و "تحديد مصدرها". احرص على ضبط قيمة رقم تعريف مشروعك بشكل صحيح، ويمكنك أيضًا ضبط المنطقة.

# 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

فعِّل واجهات برمجة التطبيقات اللازمة لهذا الدرس العملي. قد يستغرق تنفيذ التغييرات في واجهة برمجة التطبيقات من دقيقتَين إلى 3 دقائق.

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

كتابة رمز الوكيل

من "وحدة Cloud Shell الطرفية" أو الوحدة الطرفية المحلية، أنشئ دليلًا جذريًا لتطبيقك المستند إلى وكيل:

mkdir data_agent

افتح "محرِّر Cloud Shell" أو محرِّر نصوص آخر، وأنشئ agent.py في الدليل data_agent:

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

يتطلّب "حزمة تطوير التطبيقات" أيضًا __init__.py وrequirements.txt للنشر:

يجب أن يحتوي __init__.py على عملية استيراد للوكيل.
requirements.txt قائمة بملفات Python المطلوبة: 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

تجربة الوكيل محليًا

تتضمّن حزمة تطوير الوكلاء أداة adk CLI، وهي واجهة تفاعلية للطرفية مخصّصة لاختبار الوكلاء. ويكون ذلك مفيدًا للاختبار السريع والتفاعلات المكتوبة والبرامج المتكاملة/برامج التسليم المستمر (CI/CD). إحدى الميزات التي يوفّرها هي adk web - واجهة الويب الخاصة بـ "حزمة تطوير التطبيقات" - وهي طريقة بسيطة لتطوير وكلاءك وتصحيح أخطائهم بشكل تفاعلي. لا يُفترض استخدام ADK Web في عمليات النشر في مرحلة الإنتاج، ولكنّه يسهّل تجربة الوكيل.

يُشغّل هذا الأمر adk web الذي يبدأ خادم ويب محليًا على المنفذ 8080.

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، انقر على الزر "معاينة الويب" ، ثم اختَر عنصر القائمة "المعاينة على المنفذ 8080".

في واجهة مستخدم الويب الخاصة بـ ADK، اسأل الوكيل عن البيانات التي يمكنه الوصول إليها:

What data do you have?

سيستخدم الوكيل أدوات BigQuery MCP لاستكشاف مجموعة بيانات citibike. سيقدّم لك نظرة عامة على الجداول والحقول المتاحة في مجموعة بيانات Citibike.

4. نشر الوكيل على Cloud Run

سيؤدي هذا الأمر إلى نشر الوكيل على Cloud Run باستخدام واجهة سطر الأوامر الخاصة بـ ADK.

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

تجربة الوكيل

استخدمنا الخيار --with_ui لنشر الوكيل. تم نشر الوكيل باستخدام واجهة الويب الخاصة بحزمة تطوير الوكلاء (ADK).

افتح عنوان URL الخاص بالوكيل في متصفّح الويب. عرض الأمر adk deploy عنوان URL، ويمكنك أيضًا استرداده عن طريق تنفيذ الأمر gcloud run services:

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

اطلب من الوكيل تقديم تفسير بشأن بيانات Citibike المتاحة:

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

على الوكيل استكشاف مجموعة بيانات Citibike باستخدام خادم MCP في BigQuery، وتنفيذ بعض طلبات SQL، وعرض قائمة تضم 3 محطات Citibike.

5- تهانينا!

تهانينا على إكمال هذا الدرس العملي.

ننصحك بمراجعة مستندات Cloud Run.

المواضيع التي تناولناها

كيفية إنشاء وكيل ذكاء اصطناعي باستخدام Agent Development Kit وGemini
كيفية ربط الوكيل بخادم MCP في BigQuery
كيفية نشر الوكيل على Cloud Run

6. تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، يمكنك حذف المشروع أو حذف الموارد الفردية.

الخيار 1: حذف الخدمة

حذف خدمة Cloud Run

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

الخيار 2: حذف المشروع

لحذف المشروع بأكمله، انتقِل إلى إدارة المراجع، واختَر المشروع الذي أنشأته في الخطوة 2، ثم انقر على "حذف". إذا حذفت المشروع، عليك تغيير المشاريع في Cloud SDK. يمكنك الاطّلاع على قائمة بجميع المشاريع المتاحة من خلال تنفيذ gcloud projects list. إذا كنت تفضّل استخدام سطر الأوامر، يمكنك أيضًا استخدام الأمر التالي:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}