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

تجربة "وكيل تحليل البيانات" مع الاحتفاظ بالحالة على Agent Engine

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستنشئ وكيل علوم بيانات يستعلم عن بيانات حقيقية من مجموعات البيانات العامة في BigQuery ويتذكّر إعداداتك المفضّلة في جميع الجلسات. بعد ذلك، ستنشره على Agent Engine، وهي خدمة مُدارة بالكامل من Google Cloud تتولى إدارة البنية التحتية والتوسيع وإدارة الجلسات.

يستخدم الوكيل ثلاث إمكانات أساسية يتم تفعيلها تدريجيًا:

BigQuery Toolset: يستكشف الوكيل المخططات ويُجري طلبات SQL على مجموعات بيانات BigQuery الحقيقية، ويعمل ذلك محليًا وعند النشر.
Memory Bank: عند النشر، يتذكّر الوكيل إعدادات المستخدم المفضّلة والسياق في جميع الجلسات غير المتصلة.
إمكانية تتبُّع البيانات: تسجِّل خدمة Cloud Trace خطوات الاستدلال التي يتّخذها الوكيل وعمليات استدعاء الأدوات وحالات التأخير من خلال أجهزة OpenTelemetry.

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

كيفية إنشاء وكيل ADK باستخدام BigQueryToolset للوصول إلى البيانات الحقيقية
كيفية ضبط Memory Bank لاستمرار البيانات في جميع الجلسات
كيفية نشر وكيلك على Agent Engine باستخدام adk deploy
كيفية منح أذونات إدارة الهوية والوصول (IAM) لحساب خدمة الوكيل الذي تم نشره
كيفية اختبار استمرار الذاكرة وإمكانية تتبُّع البيانات

المتطلبات

مشروع على Google Cloud تم تفعيل الفوترة فيه
Google Cloud SDK (gcloud CLI)
متصفح ويب مثل Chrome
uv (مدير حِزم Python)
الإصدار 3.12 من Python أو إصدار أحدث (يتم تثبيته تلقائيًا بواسطة uv إذا لزم الأمر)

‫ADK (Agent Development Kit) هو إطار عمل Google لإنشاء وكلاء الذكاء الاصطناعي. يستخدم هذا الدرس التطبيقي حول الترميز حزمة ADK لإنشاء وكيل ونشره على Agent Engine.

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

يستغرق إكمال هذا الدرس التطبيقي حول الترميز 30 دقيقة تقريبًا (بما في ذلك 5 إلى 10 دقائق للنشر).

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

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

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

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

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

افتح Cloud Shell Editor في مشروع Google Cloud الذي أنشأته.

بعد ذلك، أنشئ وحدة طرفية > وحدة طرفية جديدة، وشغِّل الأوامر التالية.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

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

في الوحدة الطرفية، شغِّل الأمر التالي.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT

‫AI Platform API ‏ (aiplatform.googleapis.com) - استضافة Agent Engine
‫BigQuery API ‏ (bigquery.googleapis.com) - طلبات SQL على مجموعات البيانات العامة والخاصة
‫Telemetry API ‏ (telemetry.googleapis.com) - عمليات تتبُّع OpenTelemetry لإمكانية تتبُّع الوكيل

إنشاء بيئة افتراضية وتثبيت حزمة ADK

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

تتضمّن حزمة google-adk أداة سطر الأوامر adk التي ستستخدمها لاختبار الوكيل ونشره.

3. إنشاء الوكيل

أنشئ دليل مشروع وكيل جديدًا. يجب تشغيل جميع الأوامر اللاحقة من دليل العمل هذا (الدليل الرئيسي لـ data_science_agent/):

mkdir data_science_agent

سيبدو هيكل الدليل النهائي على النحو التالي:

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

ستنشئ الآن الملفَين __init__.py وagent.py، ثم ستضيف الملفَين requirements.txt و.env في خطوة النشر.

أنشئ الملف data_science_agent/__init__.py، وهو مطلوب حتى تتمكّن حزمة ADK من اكتشاف وكيلك وتحميله:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

أنشئ الملف data_science_agent/agent.py:

يتصل هذا الوكيل بـ BigQuery لاستخراج البيانات ويحفظ الجلسات في Memory Bank.

يتم تفعيل الذاكرة تلقائيًا عند النشر، ويتم ضبط المتغيّر البيئي GOOGLE_CLOUD_AGENT_ENGINE_ID من خلال بيئة تشغيل Agent Engine، ولا يكون متاحًا عند التشغيل محليًا.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by the Agent Engine runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Engine where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model="gemini-2.5-pro",
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

لنتعرّف على ما يفعله هذا الرمز:

تمنح BigQueryToolset الوكيل أدوات مثل execute_sql وlist_table_ids وget_table_info. ويمكنها استكشاف المخططات والاستعلام عن أي مجموعة بيانات يمكن للمتصل الوصول إليها.
تسترد PreloadMemoryTool تلقائيًا المعلومات المحفوظة ذات الصلة قبل كل عملية استدعاء للنموذج اللغوي الكبير من خلال البحث في Memory Bank عن محتوى ذي صلة برسالة المستخدم. تحفظ معاودة الاتصال _save_memory الجلسة في Memory Bank بعد كل عملية تشغيل للوكيل، ما يتيح للوكيل استرجاع السياق في الجلسات المستقبلية.
تغلّف App الوكيل الرئيسي في تطبيق قابل للنشر يمكن أن يعرضه Agent Engine. يجب أن يتطابق name مع اسم الدليل (data_science_agent)، ويستخدم adk web هذا الاسم للعثور على الوكيل وتحميله.
تطلب التعليمات من الوكيل استخدام مشروع الفوترة لطلبات SQL وتذكُّر الإعدادات المفضّلة للمستخدم.

4. النشر على Agent Engine

أنشئ ملف requirements.txt في الدليل data_science_agent:

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

google-adk وgoogle-genai: إطار عمل ADK وعميل Gemini
google-auth: المصادقة على Google Cloud
python-dotenv: تحميل الملف .env عند بدء التشغيل
تفعِّل حِزم opentelemetry-instrumentation-* الأربع ميزات إمكانية تتبُّع البيانات التي ستستكشفها لاحقًا. وهي تُعدِّل طلبات FastAPI HTTP وعمليات استدعاء نموذج Gemini والاتصالات الداخلية عبر gRPC/HTTP بحيث تظهر عمليات التتبُّع في علامة التبويب "عمليات التتبُّع" في Agent Engine.

أنشئ ملف .env في الدليل data_science_agent لتفعيل بيانات القياس عن بُعد على الوكيل الذي تم نشره:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: تفعيل خط أنابيب OpenTelemetry في بيئة تشغيل Agent Engine
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: تسجيل مدخلات الطلبات الكاملة وردود الوكيل، وهو أمر مفيد لتحديد الأخطاء وحلّها

انشر الوكيل. الوسيطة الأخيرة data_science_agent هي الدليل الذي يحتوي على رمز الوكيل:

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

علم	الغرض
`--project` / `--region`	مشروع Google Cloud والمنطقة المستهدفة
`--display_name`	اسم يمكن للمستخدم قراءته ويظهر في Cloud Console
`--trace_to_cloud`	تفعيل أداة تصدير Cloud Trace لنطاقات الوكيل
`--otel_to_cloud`	تفعيل خط أنابيب تعديل OpenTelemetry

عند النشر على Agent Engine، يتم تفعيل إمكانتَين تلقائيًا:

Memory Bank: PreloadMemoryTool تتصل بـ Agent Engine Memory Bank وتحفظ _save_memory الجلسات تلقائيًا.
إمكانية تتبُّع البيانات: تسجِّل خدمة Cloud Trace خطوات الاستدلال التي يتّخذها الوكيل وعمليات استدعاء الأدوات وحالات التأخير.

5. منح أذونات BigQuery

عليك منح إذن وصول BigQuery إلى حساب خدمة Agent Engine. عند النشر، يتم تشغيل الوكيل كحساب خدمة مُدار من Google (وليس بيانات الاعتماد الشخصية)، لذا يحتاج إلى أذونات صريحة لتنفيذ طلبات SQL.

PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

يعرض كل أمر الرسالة Updated IAM policy for project [...] عند نجاحه.

6. اختبار الوكيل الذي تم نشره

افتح صفحة Agent Engine في Google Cloud Console. انقر على الوكيل الذي تم نشره لفتح ساحة لعب Agent Engine.

اختبِر إمكانات BigQuery:

"List the tables in bigquery-public-data.hacker_news"
- المتوقّع: يستدعي الوكيل list_table_ids ويعرض أسماء الجداول، بما في ذلك full.
"Find the number of posts per year in bigquery-public-data.hacker_news.full"
- المتوقّع: يستدعي الوكيل execute_sql باستخدام طلب SQL ويعرض جدولاً يتضمّن السنوات وعدد المشاركات.
"What was the year-over-year percentage change in posts?"
- المتوقّع: يستدعي الوكيل execute_sql باستخدام طلب SQL يحسب النسبة المئوية للتغيير ويعرض النتائج.

7. اختبار استمرار الذاكرة

في ساحة اللعب، علِّم الوكيل إعدادًا مفضّلاً:

"Remember that my favorite dataset is bigquery-public-data.hacker_news"
"What tables does it have?"

انتظِر بضع ثوانٍ حتى يتم حفظ الذاكرة (يتم تشغيل معاودة الاتصال _save_memory بعد أن يردّ الوكيل).

الآن ابدأ جلسة جديدة من خلال النقر على الزر "+ جلسة جديدة" في الشريط الجانبي لساحة اللعب، ثم اطرح السؤال التالي:

"What is my favorite dataset?"

يجب أن يسترجع الوكيل bigquery-public-data.hacker_news على الرغم من أنّ هذه جلسة جديدة تمامًا بدون سجلّ محادثات. يعمل ذلك للأسباب التالية:

تحفظ _save_memory كل جلسة في Memory Bank من خلال callback_context.add_session_to_memory()
تسترد PreloadMemoryTool المعلومات المحفوظة ذات الصلة قبل كل عملية استدعاء للنموذج اللغوي الكبير
يطابق Memory Bank المحتوى دلاليًا، وليس فقط حسب الكلمة الرئيسية

8. استكشاف إمكانية تتبُّع البيانات

في Cloud Console، انتقِل إلى الوكيل الذي تم نشره وانقر على علامة التبويب عمليات التتبُّع.

علامة التبويب "عمليات التتبُّع" التي تعرض جدول الجلسات

يجب أن يظهر جدول الجلسات الذي يسرد الجلسات من طلبات الاختبار التي أجريتها في الخطوات السابقة. يعرض الجدول مقاييس ملخّصة لكل جلسة، مثل متوسط المدة وعمليات استدعاء النموذج وعمليات استدعاء الأدوات واستخدام الرموز وأي أخطاء.

انقر على جلسة لفحص تفاصيل عملية التتبُّع، بما في ذلك:

رسم بياني موجّه غير دوري (DAG) لنطاقاته، يعرض تفصيلاً خطوة بخطوة لاستدلال الوكيل وعمليات استدعاء الأدوات (طلبات BigQuery) وحالات التأخير
المدخلات والمخرجات لكل نطاق (يتم تفعيلها من خلال المتغيّر البيئي OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT في .env)
سمات البيانات الوصفية ، مثل أرقام تعريف النطاقات وأرقام تعريف عمليات التتبُّع والتوقيت

يمكنك أيضًا التبديل إلى عرض النطاق (التبديل في أعلى الصفحة) للاطّلاع على النطاقات الفردية في جميع الجلسات.

كيفية عمل التتبُّع

عند النشر باستخدام علامتَي --trace_to_cloud و--otel_to_cloud، تُهيئ بيئة تشغيل Agent Engine خط أنابيب OpenTelemetry الذي:

ينشئ TracerProvider باستخدام أداة تصدير OTLP تُرسِل النطاقات إلى telemetry.googleapis.com
يستخدم حِزم التعديل الأربع من ملف requirements.txt لتسجيل النطاقات من المكتبات الرئيسية (FastAPI وGemini وhttpx وgRPC)، ويتم تعديل google-genai بشكل صريح من خلال بيئة التشغيل، بينما تساهم الحِزم الأخرى من خلال الاكتشاف التلقائي لـ OpenTelemetry
يُجمِّع النطاقات ويُصدِّرها إلى Telemetry API، حيث تقرأها علامة التبويب "عمليات التتبُّع"

توفّر الصورة الأساسية لـ Agent Engine حزمة OpenTelemetry SDK وأداة التصدير، ولكن لا تتضمّن حِزم التعديل. لهذا السبب، يجب أن يسرد ملف requirements.txt جميع الحِزم الأربع، وإلا لن يتم إنشاء أي نطاقات ولن تظهر أي عمليات تتبُّع.

تحديد المشاكل وحلّها

إذا لم تظهر أي عمليات تتبُّع بعد بضع دقائق:

تأكَّد من تفعيل Telemetry API ، فقد فعّلتها في خطوة الإعداد. يمكنك التحقّق من ذلك باستخدام الأمر: gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry
تحقَّق من Cloud Logging بحثًا عن تحذيرات ، انتقِل إلى Logging > مستكشف السجلّات وابحث عن "telemetry enabled but proceeding without". إذا ظهر لك تحذير بشأن تعديل GenAI، يعني ذلك أنّ opentelemetry-instrumentation-google-genai غير متوفّرة في ملف requirements.txt.
لا تُضِف google-cloud-aiplatform[agent-engines] إلى ملف requirements.txt. يضيف سطر الأوامر ADK deploy هذا التبعية تلقائيًا، ويمكن أن تؤدي إعادة تعريفها بإصدار مختلف إلى حدوث تعارضات في حزمة OpenTelemetry وإيقاف التعديل بدون إشعار.

9. تنظيف

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

احذف الوكيل الذي تم نش1ره من صفحة Agent Engine في Cloud Console. اختَر وكيلك وانقر على حذف.

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

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

يمكنك اختياريًا تنظيف بيئتك المحلية:

deactivate
rm -rf .venv data_science_agent

10. تهانينا

لقد أنشأت وكيل علوم بيانات يحافظ على الحالة ونشرته على Agent Engine.

ما الذي ستتعلمه

كيفية إنشاء وكيل ADK باستخدام BigQueryToolset للوصول إلى البيانات الحقيقية
كيفية تفعيل الذاكرة المستمرة باستخدام Memory Bank من خلال PreloadMemoryTool وafter_agent_callback
كيفية منح أذونات إدارة الهوية والوصول (IAM) لحساب خدمة الوكيل الذي تم نشره
كيفية النشر على Agent Engine وتفعيل إمكانية تتبُّع البيانات باستخدام Cloud Trace

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

الاستعلام عن مجموعات بيانات BigQuery الخاصة بك من خلال منح حساب خدمة Agent Engine إذن الوصول إلى بياناتك
إضافة ميزة "تنفيذ الرمز" لتشغيل تحليل Python في بيئة آمنة
إعداد لوحات بيانات إمكانية تتبُّع البيانات في Cloud Trace لمراقبة وكيلك في بيئة الإنتاج
نشر النتائج على Google Workspace باستخدام أدوات MCP