ساخت سیستم‌های چندعاملی با ADK

۱. مقدمه

نمای کلی

این آزمایشگاه به شما می‌آموزد که چگونه سیستم‌های پیچیده و چندعاملی را با استفاده از کیت توسعه عامل گوگل (Google ADK) هماهنگ کنید. شما از سلسله مراتب ساده عامل‌ها به سمت ساخت گردش‌های کاری خودکار و مشارکتی حرکت خواهید کرد.

آنچه خواهید ساخت

شما دو سیستم چندعاملی مجزا خواهید ساخت:

• یک نماینده ساده برنامه‌ریزی سفر که یاد می‌گیرد مکالمات بین یک نماینده «طوفان فکری» و یک نماینده «برنامه‌ریزی جاذبه‌ها» را منتقل کند.
• یک مولد پیشرفته‌تر ارائه فیلم که از یک «اتاق نویسنده» متشکل از عوامل خودکار (مانند محقق، فیلمنامه‌نویس و منتقد) برای همکاری در یک حلقه برای ایجاد یک طرح کامل فیلم استفاده می‌کند.

آنچه یاد خواهید گرفت

• نحوه ایجاد روابط والد و زیرعامل.
• نحوه نوشتن داده‌ها در state جلسه از یک ابزار.
• چگونه با استفاده از قالب‌بندی کلید (مثلاً {my_key?} ) از state بخوانیم؟
• نحوه استفاده از SequentialAgent برای گردش‌های کاری گام به گام.
• نحوه استفاده از LoopAgent برای ایجاد چرخه‌های اصلاح تکراری.
• نحوه استفاده از ParallelAgent برای اجرای همزمان وظایف مستقل.

۲. سیستم‌های چندعاملی

کیت توسعه عامل (ADK) به توسعه‌دهندگان این امکان را می‌دهد تا رفتارهای چند مرحله‌ای، پیچیده‌تر و قابل اعتمادتری را از مدل‌های مولد دریافت کنند. ADK به جای یک دستور پیچیده، به شما امکان می‌دهد جریانی از چندین عامل ساده‌تر ایجاد کنید که با تقسیم کار، روی یک مسئله همکاری می‌کنند.

این رویکرد نسبت به استفاده از یک اعلان تکی و یکپارچه چندین مزیت دارد:

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

درخت سلسله مراتبی عامل‌ها

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

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

کل ساختار با root_agent شروع می‌شود. این عامل به عنوان والد عمل می‌کند و می‌تواند یک یا چند زیرعامل داشته باشد که به نوبه خود می‌توانند والد زیرعامل‌های خود نیز باشند و درخت را تشکیل دهند.

۳. راه‌اندازی پروژه

حساب گوگل

اگر از قبل حساب گوگل شخصی ندارید، باید یک حساب گوگل ایجاد کنید .

به جای حساب کاری یا تحصیلی از حساب شخصی استفاده کنید .

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

ورود به کنسول ابری گوگل

با استفاده از یک حساب کاربری شخصی گوگل، وارد کنسول ابری گوگل شوید.

فعال کردن صورتحساب

استفاده از اعتبار ۵ دلاری گوگل کلود (اختیاری)

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

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

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

یک حساب پرداخت شخصی تنظیم کنید

اگر صورتحساب را با استفاده از اعتبارهای Google Cloud تنظیم کرده‌اید، می‌توانید از این مرحله صرف نظر کنید.

برای تنظیم یک حساب پرداخت شخصی، به اینجا بروید تا پرداخت را در کنسول ابری فعال کنید .

برخی نکات:

• تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
• شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
• کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.

ایجاد پروژه (اختیاری)

اگر پروژه فعلی ندارید که بخواهید برای این برچسب استفاده کنید، اینجا یک پروژه جدید ایجاد کنید .

۴. ویرایشگر Cloud Shell را باز کنید

1. برای دسترسی مستقیم به ویرایشگر Cloud Shell، روی این لینک کلیک کنید.
2. اگر امروز در هر مرحله‌ای از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید.
3. اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
   • روی مشاهده کلیک کنید
   • روی ترمینال کلیک کنید
4. در ترمینال، پروژه خود را با این دستور تنظیم کنید:

   gcloud config set project [PROJECT_ID]
   

   • مثال:

     gcloud config set project lab-project-id-example
     

   • اگر نمی‌توانید شناسه پروژه خود را به خاطر بیاورید، می‌توانید تمام شناسه‌های پروژه خود را با استفاده از دستور زیر فهرست کنید:

     gcloud projects list
     

     
5. شما باید این پیام را ببینید:

   Updated property [core/project].
   

   اگر یک WARNING مشاهده کردید و از شما پرسیده شد Do you want to continue (Y/n)? احتمالاً شناسه پروژه را اشتباه وارد کرده‌اید. n را فشار دهید، Enter را بزنید و دوباره سعی کنید دستور gcloud config set project را اجرا کنید.

۵. فعال کردن APIها

برای استفاده از Vertex AI API و تعامل با مدل Gemini، باید Vertex AI API را در پروژه Google Cloud خود فعال کنید.

1. در ترمینال، API را فعال کنید:

   gcloud services enable aiplatform.googleapis.com
   

بخش‌های به‌روزرسانی‌شده در اینجا آمده است که جایگزین ایجاد دستی فایل با دستورالعمل‌هایی برای کلون کردن مخزن GitHub و نصب وابستگی‌ها شده است.

مقدمه‌ای بر Vertex AI SDK برای پایتون

برای تعامل با مدل‌های میزبانی‌شده در Vertex AI از طریق برنامه پایتون خود، از Vertex AI SDK برای پایتون استفاده خواهید کرد. این SDK فرآیند ارسال اعلان‌ها، تعیین پارامترهای مدل و دریافت پاسخ‌ها را بدون نیاز به مدیریت مستقیم پیچیدگی‌های فراخوانی‌های API زیربنایی، ساده می‌کند.

می‌توانید مستندات جامع مربوط به Vertex AI SDK برای پایتون را اینجا پیدا کنید: مقدمه‌ای بر Vertex AI SDK برای پایتون | Google Cloud .

۶. محیط پروژه را تنظیم کنید

مخزن را کلون کنید

1. در ترمینال ، مخزن حاوی فایل‌های آغازگر را کلون کنید.

   git clone --depth 1 https://github.com/GoogleCloudPlatform/devrel-demos.git
   

   پرچم --depth 1 فقط آخرین نسخه را که سریع‌تر است، شبیه‌سازی می‌کند.
2. در ترمینال ، به دایرکتوری کاری صحیح برای این آزمایش بروید.

   cd devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   

فعال کردن یک محیط مجازی

3. در ترمینال ، با استفاده از uv یک محیط مجازی ایجاد و فعال کنید:

   uv venv
   source .venv/bin/activate
   

4. در ترمینال ، google-adk و سایر وابستگی‌ها را از فایل requirements.txt نصب کنید:

   uv pip install -r requirements.txt
   

ساختار فایل خود را بررسی کنید

حالا که همه فایل‌های شما ایجاد شده‌اند، پوشه adk_multiagent_systems را در اکسپلورر باز کنید تا ساختار کامل آن را ببینید.

1. در منوی ویرایشگر پوسته ابری، گزینه File > Open Folder... را انتخاب کنید.
   
   
2. در کادری که ظاهر می‌شود، اطلاعات پوشه زیر را بعد از نام کاربری خود اضافه کنید: devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems/ . روی تأیید کلیک کنید.
   باید چیزی شبیه به این باشد:
   
   
3. پنل اکسپلورر در سمت چپ رفرش می‌شود. اکنون باید ساختار کامل پروژه خود را به همراه زیرشاخه‌های parent_and_subagents و workflow_agents ببینید که برای مراحل بعدی آماده هستند.
   

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

تنظیم متغیرهای محیطی

1. شما در حال حاضر در دایرکتوری adk_multiagent_systems هستید. در ترمینال ، یک فایل .env برای ذخیره متغیرهای محیطی خود ایجاد کنید:

   cloudshell edit .env
   

2. موارد زیر را در فایل .env که در ویرایشگر باز می‌شود، قرار دهید:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
   GOOGLE_CLOUD_LOCATION=global
   MODEL="gemini-2.5-flash"
   

3. به جای [YOUR-PROJECT-ID] ، شناسه واقعی پروژه گوگل کلود خود را وارد کنید. (مثلاً PROJECT_ID = "google-cloud-labs" )
   اگر شناسه پروژه خود را به خاطر نمی‌آورید، دستور زیر را در ترمینال خود اجرا کنید. این دستور لیستی از تمام پروژه‌های شما و شناسه‌های آنها را به شما نشان می‌دهد.

   gcloud projects list
   

4. در ترمینال ، این فایل .env را در دایرکتوری‌های sub-agent کپی کنید تا آنها نیز بتوانند به متغیرها دسترسی داشته باشند:

   cp .env parent_and_subagents/.env
   cp .env workflow_agents/.env
   

   ساختار فایل اکنون باید به این شکل باشد:
   

۷. بررسی انتقال‌ها بین والد، زیرعامل و عامل‌های همتا

مکالمه همیشه با root_agent شروع می‌شود. به طور پیش‌فرض، یک عامل والد description زیرعامل‌های خود برای تصمیم‌گیری در مورد زمان انتقال مکالمه استفاده می‌کند. همچنین می‌توانید این انتقال‌ها را به طور صریح در instruction والد با استفاده از name زیرعامل‌ها هدایت کنید.

بیایید این را آزمایش کنیم.

1. در ویرایشگر Cloud Shell، adk_multiagent_systems/parent_and_subagents/agent.py را باز کنید. به سه عامل موجود در فایل agent.py توجه کنید:
   • root_agent (با نام steering ) : از کاربر سوالی می‌پرسد تا تصمیم بگیرد به کدام زیرعامل منتقل شود. در ابتدا، فقط به description زیرعامل‌های خود متکی است.
   • travel_brainstormer : به کاربر کمک می‌کند تا در مورد مقاصد مختلف ایده‌پردازی کند.
   • attractions_planner : به کاربر کمک می‌کند تا کارهایی را که باید در یک کشور خاص انجام دهد، فهرست کند.

   نکته: برای خواندن فایل agent.py به ترتیب جریان مکالمه، اغلب ساده‌ترین راه این است که از root_agent در پایین شروع به خواندن کنید و به ترتیب به بالا بروید. دلیل این امر این است که کد پایتون مستلزم آن است که قبل از اضافه کردن sub-agentها به یک agent، آنها را تعریف کنیم.

2. با اضافه کردن خط زیر به فایل ایجاد شده‌ی root_agent توابع travel_brainstormer و attractions_planner را به sub-agentهای root_agent تبدیل کنید:

       sub_agents=[travel_brainstormer, attractions_planner]
   

   نکته : سلسله مراتب عامل فقط توسط لیست sub_agents های والد تعریف می‌شود؛ زیرعامل‌ها به پارامتر parent نیاز ندارند.

3. در ترمینال ، با نماینده خود چت کنید:

   cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   adk run parent_and_subagents
   

4. در اعلان [user]: در ترمینال ، تایپ کنید:

   hello
   

   مثال خروجی (ممکن است خروجی شما کمی متفاوت باشد):

   [steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?
   

5. حالا، به اپراتور در ترمینال بگویید:

   I could use some help deciding.
   

   مثال خروجی (ممکن است خروجی شما کمی متفاوت باشد):

   [travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip.
   ...
   

   به تگ [travel_brainstormer] توجه کنید. root_agent کنترل را فقط بر اساس description sub-agent منتقل می‌کند.
6. در اعلان user: در ترمینال ، exit تایپ کنید و ENTER را فشار دهید تا مکالمه پایان یابد.
7. حالا بیایید واضح‌تر باشیم. در agent.py ، موارد زیر را به instruction root_agent اضافه کنید:

           If they need help deciding, send them to 'travel_brainstormer'.
           If they know what country they'd like to visit, send them to the 'attractions_planner'.
   

8. در ترمینال ، دوباره عامل را اجرا کنید:

   adk run parent_and_subagents
   

9. در اعلان [user]: در ترمینال ، تایپ کنید:

   hello
   

10. پاسخ با:

    I would like to go to Japan.
    

    مثال خروجی (ممکن است خروجی شما کمی متفاوت باشد):

    [attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan:
    ...
    

    به انتقال به attractions_planner ، طبق دستورالعمل‌های جدیدتان، توجه کنید.
11. حالا با این جمله پاسخ دهید:

    Actually I don't know what country to visit.
    

    مثال خروجی (ممکن است خروجی شما کمی متفاوت باشد):

    [travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...
    

    توجه داشته باشید که شما به travel_brainstormer ، یک همتای attractions_planner منتقل شده‌اید. این به طور پیش‌فرض مجاز است.

    اگر می‌خواهید از انتقال جلوگیری کنید، می‌توانید disallow_transfer_to_peers=True را روی عامل attractions_planner تنظیم کنید.

12. در اعلان کاربر، برای پایان دادن به جلسه exit تایپ کنید.

خلاصه

در این بخش، اصول اولیه سلسله مراتب اپراتورها و جریان مکالمه را آموختید:

• مکالمه همیشه با root_agent شروع می‌شود.
• یک عامل اصلی می‌تواند به طور خودکار بر اساس description به یک عامل فرعی منتقل شود.
• شما می‌توانید با دادن instruction والد برای انتقال به یک عامل فرعی با name آن، این جریان را به صراحت کنترل کنید.
• به طور پیش‌فرض، عامل‌ها می‌توانند به عامل‌های peer (خواهر و برادرها در سلسله مراتب) خود منتقل شوند.

۸. استفاده از session state برای ذخیره و بازیابی اطلاعات

هر مکالمه ADK یک Session دارد که شامل یک دیکشنری وضعیت جلسه است. این وضعیت برای همه عامل‌ها قابل دسترسی است و آن را به راهی ایده‌آل برای انتقال اطلاعات بین آنها یا نگهداری داده‌ها (مانند یک لیست) در طول مکالمه تبدیل می‌کند.

برای بررسی اضافه کردن به حالت و خواندن از آن:

1. به فایل adk_multiagent_systems/parent_and_subagents/agent.py برگردید
2. تعریف تابع زیر را بعد از سربرگ # Tools قرار دهید:

   def save_attractions_to_state(
   tool_context: ToolContext,
   attractions: List[str]
   ) -> dict[str, str]:
       """Saves the list of attractions to state["attractions"].
   
       Args:
           attractions [str]: a list of strings to add to the list of attractions
   
       Returns:
           None
       """
       # Load existing attractions from state. If none exist, start an empty list
       existing_attractions = tool_context.state.get("attractions", [])
   
       # Update the 'attractions' key with a combo of old and new lists.
       # When the tool is run, ADK will create an event and make
       # corresponding updates in the session's state.
       tool_context.state["attractions"] = existing_attractions + attractions
   
       # A best practice for tools is to return a status message in a return dict
       return {"status": "success"}
   

   در این کد، توجه کنید:
   • این تابع tool_context: ToolContext را دریافت می‌کند. این شیء، دروازه شما به جلسه (session) است.
   • خط tool_context.state["attractions"] = ... مستقیماً از دیکشنری وضعیت جلسه می‌خواند و در آن می‌نویسد. ADK بقیه کارها را انجام می‌دهد.
3. با اضافه کردن پارامتر tools ، ابزار را به agent attractions_planner اضافه کنید:

       tools=[save_attractions_to_state]
   

4. نکات زیر را به instruction موجود عامل attractions_planner اضافه کنید:

           - When they reply, use your tool to save their selected attraction and then provide more possible attractions.
           - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.
   

   به بخش داخل آکولاد توجه کنید: { attractions? } . این ویژگی ADK، key templating ، مقدار کلید attractions را از state به اعلان عامل تزریق می‌کند. علامت ? آن را اختیاری می‌کند و از بروز خطا در صورت عدم وجود کلید جلوگیری می‌کند.

5. رابط کاربری وب Agent Development Kit را با دستور زیر در ترمینال اجرا کنید:

   adk web
   

   خروجی

   INFO:     Started server process [2434]
   INFO:     Waiting for application startup.
   +-------------------------------------------------------+
   | ADK Web Server started                                |
   |                                                       |
   | For local testing, access at http://localhost:8000.   |
   +-------------------------------------------------------+
   
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
   

   توجه: اگر پورت ۸۰۰۰ در حال استفاده است، می‌توانید روی پورت دیگری اجرا کنید، برای مثال: adk web --port 8001 شماره پورت ورودی در مراحل بعدی باید به‌روزرسانی شود تا مطابقت داشته باشد.

6. در ترمینال Cloud Shell، روی دکمه‌ی «برای مشاهده‌ی رابط وب در یک برگه‌ی جدید»، « پیش‌نمایش وب» کلیک کنید و «تغییر پورت» را انتخاب کنید.
   
7. شماره پورت ۸۰۰۰ را وارد کنید و روی «تغییر و پیش‌نمایش» کلیک کنید. یک برگه مرورگر جدید با رابط کاربری ADK Dev باز خواهد شد.
   
8. از منوی کشویی «انتخاب یک عامل» در سمت چپ، گزینه‌ی parent_and_subagents را انتخاب کنید.
9. مکالمه را با این جمله شروع کنید: hello
10. بعد از اینکه مامور به شما سلام کرد، با این جملات پاسخ دهید:

    I'd like to go to Egypt.
    

    شما باید به attractions_planner منتقل شوید و لیستی از جاذبه‌ها را دریافت کنید.
11. برای مثال، یک جاذبه گردشگری انتخاب کنید:

    I'll go to the Sphinx
    

12. شما باید پاسخی مانند این دریافت کنید: بسیار خب، من ابوالهول را در لیست شما ذخیره کردم...
13. برای مشاهده رویداد ایجاد شده از پاسخ ابزار، روی کادر ابزار پاسخ (که با علامت تیک مشخص شده است) کلیک کنید.
    توجه کنید که شامل یک فیلد actions است که شامل stateDelta است که تغییرات در state را توصیف می‌کند.
14. با جاذبه دیگری از لیست آژانس پاسخ دهید.
15. در منوی پیمایش سمت چپ، روی «X» کلیک کنید تا از تمرکز روی رویدادی که قبلاً بررسی کرده‌اید، خارج شوید.
16. در نوار کناری سمت چپ، روی تب State کلیک کنید. اکنون می‌توانید آرایه attractions را در وضعیت session مشاهده کنید که باید شامل هر دو مورد انتخابی شما باشد.
17. این پیام را برای نماینده ارسال کنید:

    What is on my list?
    

    اکنون نماینده باید از ایالت بخواند و لیست شما را برگرداند.
18. وقتی آزمایش با عامل تمام شد، تب مرورگر وب را ببندید و CTRL + C را در ترمینال Cloud Shell فشار دهید تا سرور متوقف شود.

برای ذخیره کل پاسخ متنی یک عامل در state، می‌توانید هنگام تعریف عامل، یک پارامتر output_key تنظیم کنید و کل خروجی آن در دیکشنری state تحت نام آن فیلد ذخیره می‌شود.

خلاصه بخش

در این بخش، یاد گرفتید که چگونه از Session state برای اشتراک‌گذاری داده‌ها استفاده کنید:

• برای نوشتن state : شما از درون یک ابزار، با استفاده از شیء tool_context.state (مثلاً tool_context.state["my_list"] = [...] ) در دیکشنری state می‌نویسید.
• برای خواندن وضعیت : شما داده‌های وضعیت را مستقیماً با استفاده از قالب‌بندی کلید به instruction عامل تزریق می‌کنید (مثلاً، Here is your list: {my_list?} ).
• برای بررسی وضعیت : می‌توانید وضعیت جلسه را به صورت زنده در رابط کاربری ADK Dev با استفاده از تب State مشاهده کنید.

۹. عوامل گردش کار

تا اینجا، دیدید که چگونه یک عامل والد به یک عامل فرعی منتقل می‌شود و سپس منتظر کاربر می‌ماند. عامل‌های گردش کار متفاوت هستند: آن‌ها عامل‌های فرعی خود را یکی پس از دیگری در یک جریان خودکار، بدون انتظار برای ورودی کاربر، اجرا می‌کنند .

این برای کارهای خودکار و چند مرحله‌ای مانند «برنامه‌ریزی و اجرا» یا «پیش‌نویس و اصلاح» عالی است. ADK سه عامل گردش کار داخلی برای مدیریت این موارد ارائه می‌دهد:

• SequentialAgent
• LoopAgent
• ParallelAgent

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

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

در نهایت، سیستم شما به شکل زیر خواهد بود:

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

۱۰. ساخت یک سیستم چندعامله با SequentialAgent

یک SequentialAgent یک عامل گردش کار است که زیرعامل‌های خود را به صورت ساده و خطی اجرا می‌کند. هر عامل در لیست sub_agents خود، یکی پس از دیگری و به ترتیب اجرا می‌شود. این برای خطوط لوله‌ای که در آن‌ها وظایف باید به ترتیب خاصی انجام شوند، مانند عامل ارائه فیلم که اکنون خواهید ساخت، عالی است.

این نسخه اول به این شکل ساختاربندی خواهد شد:

• یک root_agent ( greeter ) به کاربر خوشامد می‌گوید و موضوع فیلم را دریافت می‌کند.
• سپس به یک SequentialAgent به نام film_concept_team منتقل می‌شود که:
  1. یک عامل researcher را برای دریافت حقایق از ویکی پدیا اجرا کنید.
  2. یک نماینده screenwriter استخدام کنید تا از آن حقایق برای نوشتن طرح داستان استفاده کند.
  3. برای ذخیره نمودار نهایی در یک فایل، یک عامل file_writer اجرا کنید.

بیایید آن را اجرا کنیم.

1. در ویرایشگر پوسته ابری ، adk_multiagent_systems/workflow_agents/agent.py را باز کنید.
   این فایل تعریف عامل را بخوانید. از آنجا که زیرعامل‌ها باید قبل از اینکه به والد اختصاص داده شوند، تعریف شوند، برای خواندن فایل به ترتیب جریان مکالمه، می‌توانید عامل‌ها را از پایین فایل به بالا بخوانید.
2. به ابزار append_to_state توجه کنید. این تابع کمکی به عامل‌ها اجازه می‌دهد داده‌ها را به لیستی در session state اضافه کنند، که این نحوه‌ی ارسال کار researcher و screenwriter است.
3. عامل را امتحان کنید. در ترمینال ، رابط وب را با فعال کردن بارگذاری مجدد زنده اجرا کنید:

   cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
   adk web --reload_agents
   

   توجه: اگر پورت ۸۰۰۰ در حال استفاده است، می‌توانید آن را روی پورت دیگری اجرا کنید، برای مثال: adk web --reload_agents --port 8001 .

4. در ترمینال Cloud Shell، روی دکمه‌ی «برای مشاهده‌ی رابط وب در یک برگه‌ی جدید»، « پیش‌نمایش وب» کلیک کنید و «تغییر پورت» را انتخاب کنید.
   
5. شماره پورت ۸۰۰۰ را وارد کنید و روی «تغییر و پیش‌نمایش» کلیک کنید. یک برگه مرورگر جدید با رابط کاربری ADK Dev باز خواهد شد.
   
6. از منوی کشویی «انتخاب یک نماینده» ، workflow_agents انتخاب کنید.
7. مکالمه را با hello شروع کنید. اپراتور greeter پاسخ خواهد داد.
8. وقتی از شما خواسته شد، یک شخصیت تاریخی وارد کنید. می‌توانید از یکی از این‌ها یا شخصیت خودتان استفاده کنید:
   • ژانگ ژانگجینگ
   • آدا لاولیس
   • مارکوس اورلیوس
9. اکنون SequentialAgent کنترل را به دست می‌گیرد. هیچ پیام میانی مشاهده نخواهید کرد. researcher ، screenwriter و file_writer یکی پس از دیگری اجرا می‌شوند. agent فقط زمانی پاسخ می‌دهد که کل توالی کامل شده باشد.
   اگر موفق نشدید، می‌توانید روی + جلسه جدید در بالا سمت راست کلیک کنید و دوباره امتحان کنید.
10. پس از تأیید نوشته شدن فایل توسط عامل، فایل .txt جدید را در دایرکتوری movie_pitches در ویرایشگر Cloud Shell خود پیدا کرده و باز کنید تا خروجی را ببینید.
11. در رابط کاربری ADK Dev، روی آخرین آیکون اپراتور در تاریخچه چت کلیک کنید تا نمای رویداد باز شود.
12. نمای رویداد، نموداری بصری از درخت عامل‌ها را نشان می‌دهد. می‌توانید ببینید که چگونه greeter ، تابع film_concept_team را فراخوانی کرده و سپس هر یک از زیرعامل‌های آن را به ترتیب فراخوانی کرده است.
13. شما می‌توانید روی تب‌های درخواست (Request) و پاسخ (Response) برای هر اپراتور در نمودار کلیک کنید تا داده‌های دقیق ارسال شده، از جمله وضعیت جلسه (session state)، را بررسی کنید.

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

خلاصه بخش

در این بخش، نحوه استفاده از یک عامل گردش کار را آموختید:

• یک SequentialAgent زیرعامل‌های خود را یکی یکی و به ترتیب اجرا می‌کند، بدون اینکه منتظر ورودی کاربر بین مراحل باشد.
• این یک «گردش کار» است زیرا کاربر با root_agent صحبت می‌کند، که سپس کار را برای تکمیل به SequentialAgent واگذار می‌کند.
• زیرعامل‌ها در این توالی از وضعیت جلسه (مثلاً { PLOT_OUTLINE? } ) برای دسترسی به کار عامل‌های قبلی استفاده می‌کنند.
• شما می‌توانید از نمودار رویداد در رابط کاربری Dev برای تجسم و اشکال‌زدایی کل گردش کار بین عامل‌ها استفاده کنید.

۱۱. برای کارهای تکراری، یک LoopAgent اضافه کنید

LoopAgent یک عامل گردش کار است که زیرعامل‌های خود را به ترتیب اجرا می‌کند و سپس از ابتدا تکرار می‌کند. این "حلقه" تا زمانی که یک شرط برآورده شود، مانند رسیدن به تعداد max_iterations یا فراخوانی ابزار exit_loop توسط زیرعامل، ادامه می‌یابد.

این برای کارهایی که نیاز به اصلاح مکرر دارند مفید است. شما این LoopAgent برای ایجاد یک "اتاق نویسنده" برای عامل ارائه فیلم خود اضافه خواهید کرد. این به یک researcher ، screenwriter و یک عامل critic جدید اجازه می‌دهد تا در یک حلقه کار کنند و طرح را با هر بار عبور بهبود بخشند تا زمانی که critic تصمیم بگیرد که آماده است. این همچنین به عامل کمک می‌کند تا با اجازه دادن به تحقیق و اصلاح یک ایده، ورودی‌های مبهم‌تر کاربر (مانند "یک پزشک باستانی") را مدیریت کند.

برای ایجاد این تغییرات:

1. در adk_multiagent_systems/workflow_agents/agent.py ، ایمپورت exit_loop را اضافه کنید (نزدیک سایر ایمپورت‌های google.adk ):

   from google.adk.tools import exit_loop
   

2. عامل critic جدید را اضافه کنید. این عامل نمودار را بررسی می‌کند. اگر خوب باشد، exit_loop را فراخوانی می‌کند. در غیر این صورت، برای حلقه بعدی، بازخوردی به حالت اضافه می‌کند.
   تعریف عامل زیر را در بخش # Agents جایگذاری کنید:

   critic = Agent(
       name="critic",
       model=model_name,
       description="Reviews the outline so that it can be improved.",
       instruction="""
       INSTRUCTIONS:
       Consider these questions about the PLOT_OUTLINE:
       - Does it meet a satisfying three-act cinematic structure?
       - Do the characters' struggles seem engaging?
       - Does it feel grounded in a real time period in history?
       - Does it sufficiently incorporate historical details from the RESEARCH?
   
       If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool.
       If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'.
       Explain your decision and briefly summarize the feedback you have provided.
   
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       RESEARCH:
       { research? }
       """,
       before_model_callback=log_query_to_model,
       after_model_callback=log_model_response,
       tools=[append_to_state, exit_loop]
   )
   

3. LoopAgent writers_room را ایجاد کنید. این شامل سه عاملی خواهد بود که در حلقه کار خواهند کرد.
   کد زیر را بالای تعریف عامل film_concept_team قرار دهید:

   writers_room = LoopAgent(
       name="writers_room",
       description="Iterates through research and writing to improve a movie plot outline.",
       sub_agents=[
           researcher,
           screenwriter,
           critic
       ],
       max_iterations=5,
   )
   

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

4. تابع film_concept_team SequentialAgent را به‌روزرسانی کنید تا از حلقه جدید writers_room استفاده کند. به جای researcher و screenwriter از تابع writers_room استفاده کنید. تعریف film_concept_team موجود خود را با این جایگزین کنید:

   film_concept_team = SequentialAgent(
       name="film_concept_team",
       description="Write a film plot outline and save it as a text file.",
       sub_agents=[
           writers_room,
           file_writer
       ],
   )
   

5. به برگه ADK Dev UI برگردید و روی + New Session در بالا سمت راست کلیک کنید.
6. شروع یک مکالمه جدید با: hello
7. وقتی از شما خواسته شد، این بار موضوع کلی‌تری را به نماینده ارائه دهید. چند ایده:
   • یک طراح صنعتی که محصولاتی را برای عموم مردم تولید می‌کرد
   • نقشه بردار (نقشه کش)
   • آن مردی که باعث شد محصولات کشاورزی غذای بیشتری به دست آورند
   اکنون عامل از طریق حلقه کار خواهد کرد. در رابط کاربری ADK Dev، گزارش‌ها را هنگام اجرای چندین باره عامل‌ها مشاهده خواهید کرد (مثلاً "[محقق]"، "[فیلمنامه‌نویس]"، "[منتقد]"، "[محقق]"، "[فیلمنامه‌نویس]"، "[منتقد]...").
8. وقتی حلقه کامل شد، عامل فایل را می‌نویسد. فایل تولید شده را در دایرکتوری adk_multiagent_systems/movie_pitches بررسی کنید.
9. برای مشاهده ساختار حلقه، نمودار رویداد را در رابط کاربری Dev بررسی کنید.

خلاصه بخش

در این بخش، نحوه استفاده از LoopAgent را آموختید:

• یک LoopAgent یک عامل گردش کار است که توالی زیرعامل‌های خود را تکرار می‌کند و یک "حلقه داخلی" برای وظایف تکراری ایجاد می‌کند.
• عامل‌های درون حلقه از وضعیت جلسه برای انتقال کار (مثلاً PLOT_OUTLINE ) و بازخورد (مثلاً CRITICAL_FEEDBACK ) به یکدیگر در مراحل بعدی استفاده می‌کنند.
• حلقه را می‌توان با رسیدن به حد max_iterations یا با فراخوانی ابزار exit_loop توسط عاملی، متوقف کرد.

۱۲. از یک ParallelAgent برای «جمع‌آوری و انتشار» استفاده کنید

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

شما از یک ParallelAgent برای ایجاد یک "تیم پیش تولید" که به صورت موازی کار می‌کند، استفاده خواهید کرد. یک نماینده پتانسیل فروش در گیشه را بررسی می‌کند در حالی که نماینده دیگر همزمان ایده‌های بازیگری را طوفان فکری می‌کند. این اغلب الگوی "انتشار و جمع‌آوری" نامیده می‌شود: نماینده ParallelAgent کار را "انتشار" می‌کند و نماینده بعدی ( file_writer ما) نتایج را "جمع‌آوری" می‌کند.

جریان نهایی شما به صورت زیر خواهد بود:

1. greeter (ریشه) چت را شروع می‌کند.
2. به film_concept_team ( SequentialAgent ) منتقل می‌شود که اجرا می‌شود:
   • writers_room ( LoopAgent ) برای ایجاد طرح داستان.
   • تیم جدید preproduction_team ( ParallelAgent ) برای تحقیق در مورد گیشه و انتخاب بازیگران به طور همزمان .
   • file_writer برای جمع‌آوری تمام نتایج و ذخیره فایل.

برای ایجاد این تغییرات:

1. در adk_multiagent_systems/workflow_agents/agent.py ، ParallelAgent جدید و زیر-عامل‌های آن را در زیر سربرگ # Agents قرار دهید.

   box_office_researcher = Agent(
       name="box_office_researcher",
       model=model_name,
       description="Considers the box office potential of this film",
       instruction="""
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       INSTRUCTIONS:
       Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films.
       """,
       output_key="box_office_report"
   )
   
   casting_agent = Agent(
       name="casting_agent",
       model=model_name,
       description="Generates casting ideas for this film",
       instruction="""
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       INSTRUCTIONS:
       Generate ideas for casting for the characters described in PLOT_OUTLINE
       by suggesting actors who have received positive feedback from critics and/or
       fans when they have played similar roles.
       """,
       output_key="casting_report"
   )
   
   preproduction_team = ParallelAgent(
       name="preproduction_team",
       sub_agents=[
           box_office_researcher,
           casting_agent
       ]
   )
   

2. لیست sub_agents film_concept_team در SequentialAgent را به‌روزرسانی کنید تا preproduction_team جدید (بین writers_room و file_writer ) را شامل شود. تعریف film_concept_team موجود خود را با این جایگزین کنید:

   film_concept_team = SequentialAgent(
       name="film_concept_team",
       description="Write a film plot outline and save it as a text file.",
       sub_agents=[
           writers_room,
           preproduction_team,
           file_writer
       ],
   )
   

3. instruction عامل file_writer را به‌روزرسانی کنید تا گزارش‌های جدید را از وضعیت «جمع‌آوری» کرده و به فایل اضافه کند.
   رشته instruction مربوط به file_writer را با این جایگزین کنید:

       instruction="""
       INSTRUCTIONS:
       - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE.
       If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
       - Use your 'write_file' tool to create a new txt file with the following arguments:
       - for a filename, use the movie title
       - Write to the 'movie_pitches' directory.
       - For the 'content' to write, include:
       - The PLOT_OUTLINE
       - The BOX_OFFICE_REPORT
       - The CASTING_REPORT
   
       PLOT_OUTLINE:
       { PLOT_OUTLINE? }
   
       BOX_OFFICE_REPORT:
       { box_office_report? }
   
       CASTING_REPORT:
       { casting_report? }
       """,
   

4. به برگه ADK Dev UI برگردید و روی +New Session کلیک کنید.
5. برای شروع مکالمه، hello وارد کنید.
6. وقتی از شما خواسته شد، ایده‌ای برای شخصیت جدید وارد کنید. چند ایده:
   • آن بازیگر زنی که فناوری وای فای را اختراع کرد
   • یک سرآشپز هیجان‌انگیز
   • بازیگران کلیدی در نمایشگاه‌های جهانی
7. وقتی نماینده کارش را تمام کرد، فایل نهایی را در دایرکتوری adk_multiagent_systems/movie_pitches بررسی کنید. اکنون باید شامل طرح داستان، گزارش گیشه و گزارش انتخاب بازیگر، همه در یک سند باشد.

خلاصه بخش

در این بخش، نحوه استفاده از ParallelAgent را آموختید:

• یک ParallelAgent به صورت «پخش‌کننده» عمل می‌کند و تمام زیرعامل‌های خود را به طور همزمان اجرا می‌کند، نه به صورت متوالی.
• این برای کارهایی که به یکدیگر وابسته نیستند (مانند تحقیق در مورد دو موضوع مختلف) بسیار کارآمد است.
• نتایج عامل‌های موازی توسط یک عامل بعدی «جمع‌آوری» می‌شود. این کار با ذخیره کار عامل‌های موازی در حالت جلسه (با استفاده از output_key ) و خواندن آن کلیدها توسط یک عامل نهایی (مانند file_writer ) انجام می‌شود.

۱۳. عوامل گردش کار سفارشی

وقتی عامل‌های گردش کار از پیش تعریف شده SequentialAgent ، LoopAgent و ParallelAgent برای نیازهای شما کافی نیستند، CustomAgent انعطاف‌پذیری لازم برای پیاده‌سازی منطق گردش کار جدید را فراهم می‌کند.

شما می‌توانید الگوهایی برای کنترل جریان، اجرای شرطی یا مدیریت وضعیت بین زیرعامل‌ها تعریف کنید. این امر برای گردش‌های کاری پیچیده، هماهنگی‌های مبتنی بر وضعیت یا ادغام منطق کسب‌وکار سفارشی در لایه هماهنگی چارچوب مفید است.

ایجاد یک CustomAgent خارج از محدوده این آزمایش است، اما خوب است بدانید که در صورت نیاز، این امکان وجود دارد!

۱۴. تبریک می‌گویم!

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

خلاصه

در این آزمایشگاه، شما موارد زیر را انجام دادید:

• عامل‌های سازمان‌یافته در یک درخت سلسله مراتبی با روابط والد و زیرعامل.
• انتقال کنترل‌شده‌ی عامل به عامل ، هم به صورت خودکار (با استفاده از description ) و هم به صورت صریح (با استفاده از instruction ).
• از ابزاری برای نوشتن داده‌ها در دیکشنری tool_context.state استفاده شده است.
• از قالب‌بندی کلید (مثلاً { PLOT_OUTLINE? } ) برای خواندن از وضعیت جلسه و هدایت اعلان عامل استفاده شده است.
• یک SequentialAgent برای ایجاد یک گردش کار ساده و گام به گام (تحقیق -> نوشتن -> ذخیره) پیاده‌سازی شد.
• از یک LoopAgent به همراه یک عامل critic و ابزار exit_loop برای ایجاد یک چرخه اصلاح تکراری استفاده شد.
• از یک ParallelAgent برای «پخش» وظایف مستقل (مانند انتخاب بازیگر و تحقیق در مورد گیشه) به صورت همزمان استفاده کردم.

آزمایش‌های مداوم

راه‌های زیادی برای تقویت آموخته‌هایتان وجود دارد. در اینجا چند ایده ارائه شده است:

• افزودن عوامل بیشتر: سعی کنید یک عامل جدید به ParallelAgent preproduction_team خود اضافه کنید. برای مثال، می‌توانید یک marketing_agent ایجاد کنید که بر اساس PLOT_OUTLINE یک شعار برای فیلم می‌نویسد.
• ابزارهای بیشتری اضافه کنید: به researcher خود ابزارهای بیشتری بدهید. می‌توانید ابزاری ایجاد کنید که از API جستجوی گوگل برای یافتن اطلاعاتی که در ویکی‌پدیا نیست استفاده کند.
• بررسی CustomAgent : در این آزمایشگاه به CustomAgent برای گردش‌های کاری که با قالب‌های استاندارد مطابقت ندارند، اشاره شد. سعی کنید گردش کاری بسازید که مثلاً فقط در صورت وجود یک کلید خاص در حالت جلسه، یک عامل را به صورت مشروط اجرا کند.