نشر وكيل ADK في Agent Runtime باستخدام Agents CLI

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستنقل وكيل ADK 2.0 من بيئة تطوير محلية إلى عملية نشر جاهزة للاستخدام في بيئة الإنتاج. ستستخدم agents-cli لتعبئة سير العمل المستند إلى الرسم البياني والتحقّق منه واستضافته مباشرةً على Agent Runtime على Google Cloud.

لاستكشاف عملية النشر هذه، ستنشئ نموذجًا أوّليًا محليًا من Ambient Expense Agent من البداية قبل نشره على السحابة الإلكترونية. (للحصول على تفاصيل أكثر حول تصميم المنطق الأساسي لهذا الوكيل، يُرجى الاطّلاع على دروس البرمجة الأساسية على موقع Kaggle الإلكتروني الخاص بالفعاليات). يعمل Ambient Expense Agent على تبسيط عملية إعداد تقارير نفقات الموظفين من خلال الموافقة الفورية على المطالبات العادية مع الإبلاغ عن النفقات الأكبر ليراجعها موظف. يستخدم هذا النظام سير عمل مستندًا إلى الرسم البياني في "حزمة تطوير التطبيقات 2.0" لتنسيق خطوات الموافقة الآلية وتحليل المخاطر.

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

  • كيفية إعداد مشروع Ambient Expense Agent المحلي لاستضافته على السحابة الإلكترونية
  • كيفية إنشاء نماذج أولية لواصفات النشر وأغلفة الإنتاج اللازمة
  • كيفية إجراء عمليات تجريبية ونشر الرمز البرمجي مباشرةً في Agent Runtime
  • كيفية مراقبة عمليات تتبُّع تنفيذ الوكيل في مرحلة الإنتاج باستخدام Cloud Trace

المتطلبات

  • مشروع Google Cloud نشط مع تفعيل الفوترة
  • تم تثبيت gcloud SDK ومصادقتها.
  • تم تثبيت أداة إدارة الحِزم uv.
  • تثبيت Google Antigravity IDE

المتطلبات الأساسية

يفترض هذا الدرس التطبيقي حول الترميز أنّك على دراية بما يلي:

  • التنقّل في نظامك باستخدام وحدة طرفية
  • مفاهيم تطوير Python الأساسية
  • المفاهيم الأساسية في Google Cloud

2. إعداد بيئة Google Cloud

قبل النشر، يجب إعداد مشروعك على Google Cloud وتفعيل واجهات برمجة التطبيقات اللازمة.

👉 Prompt Antigravity:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

عندما ينفّذ Antigravity هذا الطلب، سيقترح أوامر gcloud الطرفية اللازمة لتكوين مشروعك وتفعيل الخدمات وتشغيلها. أثناء خطوة المصادقة، ستعرض Antigravity عنوان URL لمنح الإذن في نافذة الجهاز. انقر على الرابط لتسجيل الدخول من خلال متصفّح الويب ومنح الإذن بالوصول. بعد إكمال عملية تسجيل الدخول في المتصفّح، ستستأنف Antigravity التنفيذ لضبط متغيرات بيئة مشروعك وتفعيل واجهات برمجة التطبيقات المطلوبة.

3- إعداد واجهة سطر الأوامر الخاصة بـ "الوكلاء" ومهارات ADK

لكي تتمكّن Antigravity من إنشاء وكلاء ADK وتفعيلهم بشكل جيد، يجب أن تتوفّر لديها مجموعة مهارات ADK. هذه مراجع مجمّعة لواجهة برمجة التطبيقات ADK، وتصميم المشروع، وagents-cli سير عمل النشر، والتقييم. يؤدي تثبيت مجموعة أدوات agents-cli أيضًا إلى تثبيت هذه المهارات في وكيل الترميز، ما يجعله مجهّزًا لإدارة دورة حياة الوكيل الكاملة، بدءًا من إنشاء البنية الأساسية محليًا وصولاً إلى النشر على السحابة الإلكترونية.

👉 انسخ الطلب التالي والصقه في Antigravity:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

عندما ينفّذ Antigravity هذا الطلب، يتم تشغيل uvx google-agents-cli setup في نافذة الأوامر لتثبيت واجهة سطر الأوامر والمهارات المصاحبة لها. بعد ذلك، يتم تشغيل agents-cli info للتحقّق من عملية التثبيت، ويتم عرض مهارات النطاق المثبّتة حديثًا (مثل google-agents-cli-deploy وgoogle-agents-cli-workflow) مباشرةً في المحادثة.

4. إنشاء مشروع الوكيل

بعد إعداد بيئة السحابة الإلكترونية وتثبيت مهارات واجهة سطر الأوامر، ستكون مستعدًا لإنشاء قاعدة الرموز البرمجية المحلية للوكيل. في هذه الخطوة، ستستخدم Antigravity لإنشاء نموذج أولي لوكيل "تتبُّع النفقات المحيطة" يعمل بكامل وظائفه ومتوافق مع الإصدار 2.0 من "حزمة تطوير التطبيقات لنظام Android".

👉 Prompt Antigravity:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

عندما ينفّذ Antigravity هذا الطلب، يستفيد من مهارات إنشاء البنية الأساسية المثبَّتة حديثًا لتشغيل agents-cli scaffold create expense-agent --adk في نافذة الأوامر. بعد ذلك، سيتحقّق من رمز النموذج الأوّلي الذي تم إنشاؤه ويعدّله لضمان أنّ expense-agent ينفّذ بشكل صحيح $100 حد الموافقة التلقائية وتدفق المراجعة الذي يتضمّن تدخّل الإنسان ضمن سير عمل الرسم البياني لحزمة تطوير الوكيل (ADK).

5- الاستعداد لنشر الإصدار العلني

Agent Runtime هي خدمة مُدارة بالكامل من Google Cloud تتيح لك نشر وكلاء الذكاء الاصطناعي وإدارتهم وتوسيع نطاقهم في مرحلة الإنتاج. يتعامل Agent Runtime مع التعقيدات التشغيلية للاستضافة، ويوفّر بيئة ذات حالة مع ميزات مثل إدارة الجلسات والذاكرة الطويلة الأمد ومربّعات الحماية لتنفيذ الرموز البرمجية بشكل آمن.

لماذا يجب النشر في بيئة تشغيل الوكيل؟

عند إنشاء وكلاء محليًا باستخدام Antigravity، يتم تشغيل الوكيل على جهازك المحلي مقابل localhost. على الرغم من أنّها رائعة لإنشاء نماذج أولية سريعة، تتوقف الوكلاء المحليون عن العمل في اللحظة التي تغلق فيها الكمبيوتر المحمول.

يؤدي نشر الوكيل في Agent Runtime إلى نقل سير العمل إلى بيئة Google Cloud مُدارة بالكامل ومتاحة دائمًا. يؤدي ذلك إلى إنشاء نقطة نهاية خلفية آمنة ومباشرة تظل نشطة على مدار الساعة طوال أيام الأسبوع. في الدرس التطبيقي التالي حول الترميز، ستنشئ واجهة أمامية على الويب تتصل مباشرةً بنقطة النهاية هذه على السحابة الإلكترونية، ما يمنح الوكيل عنوان URL عامًا.

بالإضافة إلى ذلك، يوفّر Agent Runtime بنية أساسية مخصّصة تم تحسينها خصيصًا لوكلاء الذكاء الاصطناعي، ما يتيح إمكانات مضمّنة مثل:

  • التنفيذ المُدار مع الاحتفاظ بالحالة: إدارة الجلسات المضمّنة واستمرار الذاكرة الطويلة الأمد في جميع مراحل المحادثة
  • وضع الحماية الآمن: ينفّذ بأمان طلبات الأدوات الديناميكية والرموز البرمجية التي ينشئها الوكيل في بيئات معزولة.
  • مراقبة أداء المؤسسات: بث بيانات القياس عن بُعد الجاهزة للاستخدام مباشرةً إلى Cloud Trace وCloud Logging

لاستضافة وكيلك على Agent Runtime، يجب تحسين دليل مشروع على جهاز المستخدم باستخدام واصفات الإنتاج والمخططات وبرامج تضمين نقاط النهاية.

👉 Prompt Antigravity:

Scaffold the production deployment files for Agent Runtime.

عندما ينفّذ Antigravity هذا الطلب، سيشغّل agents-cli scaffold enhance --deployment-target agent_runtime --yes في جذر مشروعك. يفحص هذا الأمر دليلك وينشئ تلقائيًا ما يلي:

  • ‫app/agent_runtime_app.py: برنامج تضمين الخدمة المناسب للإنتاج
  • ‫deployment_metadata.json: مخطط التنسيق الذي يستخدمه Agent Runtime لتوفير الموارد.

سيظلّ منطق الوكيل الأساسي في app/agent.py كما هو بدون أي تغييرات.

6. التغليف والتحقّق من صحة المعلومات المحلية

قبل بدء عملية التحميل إلى السحابة الإلكترونية، يجب قفل الحِزم وإجراء عملية تجريبية محلية لتحديد تعارضات التبعيات المحتملة.

👉 Prompt Antigravity:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

عندما ينفّذ Antigravity هذا الطلب، فإنه ينفّذ أولاً uv lock في الوحدة الطرفية لإنشاء ملف قفل حتمي، ما يضمن توفّر إصدارات متسقة من المكتبة على السحابة الإلكترونية. بعد ذلك، يتم تنفيذ agents-cli deploy --dry-run للتحقّق من صحة عملية الضبط ومعاينة خطوات النشر بدون توفير موارد السحابة الإلكترونية. يمكنك مراجعة نتائج التشغيل التجريبي في نافذة الأوامر للتأكّد من صحة جميع الملفات والإعدادات.

7. النشر في Agent Runtime

انشر Ambient Expense Agent في Agent Runtime.

👉 Prompt Antigravity:

Deploy this agent to Agent Runtime.

عندما ينفّذ Antigravity هذا الطلب، يفعّل مهارة google-agents-cli-deploy ويشغّل agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. تستغرق عملية التغليف والتحميل وتوفير Agent Runtime عادةً من 5 إلى 10 دقائق. ستتتبّع Antigravity تقدّم عملية النشر في نافذة الأوامر، وبعد اكتمالها، ستعرض عنوان URL لنقطة النهاية المباشرة.

💡 نصيحة احترافية (إدارة فترات المهلة): إذا كنت تفضّل عدم قفل نافذة الجهاز الطرفي أثناء عمليات النشر الطويلة، يمكنك توجيه Antigravity لاستخدام العلامة --no-wait لبدء عملية النشر بشكل غير متزامن، والتحقّق من مستوى التقدّم لاحقًا باستخدام agents-cli deploy --status.

8. اختبار الوكيل

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

👉 اطلب من Antigravity التحقّق من المحرّك الذي تم نشره مباشرةً:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

بدلاً من ذلك، يمكنك اختبار الوكيل يدويًا باستخدام معاينة Cloud Console Playground. لفتح Playground، اتّبِع الخطوات التالية:

  1. في Google Cloud Console، استخدِم قائمة التنقّل لاختيار منصة الوكيل > عمليات النشر.
  2. اختَر الوكيل الذي تم نشره من قائمة عمليات النشر.
  3. انقر على الزر مساحة تجريبية لفتح واجهة المحادثة التفاعلية التجريبية.

👉 لاختبار ميزة "الموافقة التلقائية" (أقل من 100 دولار أمريكي)، الصِق حِمل JSON التالي في مربّع الدردشة:

{"data": {"amount": 50.0, "submitter": "user@example.com", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

من المفترض أن تتلقّى استجابة JSON تعرض ناتج عقدة auto_approve بالحالة "تمت الموافقة".

استجابة JSON تعرض الموافقة التلقائية على نفقة بقيمة 50 دولارًا أمريكيًا

👉 لاختبار مسار Human-in-the-Loop (HITL)، الصِق حِمل JSON التالي.

{"data": {"amount": 150.0, "submitter": "user@example.com", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

سيؤدي ذلك إلى تشغيل review_agent، وإصدار تنبيه تحذير، ثم إيقاف التنفيذ مؤقتًا، ما يؤدي إلى ظهور RequestInput (Human-in-the-loop) يطلب الموافقة.

استجابة JSON تطلب المزيد من المعلومات عن نفقة بقيمة 150 دولار أمريكي

9- مراقبة "وكيل الإنتاج"

باستخدام Agent Runtime، يتم ربط بيانات القياس عن بُعد تلقائيًا. يتم بث السجلات والمدد في الوقت الفعلي إلى مشروعك لكل تفاعل واستدعاء نموذج وتنفيذ أداة.

  1. فحص عمليات التتبُّع: افتح وحدة تحكّم Cloud Trace لتدقيق خرائط المعاملات المباشرة، ووقت استجابة النماذج، وخطوات تنفيذ الأدوات.
  2. سجلات التدقيق: استخدِم Cloud Logging لفحص الناتج العادي في الوقت الفعلي وعمليات تتبُّع تسلسل استدعاء الدوال البرمجية التشخيصية.

وحدة تحكّم Cloud Logging تعرض نفقات معتمَدة بقيمة 50 دولارًا أمريكيًا.

  1. إحصاءات مجمّعة: إذا تم تفعيل العلامة --bq-analytics أثناء إنشاء البنية الأساسية، يمكنك طلب البحث في سجلّاتك داخل BigQuery باستخدام SQL لعرض نسب الموافقة ومؤشرات عدد مرات التفاعل.

يقدّم استعلام SQL التالي مثالاً على كيفية احتساب نسب الموافقة. يمكنك أن تطلب من Antigravity تخصيص طلب البحث هذا لمشروعك ومجموعة بيانات BigQuery المحدّدين:

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (اختياري) التحقّق من التسجيل في "سجلّ الوكلاء"

للسماح للخدمات أو المطوّرين أو الوكلاء الآخرين في مؤسستك باكتشاف وكيل النفقات واستخدامه بأمان، يجب تسجيله في سجلّ الوكلاء الخاص بالمؤسسة (Gemini Enterprise).

بما أنّك نشرت الوكيل في Agent Runtime، يتم تسجيله تلقائيًا في Agent Registry. ستتم أيضًا تلقائيًا مزامنة أي تعديلات أو عمليات حذف مستقبلية للوكيل في Agent Runtime مع Agent Registry.

👉 اطلب من Antigravity تأكيد التسجيل التلقائي للوكيل:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

عندما ينفّذ Antigravity هذا الطلب، سيشغّل agents-cli publish gemini-enterprise --list في الوحدة الطرفية. يؤدي هذا الإجراء إلى طلب البحث في "سجلّ الوكلاء" وإدراج جميع وكلاء Gemini Enterprise المسجّلين في مشروعك، ما يتيح لك التأكّد من أنّ "وكيل Ambient Expense" نشط ويمكن اكتشافه في مؤسستك.

11. تَنظيم

لتجنُّب تحمّل رسوم مستمرة في حسابك على Google Cloud، عليك إيقاف الموارد التي تم نشرها وتنظيفها عند الانتهاء.

👉 Prompt Antigravity:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

عندما ينفّذ Antigravity هذا الطلب، تتم أتمتة عملية تنظيف الموارد بأكملها:

  1. حذف الوكيل الذي تم نشره: يقرأ هذا الأمر deployment_metadata.json للحصول على رقم تعريف وقت تشغيل الوكيل عن بُعد، ثم يحذف بشكل آلي مثيل المحرّك النشط من Vertex AI.
  2. تنظيف مساحة العمل المحلية: يؤدي هذا الخيار إلى إزالة ملف deployment_metadata.json القديم من جذر مشروعك.
  3. تنظيف Artifact Registry: ينفّذ هذا الخيار الأمر gcloud artifacts docker images delete لإزالة صور الحاويات التي تم إنشاؤها من Artifact Registry، ما يؤدي إلى إخلاء مساحة تخزين على السحابة الإلكترونية.

12. تهانينا

تهانينا! لقد نشرت وكيل Ambient Expense Agent وأثبتّ صحته بنجاح على Google Cloud.

ما تعلّمته

  • إعداد Google Cloud: تم إعداد بيانات اعتماد المشروع وتفعيل واجهات برمجة التطبيقات المطلوبة على المنصة.
  • الأدوات والمهارات: تم تثبيت agents-cli وتحميل مهارات ADK المساعدة في Antigravity.
  • إنشاء بنية أساسية للإنتاج: تم إنشاء بنية أساسية لوقت تشغيل الوكيل لـ "حزمة تطوير الوكلاء" (ADK) 2.0.
  • التحقّق من صحة التثبيت: تم إنشاء ملفات قفل حتمية (uv lock) وتنفيذ عمليات تحقّق تجريبية.
  • النشر على السحابة الإلكترونية: استضافة الوكيل مباشرةً على بنية أساسية مُدارة لبيئة تشغيل الوكيل
  • إمكانية تتبّع البيانات والتحليلات: تتبُّع التنفيذ في Cloud Trace وتحليل بيانات القياس عن بُعد في BigQuery.
  • اكتشاف المؤسسات: تسجيل تلقائي تم التحقّق منه في "سجلّ وكلاء المؤسسات"

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

  • إجراء تحليلات BigQuery: يمكنك طلب سجلّات القياس عن بُعد الخاصة بالوكيل في BigQuery لتحليل نسب الموافقة ومؤشرات الحوار بمرور الوقت.
  • درس Vibe to Live التطبيقي حول الترميز: استخدِم Google Antigravity لتطوير برنامج عميل للواجهة الأمامية على Cloud Run وربطه مباشرةً بنقطة نهاية الخلفية المباشرة في Agent Runtime.

الحصول على شارة "وكلاء الذكاء الاصطناعي في 5 أيام" على Kaggle 🎉

هل أكملت هذا المختبر كجزء من دورة تدريبية مكثّفة لمدة 5 أيام حول وكلاء الذكاء الاصطناعي: ترميز المشاعر باستخدام Google في Kaggle؟ المطالبة بشارة الإكمال:

الحصول على شارة "وكلاء الذكاء الاصطناعي خلال 5 أيام"

المراجع