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

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

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

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

کل این نرم افزار اصلی کد یک سفر عملی خواهد بود، و من شما را از طریق 2 دفترچه اصلی Colab که شامل تمام کدها و نمونه های جلسات ما هستند، راهنمایی می کنم. Colab 1: Tools & Memory ، Colab 2: MultiAgents

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

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

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

2. کلید GCP و Gemini API را راه اندازی کنید

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

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

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

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

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

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

• به Google Cloud Console بروید و یک پروژه جدید ایجاد کنید.

• به Google Cloud Console بروید و یک پروژه جدید ایجاد کنید.
• پانل سمت چپ را باز کنید، Billing کلیک کنید، بررسی کنید که آیا حساب صورت‌حساب به این حساب gcp مرتبط است یا خیر.

اگر این صفحه را می‌بینید، manage billing account بررسی کنید، Google Cloud Trial One را انتخاب کنید و به آن پیوند دهید.

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

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

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

3. جلسه 1: اولین نماینده شما با رانر

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

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

➡️ کجا آن را در نوت بوک پیدا کنیم

👉 این مربوط به سلول های زیر قسمت 1: اولین مامور شما - جن سفر روزی 🧞 .🌟

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

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

4. جلسه 2: ابزارهای سفارشی 🛠️

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

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

➡️ کجا آن را در نوت بوک پیدا کنیم

👉 این مربوط به سلول های زیر 2.1 The Simple FunctionTool: Calling a Real-Time Weather API است . 🌟

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

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

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

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

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

➡️ کجا آن را در نوت بوک پیدا کنیم

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

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

• متخصصان :
  • 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 زنجیره اعزام از ارکستراتور تا متخصصان را نشان می‌دهد. این یک زنجیره فرمان متوالی است.

6. جلسه 4: حافظه عامل 🧠

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

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

➡️ کجا آن را در نوت بوک پیدا کنیم

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

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

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

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

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

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

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

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

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

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

7. جلسه 5: عامل روتر 🚏

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

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

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

➡️ این را از کجا در نوت بوک پیدا کنیم:

👉 این مفهوم در کل نوت بوک مرکزی است، اما برای اولین بار در قسمت 1 معرفی شد: ضرب وشتم چند عاملی - گردش کار متوالی 🧠→🤖→🤖 🌟

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

8. جلسه 6: SequentialAgent ⛓️

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

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

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

➡️ این را از کجا در نوت بوک پیدا کنیم:

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

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

9. جلسه 7: LoopAgent 🔁

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

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

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

➡️ این را از کجا در نوت بوک پیدا کنیم:

👉 این در Iterative Ideas با LoopAgent 🧠→🔁→🤖 توضیح داده شده است. 🌟

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

10. جلسه هشتم: ParallelAgent ⚡️

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

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

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

➡️ این را از کجا در نوت بوک پیدا کنیم:

👉 این گردش کار در بخش Parallel Power with ParallelAgent 🧠→⚡️→🤖🤖🤖 توضیح داده شده است. 🌟

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

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

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

پیش نیازها

• پایتون 3.8 یا بالاتر
  • Python 3.9+ : google-adk==1.5.0 را نصب می کند (آخرین نسخه با ویژگی های کامل)
  • Python 3.8 : نصب google-adk==0.3.0 (نسخه سازگار)
• کلید Google AI Studio API
• اتصال به اینترنت

مرحله 1: Repository را کلون کنید

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

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

مرحله 2: محیط مجازی را تنظیم کنید و Dependencies را نصب کنید

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

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

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

# 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

مرحله 3: 🔥 مهم - متغیرهای محیطی را ایجاد کنید

⚠️ این مرحله را نادیده نگیرید! یک فایل .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 واقعی خود جایگزین کنید!

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

source .adk_env/bin/activate

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

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

adk web

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

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

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

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

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

deactivate

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

عیب یابی مک

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

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

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

پیش نیازها

• پایتون 3.8 یا بالاتر
  • Python 3.9+ : google-adk==1.5.0 را نصب می کند (آخرین نسخه با ویژگی های کامل)
  • Python 3.8 : نصب google-adk==0.3.0 (نسخه سازگار)
• کلید Google AI Studio API
• اتصال به اینترنت

مرحله 1: Repository را کلون کنید

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

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

مرحله 2: محیط مجازی را تنظیم کنید و Dependencies را نصب کنید

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

# Run the setup script in Command Prompt
setup_venv.bat

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

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

# 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

برای PowerShell:

# 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

مرحله 3: 🔥 مهم - متغیرهای محیطی را ایجاد کنید

⚠️ این مرحله را نادیده نگیرید! یک فایل .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 واقعی خود جایگزین کنید!

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

خط فرمان:

.adk_env\Scripts\activate

پاورشل:

.adk_env\Scripts\Activate.ps1

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

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

adk web

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

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

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

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

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

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

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

deactivate

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