دوره خرابی ADK - از مبتدی تا متخصص

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

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

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

کل این آزمایشگاه کد اصلی یک سفر عملی خواهد بود و من شما را در دو دفترچه اصلی Colab که شامل تمام کدها و مثال‌های جلسات ما هستند، راهنمایی خواهم کرد. Colab 1: ابزارها و حافظه ، Colab 2: چندعاملی‌ها

در پایان این آموزش، شما قادر خواهید بود:

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

بیایید شروع کنیم! 🚀

۲. تنظیم کلید API GCP و Gemini

راه‌اندازی پروژه GCP و کلید API Gemini

برای توانمندسازی عوامل هوش مصنوعی خود، به دو چیز نیاز داریم: یک پروژه ابری گوگل برای فراهم کردن پایه و اساس و یک کلید API Gemini برای دسترسی به مدل‌های قدرتمند گوگل.

مرحله ۱: فعال کردن حساب صورتحساب

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

بدون نیاز به کارت اعتباری یا پرداخت - 5 دلار اعتبار رایگان دریافت خواهید کرد. کمتر از 2 دقیقه طول می‌کشد، فقط نام خود را وارد کنید و اعتبار را بپذیرید.

مرحله 2: ایجاد یک پروژه GCP جدید

• به کنسول ابری گوگل بروید و یک پروژه جدید ایجاد کنید.

• به کنسول ابری گوگل بروید و یک پروژه جدید ایجاد کنید.
• پنل سمت چپ را باز کنید، روی Billing کلیک کنید، بررسی کنید که آیا حساب billing به این حساب gcp مرتبط است یا خیر.

اگر این صفحه را مشاهده کردید، manage billing account بررسی کنید، نسخه آزمایشی Google Cloud و لینک آن را انتخاب کنید.

مرحله 3: کلید API Gemini خود را ایجاد کنید

قبل از اینکه بتوانید کلید را ایمن کنید، باید یکی داشته باشید.

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

۳. جلسه ۱: اولین مامور شما با دونده

بیایید با اصول اولیه شروع کنیم. در اینجا، اولین عامل ساده خود، day_trip_agent ایجاد می‌کنیم. هدف این عامل، ایجاد یک برنامه سفر تمام روز بر اساس درخواست کاربر، از جمله ملاحظات بودجه است. این مثال سه جزء اصلی هرگونه تعامل عامل در ADK را معرفی می‌کند:

• عامل : مغز اصلی عملیات. این عامل با دستورالعمل‌هایش (شخصیت و ماموریتش)، مدل هوش مصنوعی که استفاده می‌کند (مانند Gemini) و ابزارهایی که می‌تواند به آنها دسترسی داشته باشد، تعریف می‌شود.
• جلسه (Session ): حافظه مکالمه. این حافظه تاریخچه تعاملات (پیام‌های کاربر و پاسخ‌های عامل) را ذخیره می‌کند و امکان گفتگوی مداوم را فراهم می‌کند.
• اجراکننده (Runner) : موتوری که وظیفه را اجرا می‌کند. این موتور، عامل (Agent) و جلسه (Session) را دریافت می‌کند، درخواست جدید کاربر را پردازش می‌کند و مراحل تولید پاسخ را هماهنگ می‌کند.

➡️ کجا آن را در دفترچه یادداشت پیدا کنیم

👉 این مربوط به سلول‌های زیر بخش ۱: اولین نماینده شما - غول سفر یک روزه 🧞 است.🌟

• تعریف عامل : به دنبال تابع create_day_trip_agent() بگردید. این جایی است که عامل تعریف می‌شود. به رشته دستورالعمل دقیق توجه کنید - این همان دستوری است که به عامل می‌گوید چگونه رفتار کند. ما همچنین اولین ابزار آن را به آن می‌دهیم: جستجوی گوگل.
• تابع کمکی : تابع کمکی run_agent_query() در اینجا تعریف شده است. ما از این ابزار در سراسر دفترچه یادداشت برای ساده‌سازی اجرای کوئری‌ها استفاده خواهیم کرد.
• اجرای آزمایشی : تابع run_day_trip_genie() درخواست یک سفر یک روزه "مقرون به صرفه" و "آرامش بخش" را برای کاربر شبیه‌سازی می‌کند. عامل با استفاده از دستورالعمل‌های خود و ابزار جستجوی گوگل، مکان‌های مناسب را پیدا کرده و یک برنامه سفر با فرمت markdown ایجاد می‌کند.

➡️ اقدام : دستورالعمل مربوط به day_trip_agent را بررسی کنید. ببینید که چگونه درخواست یک سفر «مقرون به صرفه» در پرس و جوی آزمایشی مستقیماً به دستورالعمل نماینده مبنی بر «آگاهی از بودجه» مربوط می‌شود.

۴. جلسه ۲: ابزارهای سفارشی 🛠️

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

مهم‌ترین بخش یک ابزار تابع، رشته‌ی مستندات آن است. ADK به طور خودکار رشته‌ی مستندات را تجزیه می‌کند تا بفهمد ابزار چه کاری انجام می‌دهد، چه پارامترهایی را می‌پذیرد (Args) و چه چیزی را برمی‌گرداند (Returns). مدل زبان بزرگ (LLM) این توضیحات را می‌خواند تا تصمیم بگیرد چه زمانی و چگونه از ابزار استفاده کند.

➡️ کجا آن را در دفترچه یادداشت پیدا کنیم

👉 این مربوط به سلول‌های زیر بخش ۲.۱ ابزار تابع ساده: فراخوانی یک API آب و هوای بلادرنگ است . 🌟

• تعریف ابزار : تابع get_live_weather_forecast(location: str) هسته ابزار سفارشی ما است. این تابع نام یک شهر را دریافت می‌کند، API عمومی سرویس هواشناسی ملی را فراخوانی می‌کند و یک دیکشنری حاوی دما و پیش‌بینی آب و هوا را برمی‌گرداند.
• تعریف عامل : عامل weather_agent با ارسال tools=[get_live_weather_forecast] در طول مقداردهی اولیه، ایجاد و به ابزار جدید ما مجهز می‌شود. دستورالعمل‌های عامل صراحتاً به آن می‌گویند که قبل از پیشنهاد فعالیت‌های خارج از منزل، از این ابزار استفاده کند.
• اجرای آزمایشی : عبارت «می‌خواهم نزدیک دریاچه تاهو پیاده‌روی کنم، هوا چطور است؟» مستقیماً عامل را وادار به استفاده از ابزار get_live_weather_forecast می‌کند، زیرا دستورالعمل‌های آن به آن نیاز دارند.

➡️ اقدام : رشته‌ی مستندات تابع get_live_weather_forecast و دستورالعمل مربوط به weather_agent بخوانید. به رابطه‌ی مستقیم بین آنها توجه کنید.

۵. جلسه ۳: عامل به عنوان ابزار 🧑‍🍳

چرا یک عامل واحد و یکپارچه بسازیم وقتی می‌توانیم تیمی از متخصصان تشکیل دهیم؟ الگوی Agent-as-a-Tool روشی قدرتمند برای ساخت سیستم‌های پیچیده است که در آن یک عامل اصلی، که اغلب ارکستراتور یا روتر نامیده می‌شود، وظایف را به سایر عامل‌های متمرکزتر واگذار می‌کند.

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

➡️ کجا آن را در دفترچه یادداشت پیدا کنیم

👉 این مربوط به سلول‌های زیر بخش ۲.۲ عامل به عنوان ابزار: مشاوره با یک متخصص 🧑‍🍳 است.🌟

این مثال یک سیستم عامل چندلایه و پیچیده می‌سازد:

• متخصصان :
  • food_critic_agent : یک عامل بسیار تخصصی که فقط پیشنهادات رستوران ارائه می‌دهد.
  • db_agent : یک عامل ساختگی که وانمود می‌کند در حال پرس‌وجو از پایگاه داده برای اطلاعات هتل است.
  • concierge_agent : یک عامل سطح متوسط ​​که به عنوان یک دربان مودب عمل می‌کند. نکته مهم این است که food_critic_agent به عنوان ابزار خود دارد.
• هماهنگ‌کننده ( trip_data_concierge_agent ): این عامل سطح بالایی است که کاربر با آن تعامل دارد. دستورالعمل‌های آن، آن را به یک "برنامه‌ریز سفر اصلی" تبدیل می‌کند و دو ابزار به آن داده شده است که سایر عامل‌ها را فراخوانی می‌کنند:
  • call_db_agent : تابعی که db_agent را فراخوانی می‌کند.
  • call_concierge_agent : تابعی که concierge_agent را فراخوانی می‌کند.
• جریان : اجرای آزمایشی در run_trip_data_concierge() زنجیره کامل واگذاری اختیارات را نشان می‌دهد.
  • کاربر از تنظیم‌کننده‌ی ارکستر، نام هتل و رستورانی در نزدیکی را می‌پرسد.
  • دستورالعمل‌های هماهنگ‌کننده به آن می‌گوید که ابتدا از ابزار call_db_agent برای دریافت داده‌های هتل استفاده کند.
  • سپس هماهنگ‌کننده از ابزار call_concierge_agent برای دریافت توصیه استفاده می‌کند.
  • concierge_agent پس از دریافت درخواست، از ابزار مخصوص خود، food_critic_agent ، برای دریافت ایده‌ای از رستوران استفاده می‌کند.

پاسخ منتقد غذا به متصدی پذیرش برگردانده می‌شود، که مودبانه آن را قالب‌بندی کرده و برای هماهنگ‌کننده ارسال می‌کند، که در نهایت آن را به کاربر ارائه می‌دهد.

➡️ اقدام : جریان اجرا را در اجرای آزمایشی تحت run_trip_data_concierge() ردیابی کنید. مشاهده کنید که چگونه چاپ‌های TOOL CALLED زنجیره واگذاری از هماهنگ‌کننده به متخصصان را نشان می‌دهند. این یک زنجیره متوالی از دستورات است.

۶. جلسه ۴: حافظه عامل 🧠

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

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

➡️ کجا آن را در دفترچه یادداشت پیدا کنیم

👉 این مربوط به سلول‌های زیر بخش ۳: عامل دارای حافظه - برنامه‌ریز تطبیقی ​​🗺️ است . 🌟

• تعریف عامل : تابع create_multi_day_trip_agent() عاملی را تعریف می‌کند که برای برنامه‌ریزی تدریجی یک سفر طراحی شده است. دستورالعمل‌های آن بر به خاطر سپردن زمینه، مدیریت بازخورد و برنامه‌ریزی یک روز در یک زمان تأکید دارد.

سناریوی 3a: عامل دارای حافظه (✅)

این تست در تابع run_adaptive_memory_demonstration() اجرا می‌شود.

• یک trip_session واحد ایجاد شده و برای سه نوبت متوالی مورد استفاده مجدد قرار می‌گیرد.
• مرحله ۱ : کاربر یک برنامه سفر ۲ روزه را آغاز می‌کند.
• نوبت دوم : کاربر بازخورد می‌دهد ("من طرفدار پر و پا قرص قلعه‌ها نیستم"). از آنجا که عامل، حافظه نوبت اول را دارد، می‌فهمد کدام بخش از نقشه را باید تغییر دهد و جایگزینی ارائه می‌دهد.
• مرحله ۳ : کاربر تغییر را تأیید می‌کند و درخواست مرحله بعدی را می‌دهد. عامل همه چیز را به خاطر می‌سپارد و به برنامه‌ریزی روز دوم ادامه می‌دهد.

سناریوی ۳ب: عامل بدون حافظه (❌)

این تست در تابع run_memory_failure_demonstration() اجرا می‌شود.

این موضوع با ایجاد یک اشتباه عمدی، اهمیت حیاتی مدیریت جلسه را نشان می‌دهد. برای هر نوبت، یک جلسه جدید ایجاد می‌شود .

• مرحله ۱ : کاربر سفر را در session_one آغاز می‌کند. عامل به درستی پاسخ می‌دهد.
• مرحله ۲ : کاربر درخواست برنامه‌ریزی روز دوم را دارد، اما درخواست در یک session_two کاملاً جدید ارسال می‌شود. از آنجا که این session جدید هیچ تاریخچه‌ای ندارد، عامل گیج می‌شود. دچار فراموشی شده است! نمی‌داند چه سفری در حال برنامه‌ریزی است.

اقدام : پاسخ‌های عامل را در run_adaptive_memory_demonstration() و run_memory_failure_demonstration() مقایسه کنید. این مهمترین مفهوم در دفترچه یادداشت است: یک مکالمه مداوم نیاز به یک جلسه مداوم دارد.

۷. جلسه ۵: عامل روتر 🚏

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

عامل روتر (Router Agent) به عنوان یک عامل "اصلی" یا یک توزیع‌کننده عمل می‌کند. تنها هدف آن تجزیه و تحلیل یک پرس‌وجوی کاربر ورودی و تصمیم‌گیری در مورد اینکه کدام عامل متخصص (یا گردش کار عامل‌ها) برای کار مناسب‌تر است، می‌باشد. این عامل به خود پرس‌وجو پاسخ نمی‌دهد؛ بلکه به سادگی آن را به عامل صحیح پایین‌دستی هدایت می‌کند.

برای مثال، یک پرس‌وجو در مورد «بهترین سوشی» باید به یک foodie_agent برود، در حالی که یک سوال در مورد «کنسرت‌های این آخر هفته» باید توسط یک weekend_guide_agent مدیریت شود.

➡️ این مورد را در دفترچه یادداشت کجا می‌توان پیدا کرد:

👉 این مفهوم در کل دفترچه یادداشت محوریت دارد، اما اولین بار در بخش ۱ معرفی شده است: آشفتگی چندعاملی - گردش‌های کاری متوالی 🧠→🤖→🤖 🌟

• تعاریف عامل : سلول کد، چندین عامل متخصص (day_trip_agent، foodie_agent، transportation_agent) و از همه مهم‌تر، router_agent را تعریف می‌کند. به دستورالعمل مربوط به router_agent توجه دقیق داشته باشید، به صراحت گفته شده است که فقط نام بهترین عامل برای کار را برگردانید.
• منطق اجرا : تابع run_sequential_app نشان می‌دهد که چگونه ابتدا router_agent را برای دریافت یک تصمیم (chosen_route) فراخوانی کنیم و سپس از آن تصمیم در یک بلوک if/elif برای اجرای عامل متخصص مناسب استفاده کنیم.

۸. جلسه ۶: عامل ترتیبی ⛓️

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

ADK با استفاده از SequentialAgent روشی تمیز و قدرتمند برای مدیریت این امر ارائه می‌دهد. این یک عامل گردش کار ویژه است که لیستی از زیرعامل‌ها را به ترتیب از پیش تعریف شده اجرا می‌کند.

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

➡️ این مورد را در دفترچه یادداشت کجا می‌توان پیدا کرد:

👉 این موضوع در بخش ۲ (روش ADK) پوشش داده شده است: آشوب چندعاملی با SequentialAgent 🧠→⛓️→🤖 . 🌟

• بازسازی عامل: در اولین سلول کد این بخش، به تغییرات کلیدی در foodie_agent و transportation_agent توجه کنید:
  • foodie_agent اکنون یک output_key="destination" دارد. این به ADK می‌گوید که پاسخ نهایی خود را در متغیری به نام destination در حالت مشترک ذخیره کند.
  • transportation_agent اکنون در اعلان دستورالعمل خود، جای‌نگهدار {destination} را دارد. ADK به طور خودکار مقدار را از حالت مشترک به این جای‌نگهدار تزریق می‌کند.
• تعریف گردش کار : find_and_navigate_agent به عنوان یک SequentialAgent تعریف می‌شود که sub_agents آن روی [ foodie_agent , transportation_agent ] تنظیم شده است و تضمین می‌کند که آنها دقیقاً به همان ترتیب اجرا شوند.
• اجرای ساده‌شده : به تابع run_sequential_app در این بخش نگاه کنید. منطق پیچیده‌ی if/elif از بین رفته است! find_and_navigate_agent اکنون به عنوان یک واحد واحد و قابل فراخوانی در نظر گرفته می‌شود و ADK مراحل متوالی داخلی را به طور خودکار مدیریت می‌کند.

۹. جلسه ۷: LoopAgent 🔁

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

برای این منظور، ADK، LoopAgent را ارائه می‌دهد. این عامل گردش کار، توالی‌ای از زیرعامل‌ها را تا زمان برآورده شدن یک شرط خاص، به طور مکرر اجرا می‌کند. این برای ساخت عامل‌های «کمال‌گرا» که می‌توانند کار خود را برنامه‌ریزی، نقد و بهبود بخشند، ایده‌آل است.

نمودار نشان می‌دهد که Planner Agent ابتدا یک طرح ایجاد می‌کند. سپس، وارد LoopAgent می‌شویم. Critic Agent طرح را بررسی می‌کند. اگر ناقص باشد، Refiner Agent نسخه جدیدی ایجاد می‌کند و حلقه تکرار می‌شود. اگر طرح خوب باشد، Refiner Agent ابزار exit_loop را فراخوانی می‌کند و طرح نهایی و اعتبارسنجی شده بازگردانده می‌شود.

➡️ این مورد را در دفترچه یادداشت کجا می‌توان پیدا کرد:

👉 این موضوع در بخش ایده‌های تکراری با LoopAgent 🧠→🔁→🤖 توضیح داده شده است. 🌟

• عوامل اصلی : این گردش کار از planner_agent ، critic_agent و refiner_agent استفاده می‌کند.
• تعریف حلقه : refinement_loop به عنوان یک LoopAgent تعریف می‌شود که critic_agent و refiner_agent هماهنگ می‌کند و sets max_iterations=3 .
• شرط خروج : حلقه زمانی خاتمه می‌یابد که critic_agent طرح را تأیید کند و در نتیجه refiner_agent ابزار exit_loop سفارشی را فراخوانی کند.

۱۰. جلسه ۸: عامل موازی ⚡️

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

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

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

➡️ این مورد را در دفترچه یادداشت کجا می‌توان پیدا کرد:

👉 این گردش کار در بخش «قدرت موازی با ParallelAgent» 🧠→⚡️→🤖🤖🤖 به تفصیل شرح داده شده است. 🌟

• نمایندگان متخصص : سه نماینده متخصص تعریف شده‌اند که هر کدام یک output_key منحصر به فرد دارند (مثلاً museum_result).
• گردش کار موازی : parallel_research_agent به عنوان یک ParallelAgent تعریف شده است، که سه عامل یابنده به عنوان زیرعامل‌های آن فهرست شده‌اند.
• مرحله سنتز : پس از مرحله موازی، یک synthesis_agent نهایی تمام یافته‌ها را از حالت مشترک با استفاده از متغیرهایی ( {museum_result} ، {concert_result} و غیره) جمع‌آوری می‌کند تا یک خلاصه مرتب ارائه دهد.

۱۱. پیوست: ADK Web - 🍎 برای مک/لینوکس

این راهنما شما را در راه‌اندازی و اجرای ADK Day Trip Planning Agent روی دستگاه محلی‌تان راهنمایی می‌کند.

پیش‌نیازها

• پایتون ۳.۸ یا بالاتر
  • پایتون ۳.۹+ : نصب google-adk==1.5.0 (آخرین نسخه با امکانات کامل)
  • پایتون ۳.۸ : نصب google-adk==0.3.0 (نسخه سازگار)
• کلید API گوگل هوش مصنوعی استودیو
• اتصال به اینترنت

مرحله ۱: کلون کردن مخزن

ترمینال را باز کنید و اجرا کنید:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

مرحله 2: راه‌اندازی محیط مجازی و نصب وابستگی‌ها

گزینه الف: راه‌اندازی خودکار (توصیه می‌شود)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

گزینه ب: تنظیم دستی

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

مرحله ۳: 🔥 مهم - ایجاد متغیرهای محیطی

⚠️ این مرحله را نادیده نگیرید! یک فایل .env در دایرکتوری agent/ ایجاد کنید:

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

این خطوط را به فایل اضافه کنید:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 نکته مهم : your_actual_api_key_here را با کلید API واقعی خود جایگزین کنید!

مرحله ۴: فعال کردن محیط مجازی (اگر از قبل فعال نیست)

source .adk_env/bin/activate

شما باید (.adk_env) را در ابتدای اعلان ترمینال خود ببینید.

مرحله 5: رابط وب ADK را اجرا کنید

adk web

مرحله ۶: مرورگر خود را باز کنید

1. مرورگر خود را باز کنید و به آدرس اینترنتی نشان داده شده در ترمینال بروید (معمولاً http://localhost:8000 )
2. در منوی کشویی بالا سمت چپ، agent انتخاب کنید.
3. با نماینده برنامه‌ریزی سفر روزانه‌تان چت کنید!

مکالمه‌ای مانند این را خواهید دید:

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

وقتی کار با پروژه تمام شد:

deactivate

این دستور هم در مک/لینوکس و هم در ویندوز به یک شکل کار می‌کند. متوجه خواهید شد که پیشوند (.adk_env) از اعلان ترمینال شما ناپدید می‌شود.

عیب‌یابی مک

• پایتون پیدا نشد : به جای python از python3 استفاده کنید
• مجوز رد شد : قبل از اجرای اسکریپت، دستور chmod +x setup_venv.sh را اجرا کنید.

۱۲. پیوست: ADK Web - 🪟 برای کاربران ویندوز

این راهنما شما را در راه‌اندازی و اجرای ADK Day Trip Planning Agent روی دستگاه محلی‌تان راهنمایی می‌کند.

پیش‌نیازها

• پایتون ۳.۸ یا بالاتر
  • پایتون ۳.۹+ : نصب google-adk==1.5.0 (آخرین نسخه با امکانات کامل)
  • پایتون ۳.۸ : نصب google-adk==0.3.0 (نسخه سازگار)
• کلید API گوگل هوش مصنوعی استودیو
• اتصال به اینترنت

مرحله ۱: کلون کردن مخزن

Command Prompt یا PowerShell را باز کنید و دستور زیر را اجرا کنید:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

مرحله 2: راه‌اندازی محیط مجازی و نصب وابستگی‌ها

گزینه الف: راه‌اندازی خودکار (توصیه می‌شود)

# Run the setup script in Command Prompt
setup_venv.bat

گزینه ب: تنظیم دستی

برای خط فرمان:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

برای پاورشل:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

مرحله ۳: 🔥 مهم - ایجاد متغیرهای محیطی

⚠️ این مرحله را نادیده نگیرید! یک فایل .env در دایرکتوری agent/ ایجاد کنید:

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

این خطوط را به فایل اضافه کنید:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 نکته مهم : your_actual_api_key_here را با کلید API واقعی خود جایگزین کنید!

مرحله ۴: فعال کردن محیط مجازی (اگر از قبل فعال نیست)

خط فرمان:

.adk_env\Scripts\activate

پاورشل:

.adk_env\Scripts\Activate.ps1

شما باید (.adk_env) را در ابتدای اعلان خود ببینید.

مرحله 5: رابط وب ADK را اجرا کنید

adk web

مرحله ۶: مرورگر خود را باز کنید

1. مرورگر خود را باز کنید و به آدرس اینترنتی نشان داده شده در ترمینال بروید (معمولاً http://localhost:8000 )
2. در منوی کشویی بالا سمت چپ، agent انتخاب کنید.
3. با نماینده برنامه‌ریزی سفر روزانه‌تان چت کنید!

عیب‌یابی ویندوز

• خطای خط مشی اجرای PowerShell : اجرای Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

مکالمه‌ای مانند این را خواهید دید:

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

وقتی کار با پروژه تمام شد:

deactivate

این دستور هم در مک/لینوکس و هم در ویندوز به یک شکل کار می‌کند. متوجه خواهید شد که پیشوند (.adk_env) از اعلان ترمینال شما ناپدید می‌شود.