گردش کار عامل‌گرا با ADK

۱. مقدمه

VibeStudio

این codelab شما را در ساختن سیستم‌های عامل‌دار نسل بعدی بااستفاده از گردش‌های کار و نمودارها در Agent Development Kit راهنمایی می‌کند. الگوهای معماری رایج را پیاده‌سازی خواهید کرد، تعاملات مشارکت انسانی در حلقه (HITL) را هماهنگ خواهید کرد، و اجرای ناهمگام طولانی‌مدت را مدیریت خواهید کرد. همچنین پایگاه‌های دانش سازمانی و حافظه پایدار را برای سفارشی‌سازی و تکامل رفتار عامل ادغام خواهید کرد. درنهایت، این قابلیت‌ها را برای هدایت خط لوله تولید خودکار ویدیو متصل خواهید کرد.

سناریو

شما یک کانال دیجیتال در VibeTube با مخاطبان فعال و ایده‌های خلاقانه درحال گسترش دارید. تولید هر ویدیو نیازمند اجرای مداوم در مراحل مختلف است: تحقیق درباره قالب‌های پرطرفدار، ترکیب بازخورد بینندگان، توسعه فیلم‌نامه‌ها، بررسی رعایت خط‌مشی، و تولید کلیپ‌های ویدیویی. مدل‌های زایا می‌توانند دارایی‌های فردی را پیش‌نویس کنند، اما ارائه نسخه‌های منسجم نیازمند معماری عامل هماهنگ‌شده است.

برای خودکارسازی این چرخه عمر، VibeStudio را خواهید ساخت. این خط لوله عامل، تحقیقات معمول را به‌صورت موازی اجرا می‌کند، گزینه‌های گلچین‌شده را برای تأیید انسان در حلقه ارائه می‌دهد، دروازه‌های خط‌مشی خودکارسازی‌شده را قبل‌از تولید ویدیو اعمال می‌کند، و زمینه را در طول اجراهای تولید حفظ می‌کند.

گردش کاری که می‌سازید، از ایده تا کلیپ منتشرشده

آنچه می‌آموزید

10-summary

  • مبانی مهندسی گراف: معماری‌های عامل چندمرحله‌ای به جریان کنترل صریح و مسیرهای اجرای ساختاریافته نیاز دارند. بااستفاده از تاپل‌های لبه، نقطه ورودی START، JoinNode برای تجمیع موازی، و گره‌های مسیریاب قطعی برای هدایت اجرا براساس وضعیت، Workflow‏ ADK می‌سازید.
  • حالت‌های نماینده و فراخوانی‌های چرخه حیات: کارهای تخصصی به رفتارهای عملیاتی متمایز و حفاظ‌های قطعی نیاز دارند. نمونه‌های ADK Agent را بااستفاده از حالت‌های chat،‏ single_turn، و task فعال‌شده با ابزار به‌عنوان گره‌های گردش کار پیکربندی می‌کنید و رهگیرها را با before_model_callback و after_agent_callback اعمال می‌کنید.
  • هماهنگی مشارکت انسانی در حلقه: خطوط تولید در ایستگاه‌های بازرسی خلاقانه مهم برای قضاوت انسانی متوقف می‌شوند. RequestInput را برای تعلیق اجرای گردش کار، اعمال طرح‌واره‌های پاسخ ساختاریافته، و ازسرگیری اجرا بدون زنده نگه داشتن فرایندهای زمان اجرای غیرفعال پیاده‌سازی می‌کنید.
  • حافظه سلسله‌مراتبی عامل: سیستم‌های تولیدی وضعیت اجرای زودگذر را از بافت بادوام جدا می‌کنند. شما وضعیت جلسه کوتاه‌مدت را بااستفاده از Event(state=...) و اتصال پارامتر مدیریت می‌کنید و «بانک حافظه GEAP» را برای استخراج، ادغام، و حفظ اولویت‌های محتواساز در اجراهای مختلف متصل می‌کنید.
  • پایه‌گذاری با پایگاه‌های دانش سازمانی: نمایندگان خودمختار به بافت حوزه پویا و احساس مخاطب نیاز دارند. بدنه «موتور RAG» مربوط به GEAP را به‌عنوان گره بازیابی اختصاصی در گسترش موازی متصل می‌کنید تا بروندادهای عامل را ازنظر معنایی زمینه‌سازی کنید.
  • گردش کار و استقرار طولانی‌مدت: پردازش ویدیو چندوجهی به‌صورت ناهمزمان در مدت زمان طولانی انجام می‌شود. LongRunningFunctionTool را با رسیدهای تماس معلق پیاده‌سازی می‌کنید تا گردش کار را براساس شناسه تماس تعلیق و ازسر بگیرید، و خط لوله تکمیل‌شده را بااستفاده از ADK Runner در Cloud Run مستقر می‌کنید.

نحوه سازمان‌دهی این codelab

این codelab به‌عنوان مرجع مفهومی و معماری شما عمل می‌کند. هر بخش ساختارهای ADK پیاده‌سازی‌شده در مرحله میز کار مربوطه را توضیح می‌دهد، کد مرجع ارائه می‌دهد، و اصول طراحی اصلی را تعیین می‌کند. قبل‌از تکمیل تمرین مربوطه در میزکار، هر بخش را مرور کنید.

کار عملی در میز کار VibeStudio انجام می‌شود، یک میانای وب همراه که دارای ویرایشگر کد تعاملی، درستی‌سنج‌های زمان اجرا، و بازرس ADK جاسازی‌شده است. شماره‌گذاری مرحله در میز کار مستقیماً با این کدآزمایی هم‌تراز است تا پیشرفت شما همگام‌سازی شود. ویرایش‌های نمودار بنیادی در سراسر مراحل باقی می‌مانند و میزکار به‌طور خودکار پیش‌نیازها را با پیشرفت شما تأیید می‌کند.

پس‌از تکمیل تمرین‌های میز کار، یک خط لوله عاملی سرتاسری را مونتاژ خواهید کرد و یک برنامه VibeStudio درحال اجرا را در Cloud Run مستقر خواهید کرد تا محتوای ویدیویی تولید کنید.

چه چیزی کجا اجرا می‌شود: VibeStudio Workbench، پسای شما، و سرویس‌های Google Cloud

این محیط از سه مؤلفه اصلی تشکیل شده است: VibeStudio Workbench (میانای وب محلی برای ویرایش کد و درستی‌سنجی زمان اجرا)، بخش باطنی شما (جعبه‌های امن ADK Workflow و مرحله در agent/)، و Google Cloud (مدل‌های Gemini،‏ GEAP Memory Bank،‏ RAG Engine، و تولید ویدیو Veo).

۲. راه‌اندازی

اعتبارهای کارگاهتان را مطالبه کنید

اگر در آزمایشگاه تحت رهبری مربی شرکت می‌کنید، مربی اعتبار پروژه 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 را فشار دهید تا پروژه جدیدی به‌طور خودکار ایجاد شود. اگر ترجیح می‌دهید از پروژه موجودی (مثل پروژه ازپیش اختصاص‌داده‌شده) استفاده کنید، شناسه پروژه‌تان را وارد کنید و مطمئن شوید که املا درست است و صورت‌حساب فعال است.
  • کد رویداد: کد اتاق ارائه‌شده توسط مدرستان را وارد کنید. اگر آن را دریافت نکرده‌اید، از دستیار معلم یا همسایه بپرسید. اگر این آزمایشگاه را در خانه تکمیل می‌کنید، برای پذیرفتن اتاق پیش‌فرض sandbox، کلید Enter را فشار دهید.
  • نام نمایشی کانال: وقتی setup_codelab.sh از شما خواست، نام یا نام کاربری کانال موردنظرتان را وارد کنید، یا برای پذیرفتن نام پیش‌فرض تولیدشده از حساب Google خود، کلید ورود را فشار دهید.

دو دستورگان راه‌اندازی را به‌ترتیب اجرا کنید:

./setup_project.sh
./setup_codelab.sh
  • setup_project.sh: پروژه Google Cloud را با صورت‌حساب فعال ایجاد می‌کند یا دوباره استفاده می‌کند، شناسه پروژه را در ~/project_id.txt ذخیره می‌کند، و زمینه فعال gcloud را پیکربندی می‌کند.
  • setup_codelab.sh: uv و وابستگی‌های Python را در .venv نصب می‌کند، Google Cloud APIهای لازم را فعال می‌کند، تنظیمات کانال شما را در .env پیکربندی می‌کند، دسترسی مدل را با Gemini تأیید می‌کند، منابع Memory Bank و RAG را تأمین می‌کند، میانای میزکار را می‌سازد، و 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

روی آن پیوند کلیک کنید. همین نشانی در پیش‌نمایش وب ← تغییر درگاه ← ۴۶۰۰ دردسترس است.

برای بررسی مجدد محیط در هر زمانی، python scripts/preflight.py را اجرا کنید. برای بازراه‌اندازی میزکار، scripts/restart.sh را اجرا کنید. برای راه‌اندازی مجدد، ./setup_codelab.sh را اجرا کنید؛ این کار پیکربندی و پیشرفت شما را حفظ می‌کند.

وقتی باز شد، مرحله ۱، داستان را برای سناریو و مرحله ۲، آنچه می‌سازید را برای شکل نمودار نهایی بخوانید. هیچ‌کدام تمرین ندارند. سپس برای مرحله ۳ به اینجا برگردید.

هر بخش عملی از «میز کار VibeStudio» با یک پانل درستی‌سنجی که آرتیفکت‌های واقعی را می‌خواند پایان می‌یابد: فایل روی دیسک و جلسه‌هایی که توسط اجراها نوشته شده است.

چیدمان مخزن

مخزن به منطق گردش کار اصلی، محیط‌های ایمن گام‌به‌گام، محیط میز کار، و برنامه تولید تقسیم شده است:

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 Memory Bank،‏ GEAP RAG Engine، و ترکیب ویدیویی Veo، تعامل برقرار می‌کند.
  • stage0_prompt/ تا stage6_video/: محیط‌های جعبه شنی مستقل. هر پوشه یک root_agent مستقل صادر می‌کند تا بتوانید هر مرحله را به‌صورت مجزا ازطریق رابط توسعه ADK جاسازی‌شده اجرا و بازرسی کنید.
  • server/ و web/: برنامه VibeStudio Workbench که به‌صورت محلی در درگاه ۴۶۰۰ اجرا می‌شود. این صفحه میزبان اسناد مرحله، ویرایشگر کد درون‌صفحه‌ای، درستی‌سنج‌های شواهد زمان اجرا، و دیداری‌سازی نمودار است.
  • vibestudio/: برنامه تولید کامل که در مرحله نهایی بسته‌بندی و در Cloud Run مستقر شده است. این گره حاوی نسخه مستقل خود از گراف گردش کار تکمیل‌شده است.

۳. عامل یکپارچه

قبل‌از ساختن گراف گردش کار چندگره‌ای، با یک عامل در stage0_prompt/agent.py خط مبنای معماری ایجاد می‌کنید. این عامل به پیام‌واره سیستم یکپارچه‌ای متکی است که خط تولید را به‌صورت نثر توصیف می‌کند و دو ابزار تابع Python از آن پشتیبانی می‌کنند.

ارزیابی این خط مبنا مرزهای عملیاتی هماهنگی پیام‌واره‌محور را نشان می‌دهد و مشخص می‌کند چرا سیستم‌های تولید به سازمان‌دهی گراف نیاز دارند.

معماری عامل ADK (3A)

در میز کار VibeStudio، به مرحله ۳ · عامل یکپارچه پیمایش کنید و معماری عامل ADK (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)

در میز کار، به مشخصات عامل یکپارچه (3B) بروید. stage0_prompt/agent.py را باز کنید تا تعریف عامل پایه را بررسی کنید:

  • دستور پیام‌واره تکی: پیام‌واره سیستم پنج تکلیف تولید متمایز را در یک نثر پیوسته خلاصه می‌کند: کشف گرایش‌های پلاتفرم، مرور ایده‌های معوقه، پیشنهاد مفاهیم خلاقانه، اعمال خط‌مشی‌های موضوعات ممنوعه، و پیش‌نویس کردن فهرست‌های عکس.
  • منابع داده‌های زیربنایی: عامل به دو منبع تعریف‌شده در کنار نمودار ارجاع می‌دهد:
    • ‫agent/trends.py: ده گرایش فعال قالب و سبک را از مجموعه‌ای متشکل از ۲۵۰ گرایش با امتیازهای حرارتی پویا نمونه‌برداری می‌کند.
    • ‫agent/backlog.txt: یادداشت‌های مفهومی خام محتواساز را خط‌به‌خط می‌خواند.

Tools in Agent (3C)

در میزکار، به ابزارها در نماینده (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 کلیک کنید تا میانای توسعه 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. نماینده بلافاصله تأیید را دور می‌زند و عنوان و نماها را پیش‌نویس می‌کند.
    • دلیل: دستورالعمل‌های پیام‌واره به‌جای موانع قطعی، رهنمودهای مشاوره‌ای هستند. در یک عامل یکپارچه، دستورالعمل‌های کاربر می‌توانند قوانین پیام‌واره سیستم دائمی را لغو کنند زیرا هیچ گردش کار خارجی جریان اجرا را کنترل نمی‌کند.

محدودیت‌های معماری پیام‌واره یکپارچه

درحالی‌که یک پیام‌واره می‌تواند خروجی قابل‌قبولی برای نسخه‌های نمایشی مجزا تولید کند، آزمایش شرایط مرزی در درستی‌سنج میزکار محدودیت‌های حیاتی سازمانی را آشکار می‌کند:

  • انبوهش پژوهش بدون ساختار: ترتیب اجرای ابزار غیرقطعی است. مدل داده‌های بازیابی‌شده را به‌صورت نثر آزاد خلاصه می‌کند، که این امر باعث می‌شود سیستم‌های پایین‌دستی نتوانند منبعی را که ادعاهای خاصی را تولید کرده است جدا کنند.
  • اجرای خط‌مشی تأییدنشده: مدل رعایت ایمنی خود را ارزیابی می‌کند. اگر مدل تشخیص دهد موضوعی ایمن است، هیچ منطق قطعی خارجی‌ای این یافته را تأیید نمی‌کند.
  • توقف‌های غیرالزامی با مشارکت انسانی در حلقه: دستورالعمل‌های پیام‌واره که تأیید محتواساز را درخواست می‌کنند، مشاوره‌ای هستند. ارسال پیام پیگیری که به مدل دستور می‌دهد سؤالات را دور بزند، باعث می‌شود مدل تأیید انسانی را کاملاً نادیده بگیرد.

این شکاف‌های معماری باعث می‌شود که عامل یکپارچه به گردش کار نمودار صریح ساخته‌شده در مرحله بعدی تجزیه شود.

۴. اصول اولیه گردش کار عامل‌گرا

در میز کار VibeStudio، به مرحله ۴ · اصول گردش کار عامل‌گرا، بخش‌های ۴A تا ۴D بروید.

این مرحله از خط مبنای تک‌عاملی به هماهنگ‌سازی گراف قطعی بااستفاده از ADK Workflow منتقل می‌شود. یک انشعاب پژوهشی موازی خواهید ساخت، شاخه‌ها را با گره اتصال همگام‌سازی خواهید کرد، نامزدهای خلاقانه با طرح‌واره معتبر تولید خواهید کرد، و یک دروازه تأیید قطعی با مشارکت انسانی در حلقه معرفی خواهید کرد.

معماری گراف و زنجیره‌های اجرا (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 مستقل. ‫ADK گردش‌های کار را به‌عنوان عاملان درجه یک درنظر می‌گیرد و اجازه می‌دهد کل گراف به‌عنوان یک برنامه یکپارچه بارگیری، ارائه، و بازرسی شود. name برنامه را در ADK Web ثبت می‌کند، درحالی‌که فهرست edges توپولوژی اجرای آن را تعریف می‌کند.

گسترش موازی پژوهش (۴ میلیارد)

در میز کار، به پژوهش موازی (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)])

تغییراتتان را ذخیره کنید. تأییدکننده میزکار تأیید می‌کند که اتصال و لبه‌ها سیم‌کشی شده‌اند. مرحله را بااستفاده از اجرای مرحله ۱ یا ازطریق میانای وب ADK جاسازی‌شده اجرا کنید.

چه انتظاری باید داشته باشید و چرا

  • اجرای هم‌زمان خواننده: در نمودار اجرا، scan_trends و read_backlog به‌طور هم‌زمان اجرا می‌شوند.
    • دلیل: هر دو زنجیره از START شروع می‌شوند. موتور ADK شاخه‌های مستقل را به‌طور هم‌زمان زمان‌بندی می‌کند.
  • برونداد واژه‌نامه انبوهشی: گردش کار در join_research تکمیل می‌شود و واژه‌نامه‌ای با ورودی‌های هر دو خواننده برونداد می‌کند.
    • دلیل: JoinNode تضمین می‌کند که داده‌ها به‌طور کامل ضبط شوند و سپس به گره‌های بعدی اجازه اجرا می‌دهد.

گره‌های عامل (4C)

در میز کار، به گره‌های عامل (4C) بروید. ‫stage2_direction/agent.py را باز کن.

04-4C

حالت‌های عملکرد و طرحواره‌های ساخت‌یافته

وقتی Agent در Workflow جاسازی شده باشد، به‌طور پیش‌فرض در حالت 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 به مدل دستور می‌دهد چهار نامزد را با استناد به شواهد برگرفته از روندها و کارهای معوقه پیشنهاد دهد. نامزدهای ۱ تا ۳ مفاهیم کانال قابل‌اجرایی ارائه می‌دهند. نامزد ۴ عمداً مفهومی ناقض خط‌مشی را معرفی می‌کند تا دروازه ایمنی را در مرحله بعدی آزمایش کند.

ویرایش عملی: تعریف گره عامل و زنجیره‌سازی پیوستن

در 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 معتبری مطابق با طرحواره و شناسه وقفه ارسال شود.

ویرایش عملی: تعلیق کردن اجرای «درخواست ورودی»

در 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 یا میانای میزکار، اجرا موقتاً متوقف می‌شود و فرم انتخاب نامزد تعاملی نمایش داده می‌شود.
    • دلیل: موتور با RequestInput تسلیم‌شده مواجه شد و وضعیت اجرا را در runs/sessions.db حفظ کرد.
  • ازسرگیری نیاز به ورودی ساختاریافته دارد: ارسال نوشتار گپ دلخواه باعث پیشرفت نمودار نمی‌شود. انتخاب یک گزینه (۱، ۲، ۳، یا ۴) function_response تایپ‌شده‌ای را که response_schema را برآورده می‌کند ارسال می‌کند و اجرا را ازسر می‌گیرد.

۵. ایالت و رهیاب

در میز کار VibeStudio، به مرحله ۵ · وضعیت و مسیریاب، بخش‌های (۵A) تا (۵C) بروید.

انتخاب‌های کاربر را در وضعیت جلسه حفظ می‌کنید، خط‌مشی‌های ایمنی کانال را بااستفاده از گره‌های مسیریاب قطعی اجرا می‌کنید، و کارگزاری وظیفه تکرارشونده‌ای را برای اصلاح خودکار نقض‌های خط‌مشی قبل‌از تولید کردن متن‌های ویدیو مونتاژ می‌کنید.

وضعیت گردش کار (5A)

در میزکار، به وضعیت گردش کار (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 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)

فایل‌هایتان را ذخیره کنید. در میزکار، بررسی کنید که state write in place و persist_direction in the chain هر دو علامت تیک سبز را نشان دهند.

گره رهیاب (۵ میلیارد)

در میز کار، به گره رهیاب (5B) بروید.

05-5B

مسیریابی خط‌مشی قطعی

رهیاب گره عملکردی تخصصی است که برونداد بالادستی را ارزیابی می‌کند و اجرا را در امتداد شاخه‌های گراف شرطی هدایت می‌کند. برخلاف کارگزاران زایا، مسیریاب منطق قطعی را بدون فراخوانی LLM اجرا می‌کند.

رهیابی 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 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)])

فایل‌هایتان را ذخیره کنید. در میز کار، تأیید کنید که نگاشت‌های لبه مسیریاب درستی‌سنجی شده‌اند.

حالت‌های Agent و گره تکلیف (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 آزمایش کنید:

  • مسیر تأییدشده (نامزد ۱، ۲، یا ۳):
    • انتخاب کردن نامزد تأییدشده مسیرها را از policy_check مستقیماً به scripter (route="OK") هدایت می‌کند.
    • نویسنده دستورگان یک دستورگان تولید ۳نمایی مطابق با طرح‌واره Script تولید می‌کند.
  • مسیر اصلاح قرنطینه (نامزد ۴):
    • گزینه ۴ حاوی واژگان پرچم‌گذاری‌شده است («طعمه کلیک»، «ترفند ویروسی»).
    • ‫policy_check مسیر به quarantine (route="BLOCK").
    • در ردیابی جلسه، مشاهده کنید که quarantine برای هر نقض find_policy_hits را فرا می‌خواند، suggest_replacement را فرا می‌خواند، عنوان را بازنویسی می‌کند، و finish_task را فرا می‌خواند.
    • اجرا به scripter می‌پیوندد و از دستورالعمل پالایش‌شده، دستورگان تولید می‌کند.

‫۶. بانک حافظه

در VibeStudio Workbench، به مرحله ۶ · بانک حافظه، بخش‌های (۶A) و (۶B) بروید.

درحال‌حاضر گردش کار بدون حافظه در جلسات عمل می‌کند. هر اجرا از ابتدا شروع می‌شود و از آنچه محتواساز قبلاً انتخاب کرده یا ژانرهایی که ترجیح می‌دهد بی‌اطلاع است. در این مرحله، بانک حافظه 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 ذخیره شده است.

درحال راه‌اندازی «بانک حافظه»

از کنترل‌های میزکار استفاده کنید یا فرمان‌های CLI را در ترمینال خود اجرا کنید:

  1. اتصال و آماده‌سازی بانک:
    python -m agent.platform.bank
    
    نمونه «موتور عامل» را ایجاد می‌کند و موضوع‌های CREATOR_TASTE و CHANNEL_RULES را پیکربندی می‌کند.
  2. جلسه‌های تاریخی مبنا:
    python -m agent.platform.bank load
    
    چهار جلسه محتواساز تاریخی را بار می‌کند (دو طرح زمینه حیوانات با محدودیت‌های سبک، یک طرح زمینه ابزار، و یک طرح زمینه فانتزی اخیر).
  3. بازرسی حقایق یکپارچه:
    python -m agent.platform.bank list
    
    برونداد را بررسی کنید. توجه کنید که چگونه ترانویسی‌های روایی به اظهارات واقعی ساختاریافته و یکپارچه تبدیل شده‌اند.

بازخوانی‌ها (۶ب)

در میزکار، به Callbacks (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

اطراف هر تماس استنتاج LLM

‫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 مسیرهای پیشنهادی را تولید کند اجرا می‌شود. این ابزار سابقه محتواساز را از «بانک حافظه» واکشی می‌کند، خاطرات را از قدیمی‌ترین به جدیدترین قالب‌بندی می‌کند، و آن‌ها را به LlmRequest خروجی اضافه می‌کند. پیام‌واره مدل را هدایت می‌کند تا گزینه‌های ۱ تا ۳ را به سمت سلیقه فعلی محتواساز متمایل کند و درعین‌حال قوانین کانال را به‌عنوان محدودیت‌های سخت‌گیرانه درنظر بگیرد.

  1. در stage4_memory/agent.py، scripter را به‌روز کنید تا after_agent_callback=remember_pick را پیوست کنید:
    output_schema=Script,
    after_agent_callback=remember_pick)

remember_pick پس‌از اینکه scripter نوبتش را تمام کرد اجرا می‌شود. این ابزار جهت انتخاب‌شده را از وضعیت جلسه می‌خواند، بیانیه مختصری را که تصمیم محتواساز را خلاصه می‌کند ترکیب می‌کند، و memories.generate را برای به‌روزرسانی «بانک حافظه» فراخوانی می‌کند.

آنچه انتظار می‌رود و چرا

گردش کار تقویت‌شده با فراخوانی برگشتی را در میزکار یا ADK Web آزمایش کنید:

  1. اجرای یک اجرا با پیام‌واره خالی:
    • در ردیابی جلسه، LlmRequest را برای propose_directions بازرسی کنید. به بافت حافظه پیوست‌شده توجه کنید که اولویت محتواساز برای زمینه‌های فانتزی و سرعت مختصر را شرح می‌دهد.
    • جهت‌های پیشنهادی را مشاهده کنید: نامزدهای ۱ تا ۳ با اولویت‌های تاریخی محتواساز همسو هستند، حتی زمانی که گرایش‌ها بر موضوعات دیگر تأکید دارند.
  2. نامزدی را در direction_gate انتخاب کنید.
  3. پس‌از تکمیل scripter، سوابق «بانک حافظه» را مرور کنید:
    python -m agent.platform.bank list
    
    اکنون بانک جدیدترین انتخاب را نشان می‌دهد و آن را با سوابق سلیقه قبلی ادغام می‌کند.

‫۷. موتور RAG

در VibeStudio Workbench، به مرحله ۷ · موتور RAG، بخش‌های (۷A) و (۷B) بروید.

07-7A

ویدیوهای منتشرشده بازخورد مداوم بینندگان را جمع‌آوری می‌کنند. سی نظر نمونه در agent/comments.md جمع‌آوری شده است که شامل تمجیدهای بینندگان، انتقاد از سرعت محتوای دارای حامی مالی، و اولویت‌های صوتی است. در این مرحله، این نظرات را بااستفاده از Vertex AI RAG Engine نمایه‌سازی می‌کنید و بازیابی معنایی را به توزیع پژوهش متصل می‌کنید.

بازیابی اسناد (7A)

در میزکار، به RAG Engine (7A) پیمایش کنید.

Memory Bank درمقابل RAG Engine

هر دو ابزار گردش‌های کاری را در داده‌های خارجی پایه‌مند می‌کنند، اما اهداف معماری متمایزی را دنبال می‌کنند:

ابعاد

بانک حافظه

RAG Engine

مورد استفاده اصلی

اولویت‌های کاربر بلندمدت و قوانین عملیاتی

بازیابی معنایی در مجموعه‌های بزرگ اسناد

حوزه

محدود به شناسه‌های کاربر و نام‌های برنامه

محدود به منابع مجموعه مشترک در بین همه کاربران

پردازش داده

استخراج، جاسازی، و ادغام معنایی هم‌زمان

تکه‌تکه کردن سند، جاسازی برداری، و جستجوی نزدیک‌ترین همسایه

یکپارچه‌سازی گراف

فراخوانی‌های چرخه حیات عامل (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)))
  • اندازه تکه: روی ۱۲۰ کد با ۲۰ کد هم‌پوشانی پیکربندی شده است. این کار دو تا سه نظر را در هر بخش ضبط می‌کند و تضمین می‌کند که هر بردار نشان‌دهنده یک احساس منسجم است، بدون اینکه معنی در بازخوردهای نامرتبط رقیق شود.
  • مدل جاسازی: text-embedding-005 نوشتار را به بردارهای با ابعاد بالا تبدیل می‌کند. وقتی پُرسمانی ارسال می‌شود، مدل پُرسمان را به بردار تبدیل می‌کند و براساس فاصله معنایی نزدیک‌ترین مطابقت‌ها را پیدا می‌کند. نظری درباره یک اژدهای کوچک که از جوراب‌ها محافظت می‌کند، با پیام‌واره‌ای درباره موجودات جادویی مطابقت دارد، بدون اینکه نیاز به هم‌پوشانی دقیق کلیدواژه‌ها باشد.

درحال راه‌اندازی پیکره RAG

بااستفاده از دکمه‌های میز کار یا فرمان‌های پایانه، پیکره را مقداردهی اولیه کنید:

  1. ایجاد کردن پیکره:
    python -m agent.platform.rag
    
    پایگاه داده برداری مدیریت‌شده را تأمین می‌کند و شناسه منبع را در runs/ragcorpus.json ثبت می‌کند.
  2. بارگذاری و نمایه‌سازی نظرات: agent/comments.md را با پیکربندی تکه‌تکه کردن بارگذاری می‌کند و منتظر می‌ماند تا نمایه‌سازی کامل شود.
  3. پرسش از مجموعه داده‌ها: بازیابی شباهت را با پُرسمان‌هایی که کلمات دقیق را با نظرات هم‌رسانی نمی‌کنند آزمایش کنید (برای مثال، پُرسمان «موجودات جادویی کوچک» را برای بازیابی نظرات درباره اژدها انجام دهید).

گره بازیابی (7B)

در میز کار، به The third reader (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 ایده اولیه کاربر را استخراج می‌کند و پُرسمان برداری را در پیکره «موتور RAG» اجرا می‌کند. نظرات بازیابی‌شده را در یک بار 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 قطعی است (پُرسمان‌های یکسان بخش‌های نظر یکسانی را برمی‌گردانند)، درحالی‌که گره پیشنهاد زایا گونه‌های خلاقانه‌ای تولید می‌کند.

‫۸. تولید ویدیو ناهمزمان با Veo

در میزکار VibeStudio، به مرحله ۸ · ویدیو، بخش‌های (۸A) و (۸B) بروید.

تولید ویدیو با وضوح بالا با Google Veo چند دقیقه برای هر پردازش زمان می‌برد. مسدود کردن اجرای گراف در این دوره باعث هدر رفتن منابع محاسباتی، قفل شدن استخرهای رشته، و درمعرض قطع اتصال HTTP قرار گرفتن اجرا می‌شود. در این مرحله، بااستفاده از LongRunningFunctionTool ADK، پردازش ویدیو را ناهمگام می‌کنید.

ابزارهای طولانی‌مدت (8A)

در میز کار، به ابزار طولانی‌مدت (8A) پیمایش کنید. stage6_video/agent.py و agent/deliver.py را باز کنید.

08-8A

ابزارهای همگام درمقابل ابزارهای طولانی‌مدت

ابزارهای تابع «کیت توسعه تبلیغات» استاندارد به‌صورت هم‌زمان در نوبت کارگزار اجرا می‌شوند: مدل ابزار را فرا می‌خواند، منتظر محتوای برگشتی می‌ماند، و نتیجه را در نوبت جاری ادغام می‌کند.

پرداخت ویدیو نمی‌تواند در یک نوبت تکمیل شود. درعوض، 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)])

ازسرگیری با شناسه تماس

الگوی ازسرگیری جهانی

ADK از سازوکار یکسانی برای تعلیق و ازسرگیری گردش کار برای انسان‌ها و ابزارهای خارجی استفاده می‌کند:

راه‌انداز تعلیق

درحال راه‌اندازی Construct

وضعیت تعلیق ذخیره‌شده

رویداد ازسرگیری

تصمیم انسانی

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)

در میز کار، به render_desk در نمودار (8B) بروید. ‫stage6_video/agent.py را باز می‌کند.

گره پایانی در خط لوله store_video است. این مرحله اطلاعات رندر تکمیل‌شده را از runs/state.json (جایی که فرایند تحویل آن را ضبط کرده است) می‌خواند و نشانی وب ویدیو و وضعیت تولید را در وضعیت جلسه هم‌رسانی‌شده ثبت می‌کند.

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. بااستفاده از کنسول میزکار یا در پایانه، دیمن تحویل را اجرا کنید:
    python -m agent.deliver
    
    فرایند تحویل Veo را تا زمانی که ویدیو آماده شود نظارت می‌کند، سپس رویداد ازسرگیری را ارسال می‌کند.
  5. در ADK Web، جلسه را بازآوری کنید: اجرا در store_video ازسر گرفته می‌شود، نشانی وب ویدیو را به وضعیت جلسه ارسال می‌کند، و گردش کار را تکمیل می‌کند.

‫۹. مستقر کردن در Cloud Run

در میز کار VibeStudio، به مرحله ۹ · استقرار پیمایش کنید.

هر مؤلفه از خط لوله را در محیط‌های آزمایشی اختصاصی توسعه داده و درستی‌سنجی کرده‌اید. در این مرحله، خط لوله تولید کامل را مونتاژ می‌کنید و آن را در Google Cloud Run مستقر می‌کنید.

09-9A

دونده ADK

در توسعه، 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 backend رویدادها را در یک جاری‌سازی Server-Sent Events (SSE) تکی منتشر می‌کند. React frontend visualizes graph progression in real time and handles late connections without losing state.
  • اجرای جداشده: برنامه حلقه رویداد را مدیریت می‌کند. نمودار گردش کار کاملاً بر منطق اجرا تمرکز دارد و از میانای پیش‌نما بی‌اطلاع است.

فهرست کامل لبه گردش کار در agent/graph.py همه الگوهای معماری ساخته‌شده در سراسر این codelab را ترکیب می‌کند:

        (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 بازه‌های توزیع‌شده را برای هر گره، تماس LLM، و اجرای ابزار ضبط می‌کند که در «کنسول Google Cloud» در بخش «کاوشگر ردیابی» دردسترس است.

برای اجرای دستورگان استقرار، روی دکمه استقرار در میز کار کلیک کنید. وقتی ساخت تکمیل شد، پایانه نشانی وب سرویس زنده را نمایش می‌دهد.

برنامه

‫۱۰. خلاصه

در میز کار VibeStudio، به مرحله ۱۰ · خلاصه بروید تا معماری تکمیل‌شده را بررسی کنید.

10-summary

مرحله

معماری و مفاهیم

الگوی پیاده‌سازی

یک پیام‌واره

پیام‌واره تکی، ابزارهای تابع، حلقه گپ متوالی

Agent(tools=[...])، function_call / function_response

مبانی گردش کار عامل‌گرا

نمودار گردش کار، پژوهش موازی، بروندادهای طرح‌واره، دروازه انسانی

‫Workflow،‏ START،‏ JoinNode،‏ output_schema،‏ RequestInput

ایالت و رهیاب

وضعیت جلسه مشترک، اتصال پارامتر، مسیریابی قطعی، عامل تکلیف

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

بانک حافظه

حافظه بلندمدت در سطح کاربر، ادغام معنایی، قلاب‌های چرخه حیات

‫memories.generate / retrieve،‏ before_model_callback،‏ after_agent_callback

RAG Engine

بازیابی سند ازطریق نظرات مخاطبان، جاسازی‌های معنایی

گره rag.create_corpus، RagEmbeddingModelConfig، read_feedback

تولید ویدیو ناهمگام با Veo

ابزارهای طولانی‌مدت، رسیدهای معلقه، شبح تحویل خارجی

‫LongRunningFunctionTool،‏ FunctionResponse(id=...) ازسرگیری

مستقر کردن در Cloud Run

هماهنگ‌سازی برنامه‌ریزی‌شده، رویدادهای ارسالی سرور، حامل بدون سرور

Runner(agent=wf)، run_async، استقرار Cloud Run

اصول معماری اصلی

  1. به‌جای انتظار، تعلیق کنید: گردش‌های کار برای ورودی انسانی (RequestInput) یا عملیات طولانی‌مدت (LongRunningFunctionTool) به‌طور تمیز متوقف می‌شوند. فرایندها در رشته‌ها یا سوکت‌های شبکه در حالت بیکار منتظر نمی‌مانند.
  2. ازسرگیری جهانی: هر تعلیق ازطریق یک سازوکار یکسان ازسر گرفته می‌شود: یک function_response که شناسه تماس گره تعلیق‌شده را حمل می‌کند.
  3. مدیریت وضعیت جداشده: گره‌ها داده‌ها را ازطریق کلیدهای وضعیت جلسه نام‌گذاری‌شده و اتصال پارامتر به‌جای باربرهای میانی پرحرف و محکم جفت‌شده هم‌رسانی می‌کنند.
  4. مسیریابی قطعی قبل‌از هزینه تولید: مسیریاب‌های مبتنی بر قانون و فیلترهای عبارت باقاعده، خط‌مشی را با هزینه صفر کد قبل‌از اجرای مدل‌های تولیدی ارزیابی می‌کنند.
  5. جداسازی نگرانی‌ها: زمینه مختص به یک عامل در برگشت‌های تماس چرخه حیات قرار دارد، درحالی‌که وابستگی‌های داده هم‌رسانی‌شده

10-output