من النماذج الأولية إلى موظّفي الدعم باستخدام ADK

1. نظرة عامة

من أين تبدأ عملية إنشاء التطبيقات باستخدام الذكاء الاصطناعي اليوم؟ بالنسبة إلى معظمنا، غالبًا ما تبدأ العملية بسؤال بسيط: "هل يمكن للنموذج أن يساعد في حلّ هذه المشكلة التي كنت أفكر فيها؟". وهذا هو بالضبط دور Google AI Studio. إنّها مساحة يمكنك فيها إنشاء نماذج أولية لأي شيء بسرعة. أريد إعادة تصميم مطبخي وأعتقد أنّ Gemini يمكنه مساعدتي في ذلك، ولكنّني مهندس ولست مقاولًا عامًا. لا أعرف حتى ما يجب أن أطلبه، فهناك الكثير من الأمور التي يجب أخذها في الاعتبار، مثل اللوائح والتجهيزات وما إلى ذلك. لنقسّم هذه المهمة ونطلب من Gemini إنشاء طلب مفصّل للغاية، ثم إنشاء خطة تجديد كاملة وتصوّر عملية إعادة التصميم. ولكن مهلاً. كيف يمكنني مساعدة المؤسسات في توسيع نطاق أعمالها؟ أدخِل AGENTS!!!

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

حزمة تطوير الوكلاء (ADK)

حزمة تطوير الوكلاء (ADK) هي إطار عمل مرن ونمطي لتطوير وكلاء الذكاء الاصطناعي وتفعيلهم. تتيح "حزمة تطوير الوكلاء" إنشاء تطبيقات متطورة من خلال دمج عدة مثيلات وكلاء مميزة في نظام متعدد الوكلاء (MAS).

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

ما ستنشئه

هل أنت مستعد للانتقال من النموذج الأوّلي PROMPT إلى إنشاء وكيل؟ سننشئ وكيلاً للمساعدة في إنشاء مستند الاقتراح الخاص بمشروع تجديد المطبخ. في هذا الدرس التطبيقي، ستنفّذ ما يلي:

إنشاء وكيل بسيط لإنشاء مستند اقتراح تجديد باستخدام ADK
تخزين "مستند اقتراح التجديد" الذي تم إنشاؤه في حزمة Cloud Storage
اختبار الوكيل في Cloud Shell وفي ناتج الويب الخاص بالوكيل

المتطلبات

متصفّح، مثل Chrome أو Firefox
مشروع Google Cloud تم تفعيل الفوترة فيه

2. قبل البدء

إنشاء مشروع

في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر مشروعًا على Google 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.

أرفِق صورة لمطبخك الحالي (أو يمكنك استخدام صورة المطبخ النموذجية).
غيِّر النموذج إلى "Gemini 2.0 Flash Preview Image Generation" لتتمكّن من إنشاء الصور.

حصلت على الناتج التالي:

هذه هي قوة Gemini.

من فهم الفيديوهات إلى إنشاء الصور بشكلٍ أصلي إلى ربط المعلومات الحقيقية بـ "بحث Google"، هناك ميزات لا يمكن إنشاؤها إلا باستخدام Gemini.

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

4. إعداد ADK

لننتقل الآن إلى وحدة طرفية Cloud Shell التي فعّلناها في قسم "قبل البدء":

إنشاء بيئة افتراضية وتفعيلها (يُنصح به)

من Cloud Shell Terminal، أنشئ بيئة افتراضية:

python -m venv .venv

تفعيل البيئة الافتراضية:

source .venv/bin/activate

تثبيت "حزمة تطوير التطبيقات"

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 وعدِّل الملف باستخدام المحتوى التالي من المسار التالي:

في ملف agent.py، نستورد التبعيات اللازمة، ونسترجع مَعلمات الإعداد من ملف ‎ .env، ونحدّد root_agent الذي ينشئ مستند اقتراح ويخزّنه في حزمة Cloud Storage. لتنفيذ خطوة Cloud Storage، نستخدم أداة تُسمى store_pdf.

ملاحظة: ملف PDF غير منسَّق حاليًا. استنادًا إلى طلب السحب الذي قدّمه فريق تطوير المنتدى، تم تضمين المقتطف التالي هنا [لم يتم اختباره]، ويمكنك تعديله في طريقة store_pdf:

doc = SimpleDocTemplate(
        pdf_buffer,
        pagesize=letter,
        rightMargin=0.75 * inch,
        leftMargin=0.75 * inch,
        topMargin=0.75 * inch,
        bottomMargin=0.75 * inch
    )

    styles = getSampleStyleSheet()
    story = []

    # --- CUSTOM STYLES FOR HEADERS ---
    # Define a new style for section headers
    styles.add(ParagraphStyle(name='SectionHeader',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold', # Make it bolder
                              fontSize=14,               # Make it slightly larger
                              leading=16,                # Line spacing
                              spaceAfter=0.15 * inch,    # Space after the header
                              spaceBefore=0.25 * inch,   # Space before the header
                              textColor=black            # Ensure color is bright/black (default is usually black, but explicit is good)
                             ))

    # Define a style for the main document title
    styles.add(ParagraphStyle(name='DocumentTitle',
                              parent=styles['Normal'],
                              fontName='Helvetica-Bold',
                              fontSize=20,
                              leading=24,
                              spaceAfter=0.25 * inch,
                              alignment=TA_CENTER, # Center align the title
                              textColor=black
                             ))
    # ---------------------------------

    paragraphs_raw = pdf_text.split('\n\n')

    # Heuristic for the garbled line issue (as before, temporary)
    if paragraphs_raw and len(paragraphs_raw[-1]) < 50 and any(char in paragraphs_raw[-1] for char in ['io', 'og', 'al', 'op']):
         logger.warning("Detected potentially garbled last paragraph. Attempting to trim/omit.")
         paragraphs_raw[-1] = "11. Entire Agreement:\nThis proposal constitutes the entire agreement between the parties and supersedes all prior discussions and agreements."


    for i, para_text in enumerate(paragraphs_raw):
        para_text = para_text.strip()
        if not para_text:
            continue

        # Special handling for the main document title (PROPOSAL DOCUMENT)
        if i == 0 and "PROPOSAL DOCUMENT" in para_text.upper():
            p = Paragraph("PROPOSAL DOCUMENT", styles['DocumentTitle'])
            story.append(p)
            story.append(Spacer(1, 0.15 * inch)) # Add space after the title
            # Skip the rest of this initial block if it's just the title
            remaining_text_lines = para_text.splitlines()[1:]
            if remaining_text_lines:
                formatted_text = "<br/>".join(remaining_text_lines)
                p = Paragraph(formatted_text, styles['Normal'])
                story.append(p)
                story.append(Spacer(1, 0.1 * inch))
            continue # Move to the next paragraph

        # Check if the paragraph looks like a section header (e.g., starts with a number and dot or just bold text)
        # This is a heuristic and might need fine-tuning based on actual proposal content variability.
        is_section_header = False
        # Check for numbered sections (e.g., "1. Scope of Work:")
        if para_text.startswith(('1.', '2.', '3.', '4.', '5.', '6.', '7.', '8.', '9.', '10.', '11.')):
            is_section_header = True
        # Check for Exhibit headers (e.g., "Exhibit A: Cabinet Design") or Roman numeral headings
        elif para_text.startswith(('Exhibit ', 'I.', 'II.', 'III.', 'IV.', 'V.', 'VI.', 'VII.')):
            is_section_header = True
        # Check for specific known headers
        elif para_text.strip().upper() in ["IN WITNESS WHEREOF,", "EXHIBITS:"]:
            is_section_header = True


        if is_section_header:
            p = Paragraph(para_text, styles['SectionHeader'])
            story.append(p)
            # No additional Spacer here, as SectionHeader style has spaceAfter
        else:
            formatted_text = para_text.replace('\n', '<br/>')
            p = Paragraph(formatted_text, styles['Normal'])
            story.append(p)
            story.append(Spacer(1, 0.1 * inch)) # Standard space after body paragraphs

    doc.build(story)

    pdf_buffer.seek(0)

    # Upload the PDF to GCS
    storage_client = storage.Client()
    bucket = storage_client.bucket(STORAGE_BUCKET)
    blob = bucket.blob(PROPOSAL_DOCUMENT_FILE_NAME)

    blob.upload_from_file(pdf_buffer, content_type="application/pdf")

    logger.info(f"Successfully uploaded PDF to gs://{STORAGE_BUCKET}/{PROPOSAL_DOCUMENT_FILE_NAME}")

except Exception as e:
    logger.error(f"Error writing text to PDF and uploading: {e}")
    raise
finally:
    if 'pdf_buffer' in locals():
        pdf_buffer.close()
return "Successfully uploaded PDF to GCS!!"

تأكَّد من توفّر حزمة Cloud Storage

يُستخدم هذا الحقل لتخزين مستند الاقتراح الذي ينشئه الوكيل. أنشئها واضبط إذن الوصول إليها حتى يتمكّن النظام المستند إلى الوكلاء الذي ننشئه باستخدام Vertex AI من الوصول إليها. إليك كيفية إجراء ذلك:

https://cloud.google.com/storage/docs/creating-buckets#console

أدخِل اسم الحزمة "next-demo-store". إذا اخترت اسمًا آخر، تذكَّر تعديل قيمة STORAGE_BUCKET في ملف ‎ .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. يمكنك نسخ هذا الرمز من المستودع.

شرح الرمز البرمجي لمصدر النظام الخاص بالوكيل الفردي

يحدّد ملف 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 الردود ويقدّم ناتجًا نهائيًا للمستخدم.

النماذج اللغوية الكبيرة (LLMs)

تعتمد البرامج الآلية بشكل كبير على النماذج اللغوية الكبيرة لإنشاء النصوص والإجابة عن الأسئلة وتنفيذ مهام الاستدلال. تشكّل النماذج اللغوية الكبيرة "العقول" التي تتيح للوكلاء فهم طلبات المستخدمين والردّ عليها. نستخدم Gemini 2.5 في هذا التطبيق.

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 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. النشر على Cloud Run

أنشئ ملفًا باسم Dockerfile داخل مجلد جذر المشروع:

cd agentic-apps/renovation-agent

نسخ المحتوى من مستودع GitHub

https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/Dockerfile

في ملف Dockerfile هذا.

يمكنك النشر على Cloud Run باستخدام الأمر التالي:

adk deploy cloud_run --project=abis-345004 --region=us-central1 --service_name=renovation-agent --app_name=renovation-app --with_ui .

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

13. تَنظيم

لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذه المشاركة، اتّبِع الخطوات التالية:

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

14. تهانينا

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