إنشاء نظام متعدد الوكلاء

1. مقدمة

نظرة عامة

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

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

ستنشئ نظام إنشاء دورات تدريبية يتألف من:

  1. Researcher Agent: استخدام google_search للعثور على معلومات محدّثة
  2. الوكيل الحَكَم: ينتقد البحث من حيث الجودة والاكتمال.
  3. Content Builder Agent: تحويل البحث إلى دورة تدريبية منظَّمة
  4. وكيل التنسيق: إدارة سير العمل والتواصل بين هؤلاء المتخصصين

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

  • الإلمام بأساسيات لغة بايثون
  • الإلمام بوحدة تحكّم Google Cloud

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

  • حدِّد وكيلًا يستخدم أدوات (researcher) يمكنه البحث على الويب.
  • استخدِم الناتج المنظَّم مع Pydantic من أجل judge.
  • الاتصال بموظفي الدعم البعيدين باستخدام بروتوكول Agent-to-Agent (A2A)
  • أنشئ LoopAgent لإنشاء حلقة ملاحظات وآراء بين الباحث والحكم.
  • تشغيل النظام الموزّع محليًا باستخدام "حزمة تطوير التطبيقات" (ADK)
  • انشر النظام المتعدّد الوكلاء على Google Cloud Run.

مبادئ البنية والتنسيق

قبل كتابة الرمز، دعونا نتعرّف على كيفية عمل هؤلاء الوكلاء معًا. نحن بصدد إنشاء مسار إنشاء الدورات التدريبية.

تصميم النظام

مخطط الهندسة المعمارية

التنسيق باستخدام الوكلاء

تعمل الوكلاء العاديون (مثل "الباحث"). تتولّى وكلاء التنسيق (مثل LoopAgent أو SequentialAgent) إدارة الوكلاء الآخرين. ليس لديهم أدواتهم الخاصة، بل "أداتهم" هي التفويض.

  1. LoopAgent: تعمل هذه السمة مثل حلقة while في الرمز. يتم تشغيل سلسلة من الوكلاء بشكل متكرر إلى أن يتم استيفاء شرط معيّن (أو يتم الوصول إلى الحد الأقصى لعدد التكرارات). نستخدم هذه الميزة في حلقة البحث:
    • الباحث يعثر على المعلومات.
    • يقدم القاضي ملاحظات نقدية حولها.
    • إذا عرضت Judge الحالة "تعذّر"، ستسمح EscalationChecker باستمرار التكرار.
    • إذا قال Judge "اجتياز"، سيوقف EscalationChecker التكرار.
  2. ‫SequentialAgent: يعمل هذا الإجراء مثل تنفيذ نص برمجي عادي. يتم تشغيل البرامج الوكيلة واحدًا تلو الآخر. نستخدم هذه السمة في المخطط التفصيلي عالي المستوى:
    • أولاً، شغِّل حلقة البحث (إلى أن تنتهي ببيانات جيدة).
    • بعد ذلك، شغِّل أداة إنشاء المحتوى (لكتابة الدورة التدريبية).

ومن خلال الجمع بين هاتين الطريقتين، ننشئ نظامًا قويًا يمكنه تصحيح نفسه قبل إنشاء الناتج النهائي.

2. الإعداد

إعداد البيئة

فتح Cloud Shell: افتح علامة تبويب جديدة واكتب shell.cloud.google.com

الحصول على الرمز المُعد مسبقًا للمبتدئين

  1. أنشئ نسخة طبق الأصل من مستودع الرموز البرمجية الأولية في الدليل الرئيسي:
    cd ~
git clone https://github.com/amitkmaraj/prai-roadshow-lab-1-starter.git
cd prai-roadshow-lab-1-starter
  2. نفِّذ النص البرمجي init لربط أرصدة onramp بالفوترة.
    chmod +x ./init.sh
./init.sh
  3. افتح هذا المجلد في المحرِّر.

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

بعد إنشاء مشروع جديد، نفِّذ الأمر التالي لتفعيل خدمات Google Cloud اللازمة:

gcloud services enable \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com \
    compute.googleapis.com

قد تستغرق عملية المعالجة بضع ثوانٍ.

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

نستخدم uv لإدارة التبعيات بسرعة.

  1. ثبِّت تبعيات المشروع:
    # Ensure you have uv installed: pip install uv
uv sync
  2. اضبط معرّف مشروع Google Cloud.
    • ملاحظة: يمكنك العثور على رقم تعريف مشروعك في لوحة بيانات Cloud Console، أو من خلال تنفيذ gcloud config get-value project.
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
  3. اضبط متغيرات البيئة المتبقية:
    export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=true
    تحذير: لا يتم الاحتفاظ بمتغيرات البيئة في جلسات طرفية جديدة. إذا فتحت علامة تبويب جديدة في المحطة الطرفية، عليك إعادة تنفيذ أوامر التصدير هذه.

3- ‫🕵️ وكيل الباحث

وكيل الباحث

الباحث هو شخص متخصص. مهمتها الوحيدة هي العثور على المعلومات. ولإجراء ذلك، يحتاج إلى الوصول إلى أداة، وهي "بحث Google".

لماذا يجب فصل حساب الباحث؟

نظرة تفصيلية: لماذا لا يمكن أن يقوم وكيل واحد بكل المهام؟

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

  1. إذا كنت تعمل في Cloud Shell، نفِّذ الأمر التالي لفتح محرِّر Cloud Shell:
    cloudshell workspace .
    إذا كنت تعمل في بيئتك المحلية، افتح بيئة التطوير المتكاملة المفضّلة لديك.
  2. فتح "agents/researcher/agent.py"
  3. سيظهر لك هيكل عظمي مع قائمة مهام.
  4. أضِف الرمز التالي لتحديد researcher الوكيل:
    # ... existing imports ...

# Define the Researcher Agent
researcher = Agent(
    name="researcher",
    model=MODEL,
    description="Gathers information on a topic using Google Search.",
    instruction="""
    You are an expert researcher. Your goal is to find comprehensive and accurate information on the user's topic.
    Use the `google_search` tool to find relevant information.
    Summarize your findings clearly.
    If you receive feedback that your research is insufficient, use the feedback to refine your next search.
    """,
    tools=[google_search],
)

root_agent = researcher

المفهوم الأساسي: استخدام الأدوات

لاحظ أنّنا نمرّر tools=[google_search]. تتولّى حزمة تطوير التطبيقات (ADK) مهمة وصف هذه الأداة للنموذج اللغوي الكبير. عندما يقرر النموذج أنّه بحاجة إلى معلومات، ينشئ طلبًا منظَّمًا لاستخدام الأداة، وينفّذ ADK دالة Python google_search، ويُعيد النتيجة إلى النموذج.

4. ⚖️ وكيل القاضي

وكيل التقييم

يبذل "الباحث" جهدًا كبيرًا، ولكن يمكن أن تكون النماذج اللغوية الكبيرة كسولة. نحتاج إلى حكم لمراجعة العمل. يقبل "القاضي" البحث ويعرض تقييمًا منظَّمًا بنتيجة "اجتياز" أو "عدم اجتياز".

الناتج المنظَّم

نظرة تفصيلية: لأتمتة مهام سير العمل، نحتاج إلى مخرجات يمكن توقّعها. من الصعب تحليل مراجعة نصية طويلة بشكل آلي. من خلال فرض مخطط JSON (باستخدام Pydantic)، نضمن أن تعرض أداة Judge القيمة المنطقية pass أو fail التي يمكن أن يستند إليها الرمز البرمجي بشكل موثوق.

  1. فتح "agents/judge/agent.py"
  2. حدِّد مخطط JudgeFeedback والوكيل judge.
    # 1. Define the Schema
class JudgeFeedback(BaseModel):
    """Structured feedback from the Judge agent."""
    status: Literal["pass", "fail"] = Field(
        description="Whether the research is sufficient ('pass') or needs more work ('fail')."
    )
    feedback: str = Field(
        description="Detailed feedback on what is missing. If 'pass', a brief confirmation."
    )

# 2. Define the Agent
judge = Agent(
    name="judge",
    model=MODEL,
    description="Evaluates research findings for completeness and accuracy.",
    instruction="""
    You are a strict editor.
    Evaluate the 'research_findings' against the user's original request.
    If the findings are missing key info, return status='fail'.
    If they are comprehensive, return status='pass'.
    """,
    output_schema=JudgeFeedback,
    # Disallow delegation because it should only output the schema
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
)

root_agent = judge

المفهوم الأساسي: تقييد سلوك الوكيل

لقد ضبطنا disallow_transfer_to_parent=True وdisallow_transfer_to_peers=True. يفرض ذلك على القاضي فقط إرجاع JudgeFeedback المنظَّمة. ولا يمكنه اتّخاذ قرار "المحادثة" مع المستخدم أو تفويض وكيل آخر. وهذا يجعلها عنصرًا حتميًا في مسار المنطق.

5- ‫🧪 الاختبار في بيئة معزولة

قبل ربطها، يمكننا التأكّد من أنّ كل وكيل يعمل. تتيح لك "حزمة تطوير البرامج" تشغيل الوكلاء بشكل فردي.

المفهوم الأساسي: وقت التشغيل التفاعلي

تنشئ adk run بيئة بسيطة تكون فيها أنت "المستخدم". يتيح لك ذلك اختبار تعليمات الوكيل واستخدام الأدوات بشكل منفصل. إذا تعذّر على الوكيل تنفيذ هذه الخطوة (على سبيل المثال، إذا لم يتمكّن من استخدام "بحث Google")، سيتعذّر عليه بالتأكيد تنفيذ عملية التنسيق.

  1. تشغيل "الباحث" بشكل تفاعلي يُرجى العِلم أنّنا نشير إلى دليل الوكلاء المحدّد:
    # This runs the researcher agent in interactive mode
uv run adk run agents/researcher
  2. في طلب المحادثة، اكتب:
    Find the population of Tokyo in 2020
    يجب أن تستخدم الأداة "بحث Google" وتعرض الإجابة.ملاحظة: إذا ظهر لك خطأ يشير إلى عدم ضبط المشروع والموقع الجغرافي واستخدام Vertex، تأكَّد من ضبط رقم تعريف مشروعك ونفِّذ ما يلي:
    export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=true
  3. الخروج من المحادثة (Ctrl+C)
  4. تشغيل Judge بشكل تفاعلي:
    uv run adk run agents/judge
  5. في طلب المحادثة، حاكِ الإدخال:
    Topic: Tokyo. Findings: Tokyo is a city.
    يجب أن تعرض status='fail' لأنّ النتائج موجزة جدًا.

6. ✍️ "مُنشِئ المحتوى"

أداة إنشاء المحتوى

أداة إنشاء المحتوى هي الكاتب الإبداعي. يتم تحويل الأبحاث التي تمت الموافقة عليها إلى دورات تدريبية.

  1. فتح "agents/content_builder/agent.py"
  2. حدِّد وكيل content_builder.
    content_builder = Agent(
    name="content_builder",
    model=MODEL,
    description="Transforms research findings into a structured course.",
    instruction="""
    You are an expert course creator.
    Take the approved 'research_findings' and transform them into a well-structured, engaging course module.

    **Formatting Rules:**
    1. Start with a main title using a single `#` (H1).
    2. Use `##` (H2) for main section headings.
    3. Use bullet points and clear paragraphs.
    4. Maintain a professional but engaging tone.

    Ensure the content directly addresses the user's original request.
    """,
)
root_agent = content_builder

المفهوم الأساسي: نقل السياق

قد تتساءل: "كيف يعرف "منشئ المحتوى" ما عثر عليه "الباحث"؟" في حزمة تطوير التطبيقات (ADK)، تشترك الوكلاء في مسار معالجة في session.state. في وقت لاحق، سنضبط الباحث والحكم في Orchestrator لحفظ نواتجهما في هذه الحالة المشتركة. يمكن الوصول إلى هذا السجلّ من خلال طلب "أداة إنشاء المحتوى".

7. 🎻 المنظّم

وكيل التنسيق

المنسّق هو مدير فريقنا المتعدّد الوكلاء. على عكس الوكلاء المتخصّصين (الباحث، والحكم، وصانع المحتوى) الذين ينفّذون مهام محددة، تتمثل مهمة "المنسّق" في تنسيق سير العمل وضمان تدفّق المعلومات بشكل صحيح بين الوكلاء.

🌐 البنية: من وكيل إلى وكيل (A2A)

A2A Architecture

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

ولإتاحة ذلك، نستخدم بروتوكول Agent-to-Agent (A2A).

بروتوكول A2A

نظرة تفصيلية: في نظام الإنتاج، تعمل البرامج على خوادم مختلفة (أو حتى على سُحب مختلفة). يوفّر بروتوكول A2A طريقة موحّدة لاكتشاف الأجهزة والتواصل معها عبر HTTP. ‫RemoteA2aAgent هو عميل ADK لهذا البروتوكول.

  1. فتح "agents/orchestrator/agent.py"
  2. ابحث عن التعليق # TODO: Define Remote Agents أو القسم الخاص بتعريفات الوكيل البعيد.
  3. أضِف الرمز التالي لتحديد عمليات الربط. احرص على وضع هذا السطر بعد عمليات الاستيراد وقبل أي تعريفات أخرى للوكيل.
    # ... existing code ...

# Connect to the Researcher (Localhost port 8001)
researcher_url = os.environ.get("RESEARCHER_AGENT_CARD_URL", "http://localhost:8001/a2a/agent/.well-known/agent-card.json")
researcher = RemoteA2aAgent(
    name="researcher",
    agent_card=researcher_url,
    description="Gathers information using Google Search.",
    # IMPORTANT: Save the output to state for the Judge to see
    after_agent_callback=create_save_output_callback("research_findings"),
    # IMPORTANT: Use authenticated client for communication
    httpx_client=create_authenticated_client(researcher_url)
)

# Connect to the Judge (Localhost port 8002)
judge_url = os.environ.get("JUDGE_AGENT_CARD_URL", "http://localhost:8002/a2a/agent/.well-known/agent-card.json")
judge = RemoteA2aAgent(
    name="judge",
    agent_card=judge_url,
    description="Evaluates research.",
    after_agent_callback=create_save_output_callback("judge_feedback"),
    httpx_client=create_authenticated_client(judge_url)
)

# Content Builder (Localhost port 8003)
content_builder_url = os.environ.get("CONTENT_BUILDER_AGENT_CARD_URL", "http://localhost:8003/a2a/agent/.well-known/agent-card.json")
content_builder = RemoteA2aAgent(
    name="content_builder",
    agent_card=content_builder_url,
    description="Builds the course.",
    httpx_client=create_authenticated_client(content_builder_url)
)

8. 🛑 أداة التحقّق من حالة التصعيد

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

المنطق المخصّص باستخدام BaseAgent

نظرة تفصيلية: لا يستخدم جميع موظّفي الدعم نماذج اللغات الكبيرة. في بعض الأحيان، تحتاج إلى منطق بسيط في Python. تتيح لك BaseAgent تحديد وكيل ينفّذ الرمز فقط. في هذه الحالة، نتحقّق من حالة الجلسة ونستخدم EventActions(escalate=True) للإشارة إلى LoopAgent بالتوقّف.

  1. لا يزال في agents/orchestrator/agent.py.
  2. ابحث عن العنصر النائب EscalationChecker TODO.
  3. استبدِلها بالتنفيذ التالي:
    class EscalationChecker(BaseAgent):
    """Checks the judge's feedback and escalates (breaks the loop) if it passed."""

    async def _run_async_impl(
        self, ctx: InvocationContext
    ) -> AsyncGenerator[Event, None]:
        # Retrieve the feedback saved by the Judge
        feedback = ctx.session.state.get("judge_feedback")
        print(f"[EscalationChecker] Feedback: {feedback}")

        # Check for 'pass' status
        is_pass = False
        if isinstance(feedback, dict) and feedback.get("status") == "pass":
            is_pass = True
        # Handle string fallback if JSON parsing failed
        elif isinstance(feedback, str) and '"status": "pass"' in feedback:
            is_pass = True

        if is_pass:
            # 'escalate=True' tells the parent LoopAgent to stop looping
            yield Event(author=self.name, actions=EventActions(escalate=True))
        else:
            # Continue the loop
            yield Event(author=self.name)

escalation_checker = EscalationChecker(name="escalation_checker")

المفهوم الأساسي: التحكّم في تدفّق البيانات من خلال الأحداث

لا تتواصل البرامج مع المستخدمين من خلال النصوص فقط، بل من خلال الأحداث. من خلال إرسال حدث باستخدام escalate=True، يرسل هذا العنصر إشارة إلى العنصر الرئيسي (LoopAgent). تمت برمجة LoopAgent لتلقّي هذه الإشارة وإنهاء الحلقة.

9- 🔁 حلقة البحث

Research Loop

نحتاج إلى حلقة ملاحظات: البحث -> التقييم -> (فشل) -> البحث -> ...

  1. لا يزال في agents/orchestrator/agent.py.
  2. أضِف تعريف research_loop. ضَع هذا بعد الفئة EscalationChecker والمثيل escalation_checker.
    research_loop = LoopAgent(
    name="research_loop",
    description="Iteratively researches and judges until quality standards are met.",
    sub_agents=[researcher, judge, escalation_checker],
    max_iterations=3,
)

المفهوم الأساسي: LoopAgent

يتنقّل LoopAgent بين sub_agents بالترتيب.

  1. ‫researcher: للبحث عن البيانات
  2. ‫judge: لتقييم البيانات.
  3. escalation_checker: تحدّد ما إذا كان سيتم yield Event(escalate=True). في حال حدوث escalate=True، يتم إيقاف التكرار مبكرًا. بخلاف ذلك، تتم إعادة التشغيل عند الباحث (بحد أقصى max_iterations).

10. 🔗 المسار النهائي

مسار الإحالة الناجحة النهائي

أخيرًا، اجمع كل ذلك معًا.

  1. لا يزال في agents/orchestrator/agent.py.
  2. حدِّد root_agent في أسفل الملف. تأكَّد من أنّ هذا العنصر النائب يحلّ محلّ أي عنصر نائب حالي root_agent = None.
    root_agent = SequentialAgent(
    name="course_creation_pipeline",
    description="A pipeline that researches a topic and then builds a course from it.",
    sub_agents=[research_loop, content_builder],
)

المفهوم الأساسي: التركيب الهرمي

يُرجى العِلم أنّ research_loop هو نفسه وكيل (LoopAgent)، ونعامله مثل أي وكيل فرعي آخر في SequentialAgent. تتيح لك إمكانية التركيب هذه إنشاء منطق معقّد من خلال دمج أنماط بسيطة (حلقات داخل تسلسلات، وتسلسلات داخل موجّهات، وما إلى ذلك).

11. 💻 التشغيل محليًا

قبل تشغيل كل شيء، دعونا نلقي نظرة على كيفية محاكاة ADK للبيئة الموزّعة محليًا.

نظرة متعمّقة: طريقة عمل التطوير المحلي

في بنية الخدمات المصغّرة، يعمل كل وكيل كخادم مستقل. عند النشر، سيكون لديك 4 خدمات مختلفة على Cloud Run. يمكن أن تكون محاكاة ذلك محليًا أمرًا صعبًا إذا كان عليك فتح 4 علامات تبويب في الوحدة الطرفية وتنفيذ 4 أوامر.

يبدأ هذا النص البرمجي uvicorn عملية لكل من Researcher (المنفذ 8001) وJudge (المنفذ 8002) وContent Builder (المنفذ 8003). يضبط هذا البرنامج متغيّرات البيئة، مثل RESEARCHER_AGENT_CARD_URL، ويمررها إلى Orchestrator (المنفذ 8004). هذه هي الطريقة التي سنضبط بها الإعدادات في السحابة الإلكترونية لاحقًا.

التطبيق قيد التشغيل

  1. شغِّل نص التنسيق البرمجي:
    ./run_local.sh
    يبدأ هذا الإجراء 4 عمليات منفصلة.
  2. اختبارها:
    • في حال استخدام Cloud Shell: انقر على الزر معاينة الويب (أعلى يسار نافذة الوحدة الطرفية) -> المعاينة على المنفذ 8080 -> تغيير المنفذ إلى 8000.
    • في حال التشغيل محليًا: افتح http://localhost:8000 في المتصفّح.
    • الطلب: "أنشئ دورة تدريبية حول تاريخ القهوة".
    • المراقبة: سيتصل Orchestrator بـ Researcher. يتم إرسال الناتج إلى "القاضي". إذا لم ينجح القاضي في ذلك، تستمر الحلقة.
    تحديد المشاكل وحلّها:
    • "خطأ في الخادم الداخلي" / أخطاء المصادقة: إذا ظهرت لك أخطاء في المصادقة (مثل الأخطاء المتعلقة بـ google-auth)، تأكَّد من تنفيذ gcloud auth application-default login إذا كنت تستخدم جهازًا محليًا. في Cloud Shell، تأكَّد من ضبط متغيّر البيئة GOOGLE_CLOUD_PROJECT بشكلٍ صحيح.
    • أخطاء في نافذة Terminal: إذا تعذّر تنفيذ الأمر في نافذة Terminal جديدة، تذكَّر إعادة تصدير متغيّرات البيئة (GOOGLE_CLOUD_PROJECT وما إلى ذلك).
  3. اختبار الوكلاء بشكل منفصل: حتى عند تشغيل النظام الكامل، يمكنك اختبار وكلاء محدّدين من خلال استهداف منافذهم مباشرةً. ويفيد ذلك في تصحيح خطأ في مكوّن معيّن بدون تشغيل السلسلة بأكملها.
    • الباحثون فقط (المنفذ 8001): http://localhost:8001
    • التقييم فقط (المنفذ 8002): http://localhost:8002
    • أداة إنشاء المحتوى فقط (المنفذ 8003): http://localhost:8003
    • المنسّق (المنفذ 8004): http://localhost:8004 (الوصول المباشر إلى منطق المنسّق)

12. 🚀 النشر على Cloud Run

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

التعرّف على إعدادات النشر

عند نشر وكلاء في Cloud Run، نمرّر العديد من متغيرات البيئة لضبط سلوكهم واتصالهم:

  • GOOGLE_CLOUD_PROJECT: يضمن هذا الخيار أنّ الوكيل يستخدم مشروع Google Cloud الصحيح لتسجيل البيانات وإجراء طلبات إلى Vertex AI.
  • GOOGLE_GENAI_USE_VERTEXAI: يطلب من إطار عمل الوكيل (ADK) استخدام Vertex AI لاستنتاج النموذج بدلاً من استدعاء واجهات Gemini API مباشرةً.
  • ‫[AGENT]_AGENT_CARD_URL: هذا الإعداد مهم جدًا لخدمة Orchestrator. يخبر هذا الملف أداة Orchestrator بمكان العثور على الوكلاء عن بُعد. من خلال ضبط هذه القيمة على عنوان URL الذي تم نشره في Cloud Run (وتحديدًا مسار بطاقة الوكيل)، نتيح لخدمة Orchestrator إمكانية العثور على Researcher وJudge وContent Builder والتواصل معها عبر الإنترنت.
  1. نشر تطبيق Researcher:
    gcloud run deploy researcher \
  --source agents/researcher/ \
  --region us-central1 \
  --allow-unauthenticated \
  --labels dev-tutorial=prod-ready-1 \
  --set-env-vars GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI="true"
    تسجيل عنوان URL:
    RESEARCHER_URL=$(gcloud run services describe researcher --region us-central1 --format='value(status.url)')
echo $RESEARCHER_URL
  2. نشر Judge:
    gcloud run deploy judge \
  --source agents/judge/ \
  --region us-central1 \
  --allow-unauthenticated \
  --labels dev-tutorial=prod-ready-1 \
  --set-env-vars GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI="true"
    تسجيل عنوان URL:
    JUDGE_URL=$(gcloud run services describe judge --region us-central1 --format='value(status.url)')
echo $JUDGE_URL
  3. نشر "أداة إنشاء المحتوى":
    gcloud run deploy content-builder \
  --source agents/content_builder/ \
  --region us-central1 \
  --allow-unauthenticated \
  --labels dev-tutorial=prod-ready-1 \
  --set-env-vars GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI="true"
    تسجيل عنوان URL:
    CONTENT_BUILDER_URL=$(gcloud run services describe content-builder --region us-central1 --format='value(status.url)')
echo $CONTENT_BUILDER_URL
  4. نشر Orchestrator: استخدِم متغيرات البيئة التي تم الحصول عليها لضبط Orchestrator.
    gcloud run deploy orchestrator \
  --source agents/orchestrator/ \
  --region us-central1 \
  --allow-unauthenticated \
  --labels dev-tutorial=prod-ready-1 \
  --set-env-vars RESEARCHER_AGENT_CARD_URL=$RESEARCHER_URL/a2a/agent/.well-known/agent-card.json \
  --set-env-vars JUDGE_AGENT_CARD_URL=$JUDGE_URL/a2a/agent/.well-known/agent-card.json \
  --set-env-vars CONTENT_BUILDER_AGENT_CARD_URL=$CONTENT_BUILDER_URL/a2a/agent/.well-known/agent-card.json \
  --set-env-vars GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT \
  --set-env-vars GOOGLE_GENAI_USE_VERTEXAI="true"
    تسجيل عنوان URL:
    ORCHESTRATOR_URL=$(gcloud run services describe orchestrator --region us-central1 --format='value(status.url)')
echo $ORCHESTRATOR_URL
  5. نشر الواجهة الأمامية:
    gcloud run deploy course-creator \
    --source app \
    --region us-central1 \
    --allow-unauthenticated \
    --labels dev-tutorial=prod-ready-1 \
    --set-env-vars AGENT_SERVER_URL=$ORCHESTRATOR_URL \
    --set-env-vars GOOGLE_CLOUD_PROJECT=$GOOGLE_CLOUD_PROJECT
  6. اختبار النشر عن بُعد: افتح عنوان URL الخاص بـ Orchestrator الذي تم نشره. تعمل هذه الخدمة الآن بالكامل على السحابة الإلكترونية، وتستفيد من البنية الأساسية بدون خادم من Google لتوسيع نطاق عملائك.تلميح: ستجد جميع الخدمات المصغّرة وعناوين URL الخاصة بها في واجهة Cloud Run.

13. ملخّص

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

إنجازاتنا

  • تقسيم مهمة معقّدة: بدلاً من طلب واحد كبير، قسّمنا العمل إلى أدوار متخصّصة (باحث، وحكم، ومنشئ محتوى).
  • تنفيذ مراقبة الجودة: استخدمنا LoopAgent وJudge منظَّمًا لضمان وصول المعلومات العالية الجودة فقط إلى الخطوة النهائية.
  • مصمَّم للإنتاج: باستخدام بروتوكول التواصل بين الوكلاء (A2A) وCloud Run، أنشأنا نظامًا يكون فيه كل وكيل عبارة عن خدمة مصغّرة مستقلة وقابلة للتوسيع. وهذا أكثر فعالية من تنفيذ كل شيء في نص برمجي واحد بلغة Python.
  • التنسيق: استخدمنا SequentialAgent وLoopAgent لتحديد أنماط واضحة لسير التحكّم.

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

بعد أن أصبحت لديك الأساسيات، يمكنك توسيع نطاق هذا النظام باتّباع الخطوات التالية:

  • إضافة المزيد من الأدوات: يمكنك منح الباحث إذن الوصول إلى المستندات الداخلية أو واجهات برمجة التطبيقات.
  • تحسين أداة Judge: أضِف معايير أكثر تحديدًا أو حتى خطوة "مراجعة بشرية".
  • تبديل النماذج: جرِّب استخدام نماذج مختلفة لوكلاء مختلفين (على سبيل المثال، نموذج أسرع لـ "القاضي"، ونموذج أقوى لـ "كاتب المحتوى").

أنت الآن جاهز لإنشاء عمليات سير عمل معقّدة وموثوقة مستندة إلى وكلاء على Google Cloud.