لمحة عن هذا الدرس التطبيقي حول الترميز
1. نظرة عامة
ما هي الخطوات الأولى لاستخدام الذكاء الاصطناعي اليوم؟ بالنسبة إلى معظمنا، يبدأ الأمر غالبًا بسؤال بسيط: "هل يمكن للنموذج المساعدة في حلّ هذه المشكلة التي أفكر فيها؟". وهنا يأتي دور Google AI Studio. وهو مكان يمكنك فيه إنشاء نماذج أولية لأي شيء بسرعة. أريد إعادة تصميم مطبخي وأعتقد أنّ Gemini يمكنه مساعدتي، ولكنّني مهندس، لست مقاولاً عامًا. لست متأكّدًا من الطلب الذي أريد تقديمه، فهناك الكثير من العوامل التي يجب مراعاتها: اللوائح التنظيمية والتجهيزات وما إلى ذلك. لذا، لنقسّم هذه المسألة ونطلب من Gemini إنشاء طلب مفصّل للغاية، ثم إنشاء خطة تجديد كاملة وعرض التصميم الجديد أيضًا. ولكن انتظر. كيف يمكنني مساعدة الأنشطة التجارية على توسيع نطاق عملها من هنا؟ إدخال AGENTS!!!
الوكيل هو برنامج مستقل يتواصل مع نموذج الذكاء الاصطناعي لتنفيذ عملية مستندة إلى الأهداف باستخدام الأدوات والسياق المتوفّرَين لديه، وهو قادر على اتّخاذ قرارات مستقلة تستند إلى الحقائق.
مجموعة تطوير موظّفي الدعم (ADK)
مجموعة تطوير موظّفي الدعم (ADK) هي إطار عمل مرن ومكوّن من وحدات لتطوير موظّفي الدعم المستندين إلى الذكاء الاصطناعي ونشرهم. تتيح ADK إنشاء تطبيقات متقدّمة من خلال إنشاء مثيلات متعدّدة ومميّزة للوكيل في نظام متعدّد الوكلاء (MAS).
في ADK، نظام الوكلاء المتعدّدين هو تطبيق يتعاون فيه وكلاء مختلفون أو ينسقون لتحقيق هدف أكبر، وغالبًا ما يشكّلون تسلسلاً هرميًا. توفّر لك بنية تطبيقك هذه مزايا كبيرة، بما في ذلك الوحدات المحسّنة والتخصص وإمكانية إعادة الاستخدام وسهولة الصيانة والقدرة على تحديد مسارات التحكّم منظَّمة باستخدام وكلاء سير العمل المخصّصين.
ما ستُنشئه
هل أنت مستعد للانتقال من النموذج الأوّلي لطلب المساعدة إلى إنشاء موظّف دعم؟ سننشئ وكيلاً لمساعدتك في إنشاء مستند الاقتراح لمشروع تجديد المطبخ. كجزء من هذا الدرس التطبيقي، عليك تنفيذ ما يلي:
- إنشاء وكيل بسيط لإنشاء مستند اقتراح تجديد باستخدام ADK
- تخزين مستند "اقتراح التجديد" الذي تم إنشاؤه في حزمة Cloud Storage
- اختبار موظّف الدّعم في Cloud Shell وفي إخراج موظّف الدّعم على الويب
المتطلبات
2. قبل البدء
إنشاء مشروع
- في Google Cloud Console، في صفحة أداة اختيار المشاريع، اختَر مشروعًا على Google Cloud أو أنشِئه.
- تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في أحد المشاريع .
- إذا كنت تقرأ هذه المقالة وتريد الحصول على بعض الأرصدة لمساعدتك في بدء استخدام Google Cloud واستخدام ADK، يمكنك استخدام هذا الرابط لاستبدال الأرصدة.
- يمكنك اتّباع التعليمات هنا لاسترداد القيمة. يُرجى العِلم أنّ هذا الرابط صالح لاسترداد القيمة حتى 15 تموز (يوليو) 2025 فقط.
- فعِّل Cloud Shell بالنقر على هذا الرابط. يمكنك التبديل بين Cloud Shell Terminal (لتشغيل أوامر السحابة الإلكترونية) و"المحرِّر" (لإنشاء المشاريع) من خلال النقر على الزرّ المقابل من Cloud Shell.
- بعد الاتصال بخدمة Cloud Shell، عليك التحقّق من أنّك سبق أن تم مصادقة حسابك وأنّ المشروع قد تم ضبطه على معرّف مشروعك باستخدام الأمر التالي:
gcloud auth list
- شغِّل الأمر التالي في Cloud Shell للتأكّد من أنّ الأمر gcloud يعرف مشروعك.
gcloud config list project
- إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:
gcloud config set project <YOUR_PROJECT_ID>
- تأكَّد من توفُّر الإصدار 3.9 من Python أو الإصدارات الأحدث.
يُرجى الرجوع إلى المستندات لمعرفة أوامر gcloud الأخرى وكيفية استخدامها.
3. النموذج الأولي
انتقِل إلى Google AI Studio. ابدأ كتابة طلبك. إليك الطلب:
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
عدِّل المعلمات وضبطها على يسار الصفحة للحصول على أفضل استجابة.
استنادًا إلى هذا الوصف البسيط، أنشأت خدمة Gemini طلبًا مفصّلاً للغاية لبدء عملية التجديد. وبالتالي، نستخدم Gemini للحصول على ردود أفضل من AI Studio ونماذجنا. يمكنك أيضًا اختيار نماذج مختلفة لاستخدامها استنادًا إلى حالة الاستخدام.
لقد اخترنا Gemini 2.5 Pro. هذا نموذج "تفكير"، ما يعني أنّنا نحصل على المزيد من الرموز المميّزة للإخراج، في هذه الحالة ما يصل إلى 65 ألف رمز مميّز، لتحليلات طويلة ومستندات مفصّلة. يظهر مربّع التفكير في Gemini عند تفعيل Gemini 2.5 Pro الذي يتمتع بإمكانات استدلال أساسية ويمكنه معالجة طلبات السياق الطويل.
راجِع المقتطف من الردّ أدناه:
حلّلت أداة AI Studio بياناتي وأنتجت كل هذه العناصر، مثل الخزائن وأسطح المطبخ والخلفية الأرضية والمغسلة والتماسك ومجموعة الألوان واختيار المواد. ويذكر Gemini المصادر أيضًا.
الآن، حاوِل تنفيذ الفكرة باستخدام طلب مختلف.
- انسخ هذا الطلب والصقه في محرِّر الطلبات:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- إرفاق صورة لمطبخك الحالي (أو يمكنك استخدام نموذج صورة المطبخ)
- غيِّر النموذج إلى "إنشاء صور من خلال معاينة فلاش 2.0 في Gemini" حتى تتمكّن من إنشاء الصور.
حصلت على هذا الناتج:
هذه هي قوة Gemini.
بدءًا من فهم الفيديوهات وإنشاء صور أصلية ووصولاً إلى تقديم معلومات حقيقية باستخدام "بحث Google"، هناك ميزات لا يمكن إنشاؤها إلا باستخدام Gemini.
من AI Studio، يمكنك استخدام هذا النموذج الأوّلي والحصول على مفتاح واجهة برمجة التطبيقات وتوسيع نطاقه إلى تطبيق وكيل كامل باستخدام إمكانات Vertex AI ADK.
4. إعداد حزمة ADK
لننتقل الآن إلى وحدة Cloud Shell الطرفية التي فعّلناها في قسم "قبل البدء":
- إنشاء بيئة افتراضية وتفعيلها (إجراء مقترَح)
من Cloud Shell Terminal، أنشئ بيئة افتراضية:
python -m venv .venv
فعِّل البيئة الافتراضية:
source .venv/bin/activate
- تثبيت حزمة ADK
pip install google-adk
5. بنية المشروع
- من Cloud Shell Terminal، أنشئ دليلاً جذرًا لتطبيقاتك المُدارة في الموقع المطلوب للمشروع:
mkdir agentic-apps
- داخل الدليل الرئيسي، أنشئ مجلدًا واحدًا خاصًا بمشروعنا الحالي:
mkdir renovation-agent
- انتقِل إلى محرِّر Cloud Shell وأنشئ بنية المشروع التالية من خلال إنشاء الملفات (فارغة في البداية):
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. رمز المصدر
- انتقِل إلى init.py وعدِّل الملف باستخدام المحتوى التالي:
from . import agent
- انتقِل إلى agent.py وعدِّل الملف باستخدام المحتوى التالي من المسار التالي:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
في agent.py، نستورِد التبعيات اللازمة ونسترِد مَعلمات الضبط من ملف .env ونحدِّد root_agent الذي ينشئ مستند اقتراح ويخزّنه في حزمة Cloud Storage. لتنفيذ خطوة Cloud Storage، نستخدم أداة تُسمى store_pdf.
- تأكَّد من توفّر حزمة Cloud Storage.
يُستخدَم هذا الحقل لتخزين مستند الاقتراح الذي ينشئه موظّف الدّعم. أنشئ هذا النموذج ووفِّر إمكانية الوصول إليه حتى يتمكّن النظام الوكيل الذي ننشئه باستخدام Vertex AI من الوصول إليه. إليك كيفية إجراء ذلك:
https://cloud.google.com/storage/docs/creating-buckets#console
أدخِل اسم "next-demo-store" للحزمة. إذا اخترت اسمًا آخر، تذكَّر تعديل قيمة STORAGE_BUCKET في ملف .env (في خطوة إعداد متغيّرات ENV).
- لإعداد إمكانية الوصول إلى الحزمة، انتقِل إلى وحدة تحكّم Cloud Storage وإلى حزمة التخزين (في هذه الحالة، اسم الحزمة هو next-demo-storage: https://console.cloud.google.com/storage/browser/next-demo-storage.
انتقِل إلى "الأذونات" -> عرض "المشرفين" -> منح إذن الوصول. اختَر "allUsers" كجهات أساسية و "مستخدم عنصر تخزين" كدور.
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- إنشاء قائمة بالتبعيات
أدرِج جميع التبعيات في requirements.txt. يمكنك نسخ هذا من repo.
شرح رمز المصدر لنظام الوكيل الفردي
يحدِّد ملف agent.py بنية نظام متعدّد العوامل لتجديد المطبخ وسلوكه باستخدام حزمة تطوير العوامل (ADK). لنطّلِع على المكونات الرئيسية:
تعريف الوكيل
الوكيل الجذر (المنسّق): proposal_agent
يعمل root_agent كمنسق لهذا النظام المكوّن من وكيل واحد. يتلقّى هذا الإجراء طلب التجديد الأولي ويحدّد الأدوات التي سيتمّ استدعاؤها استنادًا إلى احتياجات الطلب.
بعد ذلك، يجمع root_agent الردود من الأدوات ويجمعها لتقديم ردّ شامل للمستخدم. في هذه الحالة، لدينا أداة واحدة فقط هي "store_pdf".
7. تدفّق البيانات والمفاهيم الرئيسية
يبدأ المستخدم طلبًا من خلال واجهة ADK (إما المحطة الطرفية أو واجهة مستخدم الويب).
- يتلقّى root_agent الطلب.
- يحلِّل root_agent الطلب ويوجّهه إلى الأداة عند الحاجة.
- تم تصميم الأداة "store_pdf" لكتابة محتوى النص الذي تم تجديده في ملف PDF، ثم تحميله إلى Google Cloud Storage.
- يؤدي ذلك بعد ذلك إلى عرض الردّ على root_agent.
- يجمع root_agent الاستجابات ويقدّم نتيجة نهائية للمستخدم.
النماذج اللغوية الكبيرة (LLM)
يعتمد موظّفو الدعم بشكل كبير على نماذج اللغة الكبيرة لإنشاء النصوص والإجابة عن الأسئلة وتنفيذ مهام التفكير. إنّ النماذج اللغوية الكبيرة هي "العقل" الذي يقف وراء قدرة موظّفي الدعم على فهم طلبات المستخدمين والردّ عليها. نحن نستخدم الإصدار 2.5 من Gemini في هذا التطبيق.
Google Cloud Storage
تُستخدَم لتخزين مستندات اقتراحات التجديد التي تم إنشاؤها. عليك إنشاء حزمة ومنح موظّفي الدعم الأذونات اللازمة للوصول إليها.
Cloud Run (اختياري)
يستخدم OrderingAgent دالة Cloud Run للتواصل مع AlloyDB. توفّر Cloud Run بيئة بدون خادم لتنفيذ الرمز البرمجي استجابةً لطلبات HTTP.
AlloyDB
إذا كنت تستخدم OrderingAgent، ستحتاج إلى إعداد قاعدة بيانات AlloyDB لتخزين معلومات الطلبات.
ملف .env
يخزّن ملف .env معلومات حسّاسة، مثل مفاتيح واجهة برمجة التطبيقات وبيانات اعتماد قاعدة البيانات وأسماء الحِزم. من المهم الحفاظ على أمان هذا الملف وعدم إرساله إلى مستودعك. ويخزّن أيضًا إعدادات الضبط لموظّفي الدعم ومشروعك على Google Cloud. عادةً ما تقرأ الدالة root_agent أو الدوال الداعمة القيم من هذا الملف. تأكَّد من ضبط جميع المتغيّرات المطلوبة بشكل صحيح في ملف .env. ويشمل ذلك اسم حزمة Cloud Storage.
8. إعداد النموذج
تستند قدرة موظّف الدعم على فهم طلبات المستخدمين وإنشاء الردود إلى نموذج لغوي كبير (LLM). على موظّف الدعم إجراء مكالمات آمنة بخدمة LLM الخارجية هذه، ما يتطلّب بيانات اعتماد المصادقة. في حال عدم توفّر مصادقة صالحة، سترفض خدمة LLM طلبات الوكيل، ولن يتمكّن الوكيل من العمل.
- احصل على مفتاح واجهة برمجة التطبيقات من Google AI Studio.
- في الخطوة التالية التي يتم فيها إعداد ملف .env، استبدِل
<<your API KEY>>بقيمة مفتاح واجهة برمجة التطبيقات الفعلية.
9. إعداد متغيّرات ENV
- اضبط قيم المَعلمات في ملف .env للنموذج في هذا المستودع. في حالتي، يحتوي ملف .env على المتغيّرات التالية:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
استبدِل العناصر النائبة بقيمك.
10. تشغيل الوكيل
- باستخدام وحدة التحكّم الطرفي، انتقِل إلى الدليل الرئيسي لمشروع موظّف الدّعم:
cd agentic-apps/renovation-agent
- تثبيت جميع التبعيات
pip install -r requirements.txt
- يمكنك تنفيذ الأمر التالي في وحدة Cloud Shell الطرفية لتشغيل الوكيل:
adk run .
- يمكنك تنفيذ ما يلي لتشغيله في واجهة مستخدم ويب تم توفيرها من خلال ADK:
adk web
- يمكنك إجراء الاختبار باستخدام الطلبات التالية:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
11. النتيجة
بالنسبة إلى الأمر adk run . النتيجة هي كما يلي"
...
يمكنك التحقّق مما إذا تم إنشاء مستند "اقتراح التجديد" في حزمة التخزين في السحابة الإلكترونية.
12. تَنظيم
لتجنُّب تحصيل رسوم من حسابك على Google Cloud مقابل الموارد المستخدَمة في هذه المشاركة، اتّبِع الخطوات التالية:
- في وحدة تحكّم Google Cloud، انتقِل إلى صفحة إدارة الموارد.
- في قائمة المشاريع، اختَر المشروع الذي تريد حذفه، ثم انقر على حذف.
- في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على إيقاف لحذف المشروع.
13. تهانينا
تهانينا! لقد أنشأت تطبيقًا متعدّد موظّفي الدعم وتفاعلت معه باستخدام ADK. تم تصميم نظام الوكلاء المتعدّدين لتبسيط عملية تجديد المطبخ من خلال التشغيل الآلي للمهام، مثل إنشاء العروض وفحص التراخيص وتتبُّع حالة الطلبات. لكلّ وكيل دور محدّد، وينسّق root_agent أنشطتهم لتقديم حلّ شامل. يستفيد النظام من النماذج اللغوية الكبيرة وخدمات Google Cloud وواجهات برمجة التطبيقات الخارجية المحتملة لتقديم وظائفه. في ما يلي رابط يؤدي إلى مستندات المنتج.