الكلمة الافتتاحية لمؤتمر Next ‘26 Developer: تصحيح أخطاء الوكلاء على نطاق واسع

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية تصحيح أخطاء وكلاء الذكاء الاصطناعي الذين يعملون على Google Cloud. ستنشئ وكيل محاكاة في Agent Runtime، وتستخدم Cloud Observability لرصد المشاكل، وتستخدم Gemini Cloud Assist وAntigravity IDE لتحديد السبب الأساسي للأخطاء وحلّها في الوقت الفعلي.

تستند فكرة هذا العرض التوضيحي إلى أنّنا أضفنا ADK EventCompaction إلى Simulator Agent. يتيح ذلك لـ "المحاكي" تلخيص سير العمل بشكل دوري باستخدام Gemini، ما يقلّل من إجمالي السياق المُرسَل إلى النموذج في كل خطوة، وبالتالي يحسّن جودة الردود ويقلّل من التكاليف الإجمالية. ولكن، سنعرف أنّ هناك خطأً في EventCompactionConfig، ما يتسبّب في حدوث أخطاء في البرنامج. يوضّح لك هذا الدرس العملي كيفية رصد هذا النوع من المشاكل وحلّه بسرعة.

الإجراءات التي ستنفذّها

• انشر وكيل Marathon Simulator إلى Agent Runtime.
• إعداد تنبيه في Cloud Monitoring لرصد أخطاء الوكيل
• التحقيق في الأخطاء باستخدام Cloud Trace وGemini Cloud Assist
• تحديد السبب الجذري للخطأ وتصحيحه باستخدام Antigravity وMCP

ملاحظة: يتوفّر Gemini Cloud Assist حاليًا في "البرنامج التجريبي الخاص". لا تحتاج إلى إدراجك في القائمة المسموح بها لتشغيل هذا الدرس العملي. جميع خطوات Cloud Assist محصورة في الخطوة رقم 8 (اختياري): استخدام "تحقيقات Cloud Assist" - تخطَّ هذه الصفحة إذا لم تتمكّن من الوصول إلى Cloud Assist بعد.

المتطلبات

• متصفّح ويب، مثل Chrome
• حساب Google
• ‫Antigravity (متوافق مع أجهزة Mac وLinux وWindows)
• الإصدار 3.13 من Python أو إصدار أحدث
• uv (أداة إدارة حِزم Python)

المدة المقدَّرة: 45 دقيقة

التكلفة المقدَّرة: أقل من 5 دولار أمريكي

2. قبل البدء

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

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

إعداد البيئة

افتح Antigravity وسجِّل الدخول. بعد ذلك، افتح وحدة طرفية من خلال الضغط على cmd-shift-P (أو ctrl-shift-P)، ثم كتابة "إنشاء وحدة طرفية جديدة".

1. من "وحدة التحكّم"، يمكنك المصادقة باستخدام Google Cloud باتّباع الخطوات التالية:

gcloud auth login
gcloud auth application-default login

2. اضبط رقم تعريف مشروعك:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

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

نفِّذ الأمر التالي لتفعيل واجهات Google Cloud APIs المطلوبة:

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

إذا تم إدراجك في القائمة المسموح بها لاستخدام Gemini Cloud Assist (الإصدار الحصري الخاص)، فعِّل واجهات برمجة التطبيقات الإضافية التالية:

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3- إعداد "وكيل المحاكي"

في هذه الخطوة، ستنسخ مستودع العرض التوضيحي وتضبط متغيرات البيئة الخاصة بـ "وكيل المحاكي".

إنشاء نسخة طبق الأصل من المستودع

أنشئ نسخة طبق الأصل من مستودع next-26-keynotes وانتقِل إلى دليل العرض التوضيحي:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

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

يستخدم "وكيل المحاكي" ملف .env للإعداد.

ابحث عن ملف sample.env على يمين نافذة Antigravity (المستكشف):

افتح sample.env وعدِّل الحقل GCP_PROJECT_ID باستخدام رقم تعريف مشروع Google Cloud الفعلي. يجب أن يبدو الملف مشابهًا لما يلي:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

نعمل على تفعيل عمليات دمج OpenTelemetry لتسجيل عمليات التتبُّع الدقيقة لطلبات الأدوات التي يرسلها الوكيل ومسار الاستدلال.

4. نشر وكيل المحاكي في بيئة تشغيل الوكيل

الآن، ستفعّل الوكيل في وقت تشغيل الوكيل باستخدام حزمة تطوير الوكلاء (ADK).

تثبيت الحِزم التابعة

uv sync

النشر في Agent Runtime

1. نفِّذ الأمر adk deploy. في هذه الخطوة، يتم تجميع الوكيل ونشره على Google Cloud (بيئة تشغيل الوكيل).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

قد تستغرق هذه العملية مدة تصل إلى 5 دقائق. من المفترض أن تظهر لك نتيجة مشابهة لما يلي:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

دوِّن رقم تعريف بيئة تشغيل الوكيل الذي تم إنشاؤه. ستحتاج إلى ذلك لاحقًا.

2. من متصفّح ويب، افتح وحدة تحكّم Agent Runtime. من المفترض أن ترى simulator_agent يعمل على Agent Runtime، مع تفعيل عملية جمع بيانات القياس عن بُعد.

5- إعداد "سياسة تنبيه"

لرصد أخطاء Agent Runtime تلقائيًا، عليك إنشاء تنبيه مستند إلى السجلّ في Google Cloud Console.

1. انتقِل إلى وحدة تحكّم Cloud Monitoring - التنبيهات.

2. انقر على تعديل قنوات الإشعارات. انتقِل للأسفل إلى نوع البريد الإلكتروني، ثم أنشِئ قناة إشعارات عبر البريد الإلكتروني لإرسالها إلى بريدك الإلكتروني الشخصي. انقر على حفظ.

3. ارجع إلى لوحة بيانات "التنبيهات"، وانقر على إنشاء سياسة.
4. على يسار الشاشة، انقر على إنشاء تنبيه مستند إلى السجلّ.

5. ستتم إعادة توجيهك إلى مستكشف السجلّ. الصِق طلب البحث التالي في السجلّ، مع استبدال رقم تعريف مشروعك.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

يبحث طلب البحث في السجلّ هذا عن سجلّات الأخطاء ضمن وكيل Agent Runtime، حيث أنّ ReasoningEngine هو اسم واجهة برمجة التطبيقات الأساسية لـ Agent Runtime.

6. انقر على تنفيذ طلب البحث. لن تظهر لك أي سجلّات بعد، وهذا أمر متوقّع.
7. انقر على الإجراءات في شريط أدوات النتائج، ثمّ انقر على إنشاء تنبيه سجلّ.

8. ضبط التنبيه المستند إلى السجلّ امنح التنبيه اسمًا (أي اسم)، ثم اضبط مستوى الخطورة على خطأ.

9. انقر على التالي للانتقال إلى قسم "ضبط معدّل تكرار الإشعارات" (احتفظ بالإعدادات التلقائية).

10. في قسم مَن يجب إعلامه؟، اضبط التنبيه لتشغيل قناة الإشعارات عبر البريد الإلكتروني التي أعددتها للتو (مثل My Email).
11. انقر على حفظ.

6. تفعيل الحادث

بعد نشر البرنامج وتتبُّعه، لنحاول الآن تشغيل محاكاة الماراثون بطريقة تؤدي إلى ظهور خطأ.

1. في Google Cloud Console، انتقِل إلى وحدة تحكّم وقت تشغيل الوكيل.
2. انقر على simulator_agent.
3. من شريط الأدوات العلوي، انقر على ساحة اللعب. سيؤدي ذلك إلى بدء جلسة جديدة مع وكيل ADK.

4. من نافذة محادثة الجلسة، اكتب Test Simulation واضغط على enter لإرسال الطلب.

سيؤدي ذلك إلى بدء محاكاة الماراثون، وتتبُّع آلاف العدّائين الافتراضيين على طول المسار المخطط له. من المفترض أن تظهر لك طلبات متعددة لاستخدام الأدوات get_runner_telemetry وanalyze_medical_risk، لأنّ المحاكاة تقيِّم "مناطق" متعددة من السباق.

بعد بضع دقائق، من المفترض أن يتوقف الوكيل عن العمل، ولن يعرض أي رد.

5. في غضون دقيقة أو نحو ذلك، من المفترض أن تصلك رسالة إلكترونية في بريدك الوارد تنبّهك إلى "حادثة" جديدة ضمن "الوكيل".

انقر على عرض الحادث لفتح وحدة تحكّم Cloud Monitoring. انتقِل إلى الصفحة التالية للتحقيق في المشكلة ضمن "وحدة التحكّم".

7. التحقيق في الحادث في وحدة التحكّم

1. اطّلِع على "الحادث" في Cloud Monitoring Console. من المفترض أن تظهر لك سجلّات الأخطاء الواردة من Simulator Agent.

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

2. افتح وحدة تحكّم Agent Runtime مرة أخرى. انقر على simulator_agent، ثم افتح علامة التبويب عمليات التتبُّع.

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

4. انقر على المدّة الأخيرة في عرض التتبُّع. يجب أن يكون أحمر.
5. انقر على تتبُّع تسلسل استدعاء الدوال البرمجية. من المفترض أن تظهر لك سجلّات الأخطاء المتعلّقة بطلب نموذج Gemini API. على وجه التحديد، حدث خطأ 400: Invalid Argument. تشير هذه الرسالة إلى مشكلة على مستوى الطلب في حمولة أرسلها Simulator Agent إلى Gemini API.

8. [اختياري] استخدام "تحقيقات Cloud Assist" لتصحيح الأخطاء

اتّبِع هذه الخطوات فقط إذا كنت مدرَجًا في القائمة المسموح بها لاستخدام Gemini Cloud Assist (معاينة خاصة). بخلاف ذلك، انتقِل إلى الصفحة التالية.

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

2. سيؤدي ذلك إلى بدء تحقيق Cloud Assist من شريط جانبي على يسار الشاشة. سيستغرق تحميل هذه الصفحة من 3 إلى 5 دقائق تقريبًا.

3. بعد اكتمالها، افتح التحقيق.

4. اطّلِع على ملخّص التحقيق.

5. انتقِل للأسفل واطّلِع على الفرضيات. من المفترض أنّ Gemini Cloud Assist قد حدّد السطر المحدّد في ملف agent.py الخاص بـ Simulator Agent الذي يعرض الخطأ 400 في Gemini API.

لنتعمّق أكثر في المشكلة من خلال فتح الرمز المصدر للوكيل، واستخدام Antigravity للعثور على السبب الأساسي للمشكلة. انتقِل إلى الصفحة التالية.

9- استخدام Antigravity لتحديد السبب الجذري للمشكلة وإصلاحها

1. أعِد فتح Antigravity.
2. افتح إدارة الوكلاء في أعلى يسار الشاشة.

3. تأكَّد من ضبط النموذج على Gemini 3 Flash ووضع التخطيط.

4. أدخِل الطلب التالي، ثم اضغط على enter.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.    

من المفترض أن ترى Antigravity وهي تفحص الرمز في agent.py، وتبحث في GitHub عن المشاكل ذات الصلة:

السبب الأساسي لظهور الخطأ 400 في Gemini API هو تجاوز الحدّ الأقصى لعدد الرموز المميزة في سياق الإدخال في Gemini 3 Flash، والذي يبلغ مليون رمز مميز تقريبًا. والسبب في حدوث ذلك هو أنّنا لا نفعّل EventCompaction بشكلٍ كافٍ لتلخيص الردود الكبيرة من عمليات استدعاء الأداة Simulator Agents بشكلٍ فعّال.

لحلّ هذه المشكلة، يجب أن تقترح Antigravity إضافة المَعلمة token_threshold إلى EventsCompactionConfig، وذلك لضغط السياق بشكلٍ دوري في كل استدعاء عند الوصول إلى عدد معيّن من الرموز المميزة.

يتوافق ذلك مع الحلّ المقترَح في مشكلة GitHub هذه.

تطبيق الحلّ على agent.py.

تأكَّد من ظهور شيء مشابه لما يلي:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

الأهم من ذلك، يجب تحديد token_threshold وevent_retention_size.

10. إعادة نشر الإصلاح والتحقّق منه

بعد تطبيق token_threshold على EventCompactionConfig وكيل ADK، يمكننا إعادة نشر وكيل المحاكي في بيئة تشغيل الوكيل.

1. افتح Antigravity –> New Terminal (وحدة طرفية جديدة).
2. ضبط متغيرات البيئة يجب أن يكون AGENT_RUNTIME_ID هو اسم المرجع الكامل simulator_agent. يمكن العثور على ذلك في وحدة تحكّم وقت تشغيل الوكيل - قائمة الوكلاء.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

3. أعِد نشر الوكيل:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

سيستغرق تنفيذ هذه العملية بضع دقائق. بعد إكمال العملية بنجاح، من المفترض أن يظهر لك ما يلي:

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

4. افتح وحدة تحكّم Agent Runtime. أعِد فتح simulator_agent. انقر على مساحة المرح.
5. أدخِل الطلب نفسه: Test Simulation - ثم اضغط على مفتاح Enter.
6. من المفترض أن تستغرق عملية محاكاة Marathon الكاملة في الخلفية بضع دقائق. من المفترض أن تظهر لك طلبات أدوات متعدّدة. في النهاية، من المفترض أن يظهر لك ردّ على النحو التالي:

يشير ذلك إلى أنّ المحاكي قد تم تشغيله بنجاح. ✅

7. افتح "عرض التتبُّع" لجلسة ADK هذه.
8. من المفترض أن تظهر جميع الفترات "الزرقاء"، بدون أي أخطاء حمراء. لاحظ كيف يتجاوز إجمالي عدد الرموز المميزة للجلسات الحدّ الأقصى المسموح به لرموز السياق في Gemini API، وهو مليون رمز مميز. لا بأس في ذلك، لأنّ EventCompaction يعمل الآن بشكل متكرر بما يكفي ضمن كل استدعاء، وذلك لتجنُّب تجاوز الحد الأقصى للسياق العام عند إجراء طلبات فردية من النموذج.

🎊 رائع! لقد أصلحنا الخطأ في وكيل المحاكي.

11. تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس العملي.

حذف تطبيق Agent Runtime

يمكنك حذف مثيل Reasoning Engine من خلال وحدة التحكّم أو باستخدام الأمر gcloud (إذا كان لديك اسم المورد). لتبسيط الأمر، استخدِم وحدة التحكّم:

1. انتقِل إلى صفحة بيئة تشغيل الوكيل.
2. انقر على simulator_agent –> زر النقاط الثلاث على الجانب الأيسر.
3. انقر على حذف.

حذف "سياسة Cloud Monitoring"

1. انتقِل إلى وحدة تحكّم Cloud Monitoring -> التنبيه.
2. انتقِل للأسفل إلى السياسات، ثم انقر على زر النقاط الثلاث حذف السياسة.

12. 🎊 تهانينا!

تهانينا! لقد تمكّنت للتو من تصحيح خطأ في وكيل الذكاء الاصطناعي على Google Cloud.

ما تعلّمته

• كيفية نشر الوكلاء في بيئة تشغيل الوكيل
• كيفية رصد الأخطاء باستخدام تنبيهات Cloud Monitoring
• كيفية استكشاف "الحوادث" النشطة باستخدام Cloud Logging وعرض التتبُّع في Agent Runtime
• كيفية التحقيق في حالات الفشل باستخدام Gemini Cloud Assist
• كيفية استخدام Antigravity لتحديد السبب الجذري لأخطاء الوكيل وتصحيحها
• كيفية ضبط ضغط أحداث ADK بدقة للتعامل مع عمليات الوكيل الطويلة التي تتضمّن أدوات كثيرة

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

• مزيد من المعلومات حول "بيئة تشغيل الوكيل"
• مزيد من المعلومات عن "حزمة تطوير الوكيل"
• مزيد من المعلومات عن التنبيهات في Cloud Monitoring
• مزيد من المعلومات حول "مساعد Gemini السحابي"