سير عمل الذكاء الاصطناعي الوكيل باستخدام "حزمة تطوير الوكلاء" (ADK)

1. مقدمة

VibeStudio

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

السيناريو

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

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

سير العمل الذي تنشئه، بدءًا من فكرة إلى مقطع منشور

ما ستتعلمه

10-summary

  • أسس هندسة الرسوم البيانية: تتطلّب بُنى الوكلاء المتعدّدة الخطوات تدفق تحكّم واضحًا ومسارات تنفيذ منظَّمة. يمكنك إنشاء Workflow في ADK باستخدام صفوف الحواف، ونقطة الدخول START، وJoinNode للتجميع المتوازي، وعُقد التوجيه الحتمية لتوجيه التنفيذ استنادًا إلى الحالة.
  • أوضاع الوكيل وعمليات معاودة الاتصال بدورة الحياة: تتطلّب المهام المتخصّصة سلوكيات تشغيلية مميّزة وضوابط حتمية. يمكنك ضبط مثيلات ADK Agent باستخدام أوضاع chat وsingle_turn وtask المزوّدة بالأدوات كعُقد لسير العمل، وتطبيق أدوات الاعتراض باستخدام before_model_callback وafter_agent_callback.
  • التنسيق مع الإشراف البشري: يتم إيقاف خطوط الإنتاج مؤقتًا للحصول على حكم بشري عند نقاط التحقّق الإبداعية المهمة. يمكنك تنفيذ RequestInput لتعليق تنفيذ سير العمل، وفرض مخططات الاستجابة المنظَّمة، واستئناف التنفيذ بدون إبقاء عمليات وقت التشغيل غير النشطة قيد التشغيل.
  • ذاكرة الوكيل الهرمية: تفصل أنظمة الإنتاج حالة التنفيذ المؤقتة عن السياق الدائم. يمكنك إدارة حالة الجلسة القصيرة الأمد باستخدام Event(state=...) وربط المَعلمات، وربط "بنك الذاكرة" في GEAP لاستخراج إعدادات صنّاع المحتوى المفضّلة وتوحيدها والاحتفاظ بها في جميع عمليات التشغيل.
  • التحقّق من المصادر باستخدام قواعد المعرفة الخاصة بالمؤسسات: يحتاج الوكلاء المستقلون إلى سياق ديناميكي للنطاق ومعرفة آراء الجمهور. يمكنك ربط مجموعة نصوص GEAP RAG Engine كعقدة استرجاع مخصّصة ضمن التوزيع الموسّع المتوازي لتحديد مصدر مخرجات الوكيل من الناحية الدلالية.
  • سير العمل والنشر على المدى الطويل: تعمل ميزة عرض الفيديوهات المتعدّدة الوسائط بشكل غير متزامن على مدار فترات طويلة. يمكنك تنفيذ LongRunningFunctionTool مع إيصالات المكالمات في انتظار المراجعة لتعليق سير العمل واستئنافه حسب رقم تعريف المكالمة، ونشر المسار النهائي باستخدام ADK Runner على Cloud Run.

طريقة تنظيم هذا الدرس التطبيقي حول الترميز

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

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

بعد إكمال تمارين Workbench، ستتمكّن من تجميع مسار آلي شامل قائم على الوكلاء ونشر تطبيق VibeStudio قيد التشغيل على Cloud Run لإنشاء محتوى فيديو.

ما يتم تشغيله وأين: VibeStudio Workbench، والواجهة الخلفية، وخدمات Google Cloud

تتكوّن البيئة من ثلاثة مكوّنات أساسية: VibeStudio Workbench (واجهة الويب المحلية لتعديل الرموز والتحقّق من وقت التشغيل)، والواجهة الخلفية (حزمة ADK Workflow والبيئات التجريبية في agent/)، وGoogle Cloud (نماذج Gemini وGEAP Memory Bank وRAG Engine وإنشاء فيديوهات Veo).

2. الإعداد

كيفية الحصول على أرصدة ورش العمل

إذا كنت تحضر معملًا موجَّهًا من المعلّم، سيوزّع المعلّم أرصدة لمشروعك على Google Cloud. اتّبِع تعليمات المعلّم لتحصيل قيمة الأرصدة والتأكّد من أنّ الفوترة مفعّلة في حسابك قبل المتابعة.

فتح Cloud Shell

‫Cloud Shell هي بيئة تطوير مستندة إلى المتصفّح ومثبَّتة مسبقًا مع gcloud وPython وgit.

لتشغيل Cloud Shell:

  1. انتقِل إلى Google Cloud Shell.

تُفتح جلسة محطة طرفية في أسفل نافذة المتصفّح.

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

نفِّذ الأوامر التالية في وحدة Cloud Shell الطرفية لنسخ المشروع:

git clone https://github.com/gca-americas/vibetube-studio
cd ~/vibetube-studio

طلبات الإعداد

أثناء عملية الإعداد، سيُطلب منك تقديم التفاصيل التالية:

  • معرّف مشروع Google Cloud: عندما يطلب منك setup_project.sh ذلك، اضغط على Enter لإنشاء مشروع جديد تلقائيًا. إذا كنت تفضّل استخدام مشروع حالي (مثل مشروع تم تعيينه مسبقًا)، أدخِل رقم تعريف مشروعك وتأكَّد من صحة الإملاء مع تفعيل الفوترة.
  • رمز الحدث: أدخِل رمز الغرفة الذي قدّمه لك المعلّم. إذا لم تتلقَ واحدة، فراجع مساعد التدريس أو أحد الجيران. إذا كنت تُكمل هذا الدرس التطبيقي في المنزل، اضغط على Enter لقبول غرفة sandbox التلقائية.
  • الاسم المعروض للقناة: أدخِل اسمك أو الاسم المعرِّف المفضّل للقناة عندما يطلب منك setup_codelab.sh ذلك، أو اضغط على Enter لقبول الاسم التلقائي الذي تم إنشاؤه من حسابك على Google.

شغِّل نصَّي التهيئة البرمجيَّين بالترتيب:

./setup_project.sh
./setup_codelab.sh
  • setup_project.sh: لإنشاء مشروع Google Cloud أو إعادة استخدامه مع تفعيل الفوترة، وحفظ معرّف المشروع في ~/project_id.txt، وإعداد سياق gcloud النشط
  • setup_codelab.sh: يثبّت uv وتبعيات Python في .venv، ويفعّل واجهات برمجة تطبيقات Google Cloud المطلوبة، ويضبط إعدادات قناتك في .env، ويتحقّق من إمكانية الوصول إلى النموذج باستخدام Gemini، ويوفّر موارد Memory Bank وRAG، وينشئ واجهة workbench، ويبدأ VibeStudio Workbench.

ينفّذ النص البرمجي عملية التحقّق قبل التشغيل ويبدأ تشغيل VibeStudio Workbench في الخلفية. وتعرض الأسطر الأخيرة الرابط الذي سيتم فتحه.

7 · Preflight
  ✓ python 3.12
  ✓ auth path A: Vertex via ADC (STUDIO_VERTEX=1)
  ✓ Google Cloud ADC (project <your-project>)
  ✓ stage0_prompt loads
  ...
  ✓ stage6_video loads (13 edges)
  ✓ aiplatform.googleapis.com enabled (Gemini, Veo, Memory Bank, RAG Engine)
  ✓ vectorsearch.googleapis.com enabled (the vector store a RAG corpus is built on)
  ✓ Memory Bank connected
  ✓ RAG corpus connected
  ✓ VibeStudio Workbench running on port 4600

PREFLIGHT GREEN

Setup finished. The VibeStudio Workbench is already running.

  Open this and start at step 1
      https://4600-<your cloud shell host>/step/story

  It runs in the background. You do not need to start anything else.
      log      runs/lab.log
      stop     kill $(cat runs/lab.pid)
      start    scripts/start.sh

انقر على هذا الرابط. يتوفّر العنوان نفسه ضمن معاينة الويب (Web Preview) ← تغيير المنفذ (Change port) ← 4600.

لإعادة التحقّق من البيئة في أي وقت، شغِّل python scripts/preflight.py. لإعادة تشغيل workbench، شغِّل scripts/restart.sh. لإعادة الإعداد، شغِّل ./setup_codelab.sh، وسيتم الاحتفاظ بالإعدادات ومستوى التقدّم.

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

ينتهي كل جزء عملي من VibeStudio Workbench بلوحة تحقّق تعرض العناصر الحقيقية: الملف على القرص والجلسات التي تم إنشاؤها بواسطة عمليات التشغيل.

تنسيق المستودع

تم تنظيم المستودع في منطق سير العمل الأساسي، وبيئات الاختبار التفصيلية، وبيئة workbench، وتطبيق الإنتاج:

vibe-studio-lab/
├── agent/                  # Core ADK workflow, graph definition, and platform services
│   ├── graph.py            # Workflow graph definition, node functions, and routers
│   ├── desk.py             # Video render desk using LongRunningFunctionTool
│   ├── schemas.py          # Pydantic schemas for directions, gates, and scripts
│   ├── trends.py           # Trend generation and sampling utilities
│   ├── backlog.txt         # Creator video ideas backlog
│   ├── comments.md         # Audience comments for RAG Engine corpus seeding
│   ├── policy_words.txt    # Blocked subject words for deterministic policy checks
│   └── platform/           # Google Cloud service clients (Memory Bank, RAG, Veo)
│       ├── config.py       # Environment variables, locations, and model configurations
│       ├── memory.py       # GEAP Memory Bank callbacks and context injection
│       ├── rag.py          # GEAP RAG Engine corpus creation and semantic retrieval
│       └── videogen.py     # Veo video generation and operation polling
├── stage0_prompt/          # Step sandboxes: isolated agent.py files runnable in adk web
│   └── ...                 # stage1_fanout through stage6_video for incremental steps
├── server/ & web/          # VibeStudio Workbench (FastAPI backend and React frontend)
├── vibestudio/             # Complete production application deployed to Cloud Run
│   ├── server/             # FastAPI production server and event runner
│   ├── web/                # End-user React web application
  • agent/: يحتوي على الرسم البياني الأساسي لسير العمل. ستعدّل الملفات في هذا الدليل لتنفيذ عُقد التوزيع المتوازي، وتوجيه السياسات الحتمية، وعمليات معاودة الاتصال بالذاكرة، وأدوات إنشاء الفيديو.
  • ‫agent/platform/: تتفاعل مع خدمات Google Cloud، بما في ذلك نماذج Gemini و"بنك ذاكرة" GEAP و"محرك التوليد المعزّز بالاسترجاع" GEAP وتركيب الفيديو في Veo.
  • stage0_prompt/ من خلال stage6_video/: بيئات وضع الحماية المستقلة يصدّر كل مجلد root_agent مستقلاً، ما يتيح لك تشغيل كل خطوة وفحصها بشكل منفصل من خلال واجهة تطوير ADK المضمّنة.
  • server/ وweb/: تطبيق VibeStudio Workbench الذي يتم تشغيله محليًا على المنفذ 4600 يستضيف هذا القسم مستندات الخطوات ومحرّر التعليمات البرمجية داخل الصفحة وأدوات التحقّق من صحة أدلة وقت التشغيل والعرض المرئي للرسوم البيانية.
  • vibestudio/: التطبيق الكامل المخصّص للإنتاج والذي تم تجميعه ونشره على Cloud Run في الخطوة الأخيرة يحتوي على نسخة مستقلة خاصة به من الرسم البياني لسير العمل المكتمل.

3- الوكيل الموحَّد

قبل إنشاء رسم بياني لسير عمل متعدّد العُقد، عليك إنشاء أساس معماري باستخدام وكيل واحد في stage0_prompt/agent.py. يعتمد هذا الوكيل على طلب نظام شامل يصف مسار الإنتاج في شكل نثر، ويستند إلى أداتَي دالة Python.

يُظهر تقييم هذا المرجع الحدود التشغيلية للتنسيق المستند إلى الطلبات، ويوضّح سبب حاجة أنظمة الإنتاج إلى تنظيم الرسوم البيانية.

بنية وكيل ADK (3A)

في VibeStudio Workbench، انتقِل إلى الخطوة 3: وكيل متكامل وافتح بنية وكيل حزمة تطوير الوكلاء (3A). يعرض هذا المخطط الطبقات المعمارية الأساسية لوكيل ADK (LlmAgent):

03-3A

from google.adk.agents import LlmAgent
from google.adk.tools import mcp_toolset

root_agent = LlmAgent(
    model="gemini-3.5-flash",                 # model
    instruction=BRAND_INSTRUCTION,            # instruction
    skills=[load_skill("brand-audit")],       # skills
    tools=[mcp_toolset("mcp_brand_style")],   # tools
    output_schema=BrandStyleReport,           # structured output
    before_agent_callback=setup_ctx,          # interceptor
    before_model_callback=require_image,      # interceptor
    after_model_callback=schema_guard,        # interceptor
)

يصنّف الرسم التخطيطي التفاعلي مكوّنات الوكيل إلى خمسة مجالات تشغيلية:

  • طبقة الاستدلال (النموذج): النموذج اللغوي الأساسي (مثل Gemini 3 Flash) الذي ينفّذ المهام الإدراكية والاستدلال على الطلبات واختيار الأدوات. وتستند جميع العناصر الأخرى في البنية إلى هذا النموذج أو تفرض قيودًا عليه.
  • طبقة السياق (التعليمات والمهارات): توجيهات تشكّل طريقة استنتاج النموذج. يحدّد instruction الطلب الثابت للنظام والشخصية وقواعد التشغيل. skills تقديم إرشادات إجرائية (SKILL.md) تتضمّن إصدارات مختلفة لمهام سير العمل المتكرّرة
  • طبقة التعاون واتّخاذ الإجراءات (الأدوات والوكلاء الفرعيون وسير العمل ومخطط الإخراج): واجهات تتيح للوكيل اتّخاذ إجراءات في الأنظمة الخارجية وإصدار بيانات مكتوبة. توفّر tools وظائف Python قابلة للاستدعاء أو نقاط نهاية "بروتوكول سياق النموذج" (MCP). subagents تنفيذ المهام المفوضة التابعة ينسّق workflow الرسوم البيانية المتعدّدة الوكلاء. يطبّق output_schema نماذج Pydantic لضمان تلقّي المستهلكين النهائيين ملفات JSON تم التحقّق منها بدلاً من النصوص غير المنظَّمة.
  • طبقة الاعتراض (الاستدعاء في إحدى مراحل النشاط): إجراءات وقائية حتمية تنفّذ رمزًا مخصّصًا قبل تنفيذ الوكيل وبعده (before_agent/after_agent)، وجولات النموذج الفردية (before_model/after_model)، وطلبات الأدوات (before_tool/after_tool). تفرض أدوات الاعتراض قواعد السياسة بدون الاعتماد على امتثال النموذج.
  • الحالة الخارجية (الجلسة والذاكرة): استمرار الحالة منفصل عن منطق الوكيل. يحتفظ Session بالذاكرة العاملة المؤقتة وتتبُّع الأحداث لسلسلة التنفيذ الحالية. تحتفظ Memory بالحقائق والإعدادات المفضّلة الدائمة على مستوى الجلسات باستخدام خدمات مُدارة، مثل GEAP Memory Bank.

ينفّذ الوكيل الأحادي في هذه الخطوة ثلاثة فقط من هذه العناصر الأساسية: model وinstruction وtools. تتضمّن الخطوات اللاحقة مهام سير عمل الرسومات البيانية والمخططات المنظَّمة وعناصر الاعتراض وخدمات الذاكرة الثابتة.

مواصفات الوكيل الأحادي (3B)

في workbench، انتقِل إلى مواصفات الوكيل الموحّد (3B). افتح stage0_prompt/agent.py لفحص تعريف الوكيل الأساسي:

  • تعليمات الطلب الواحد: يختصر طلب النظام خمس مهام إنتاجية مختلفة في نص متواصل: اكتشاف اتجاهات المنصة، ومراجعة الأفكار المتراكمة، واقتراح مفاهيم إبداعية، وتطبيق سياسات المواضيع المحظورة، وصياغة قوائم اللقطات.
  • مصادر البيانات الأساسية: يشير الوكيل إلى مصدرَين محدَّدَين بجانب الرسم البياني:
    • ‫agent/trends.py: يعرض عشرة من أبرز أساليب التصميم وتنسيقات الإعلانات النشطة من مجموعة تضم 250 أسلوبًا وتنسيقًا مع نتائج ديناميكية لمستوى الاهتمام.
    • agent/backlog.txt: يقرأ ملاحظات الأفكار الأولية لصانع المحتوى سطرًا سطرًا.

الأدوات في "الوكيل" (3C)

في مساحة العمل، انتقِل إلى الأدوات في Agent (3C).

ما هي الأداة بالنسبة إلى الوكيل؟

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

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

03-3C

يتبع استدعاء الأدوات بروتوكولاً صريحًا من خمس مراحل بين النموذج ووقت تشغيل ADK:

  1. تعريف المخطط: يقدّم المطوّر دوال Python للوكيل. تفحص ADK اسم كل دالة وتعليقاتها التوضيحية وسلاسل المستندات لإنشاء بيان مخطط JSON متوافق مع OpenAPI يصف مَعلماتها والغرض منها.
  2. الاستدلال في النموذج: أثناء الاستدلال، يقيّم النموذج ما إذا كان طلب المستخدم يتطلّب بيانات خارجية. إذا لزم الأمر، يُصدر النموذج حدث function_call منظَّمًا يحتوي على اسم الدالة المستهدَفة وقاموس الوسيطات المطابق للمخطط.
  3. التنفيذ في وقت التشغيل: لا ينفّذ النموذج الرمز البرمجي بنفسه. يعترض وقت تشغيل حزمة ADK الـ function_call، وينفّذ دالة Python المحلية الفعلية باستخدام الوسيطات المقدَّمة، ويلتقط القيمة المعروضة.
  4. إعادة إدخال السياق: تحزّم حزمة وقت تشغيل ADK قيمة العرض للدالة في حدث function_response وتلحقها بسجلّ الجلسة النشطة.
  5. التركيب النهائي: يعالج النموذج مخرجات الأداة الموجودة الآن في قدرة استيعابه ويكمل ردّه.

في stage0_prompt/agent.py، يتم تعريف أداتَي البحث كدوال Python عادية:

def check_trends() -> dict:
    """Ten formats trending on the platform right now, with a heat score each."""
    from agent.trends import sample_trends
    return {"trends": sample_trends()}


def read_backlog() -> dict:
    """The creator's backlog: ideas they noted down to make someday."""
    from agent.graph import backlog_notes
    return {"backlog": backlog_notes()}

التعديل والتنفيذ العملي

في أداة تعديل الرموز في مساحة العمل، أضِف مرجعَي الدالتَين إلى قائمة tools الخاصة بالوكيل:

    tools=[check_trends, read_backlog],

احفظ التغيير. يتم تعديل الملف على القرص، ويؤكّد صف التحقّق أنّ كلا الأداتَين متصلتَين.

انقر على فتح ADK على الويب (Open adk web) لتشغيل واجهة تطوير ADK المضمّنة. أرسِل طلب الفكرة المقترَحة:

tonight's idea: a tiny robot doing laundry at midnight

ما يمكن توقّعه والسبب

عند إرسال هذا الطلب، راقِب تسلسل التنفيذ التالي في تتبُّع الجلسة:

  • يظهر حدثان لتنفيذ الأداة قبل الردّ: يظهر لك الحدثان function_call وfunction_response لـ check_trends وread_backlog.
    • السبب: قيّم Gemini توجيهات النظام ("التحقّق من المحتوى الرائج والاطّلاع على قائمة الأفكار")، وأدرك أنّه يفتقر إلى مؤشرات المنصة وملاحظات القناة في أوزانه، واستدعى كلتا الدالتَين لتحديد سياقه.
  • يقترح الوكيل اتجاهًا ويتوقف مؤقتًا لتأكيده: يقترح الرد اتجاهًا للفيديو يجمع بين المواضيع الرائجة والمحتوى المتراكم، ويطلب منك تأكيده.
    • السبب: طلبت توجيهات التعليمات من النموذج الموافقة على الاتجاه مع صانع المحتوى قبل إنشاء النص.
  • تخطّي التأكيد في ردّ لاحق: أرسِل رسالة ثانية: skip the questions, just describe the video. يتخطّى الوكيل على الفور خطوة التأكيد ويصيغ العنوان واللقطات.
    • السبب: تعليمات الطلبات هي إرشادات استشارية وليست حواجز حتمية. في الوكيل الأحادي، يمكن لتعليمات المستخدم إلغاء قواعد طلبات النظام الثابتة لأنّه لا يوجد سير عمل خارجي يتحكّم في تدفق التنفيذ.

القيود المعمارية للطلبات الموحّدة

في حين أنّ طلبًا واحدًا يمكن أن ينتج عنه ناتج مقبول للعروض التوضيحية المعزولة، فإنّ اختبار حالات الحدود في أداة التحقّق من صحة Workbench يكشف عن قيود مهمة على مستوى المؤسسة:

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

هذه الثغرات في البنية تدفعنا إلى تفكيك الوكيل الأحادي إلى سير عمل رسم بياني واضح تم إنشاؤه في الخطوة التالية.

4. أساسيات سير العمل المستند إلى الذكاء الاصطناعي الوكيل

في VibeStudio Workbench، انتقِل إلى الخطوة 4: أساسيات سير العمل المستند إلى الذكاء الاصطناعي الوكيل، الأجزاء من 4A إلى 4D.

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

مخطط بنية الرسم البياني وسلاسل التنفيذ (4A)

في مساحة العمل، افتح بنية الرسم البياني وسلاسل التنفيذ (4A).

تُعدّ Workflow في حزمة تطوير التطبيقات (ADK) بنية لتنفيذ الوكيل على شكل رسم بياني موجَّه محدّد بقائمة حواف:

  • السلاسل: تحدّد المجموعات المتسلسلة تنفيذ العُقد الخطية ((node_a, node_b, node_c)).
  • الفروع المتوازية: يتم تنفيذ السلاسل المستقلة التي تشترك في عقدة أصلية بشكل متزامن.
  • المزامنة: تنتظر السلاسل التي تتقارب في JoinNode حتى تبلّغ جميع الفروع الواردة قبل الإصدار.
  • التحكّم الحتمي: يتم التحكّم في مسار التنفيذ من خلال بُنى الرموز البرمجية المُعلَنة بدلاً من استنتاجها من نص الطلب.

04-4A

أنماط العُقد في ADK

تتألف عمليات سير عمل ADK من عدة أنواع متخصصة من العُقد. يؤدي كل نموذج دورًا تشغيليًا محدّدًا في الرسم البياني، ويفصل بين تنفيذ الرموز البرمجية الحتمية واستدلال النموذج التوليدي:

النمط الأصلي للعقدة

التنفيذ

الدور في مسار التعلّم

عقدة الدالة

دالة Python تعرض Event

ينفّذ المنطق الحتمي واسترداد البيانات وتغييرات الحالة.

عقدة الانضمام

مثيل JoinNode مدمج

تتم مزامنة الفروع المتزامنة في قاموس مجمّع.

عقدة الوكيل

‫Agent قيد التشغيل في وضع single_turn

تقيّم التعليمات مقارنةً بالبيانات التي تم إدخالها في المصدر وتُصدر بيانات تم التحقّق من صحتها.

عقدة جهاز التوجيه

دالة تعرض Event مع علامة route

تقييم المنطق الشرطي لاختيار فروع التنفيذ النهائية

عقدة إدخال البيانات

الدالة التي تنتج RequestInput

يؤدي هذا الإجراء إلى تعليق حالة التنفيذ إلى أن يصل ردّ من مستخدم خارجي.

root_agent = Workflow(
    name="stage1_fanout",
    description="2 real readers -> join -> one research dict",
    edges=[...])

في هذه الإعدادات، يكون root_agent مثيلاً لـ Workflow بدلاً من Agent مستقل. تعامل "حزمة تطوير التطبيقات" مع سير العمل كعناصر أساسية، ما يسمح بتحميل رسم بياني كامل وعرضه وفحصه كتطبيق موحّد. يسجّل name التطبيق في ADK Web، بينما تحدّد قائمة edges بنية التنفيذ.

التوسّع في البحث الموازي (4B)

في مساحة العمل، انتقِل إلى التوسّع في البحث المتوازي (4B). افتح stage1_fanout/agent.py.

04-4B

عُقد الدوال وحواجز المزامنة

تستخدم مرحلة البحث عقدتَي دالتَين تم استيرادهما من agent/graph.py:

  • ‫scan_trends: تعرض Event(output={"trends": [...]}) تحتوي على عشرة مؤشرات رائجة على المنصة تم تسجيلها.
  • ‫read_backlog: يعرض Event(output={"backlog": [...], "idea": "..."}) الذي يحتوي على خمس عشرة فكرة من الأفكار المتراكمة للقناة إلى جانب طلب التشغيل الأولي.

تقبل كل دالة node_input (ناتج العقدة السابقة) وتعرض Event.

يُعدّ JoinNode حاجزًا للمزامنة: فهو يتوقف مؤقتًا إلى أن تقدّم كل سلسلة واردة حدثًا، ثم يجمع كل نتائج الفروع في قاموس يتم إدخاله حسب اسم العقدة ({"scan_trends": {...}, "read_backlog": {...}}).

تعديل عملي: تحديد الحواف المتصلة والمتوازية

في stage1_fanout/agent.py، أنشئ مثيلاً لـ JoinNode واربط السلسلتَين المتوازيتَين بدءًا من START:

join_research = JoinNode(name="join_research")
    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research)])

احفظ التغييرات. يؤكّد مدقّق طاولة العمل أنّ الوصلات والحواف موصّلة. شغِّل المرحلة باستخدام تشغيل المرحلة 1 أو من خلال واجهة الويب المضمّنة في ADK.

ما يمكن توقّعه والسبب

  • تنفيذ القارئ المتزامن: في الرسم البياني للتنفيذ، يتم تنفيذ scan_trends وread_backlog في الوقت نفسه.
    • السبب: تبدأ السلسلتان عند START. يجدوِل محرّك ADK الفروع المستقلة في الوقت نفسه.
  • الناتج المجمّع للقاموس: يكتمل سير العمل عند join_research، ما يؤدي إلى إنشاء قاموس يحتوي على إدخالات لكل من القارئَين.
    • السبب: يضمن JoinNode التقاط البيانات بالكامل قبل السماح للعُقد اللاحقة بالتنفيذ.

عُقد الوكلاء (4C)

في workbench، انتقِل إلى عُقد الوكيل (4C). افتح stage2_direction/agent.py.

04-4C

أوضاع التشغيل والمخططات المنظَّمة

عند تضمين في Workflow، يتم تشغيل Agent في وضع single_turn تلقائيًا:

  • يتلقّى مخرجات العقدة السابقة كمدخلات سياق.
  • ينفّذ هذا الوضع طلب استنتاج واحدًا بدون تبادُل حواري.
  • تُخرج هذه العقدة بيانات منظَّمة إلى العقدة التالية.

من خلال تعيين output_schema=Directions، يفرض الوكيل التحقّق من صحة Pydantic على مخرجات النموذج. يتلقّى الرسم البياني النهائي عناصر مكتوبة بدلاً من النثر غير المنظَّم:

class Direction(BaseModel):
    title: str           # <=60 chars, filmable, characterful
    angle: str           # the twist, one line
    hook: str = ""       # 2-4 words, the video's sticker line
    evidence: list[Evidence]


class Directions(BaseModel):
    candidates: list[Direction]   # exactly 4

توجّه PROPOSE_INSTRUCTION النموذج إلى اقتراح أربعة مرشحين مع الاستشهاد بأدلة من كل من المؤشرات المتداولة وقائمة المهام المتراكمة. يقدّم المرشحون من 1 إلى 3 أفكارًا قابلة للتطبيق للقناة. تقدّم المرشحة 4 عن قصد مفهومًا ينتهك السياسة لاختبار بوابة الأمان في الخطوة التالية.

تعديل عملي: تحديد عقدة الوكيل وربط عملية الانضمام

في stage2_direction/agent.py، اضبط propose_directions ووسِّع حواف سير العمل:

propose_directions = Agent(
    name="propose_directions",
    model=config.MODEL,
    instruction=PROPOSE_INSTRUCTION,
    output_schema=Directions)
    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research),
           (join_research, propose_directions, direction_gate)])

ما يمكن توقّعه وسبب ذلك

  • استخدام القاموس مباشرةً: يستخدم "propose_directions" حمولة JSON الصادرة عن "join_research" بدون تنسيق يدوي.
  • النتائج المرشّحة المكتوبة: يُصدر الوكيل كائن Directions تم التحقّق منه يحتوي على أربع نتائج مرشّحة منفصلة. تقرأ العُقد النهائية الحقول حسب اسم السمة (candidate.title) بدون تحليل السلسلة.

المشاركة البشرية (4D)

في مساحة العمل، انتقِل إلى الإشراف البشري (4D). افتح agent/graph.py.

04-4D

تعليمات الطلبات مقابل التعليق الحتمي

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

  • يؤدي عرض RequestInput إلى تعليق تنفيذ سير العمل على الفور.
  • تسجّل ADK مكالمة مقاطعة مفتوحة في مخزن الجلسات وتُصدر interrupt_id فريدًا.
  • تتوقف عملية التنفيذ بدون استهلاك الرموز المميّزة أو سلاسل المحادثات على الخادم.
  • ولا يتم استئناف تنفيذ الرسم البياني إلا عند إرسال function_response صالح يتطابق مع المخطط ومعرّف المقاطعة.

تعديل عملي: تعليق التنفيذ باستخدام RequestInput

في agent/graph.py، نفِّذ طلب التعليق داخل direction_gate:

    yield RequestInput(
        message="Pick tonight's direction: 1, 2, 3 or 4.",
        response_schema={
            "type": "object",
            "properties": {
                "pick": {"type": "string", "enum": ["1", "2", "3", "4"]}}},
        payload={"candidates": cands})

يضبط RequestInput ثلاث سمات:

  • ‫message: طلب المراجعة المعروض للمستخدم.
  • ‫response_schema: مخطّط JSON يعرضه الواجهة الأمامية كنموذج إدخال، ويتم التحقّق من صحته من خلال ADK عند الإرسال.
  • payload: البيانات الوصفية المضمّنة في الطلب (الخيارات الأربعة)، ما يتيح لواجهات العميل عرض بطاقات المراجعة بدون طلب حالة الجلسة

ما يمكن توقّعه والسبب

  • توقُّف سير العمل عند direction_gate: في ADK Web أو واجهة workbench، يتوقف التشغيل مؤقتًا ويعرض نموذجًا تفاعليًا لاختيار المرشحين.
    • السبب: واجه المحرّك RequestInput متوقفة مؤقتًا وحافظ على حالة التنفيذ في runs/sessions.db.
  • تتطلّب الاستئناف إدخال بيانات منظَّمة: لن يؤدي إرسال نص عشوائي في المحادثة إلى تقدّم الرسم البياني. يؤدي اختيار أحد الخيارات (1 أو 2 أو 3 أو 4) إلى إرسال function_response مكتوب يستوفي response_schema واستئناف التنفيذ.

5- الحالة وجهاز التوجيه

في VibeStudio Workbench، انتقِل إلى الخطوة 5: الحالة والموجّه، الأجزاء من (5A) إلى (5C).

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

حالة سير العمل (5A)

في workbench، انتقِل إلى Workflow State (5A).

‫05-5A

حالة الجلسة في مقابل ناتج العقدة

في سير عمل ADK، تنتقل البيانات عبر الرسم البياني من خلال آليتَين مختلفتَين:

  • ناتج العُقدة (Event(output=...)): البيانات الموجّهة بدقة إلى المستهلكين المباشرين في اتجاه سير البيانات المحدّدين في قائمة الحافة
  • حالة الجلسة (Event(state=...)): قاموس مشترك يتضمّن أزواجًا من المفاتيح والقيم ويمكن لأي عقدة لاحقة الوصول إليه في دورة حياة التنفيذ.

05-5A

عندما يختار المستخدم مرشحًا في direction_gate، يصل الاختيار كفهرس رقمي ({"pick": "2"}). تحتاج العُقد النهائية إلى كائن التوجيه الكامل: العنوان وزاوية السرد والجملة الجذابة. بدلاً من تمرير بيانات وصفية مطوّلة من خلال كل حمولة عقدة وسيطة، تكتب persist_direction المرشّح الذي تمّت تسويته إلى حالة الجلسة المشتركة.

لا تحتاج العُقد إلى تمرير قاموس حالة الجلسة بالكامل. عندما ينتج عن عقدة Event(state=...)، فإنّها توفّر فقط أزواج المفتاح/القيمة الجديدة أو المعدَّلة. يدمج ADK هذه التعديلات تلقائيًا في مخزن الجلسات:

    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})

يؤدي عرض Event إلى نقل التحكّم إلى وقت تشغيل Workflow، ما يؤدي إلى الاحتفاظ بالقيم الجديدة في سجلّ الجلسة في runs/sessions.db.

ربط المَعلمات

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

def persist_direction(node_input, candidates: list = []):
    ni = node_input if isinstance(node_input, dict) else {}
    raw = ni.get("pick")
    pick = str(raw).strip() if raw is not None else ""
    if candidates:
        i = int(pick) - 1 if pick.isdigit() else 0
        chosen = candidates[max(0, min(len(candidates) - 1, i))]
    else:
        chosen = {"title": "untitled", "angle": "", "evidence": []}
    hook = chosen.get("hook") or " ".join(chosen["title"].split()[:4])

في هذه الحالة، تمت كتابة candidates في حالة الجلسة بواسطة direction_gate. يربط ADK هذه السمة مباشرةً في persist_direction(node_input, candidates: list = []) بدون الحاجة إلى عمليات بحث صريحة في القاموس.

يتم الاحتفاظ بالمفاتيح التي تبدأ بـ user: في جميع الجلسات في مساحة التخزين على مستوى المستخدم، ما يتيح لعمليات سير العمل اللاحقة الوصول إلى الإعدادات المفضّلة لصانع المحتوى.

التعديل العملي: الحفاظ على الحالة وربط العقدة

  1. في agent/graph.py، داخل persist_direction، استبدِل السطر TODO: PERSIST_STATE بـ yield لحدث الحالة:
    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})
  1. في stage3_router/agent.py، أضِف persist_direction إلى السلسلة الثالثة في قائمة edges:
           (join_research, propose_directions, direction_gate,
            persist_direction)

احفظ ملفاتك. في workbench، تأكَّد من ظهور علامات صح خضراء لكل من state write in place وpersist_direction in the chain.

عقدة جهاز التوجيه (5B)

في workbench، انتقِل إلى عقدة جهاز التوجيه (5B).

05-5B

توجيه السياسات الحتمي

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

يعرض جهاز التوجيه Event يحدّد علامة route:

def length_check(node_input):
    too_long = len(node_input.get("title", "")) > 60
    return Event(output=node_input, route="TRIM" if too_long else "PASS")

في تعريف سير العمل، يتم تحديد هدف الحافة كقاموس يربط أسماء المسارات بعُقد الوجهة:

    (length_check, {"TRIM": shorten, "PASS": scripter}),

يقرأ موجّه سير العمل policy_check العبارات المحظورة من agent/policy_words.txt ويجري مطابقة الكلمات الكاملة مع عنوان الاتجاه وزاويته المحدّدة:

    return Event(output=node_input, route="BLOCK" if bad else "OK")

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

الوجهات: Scripter والحجر الصحي

يوجّه جهاز التوجيه الزيارات إلى إحدى العقدتَين التاليتَين:

  • ‫scripter: عقدة وكيل single_turn تحوّل التوجيهات الموافَق عليها إلى نص إنتاج منظَّم يلتزم بمخطط Script Pydantic:
scripter = Agent(
    name="scripter",
    model=config.MODEL,
    instruction=SCRIPT_INSTRUCTION,
    output_schema=Script)
  • ‫quarantine: هي دالة عنصر نائب في البداية توقف الاتجاهات التي تم الإبلاغ عنها، ويتم استبدالها في الجزء التالي بوكيل معالجة مستقل.

تعديل عملي: توجيه عملية التحقّق من السياسة

  1. في agent/graph.py، داخل policy_check، أكمِل عبارة return:
    return Event(output=node_input, route="BLOCK" if bad else "OK")
  1. في stage3_router/agent.py، عدِّل edges لتوجيه policy_check وإعادة دمج فرع العزل في scripter:
           (join_research, propose_directions, direction_gate,
            persist_direction, policy_check),
           (policy_check, {"OK": scripter, "BLOCK": quarantine}),
           (quarantine, scripter)])

احفظ ملفاتك. في workbench، تأكَّد من إثبات صحة عمليات ربط حواف جهاز التوجيه.

أوضاع الوكيل وعقدة المهام (5C)

في مساحة العمل، انتقِل إلى أوضاع الوكيل وعقدة المهمة (5C).

05-5C

أوضاع تنفيذ الوكيل

تتيح مثيلات ADK Agent ثلاثة أوضاع تنفيذ مخصّصة لمتطلبات مسارات معيّنة:

الوضع

مراحل نشاط التنفيذ

الدور في مسار التعلّم

chat

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

الوكلاء الأساسيون الذين يتفاعلون مع مستخدم بشري

single_turn

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

عمليات تحويل الرسومات البيانية التسلسلية (propose_directions، scripter)

task

حلقة مستقلة مع تنفيذ الأداة. يكرّر الوكيل العملية إلى أن يستدعي أداة finish_task المضمّنة.

المعالجة والفحص المتعدّد الخطوات (quarantine)

إصلاح السياسات الذاتي

تتطلّب إعادة كتابة توجيه تم الإبلاغ عنه استخدام وضع "task" لأنّ عدد تكرارات المعالجة متغيّر. يتلقّى الوكيل التعليمات التي تم الإبلاغ عنها، ويستدعي find_policy_hits لرصد الانتهاكات، ويطلب بدائل معتمَدة من خلال suggest_replacement، ويعيد كتابة التعليمات، ويتحقّق من سلامة المحتوى قبل المتابعة.

يتم تحديد كلتا الأداتَين في agent/cleanup_tools.py باستخدام توقيعات مكتوبة وسلاسل مستندات:

def find_policy_hits(text: str) -> dict:
    """Which refused words appear in `text`. Matches whole words and phrases
    from agent/policy_words.txt, case-insensitive.

    Returns {"hits": [...], "clean": bool}. clean is true when hits is empty.
    """


def suggest_replacement(word: str) -> dict:
    """The channel's approved stand-in for a refused word, read from
    agent/policy_replacements.txt.

    Returns {"word", "replacement", "listed"}. When the word has no entry,
    listed is false and replacement is a hint to pick a gentle synonym.
    """

تعديل عملي: تجميع وكيل مهام العزل

في stage3_router/agent.py، استبدِل الدالة النائبة quarantine بتعريف وكيل المهام:

quarantine = Agent(
    name="quarantine",
    model=config.MODEL,
    instruction=QUARANTINE_INSTRUCTION,
    mode="task",
    tools=[find_policy_hits, suggest_replacement],
    output_schema=CleanedDirection,
)

يوفّر وضع المهام للوكيل الأدوات اللازمة وينهي التنفيذ من خلال استدعاء finish_task. عند ضبط mode="task"، يوفّر ADK تلقائيًا finish_task ويستمدّ مَعلماته من output_schema، ما يضمن أن تنتج العقدة كائن CleanedDirection مكتوبًا يتطابق مع مخطط الإدخال لعقدة النص البرمجي.

05-5C

ما يمكن توقّعه والسبب

اختبِر مسارَي التنفيذ في ADK Web أو VibeStudio Workbench:

  • المسار الموافق عليه (المُرشَّح 1 أو 2 أو 3):
    • يؤدي اختيار مرشّح موافَق عليه إلى توجيه الطلبات من policy_check مباشرةً إلى scripter (route="OK").
    • ينشئ كاتب النص نصًا برمجيًا للإنتاج من 3 لقطات يلتزم بمخطط Script.
  • مسار معالجة العزل (المرشّح 4):
    • يحتوي المرشّح 4 على مفردات محظورة ("محتوى مضلّل لجذب النقرات" و"حيلة رائجة").
    • ‫policy_check مسار إلى quarantine (route="BLOCK")
    • في تتبُّع الجلسة، يمكنك ملاحظة استدعاء quarantine لـ find_policy_hits، واستدعاء suggest_replacement لكل انتهاك، وإعادة كتابة العنوان، واستدعاء finish_task.
    • يعود التنفيذ إلى "scripter"، ما يؤدي إلى إنشاء نص برمجي من الاتجاه الذي تم تنقيته.

6. Memory Bank

في VibeStudio Workbench، انتقِل إلى الخطوة 6 · Memory Bank، الأجزاء (6A) و(6B).

لا يتوفّر حاليًا سجلّ للعملية بين الجلسات. يبدأ كل تنفيذ من الصفر، بدون معرفة ما اختاره صانع المحتوى سابقًا أو الأنواع التي يفضّلها. في هذه الخطوة، يمكنك ربط Vertex AI Agent Engine Memory Bank لتخزين الإعدادات المفضّلة لصنّاع المحتوى واسترجاعها في عمليات التشغيل المختلفة.

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

بنك الذاكرة (6A)

في مساحة العمل، انتقِل إلى مستودع الذاكرة (6A).

06-6A

الذاكرة المُدارة على مستوى المستخدم

‫Memory Bank هي خدمة مُدارة لتخزين بيانات الذاكرة الطويلة المدى للمستخدمين. وهي تنظّم الحقائق حول شخص ضمن نطاق محدّد، يتم تحديده هنا من خلال اسم التطبيق ورقم تعريف المستخدم:

SCOPE = {"app_name": config.APP, "user_id": config.USER}
TOPICS = {
    "CREATOR_TASTE": "Which video directions this creator picks and passes on, "
                     "and how that preference changes over time.",
    "CHANNEL_RULES": "Standing instructions the creator states for every video "
                     "(style, subjects to avoid, format rules).",
}

تحدّد مواضيع الذاكرة المخصّصة حدود ما يسجّله البنك، وهي:

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

يتم تنفيذ كلتا العمليتين في agent/platform/memory.py. يتم تخزين اسم مرجع المصرف الذي تم توفيره مؤقتًا على الجهاز في runs/memorybank.json.

إعداد "بنك الذكريات"

استخدِم عناصر التحكّم في workbench أو نفِّذ أوامر CLI في الوحدة الطرفية:

  1. ربط المصرف وتوفيره:
    python -m agent.platform.bank
    
    ينشئ مثيل Agent Engine ويضبط موضوعَي CREATOR_TASTE وCHANNEL_RULES.
  2. الجلسات السابقة الأساسية:
    python -m agent.platform.bank load
    
    يتم تحميل أربع جلسات سابقة لإنشاء المظاهر (مظهران بطابع الحيوانات مع قيود على الأنماط، ومظهر بطابع الأجهزة، ومظهر حديث بطابع الخيال).
  3. فحص الحقائق الموحّدة:
    python -m agent.platform.bank list
    
    افحص الناتج. لاحظ كيف تم تحويل النصوص السردية إلى بيانات حقيقة منظمة وموحدة.

عمليات إعادة الاستدعاء (6B)

في طاولة العمل، انتقِل إلى عمليات معاودة الاتصال (6B). افتح stage4_memory/agent.py.

06-6A

عمليات الاستدعاء في إحدى مراحل نشاط وكيل ADK

ردّ الاتصال هو دالة يتم تمريرها كوسيطة إلى Agent. يستدعي ADK عمليات رد الاتصال في لحظات محدّدة مسبقًا من مراحل النشاط، مع تمرير السياق النشط. يؤدي عرض None إلى مواصلة التنفيذ العادي، بينما يؤدي عرض عنصر بديل إلى إلغاء العملية أو اعتراضها.

06-6A

توفّر حزمة ADK ثلاث مجموعات من عمليات الاستدعاء:

زوج معاودة الاتصال

نقطة الاستدعاء

المَعلمات التي تم تلقّيها

سلوك القيمة المعروضة

before_agent_callback
after_agent_callback

تحيط بردّ الوكيل بالكامل

‫CallbackContext (الحالة والجلسة والاستدعاء)

يؤدي عرض Content إلى استبدال ردّ الوكيل، بينما يستمر None بشكل طبيعي.

before_model_callback
after_model_callback

حول كل طلب استنتاج من نموذج لغوي كبير

LlmRequest أو LlmResponse

يؤدي عرض LlmResponse إلى اعتراض طلب النموذج أو تخطّيه، بينما يؤدي عرض None إلى المتابعة.

before_tool_callback
after_tool_callback

حول كل عملية تنفيذ للأداة

تعريف الأداة والوسيطات والنتيجة

يؤدي عرض قاموس إلى إلغاء مخرجات الأداة، ويتابع None.

توفّر عمليات الاسترجاع موقعًا واضحًا لإدخال السياق، وضوابط الحماية، وقياس استخدام التطبيق، وعمليات البحث في ذاكرة التخزين المؤقت بدون إدخال عُقد خارجية في الرسم البياني لسير العمل.

تعديل عملي: استدعاء الأسلاك وتذكُّر عمليات الاستدعاء

  1. في stage4_memory/agent.py، عدِّل propose_directions لإرفاق before_model_callback=recall_taste:
    output_schema=Directions,
    before_model_callback=recall_taste)

يتم تنفيذ recall_taste مباشرةً قبل أن ينشئ Gemini الاتجاهات المرشحة. وتجلب سجلّ صانع المحتوى من Memory Bank، وتنسّق الذكريات من الأقدم إلى الأحدث، وتُلحقها بـ "LlmRequest" الصادر. يوجّه الطلب النموذج إلى جعل المرشحين من 1 إلى 3 يميلون نحو ذوق صانع المحتوى الحالي مع التعامل مع قواعد القناة كقيود صارمة.

  1. في stage4_memory/agent.py، عدِّل scripter لإرفاق after_agent_callback=remember_pick:
    output_schema=Script,
    after_agent_callback=remember_pick)

يتم تنفيذ remember_pick بعد أن يكمل scripter دوره. يقرأ الاتجاه المختار من حالة الجلسة، ويصيغ عبارة موجزة تلخّص قرار صانع المحتوى، ويستدعي memories.generate لتعديل "بنك الذاكرة".

ما يمكن توقّعه والسبب

اختبِر سير العمل المعزَّز بعمليات الاستدعاء في Workbench أو ADK Web:

  1. تنفيذ عملية بطلب فارغ:
    • في تتبُّع الجلسة، افحص LlmRequest بحثًا عن propose_directions. لاحظوا سياق الذاكرة الملحق الذي يوضّح تفضيل صانع المحتوى لمواضيع الخيال وسرعة السرد الموجز.
    • اتّبِعوا الاتجاهات المقترَحة: تتوافق الخيارات من 1 إلى 3 مع التفضيلات السابقة لصنّاع المحتوى حتى عندما تشير المؤشرات إلى مواضيع أخرى.
  2. اختَر مرشحًا في direction_gate.
  3. بعد اكتمال عملية "scripter"، راجِع سجلّات Memory Bank:
    python -m agent.platform.bank list
    
    يعرض بنك المعلومات الآن الخيار الأخير، ويدمجه مع سجلات الاهتمامات السابقة.

7. RAG Engine

في VibeStudio Workbench، انتقِل إلى الخطوة 7: محرّك RAG، الجزأين (7A) و(7B).

07-7A

تتلقّى الفيديوهات المنشورة ملاحظات مستمرة من المشاهدين. يتم جمع ثلاثين تعليقًا تمثيليًا في agent/comments.md، ما يتيح رصد إشادات المشاهدين وانتقاداتهم بشأن وتيرة المحتوى الدعائي وخياراتهم المفضّلة بشأن الصوت. في هذه الخطوة، يمكنك فهرسة هذه التعليقات باستخدام Vertex AI RAG Engine وربط الاسترجاع الدلالي بالتوزيع الموسَّع للبحث.

استرجاع المعلومات من المستندات (7A)

في مساحة العمل، انتقِل إلى محرك التوليد المعزَّز بالاسترجاع (7A).

مقارنة بين Memory Bank ومحرّك RAG

تستند كلتا الأداتَين إلى البيانات الخارجية في سير العمل، ولكنّهما تخدمان أغراضًا معمارية مختلفة:

السمة

Memory Bank

محرّك التوليد المعزّز بالاسترجاع

حالة الاستخدام الأساسية

الإعدادات المفضّلة للمستخدمين على المدى الطويل والقواعد التشغيلية

استرجاع دلالي من مجموعات مستندات كبيرة

النطاق

يقتصر على أرقام تعريف المستخدمين الفردية وأسماء التطبيقات

يقتصر على موارد مجموعة المستندات المشتركة بين جميع المستخدمين

معالجة البيانات

استخراج البيانات وتضمينها ودمجها دلاليًا في الوقت الفعلي

تقسيم المستندات إلى أجزاء وتضمين المتّجهات والبحث عن أقرب تطابق

دمج Graph

الاستدعاءات في إحدى مراحل نشاط الوكيل (before_model_callback وafter_agent_callback)

عقدة وظيفة مخصّصة في عملية توسيع نطاق البحث (read_feedback)

07-7A

تقسيم المستندات إلى أجزاء وتضمينها

يفهرس محرّك RAG المستندات من خلال تقسيم النص إلى فقرات دلالية وتخزين متّجهاتها في قاعدة بيانات مُدارة:

corpus = rag.create_corpus(
    display_name="vibestudio-feedback",
    description="Vibe Studio: what the audience wrote under the channel's past videos.",
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=rag.RagEmbeddingModelConfig(
            vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
                publisher_model="publishers/google/models/text-embedding-005"))))

rag.upload_file(
    corpus_name=corpus.name, path="agent/comments.md", display_name="comments.md",
    transformation_config=rag.TransformationConfig(
        chunking_config=rag.ChunkingConfig(chunk_size=120, chunk_overlap=20)))
  • حجم الجزء: تم ضبطه على 120 رمزًا مميزًا مع تداخل 20 رمزًا مميزًا. يتم تسجيل تعليقَين أو ثلاثة تعليقات لكل مقطع، ما يضمن أن يمثّل كل متجه رأيًا متماسكًا بدون تخفيف المعنى من خلال ملاحظات غير ذات صلة.
  • نموذج التضمين: يحوّل text-embedding-005 النص إلى متّجهات عالية الأبعاد. عند إرسال طلب بحث، يحوّل النموذج طلب البحث إلى متّجه ويعثر على أقرب النتائج المطابقة استنادًا إلى المسافة الدلالية. تعليق حول تنين صغير يحرس الجوارب يتطابق مع طلب حول مخلوقات سحرية بدون الحاجة إلى تطابق الكلمات الرئيسية بدقة.

إعداد مجموعة بيانات RAG

ابدأ بإنشاء مجموعة النصوص باستخدام أزرار مساحة العمل أو أوامر الوحدة الطرفية:

  1. إنشاء المجموعة:
    python -m agent.platform.rag
    
    توفّر قاعدة بيانات المتّجهات المُدارة وتسجّل معرّف المورد في runs/ragcorpus.json.
  2. تحميل التعليقات وفهرستها: يتم تحميل agent/comments.md مع إعدادات تقسيم المحتوى إلى أجزاء، ويتم انتظار اكتمال الفهرسة.
  3. الاستعلام عن النص: اختبِر استرجاع التشابه باستخدام طلبات بحث لا تتشارك كلمات دقيقة مع التعليقات (على سبيل المثال، طلب البحث "مخلوقات سحرية صغيرة" لاسترداد التعليقات حول التنانين).

عقدة الاسترجاع (7B)

في مساحة العمل، انتقِل إلى القارئ الثالث (7B). افتح stage5_rag/agent.py.

07-7B

استرداد البيانات كعقدة رسم بياني

تمثّل ملاحظات الجمهور بيانات البحث التي تتم مشاركتها في سير العمل. على عكس ذاكرة صانع المحتوى الشخصية، يتم إدخال آراء المشاهدين مباشرةً في "join_research" إلى جانب المؤشرات والبيانات المتراكمة. لذلك، يتم تنفيذه كعقدة دالة:

07-7B

def read_feedback(node_input):
    """The third reader (step 7): what the audience wrote under past videos,
    the passages nearest to tonight's idea. Retrieval, not a model call."""
    from .platform import rag
    idea = idea_text(node_input)
    query = idea or "what viewers liked and what they complained about"
    try:
        hits = rag.retrieve(query)
    except Exception as e:
        print(f"  [rag] feedback unavailable ({str(e)[:80]})")
        return Event(output={"query": query, "feedback": [],
                             "note": "no corpus connected - run: python -m agent.platform.rag"})
    return Event(output={"query": query, "feedback": [h["text"] for h in hits]})

يستخرج read_feedback الفكرة الأولية للمستخدم وينفّذ طلب بحث متّجه على مجموعة بيانات "محرك التوليد المعزّز بالاسترجاع". ويتم عرض التعليقات التي تم استردادها في حمولة Event(output=...).

تعديل عملي: ربط القارئ الثالث بالتوزيع الموسَّع

في stage5_rag/agent.py، عدِّل edges لإضافة read_feedback كفرع موازٍ ثالث يدخل join_research:

           (START, read_backlog, join_research),
           (START, read_feedback, join_research),

بما أنّ join_research هي JoinNode، فإنّها تزامن جميع الفروع الواردة، وتنتظر إلى أن تُصدر scan_trends وread_backlog وread_feedback جميع الأحداث قبل تمرير الحزمة المجمّعة إلى أسفل السلسلة.

ما يمكن توقّعه وسبب ذلك

تشغيل سير العمل في مساحة العمل:

  1. أرسِلوا طلبًا للحصول على أفكار (مثل "تنين صغير يحرس طاولة المطبخ").
  2. في تتبع التنفيذ، تحقق من تنفيذ جميع عقد القارئ الثلاث بشكل متزامن.
  3. لاحظ join_research: يحتوي قاموس الإخراج الآن على trends وbacklog وfeedback.
  4. راجِعوا الاقتراحات التي تم إنشاؤها من "propose_directions": يدمج النموذج تعليقات المشاهدين في اقتراحاته ويشير إلى آراء الجمهور في حقول الأدلة.
  5. يُرجى العِلم أنّ عملية استرجاع البيانات في نموذج RAG هي عملية حتمية (تؤدي طلبات البحث المتطابقة إلى عرض فقرات تعليقات متطابقة)، في حين أنّ عقدة الاقتراحات التوليدية تنتج خيارات إبداعية متنوعة.

8. إنشاء الفيديوهات بشكل غير متزامن باستخدام Veo

في VibeStudio Workbench، انتقِل إلى الخطوة 8 · الفيديو، الأجزاء (8A) و(8B).

يتطلّب إنشاء فيديو عالي الدقة باستخدام Google Veo عدة دقائق لكل عملية عرض. يؤدي حظر تنفيذ الرسم البياني خلال هذه الفترة إلى إهدار موارد الحوسبة وقفل مجموعات سلاسل المحادثات وتعريض عملية التشغيل لانقطاع اتصال HTTP. في هذه الخطوة، يمكنك جعل عرض الفيديو غير متزامن باستخدام LongRunningFunctionTool في "حزمة تطوير البرامج" (ADK).

الأدوات التي تستغرق وقتًا طويلاً (8A)

في مساحة العمل، انتقِل إلى أداة تعمل لفترة طويلة (8A). افتح "stage6_video/agent.py" و"agent/deliver.py".

08-8A

الأدوات المتزامنة مقابل الأدوات التي تستغرق وقتًا طويلاً

تُنفَّذ أدوات الدوال العادية في ADK بشكل متزامن داخل دور الوكيل: يستدعي النموذج الأداة، وينتظر حمولة البيانات التي يتم عرضها، ويدمج النتيجة في الدور الحالي.

لا يمكن إكمال عرض الفيديو في طلب واحد. بدلاً من ذلك، يبدأ render_submit مهمة الإنشاء ويعرض على الفور إيصالاً تشغيليًا بالحالة "pending":

def render_submit(prompt: str) -> dict:
    """Submit one Veo render of `prompt`. Returns at once with a pending
    receipt; the clip is delivered later, to this call, by id."""
    receipt = videogen.start(f"{prompt} {videogen.NO_TEXT}")
    return {"status": "pending", "operation": receipt["operation"], "prompt": receipt["prompt"]}

عند استخدام LongRunningFunctionTool، تعترض حزمة ADK حالة "pending". ينتهي دور الوكيل، ويتم تعليق سير العمل عند العقدة، ويتم تسجيل البيانات الوصفية للمكالمة المعلّقة (بما في ذلك معرّف المكالمة والإيصال) في runs/sessions.db. يتم إنهاء عملية التنفيذ بشكل سليم بدون الحفاظ على اتصالات الشبكة النشطة أو سلاسل الوحدات العاملة.

تعديل عملي: تغليف أداة العرض

في stage6_video/agent.py، عدِّل render_desk لتضمين render_submit في LongRunningFunctionTool:

    tools=[LongRunningFunctionTool(render_submit)])

استئناف المكالمة حسب رقم تعريفها

نمط الاستئناف العام

تطبِّق "حزمة تطوير التطبيقات" آلية مماثلة لتعليق واستئناف سير العمل لكل من المستخدمين والأدوات الخارجية:

سبب تعليق الحساب

بدء عملية الإنشاء

حالة التعليق المخزّنة

حدث الاستئناف

قرار بشري

yield RequestInput(...)

فتح طلب الإدخال في متجر الجلسات

‫FunctionResponse يحمل معرّف مكالمة التعليق

أداة طويلة المدى

LongRunningFunctionTool(...) إرجاع pending

فتح طلب استخدام الأداة في متجر الجلسات

‫FunctionResponse يحمل معرّف مكالمة التعليق

في كلا السيناريوهَين، يتوقف سير العمل تمامًا ولا يُستأنف إلا عند وصول حدث يحمل FunctionResponse مطابقة من مصدر خارجي: واجهة مستخدم أو ردّ تلقائي على الويب أو عامل في الخلفية.

تعديل عملي: إكمال الرد على التسليم

في agent/deliver.py، أنشِئ جزء الاستئناف FunctionResponse:

    part = Part(function_response=FunctionResponse(
        id=row["call_id"], name=row["name"], response=response))

يستمر برنامج التسليم في طلب الفيديو من Veo إلى أن يتم إنشاؤه، ثم يرسل FunctionResponse إلى الجلسة. يطابق ADK معرّف المكالمة ويستأنف سير العمل مباشرةً في العقدة التالية. لا تتم إعادة تنفيذ العُقَد المكتملة، ولا يتّخذ الوكيل دورًا توليديًا آخر.

يؤدي ضبط STUDIO_REAL_VIDEO=0 في .env إلى تفعيل العرض الوهمي: يعرض start إيصال اختبار فوريًا، ويحاكي check عملية الإكمال في خمس ثوانٍ بدون إجراء طلبات بيانات من واجهة برمجة التطبيقات Veo API قابلة للفوترة.

دمج مسار الإجراءات (8B)

في workbench، انتقِل إلى render_desk في الرسم البياني (8B). افتح stage6_video/agent.py.

العقدة الطرفية في المسار هي store_video. يقرأ هذا المكوّن معلومات العرض المكتملة من runs/state.json (حيث سجّلتها عملية التسليم) ويُرسل عنوان URL للفيديو وحالة الإنشاء إلى حالة الجلسة المشتركة.

08-8B

التعديل العملي: ربط مسار الفيديو الكامل

في stage6_video/agent.py، عدِّل edges لإضافة render_desk وstore_video:

           (quarantine, scripter),
           (scripter, render_desk, store_video)])

ما يمكن توقّعه والسبب

اختبِر مسار الإنشاء غير المتزامن في مساحة العمل:

  1. نفِّذ سير العمل من خلال اختيار المرشّحين وإنشاء السيناريو.
  2. في الساعة render_desk، راقِب الوكيل وهو يستدعي "render_submit".
  3. يتم تعليق سير العمل على الفور. في "مساحة العمل" أو ADK Web، راقِب الحالة "في انتظار المراجعة": تحتفظ الجلسة بمعرّف المكالمة المفتوحة، ولا تستهلك أي عمليات في الخلفية الموارد.
  4. شغِّل برنامج التسليم الخفي باستخدام وحدة تحكّم workbench أو في الوحدة الطرفية:
    python -m agent.deliver
    
    تراقب عملية التسليم Veo إلى أن يصبح الفيديو جاهزًا، ثم ترسل حدث الاستئناف.
  5. في ADK Web، أعِد تحميل الجلسة: سيتم استئناف التنفيذ عند store_video، وحفظ عنوان URL للفيديو في حالة الجلسة، وإكمال سير العمل.

9. النشر على Cloud Run

في VibeStudio Workbench، انتقِل إلى الخطوة 9: النشر.

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

09-9A

The ADK Runner

في مرحلة التطوير، نظّمت adk web الرسم البياني. في مرحلة الإنتاج، يستضيف التطبيق سير العمل باستخدام فئة Runner في حزمة تطوير التطبيقات (ADK):

self._svc = DatabaseSessionService(db_url=config.DB_URL)
self._runner = Runner(app_name=config.APP, agent=wf, session_service=self._svc)

async for ev in self._runner.run_async(user_id=config.USER, session_id=run_id, new_message=message):
    self._absorb(ev)    # fold the ADK event into the run state, publish one app event

# the gate's answer and the render's delivery are the same call, with a function_response part
part = Part(function_response=FunctionResponse(id=call_id, name=name, response=response))
  • run_async: يؤدي إلى تنفيذ سير العمل، ما يؤدي إلى إنشاء الأحداث بالتسلسل أثناء تنفيذ العُقد، ويؤدي إلى استمرار التعديلات في خدمة الجلسة.
  • الاستئناف الموحّد: يتم استئناف تنفيذ كلّ من قرارات المستخدم في direction_gate وعمليات تسليم الفيديو المكتملة من Veo من خلال عناصر FunctionResponse متطابقة يتم إرسالها إلى run_async.

بنية تطبيق الإنتاج

يتضمّن تطبيق الإنتاج في vibestudio/ مسار العمل الكامل:

vibestudio/
  server/
    main.py                 FastAPI: application server, REST routes, static assets
    api.py                  REST API endpoints: run, pick, publish, backlog, profile, history
    runner.py               Runner orchestration over the workflow, background render poller
    platform/               Event bus (SSE stream), file storage, publishing, telemetry
    agent/                  Production agent package, verified by checks/verify_app.py
      graph.py              The complete workflow graph and node definitions
      desk.py               render_desk and render_submit wrapped with LongRunningFunctionTool
      schemas.py            Pydantic schemas: Directions, CleanedDirection, Script
      cleanup_tools.py      Deterministic policy tools: find_policy_hits, suggest_replacement
      platform/             Memory Bank, RAG Engine, and Veo integrations
  web/                      Production React user interface
  Dockerfile · deploy.py · run.sh
  • بث حدث واحد: تنشر الخلفية في FastAPI الأحداث عبر بث واحد من "الأحداث المُرسَلة من الخادم" (SSE). تعرض واجهة React الأمامية تقدّم الرسم البياني في الوقت الفعلي وتتعامل مع الاتصالات المتأخرة بدون فقدان الحالة.
  • التنفيذ غير المرتبط: يدير التطبيق حلقة معالجة الأحداث. يركّز الرسم البياني لسير العمل بالكامل على منطق التنفيذ، بدون معرفة واجهة العرض الأمامية.

تجمع قائمة حواف سير العمل الكاملة في agent/graph.py كل نمط معماري تم إنشاؤه خلال هذا الدرس العملي:

        (START, scan_trends, join_research),
        (START, read_backlog, join_research),
        (START, read_feedback, join_research),
        (join_research, propose_directions, direction_gate,
         persist_direction, policy_check),
        (policy_check, {"OK": scripter, "BLOCK": quarantine}),
        (quarantine, scripter),
        (scripter, render_desk, store_video),

النشر على Cloud Run

توفّر خدمة Google Cloud Run استضافة بدون خادم مع تدرّج تلقائي وتوجيه الطلبات وعمليات إنشاء حاويات مدمجة:

gcloud run deploy vibestudio --source vibestudio \
  --project $GOOGLE_CLOUD_PROJECT --region us-central1 \
  --labels dev-tutorial-codelab=vibetube --allow-unauthenticated \
  --memory 2Gi --cpu 2 --timeout 3600 --concurrency 40 \
  --max-instances 1 --min-instances 1 --session-affinity \
  --set-env-vars GOOGLE_CLOUD_PROJECT=...,STUDIO_VERTEX=1,STUDIO_MEMORY_BANK=...,STUDIO_RAG_CORPUS=...,VIBETUBE_URL=...,VIBETUBE_EVENT=...,VIBETUBE_NAME=...,VIBETUBE_PROJECT=...
  • إنشاء الحاوية: يحزم gcloud run deploy --source الدليل vibestudio/، وينشئ نسخة الحاوية باستخدام Cloud Build، وينشر الخدمة في عملية واحدة.
  • تقارب الجلسات: يوجّه الطلبات من المستخدم نفسه إلى مثيل الحاوية نفسه، ما يحافظ على حالة الجلسة المحلية على مستوى الخطوات التكرارية.
  • إمكانية تتبّع البيانات: يسجّل دمج Cloud Trace فترات موزّعة لكل عقدة وطلب نموذج لغوي كبير وتنفيذ أداة، ويمكن الوصول إليها في Google Cloud Console ضمن Trace Explorer.

انقر على الزر نشر في طاولة العمل لتنفيذ نص النشر البرمجي. عند اكتمال عملية الإنشاء، يعرض Terminal عنوان URL للخدمة المباشرة.

التطبيق

10. ملخّص

في VibeStudio Workbench، انتقِل إلى الخطوة 10: الملخّص لمراجعة البنية المكتملة.

10-summary

الخطوة

البنية والمفاهيم

نمط التنفيذ

طلب واحد

طلب واحد، وأدوات الدوال، وحلقة محادثة متسلسلة

‫Agent(tools=[...])، function_call من أصل function_response

أساسيات سير العمل المستند إلى الذكاء الاصطناعي الوكيل

سير عمل الرسم البياني، والبحث الموازي، ومخرجات المخطط، والمراجعة البشرية

Workflow، وSTART، وJoinNode، وoutput_schema، وRequestInput

الحالة وجهاز التوجيه

حالة الجلسة المشتركة، وربط المَعلمات، والتوجيه الحتمي، ووكيل المهام

Event(state=...)، وEvent(route=...)، وmode="task"، وfinish_task

Memory Bank

الذاكرة الطويلة الأمد على مستوى المستخدم، والدمج الدلالي، وخطوات مراحل النشاط

memories.generate / retrieve، before_model_callback، after_agent_callback

RAG Engine

استرداد المستندات من خلال تعليقات الجمهور والتضمينات الدلالية

‫rag.create_corpus، RagEmbeddingModelConfig، read_feedback عقدة

إنشاء فيديوهات بشكل غير متزامن باستخدام Veo

الأدوات التي تعمل لفترة طويلة، والإيصالات في انتظار المراجعة، وبرنامج التسليم الخارجي

LongRunningFunctionTool، استئناف FunctionResponse(id=...)

النشر على Cloud Run

التنظيم الآلي، وأحداث Server-Sent Events، والحاويات بدون خادم

Runner(agent=wf)، run_async، نشر Cloud Run

المبادئ الأساسية للتصميم

  1. التعليق بدلاً من الانتظار: يتم إيقاف مهام سير العمل مؤقتًا بشكل سلس في انتظار إدخال المستخدم (RequestInput) أو العمليات الطويلة (LongRunningFunctionTool)، ولا تظل العمليات في وضع الانتظار على سلاسل المحادثات أو مآخذ الشبكة.
  2. الاستئناف العام: يتم استئناف كل عملية تعليق من خلال آلية مماثلة: function_response واحد يحمل معرّف الاتصال للعقدة المعلّقة.
  3. إدارة الحالة المنفصلة: تتشارك العُقد البيانات من خلال مفاتيح حالة الجلسة المسماة وربط المَعلمات بدلاً من الحمولات الوسيطة المطوّلة والمرتبطة بإحكام.
  4. التوجيه الحتمي قبل التكلفة التوليدية: تقيّم موجّهات المستندات المستندة إلى القواعد وفلاتر التعبيرات العادية السياسة بتكلفة صفرية للرموز المميزة قبل تشغيل النماذج التوليدية.
  5. فصل الاهتمامات: السياق الخاص بوكيل فردي ينتمي إلى عمليات الاستدعاء في إحدى مراحل النشاط، بينما تنتمي تبعيات البيانات المشتركة

10-output