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

1. نظرة عامة

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

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

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

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

كيفية إنشاء وكيل ADK باستخدام BigQueryToolset للوصول إلى البيانات الحقيقية
كيفية ضبط "بنك الذاكرة" للاحتفاظ بالبيانات بين الجلسات
كيفية نشر الوكيل في Agent Engine باستخدام adk deploy
كيفية منح أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة الوكيل الذي تم نشره
كيفية اختبار استمرار الذاكرة وإمكانية مراقبتها

المتطلبات

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

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

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

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

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

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

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

في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على 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 لاستخراج البيانات ويحتفظ بالجلسات في "بنك الذاكرة".

يتم تفعيل الذاكرة تلقائيًا عند نشرها، ويتم ضبط متغيّر البيئة 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 تلقائيًا الذكريات ذات الصلة قبل كل طلب من نموذج اللغة الكبير، وذلك من خلال البحث في "بنك الذاكرة" عن محتوى ذي صلة برسالة المستخدم. تحتفظ دالة الاستدعاء _save_memory بالجلسة في "بنك الذاكرة" بعد كل عملية تشغيل للوكيل، ما يتيح للوكيل استرجاع السياق في الجلسات المستقبلية.
تغلف 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-* الأربع ميزات إمكانية تتبّع البيانات التي ستستكشفها لاحقًا. تتضمّن هذه الأدوات طلبات HTTP من FastAPI، وطلبات نموذج 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، يتم تفعيل ميزتَين تلقائيًا:

مستودع الذاكرة: يتصل PreloadMemoryTool بمستودع الذاكرة في Agent Engine ويحفظ الجلسات تلقائيًا._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 Playground.

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

"أدرِج الجداول في 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 ويعرض جدولاً يتضمّن السنوات وعدد المشاركات.
"ما هي النسبة المئوية للتغيّر في المشاركات مقارنةً بالعام السابق؟"
- النتيجة المتوقّعة: يستدعي الوكيل execute_sql باستخدام طلب بحث SQL يحسب النسبة المئوية للتغيير ويعرض النتائج.

7. اختبار الاحتفاظ بالذاكرة

في Playground، علِّم الوكيل إحدى الإعدادات المفضّلة:

"تذكَّر أنّ مجموعة البيانات المفضّلة لديّ هي bigquery-public-data.hacker_news"
"ما هي الجداول التي يتضمّنها؟"

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

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

"ما هي مجموعة البيانات المفضّلة لديّ؟"

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

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

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 الأساسية حزمة تطوير البرامج (SDK) وأداة التصدير OpenTelemetry، ولكنها لا تتضمّن حِزم قياس حالة التطبيق. لهذا السبب، يجب أن تتضمّن requirements.txt جميع العناصر الأربعة، وإلا لن يتم إنشاء أي نطاقات ولن تظهر أي عمليات تتبُّع.

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

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

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

9- تنظيف

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

احذف الوكيل الذي تم نشره من صفحة "محرك الوكيل" في 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
كيفية منح أذونات "إدارة الهوية وإمكانية الوصول" لحساب خدمة الوكيل الذي تم نشره
كيفية النشر في Agent Engine وتفعيل إمكانية تتبُّع البيانات باستخدام Cloud Trace

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

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