درباره این codelab
1. نمای کلی
امروز ساختن با هوش مصنوعی از کجا شروع می شود؟ خوب برای بسیاری از ما، اغلب با یک سوال ساده شروع می شود، "آیا این مدل واقعا می تواند به حل این مشکلی که من به آن فکر می کردم کمک کند؟" دقیقاً همان جایی است که استودیوی هوش مصنوعی گوگل وارد می شود. این مکانی است که می توانید به سرعت هر چیزی را نمونه اولیه کنید. من می‌خواستم آشپزخانه‌ام را بازسازی کنم و شرط می‌بندم جمینی می‌تواند کمک کند - اما من یک مهندس هستم، نه یک پیمانکار عمومی. من حتی مطمئن نیستم که چه چیزی را بخواهم - چیزهای زیادی وجود دارد که باید در نظر بگیریم: مقررات، وسایل و غیره. پس بیایید این را تجزیه کنیم و جمینی یک درخواست فوق العاده دقیق برای ما ایجاد کند، سپس یک طرح نوسازی کامل ایجاد کند و همچنین بازسازی را تجسم کنیم! اما صبر کن چگونه می توانم واقعاً از اینجا به کسب و کارها کمک کنم تا مقیاس شوند؟ عوامل را وارد کنید!!!
Agent یک برنامه مستقل است که با یک مدل هوش مصنوعی صحبت می کند تا یک عملیات مبتنی بر هدف را با استفاده از ابزارها و زمینه ای که دارد انجام دهد و قادر به تصمیم گیری مستقل مبتنی بر حقیقت است!
کیت توسعه عامل (ADK)
کیت توسعه عامل (ADK) یک چارچوب انعطاف‌پذیر و ماژولار برای توسعه و استقرار عوامل هوش مصنوعی است. ADK از ساخت برنامه های پیچیده با ترکیب چندین نمونه عامل متمایز در یک سیستم چند عاملی (MAS) پشتیبانی می کند.
در ADK، یک سیستم چند عامله برنامه‌ای است که در آن عوامل مختلف، که اغلب یک سلسله مراتب را تشکیل می‌دهند، برای دستیابی به یک هدف بزرگ‌تر با یکدیگر همکاری یا هماهنگی می‌کنند. ساختار برنامه شما به این روش مزایای قابل توجهی را ارائه می دهد، از جمله ماژولار بودن، تخصصی شدن، قابلیت استفاده مجدد، قابلیت نگهداری، و توانایی تعریف جریان های کنترل ساخت یافته با استفاده از عوامل گردش کار اختصاصی.
چیزی که خواهی ساخت
آماده انتقال از نمونه اولیه PROMPT به ساخت عامل هستید؟؟؟ ما یک نماینده برای کمک به ایجاد سند پیشنهادی برای پروژه بازسازی آشپزخانه ایجاد خواهیم کرد. به عنوان بخشی از این آزمایشگاه، شما:
- یک عامل ساده برای تولید سند پیشنهادی نوسازی با ADK بسازید
- سند پیشنهاد بازسازی ایجاد شده را در یک سطل ذخیره سازی ابری ذخیره کنید
- عامل را در Cloud Shell و در خروجی وب عامل آزمایش کنید
الزامات
2. قبل از شروع
یک پروژه ایجاد کنید
- در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورتحساب در پروژه آشنا شوید.
- همچنین اگر در حال خواندن این مطلب هستید و می‌خواهید چند اعتبار برای شروع کار با Google Cloud و استفاده از ADK دریافت کنید، از این پیوند برای بازخرید اعتبار استفاده کنید.
- برای بازخرید آن می توانید دستورالعمل های اینجا را دنبال کنید. لطفاً توجه داشته باشید که این پیوند فقط تا 15 جولای 2025 برای بازخرید معتبر است.
- Cloud Shell را با کلیک بر روی این پیوند فعال کنید. می توانید با کلیک بر روی دکمه مربوطه از Cloud Shell بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژه ها) جابه جا شوید.
- پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که قبلاً احراز هویت شده‌اید و پروژه به ID پروژه شما تنظیم شده است:
gcloud auth list
- دستور زیر را در Cloud Shell اجرا کنید تا تأیید کنید که دستور gcloud از پروژه شما اطلاع دارد.
gcloud config list project
- اگر پروژه شما تنظیم نشده است، از دستور زیر برای تنظیم آن استفاده کنید:
gcloud config set project <YOUR_PROJECT_ID>
- حتما پایتون 3.9+ را داشته باشید
برای سایر دستورات و استفاده از gcloud به اسناد مراجعه کنید.
3. نمونه اولیه
به Google AI Studio بروید. شروع به تایپ کردن در درخواست خود کنید. این درخواست من است:
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
پارامترها را در سمت راست تنظیم و پیکربندی کنید تا پاسخ بهینه را دریافت کنید.
بر اساس این توصیف ساده، Gemini از من یک درخواست فوق‌العاده دقیق برای شروع بازسازی من ساخت! در واقع، ما از Gemini برای دریافت پاسخ‌های بهتر از AI Studio و مدل‌هایمان استفاده می‌کنیم. همچنین می‌توانید مدل‌های مختلفی را بر اساس موارد استفاده خود انتخاب کنید.
ما Gemini 2.5 Pro را انتخاب کرده ایم. این یک مدل تفکر است، به این معنی که ما توکن‌های خروجی بیشتری، در این مورد تا 65 هزار توکن، برای تحلیل‌های طولانی و اسناد دقیق دریافت می‌کنیم. جعبه تفکر Gemini زمانی می آید که Gemini 2.5 Pro را فعال کنید که دارای قابلیت استدلال بومی است و می تواند درخواست های متنی طولانی را انجام دهد.
متن پاسخ را در زیر ببینید:
استودیوی هوش مصنوعی داده‌های من را تجزیه و تحلیل کرد و همه این موارد مانند کابینت‌ها، رومیزی‌ها، پشتی، کف‌پوش، سینک، انسجام، پالت رنگ و انتخاب مواد را تولید کرد. جمینی حتی به منابع استناد می کند!
اکنون سعی کنید این ایده را با یک اعلان متفاوت ببینید.
- این دستور را کپی کرده و در ویرایشگر سریع پیست کنید:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- تصویری از آشپزخانه فعلی خود را پیوست کنید (یا می توانید از نمونه تصویر آشپزخانه من استفاده کنید).
- مدل را به "Gemini 2.0 Flash Preview Image Generation" تغییر دهید تا به تولید تصاویر دسترسی داشته باشید.
من این خروجی رو گرفتم:
این قدرت جمینی است!
از درک ویدیوها، تولید تصاویر بومی، تا پایه‌گذاری اطلاعات واقعی با جستجوی Google – چیزهایی وجود دارند که فقط با Gemini ساخته می‌شوند.
از استودیوی هوش مصنوعی، می‌توانید این نمونه اولیه را بگیرید، کلید API را بگیرید و با استفاده از قدرت Vertex AI ADK آن را به یک برنامه کاربردی کامل تبدیل کنید.
4. راه اندازی ADK
اکنون اجازه دهید به ترمینال Cloud Shell که در بخش "قبل از شروع" فعال کرده ایم برویم:
- ایجاد و فعال کردن محیط مجازی (توصیه می شود)
از ترمینال Cloud Shell خود، یک محیط مجازی ایجاد کنید:
python -m venv .venv
فعال کردن محیط مجازی:
source .venv/bin/activate
- ADK را نصب کنید
pip install google-adk
5. ساختار پروژه
- از Cloud Shell Terminal، یک دایرکتوری ریشه برای برنامه های عامل خود در محل پروژه مورد نظر خود ایجاد کنید:
mkdir agentic-apps
- در داخل دایرکتوری اصلی، یک پوشه خاص برای پروژه فعلی ما ایجاد کنید:
mkdir renovation-agent
- به ویرایشگر Cloud Shell بروید و با ایجاد فایل‌ها (برای شروع خالی) ساختار پروژه زیر را ایجاد کنید:
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. کد منبع
- به « init .py» بروید و با محتوای زیر به‌روزرسانی کنید:
from . import agent
- به agent.py بروید و فایل را با محتوای زیر از مسیر زیر به روز کنید:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
در agent.py، وابستگی‌های لازم را وارد می‌کنیم، پارامترهای پیکربندی را از فایل .env بازیابی می‌کنیم و root_agent را تعریف می‌کنیم که یک سند پیشنهادی ایجاد می‌کند و آن را در یک سطل ذخیره‌سازی ابری ذخیره می‌کند. برای انجام مرحله Cloud Storage از ابزاری به نام store_pdf استفاده می کنیم.
- مطمئن شوید که Cloud Storage Bucket را دارید
این برای ذخیره سند پیشنهادی است که عامل ایجاد می کند. آن را ایجاد کنید و دسترسی را فراهم کنید تا سیستم عاملی که با Vertex AI ایجاد می کنیم بتواند به آن دسترسی داشته باشد. در اینجا نحوه انجام این کار آمده است:
https://cloud.google.com/storage/docs/creating-buckets#console
نام سطل خود را " next-demo-store " بگذارید. اگر نام آن را چیز دیگری می‌گذارید، به یاد داشته باشید که مقدار STORAGE_BUCKET را در فایل env. به‌روزرسانی کنید (در مرحله تنظیم متغیرهای ENV).
- برای تنظیم دسترسی به سطل، به کنسول Cloud Storage و به Storage Bucket بروید (در مورد ما نام سطل "next-demo-storage" است: https://console.cloud.google.com/storage/browser/next-demo-storage .
به Permissions -> View Principals -> Grant Access بروید. Principals را به عنوان "allUsers" و Role را به عنوان "Storage Object User" انتخاب کنید.
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- ایجاد لیست وابستگی ها
همه وابستگی ها را در requirement.txt فهرست کنید. می توانید این را از repo کپی کنید.
توضیح کد منبع سیستم عامل تک
فایل agent.py ساختار و رفتار سیستم چند عامله بازسازی آشپزخانه ما را با استفاده از کیت توسعه عامل (ADK) تعریف می کند. بیایید اجزای اصلی را تجزیه کنیم:
تعریف عامل
عامل ریشه (ارکستراتور): پیشنهاد_عامل
root_agent به عنوان هماهنگ کننده این سیستم تک عاملی عمل می کند. درخواست بازسازی اولیه را دریافت می کند و تعیین می کند که بر اساس نیازهای درخواست از چه ابزارهایی استفاده کند.
سپس root_agent پاسخ‌ها را از ابزارها جمع‌آوری می‌کند و آنها را ترکیب می‌کند تا پاسخی جامع به کاربر ارائه دهد. در این مورد ما فقط یک ابزار "store_pdf" داریم.
7. جریان داده و مفاهیم کلیدی
کاربر درخواستی را از طریق رابط ADK (چه ترمینال یا رابط وب) آغاز می کند.
- درخواست توسط root_agent دریافت می شود.
- root_agent درخواست را تجزیه و تحلیل می کند و آن را در صورت لزوم به ابزار هدایت می کند.
- ابزار "store_pdf" برای نوشتن محتوای متنی بازسازی شده در یک فایل PDF و آپلود آن در Google Cloud Storage طراحی شده است.
- سپس پاسخ را به root_agent برمی گرداند.
- root_agent پاسخ ها را ترکیب می کند و خروجی نهایی را به کاربر ارائه می دهد.
LLM (مدل های زبان بزرگ)
عوامل برای تولید متن، پاسخ به سؤالات و انجام وظایف استدلالی، به شدت به LLMها متکی هستند. LLMها "مغز"هایی هستند که در پشت توانایی نمایندگان برای درک و پاسخگویی به درخواست‌های کاربر قرار دارند. ما در این برنامه از Gemini 2.5 استفاده می کنیم.
Google Cloud Storage
برای ذخیره اسناد پیشنهادی بازسازی ایجاد شده استفاده می شود. شما باید یک سطل ایجاد کنید و مجوزهای لازم را برای دسترسی عوامل به آن بدهید.
اجرای ابری (اختیاری)
OrderingAgent از یک تابع Cloud Run برای ارتباط با AlloyDB استفاده می کند. Cloud Run یک محیط بدون سرور برای اجرای کد در پاسخ به درخواست های HTTP فراهم می کند.
AlloyDB
اگر از OrderingAgent استفاده می کنید، باید یک پایگاه داده AlloyDB برای ذخیره اطلاعات سفارش راه اندازی کنید.
فایل env
فایل .env اطلاعات حساسی مانند کلیدهای API، اعتبار پایگاه داده و نام سطل را ذخیره می کند. بسیار مهم است که این فایل را ایمن نگه دارید و آن را به مخزن خود متعهد نکنید. همچنین تنظیمات پیکربندی را برای نمایندگان و پروژه Google Cloud شما ذخیره می کند. root_agent یا توابع پشتیبان معمولاً مقادیر این فایل را می خوانند. مطمئن شوید که تمام متغیرهای مورد نیاز به درستی در فایل env. تنظیم شده اند. این شامل نام سطل Cloud Storage نیز می شود
8. راه اندازی مدل
توانایی نماینده شما برای درک درخواست‌های کاربر و ایجاد پاسخ توسط یک مدل زبان بزرگ (LLM) ارائه می‌شود. نماینده شما باید با این سرویس خارجی LLM تماس های ایمن برقرار کند که به اعتبارنامه احراز هویت نیاز دارد. بدون احراز هویت معتبر، سرویس LLM درخواست های عامل را رد می کند و عامل قادر به کار نخواهد بود.
- یک کلید API از Google AI Studio دریافت کنید.
- در مرحله بعدی که فایل .env را راه اندازی کردید،
<<your API KEY>>را با مقدار واقعی کلید API خود جایگزین کنید.
9. تنظیم متغیرهای ENV
- مقادیر خود را برای پارامترهای موجود در فایل template.env در این مخزن تنظیم کنید. در مورد من، .env این متغیرها را دارد:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
جانشین ها را با مقادیر خود جایگزین کنید.
10. نماینده خود را اجرا کنید
- با استفاده از ترمینال، به دایرکتوری والد پروژه نماینده خود بروید:
cd agentic-apps/renovation-agent
- همه وابستگی ها را نصب کنید
pip install -r requirements.txt
- برای اجرای عامل می توانید دستور زیر را در ترمینال Cloud Shell خود اجرا کنید:
adk run .
- می توانید موارد زیر را برای اجرای آن در یک UI وب ارائه شده ADK اجرا کنید:
adk web
- با دستورات زیر تست کنید:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
11. نتیجه
برای دستور adk اجرا کنید. نتیجه به شرح زیر است"
...
اگر سند پیشنهاد نوسازی در سطل ذخیره‌سازی ابری ایجاد شده باشد، می‌توانید تأیید کنید.
12. تمیز کردن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع استفاده شده در این پست، این مراحل را دنبال کنید:
- در کنسول Google Cloud، به صفحه مدیریت منابع بروید.
- در لیست پروژه، پروژه ای را که می خواهید حذف کنید انتخاب کنید و سپس روی Delete کلیک کنید.
- در محاوره، شناسه پروژه را تایپ کنید و سپس روی Shut down کلیک کنید تا پروژه حذف شود.
13. تبریک میگم
تبریک می گویم! شما با موفقیت برنامه چند عامله خود را با استفاده از ADK ایجاد کرده اید و با آن تعامل برقرار کرده اید! سیستم چند عاملی برای ساده کردن فرآیند بازسازی آشپزخانه با خودکار کردن وظایفی مانند تولید پیشنهاد، بررسی مجوز و ردیابی وضعیت سفارش طراحی شده است. هر عامل نقش خاصی دارد و root_agent فعالیت های آنها را برای ارائه راه حل جامع هماهنگ می کند. این سیستم از LLM ها، خدمات Google Cloud و APIهای خارجی بالقوه برای ارائه عملکرد خود استفاده می کند. در اینجا یک لینک به مستندات محصول است.