۱. هدف این آزمایشگاه
در این آزمایشگاه عملی، شما یاد خواهید گرفت که چگونه با استفاده از ADK (Agent Development Kit) Visual Builder، عاملها را ایجاد کنید. ADK (Agent Development Kit) Visual Builder روشی کمکد برای ایجاد عاملهای ADK (Agent Development Kit) ارائه میدهد. شما یاد خواهید گرفت که چگونه برنامه را بهصورت محلی آزمایش کرده و در Cloud Run مستقر کنید.
آنچه یاد خواهید گرفت
- اصول اولیه ADK (کیت توسعه عامل) را درک کنید.
- اصول اولیه ADK (کیت توسعه عامل) Visual Builder را درک کنید
- یاد بگیرید که چگونه با استفاده از ابزارهای GUI، Agents ایجاد کنید.
- بیاموزید که چگونه به راحتی عاملها را در Cloud Run مستقر و استفاده کنید.
شکل ۱: با ADK Visual Builder میتوانید با استفاده از رابط کاربری گرافیکی و با کدنویسی کم، عاملها را ایجاد کنید
۲. راهاندازی پروژه
- اگر از قبل پروژهای ندارید که بتوانید از آن استفاده کنید، باید یک پروژه جدید در کنسول GCP ایجاد کنید. پروژهای را که در انتخابگر پروژه (بالا سمت چپ کنسول Google Cloud) قرار دارد، انتخاب کنید.
شکل ۲: کلیک روی کادر کنار لوگوی گوگل کلود به شما امکان انتخاب پروژهتان را میدهد. مطمئن شوید که پروژهتان انتخاب شده است.
- در این آزمایش، ما از ویرایشگر Cloud Shell برای انجام وظایف خود استفاده خواهیم کرد. Cloud Shell را باز کنید و پروژه را با استفاده از Cloud Shell تنظیم کنید.
- برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
- اگر ترمینال از قبل باز نشده است، با کلیک روی ترمینال>ترمینال جدید از منو، آن را باز کنید. میتوانید تمام دستورات این آموزش را در این ترمینال اجرا کنید.
- میتوانید با استفاده از دستور زیر در ترمینال Cloud Shell بررسی کنید که آیا پروژه از قبل احراز هویت شده است یا خیر.
gcloud auth list
- برای تأیید پروژه خود، دستور زیر را در Cloud Shell اجرا کنید
gcloud config list project
- شناسه پروژه را کپی کنید و از دستور زیر برای تنظیم آن استفاده کنید.
gcloud config set project <YOUR_PROJECT_ID>
- اگر نمیتوانید شناسه پروژه خود را به خاطر بیاورید، میتوانید تمام شناسههای پروژه خود را با ... فهرست کنید.
gcloud projects list
۳. فعال کردن APIها
برای اجرای این آزمایشگاه باید برخی از سرویسهای API را فعال کنیم. دستور زیر را در Cloud Shell اجرا کنید.
gcloud services enable aiplatform.googleapis.com
gcloud services enable cloudresourcemanager.googleapis.com
معرفی API ها
- رابط برنامهنویسی کاربردی هوش مصنوعی ورتکس (
aiplatform.googleapis.com) امکان دسترسی به پلتفرم هوش مصنوعی ورتکس را فراهم میکند و به برنامه شما اجازه میدهد تا با مدلهای Gemini برای تولید متن، جلسات چت و فراخوانی تابع تعامل داشته باشد. - رابط برنامهنویسی کاربردی مدیریت منابع ابری (
cloudresourcemanager.googleapis.com) به شما امکان میدهد تا به صورت برنامهنویسی، فرادادههای پروژههای گوگل کلود خود، مانند شناسه و نام پروژه را مدیریت کنید، که اغلب توسط سایر ابزارها و SDKها برای تأیید هویت و مجوزهای پروژه مورد نیاز است.
۴. تأیید کنید که آیا اعتبار شما اعمال شده است یا خیر
در مرحله راهاندازی پروژه، شما برای دریافت اعتبار رایگان که به شما امکان استفاده از خدمات گوگل کلود را میدهد، اقدام کردید. وقتی اعتبارها را اعمال میکنید، یک حساب پرداخت رایگان جدید به نام «حساب پرداخت آزمایشی پلتفرم گوگل کلود» ایجاد میشود. برای اطمینان از اعمال اعتبارها، مراحل زیر را در ویرایشگر پوسته کلود دنبال کنید.
curl -s https://raw.githubusercontent.com/haren-bh/gcpbillingactivate/main/activate.py | python3
در صورت موفقیت، باید بتوانید نتیجه را مانند زیر مشاهده کنید: اگر عبارت "پروژه با موفقیت پیوند داده شد" را مشاهده کردید، حساب صورتحساب شما به درستی تنظیم شده است. با اجرای مرحله بالا میتوانید بررسی کنید که آیا حساب شما پیوند داده شده است یا خیر، در صورت عدم پیوند، آن را برای شما پیوند میدهد. اگر پروژه را انتخاب نکرده باشید، از شما خواسته میشود که یک پروژه انتخاب کنید یا میتوانید این کار را از قبل با دنبال کردن مراحل راهاندازی پروژه انجام دهید. 
شکل ۳: تأیید اتصال حساب صورتحساب
۵. مقدمهای بر کیت توسعه عامل
کیت توسعه عامل چندین مزیت کلیدی برای توسعهدهندگانی که برنامههای عاملمحور میسازند، ارائه میدهد:
- سیستمهای چندعاملی : با ترکیب چندین عامل تخصصی در یک سلسله مراتب، برنامههای کاربردی ماژولار و مقیاسپذیر بسازید. هماهنگی و تفویض اختیار پیچیده را امکانپذیر کنید.
- اکوسیستم غنی ابزار : عاملها را به قابلیتهای متنوعی مجهز کنید: از ابزارهای از پیش ساخته شده (جستجو، اجرای کد و غیره) استفاده کنید، توابع سفارشی ایجاد کنید، ابزارها را از چارچوبهای عامل شخص ثالث (LangChain، CrewAI) ادغام کنید، یا حتی از عاملهای دیگر به عنوان ابزار استفاده کنید.
- ارکستراسیون انعطافپذیر : تعریف گردشهای کاری با استفاده از عاملهای گردش کار (
SequentialAgent،ParallelAgentوLoopAgent) برای خطوط لوله قابل پیشبینی، یا بهرهگیری از مسیریابی پویا مبتنی بر LLM (انتقالLlmAgent) برای رفتار تطبیقی. - تجربه یکپارچه توسعهدهنده : توسعه، آزمایش و اشکالزدایی به صورت محلی با یک رابط خط فرمان قدرتمند و یک رابط کاربری توسعه تعاملی. بررسی رویدادها، وضعیت و اجرای عامل گام به گام.
- ارزیابی داخلی : با ارزیابی کیفیت پاسخ نهایی و مسیر اجرای گام به گام در برابر موارد آزمایشی از پیش تعریف شده، عملکرد عامل را به طور سیستماتیک ارزیابی کنید.
- آماده برای استقرار : عاملهای خود را در هر مکانی کانتینریزه و مستقر کنید - به صورت محلی اجرا کنید، با Vertex AI Agent Engine مقیاسپذیر کنید، یا با استفاده از Cloud Run یا Docker در زیرساختهای سفارشی ادغام شوید.
در حالی که سایر SDK های Gen AI یا چارچوب های عامل نیز به شما امکان می دهند مدل ها را پرس و جو کنید و حتی آنها را با ابزارها توانمند کنید، هماهنگی پویا بین چندین مدل نیاز به مقدار قابل توجهی کار از طرف شما دارد.
کیت توسعه عامل، چارچوبی سطح بالاتر از این ابزارها ارائه میدهد و به شما این امکان را میدهد که به راحتی چندین عامل را برای گردشهای کاری پیچیده اما آسان برای نگهداری، به یکدیگر متصل کنید.
شکل ۴: موقعیت ADK (کیت توسعه عامل)
در نسخههای اخیر، یک ابزار ADK Visual Builder به ADK (کیت توسعه عامل) اضافه شده است که به شما امکان میدهد عاملهای ADK (کیت توسعه عامل) را با کد کم بسازید. در این آزمایش، ابزار ADK Visual Builder را به طور مفصل بررسی خواهیم کرد.
۶. ADK را نصب کنید و محیط خود را راهاندازی کنید
اول از همه باید محیط را طوری تنظیم کنیم که بتوانیم ADK (کیت توسعه عامل) را اجرا کنیم. در این آزمایش ADK (کیت توسعه عامل) را اجرا خواهیم کرد و تمام وظایف را در ویرایشگر پوسته ابری گوگل (Google Cloud In Cloud Shell Editor ) انجام خواهیم داد.
یک ویرایشگر Cloud Shell آماده کنید
- برای دسترسی مستقیم به ویرایشگر Cloud Shell ، روی این لینک کلیک کنید.
- روی ادامه کلیک کنید.
- وقتی از شما خواسته شد Cloud Shell را تأیید کنید، روی تأیید کلیک کنید.
- در ادامهی این آزمایش، میتوانید در این پنجره به عنوان IDE خود با ویرایشگر Cloud Shell و ترمینال Cloud Shell کار کنید.
- با استفاده از مسیر Terminal>New Terminal در ویرایشگر Cloud Shell، یک ترمینال جدید باز کنید. تمام دستورات زیر در این ترمینال اجرا خواهند شد.
ویرایشگر بصری ADK را اجرا کنید
- دستورات زیر را برای کپی کردن منبع مورد نیاز از گیتهاب و نصب کتابخانههای لازم اجرا کنید. دستورات را در ترمینال باز شده در ویرایشگر Cloud Shell اجرا کنید.
#create the project directory
mkdir ~/adkui
cd ~/adkui
- ما از uv برای ایجاد محیط پایتون استفاده خواهیم کرد (در ترمینال ویرایشگر Cloud Shell اجرا کنید):
#Install uv if you do not have installed yet
pip install uv
#go to the project directory
cd ~/adkui
#Create the virtual environment
uv venv
#use the newly created environment
source .venv/bin/activate
#install libraries
uv pip install google-adk==1.22.1
uv pip install python-dotenv
توجه : اگر نیاز به راهاندازی مجدد ترمینال داشتید، مطمئن شوید که محیط پایتون خود را با اجرای " source .venv/bin/activate " تنظیم کردهاید.
- در ویرایشگر به View->Toggle hidden files بروید. و در پوشه adkui یک فایل .env با محتوای زیر ایجاد کنید.
#go to adkui folder
cd ~/adkui
cat <<EOF>> .env
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
GOOGLE_CLOUD_LOCATION=us-central1
IMAGEN_MODEL="imagen-3.0-generate-002"
GENAI_MODEL="gemini-2.5-flash"
EOF
۷. با ADK Visual Builder یک Agent ساده ایجاد کنید
در این بخش، ما یک عامل ساده با استفاده از ADK Visual Builder ایجاد خواهیم کرد. ADK Visual Builder ابزاری مبتنی بر وب است که یک محیط طراحی گردش کار بصری برای ایجاد و مدیریت عاملهای ADK (Agent Development Kit) فراهم میکند. این ابزار به شما امکان میدهد عاملهای خود را در یک رابط گرافیکی مناسب برای مبتدیان طراحی، ساخت و آزمایش کنید و شامل یک دستیار مبتنی بر هوش مصنوعی است که به شما در ساخت عاملها کمک میکند.
شکل 5: سازنده بصری ADK
- به دایرکتوری adkui در ترمینال برگردید و دستور زیر را برای اجرای عامل به صورت محلی اجرا کنید (اجرا در ترمینال ویرایشگر Cloud Shell ). شما باید بتوانید سرور ADK را اجرا کنید و نتایجی مشابه شکل 6 را در ترمینال مشاهده کنید.
#go to the directory adkui
cd ~/adkui
# Run the following command to run ADK locally
adk web
شکل ۶: راهاندازی برنامه ADK
- برای باز کردن ابزار رابط کاربری گرافیکی مبتنی بر مرورگر ADK (Agent Development Kit) روی آدرس http:// که در ترمینال نمایش داده میشود ، Ctrl+Click (برای مک CMD+Click ) را نگه دارید.
شکل 7: رابط کاربری وب ADK، ADK دارای اجزای زیر است: 1: تغییر حالت روشن و تاریک 2: بستن پنل 3: ایجاد عامل 4: ویرایش و عامل
- برای ایجاد یک نماینده جدید، دکمه "+" را فشار دهید.
شکل ۸ : پنجرهی ایجاد یک برنامهی جدید
- نام "Agent1" را انتخاب کرده و ایجاد کنید.
شکل 9: رابط کاربری برای سازنده عامل
- این پنل به سه بخش اصلی تقسیم شده است: سمت چپ شامل کنترلهایی برای ایجاد عامل مبتنی بر رابط کاربری گرافیکی است، مرکز آن تصویری از پیشرفت شما را ارائه میدهد و سمت راست شامل دستیار برای ساخت عاملها با استفاده از زبان طبیعی است.
- نماینده شما با موفقیت ایجاد شد. برای ادامه روی دکمه ذخیره کلیک کنید. ( توجه: برای جلوگیری از از دست رفتن تغییرات، ضروری است که دکمه ذخیره را فشار دهید.)
- اکنون عامل باید برای آزمایش آماده باشد. برای شروع، در کادر چت، یک درخواست مانند زیر وارد کنید:
Hi, what can you do?
شکل ۱۰: آزمایش عامل.
۷. به ویرایشگر برگردیم، بیایید فایلهای تازه تولید شده را بررسی کنیم. اکسپلورر را در سمت چپ خواهید یافت. به پوشه adkgui بروید و آن را باز کنید تا پوشه Agent 1 نمایان شود. در این پوشه، میتوانید فایل YAML که agent را تعریف میکند، همانطور که در شکل زیر نشان داده شده است، بررسی کنید.
شکل ۱۱: تعریف عامل با استفاده از فایل YAML
- حالا بیایید به ویرایشگر رابط کاربری گرافیکی برگردیم و چند ویژگی به عامل اضافه کنیم. برای انجام این کار، دکمه ویرایش را فشار دهید (شکل 7، جزء شماره 4، نماد قلم را ببینید).
- ما قصد داریم یک ویژگی جستجوی گوگل را به عامل اضافه کنیم، برای این کار باید جستجوی گوگل را به عنوان ابزاری که در دسترس عامل است و یک عامل میتواند از آن استفاده کند، اضافه کنیم. برای انجام این کار، روی علامت "+" در کنار بخش ابزارها در پایین سمت چپ صفحه کلیک کنید و از منو روی ابزار داخلی کلیک کنید ( شکل 12 را ببینید ).
شکل ۱۲: افزودن یک ابزار جدید به یک عامل
- از فهرست ابزارهای داخلی، google_search را انتخاب کرده و روی ایجاد کلیک کنید (شکل ۱۲ را ببینید) . با این کار، جستجوی گوگل به عنوان ابزاری در عامل شما اضافه میشود.
- دکمه ذخیره را فشار دهید تا تغییرات ذخیره شوند.
شکل ۱۳: فهرست ابزارهای موجود در رابط کاربری ADK Visual Builder
- اکنون آماده آزمایش Agent هستید. ابتدا سرور ADK را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و در صورت اجرا ، CTRL+C را برای خاموش کردن سرور فشار دهید. برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- از لیست نمایندگان ، Agent1 را انتخاب کنید. اکنون نماینده شما میتواند در گوگل جستجو کند. در کادر گفتگو، با دستور زیر تست کنید.
What is the weather today in Yokohama?
شما باید پاسخ را از جستجوی گوگل مانند زیر ببینید. 
شکل ۱۴: جستجوی گوگل با عامل
- حالا بیایید به ویرایشگر برگردیم و کدی را که در این مرحله ایجاد شده است بررسی کنیم. از پنل کناری ویرایشگر اکسپلورر روی root_agent.yaml کلیک کنید تا باز شود. تأیید کنید که google_search به عنوان ابزار اضافه شده است (شکل 15).
شکل ۱۵: تأیید اینکه google_search به عنوان ابزاری در Agent1 اضافه شده است
۸. عامل را در Cloud Run مستقر کنید
حالا بیایید عامل ایجاد شده را در Cloud Run مستقر کنیم! با Cloud Run میتوانید برنامهها یا وبسایتها را به سرعت روی یک پلتفرم کاملاً مدیریتشده بسازید.
شما میتوانید سرویسهای frontend و backend، کارهای دستهای، LLMهای میزبان و بارهای کاری پردازش صف را بدون نیاز به مدیریت زیرساخت اجرا کنید.
در ترمینال ویرایشگر Cloud Shell ، اگر هنوز سرور ADK (Agent Development Kit) را اجرا میکنید، Ctrl+C را برای توقف آن فشار دهید.
- به دایرکتوری ریشه پروژه بروید.
cd ~/adkui
- کد استقرار را دریافت کنید. پس از اجرای دستور، باید فایل deploycloudrun.py را در پنل Cloud Shell Editor Explorer مشاهده کنید.
curl -LO https://raw.githubusercontent.com/haren-bh/codelabs/main/adk_visual_builder/deploycloudrun.py
- گزینههای استقرار را در deploycloudrun.py بررسی کنید. ما از دستور adk deploy برای استقرار عامل خود در Cloud Run استفاده خواهیم کرد. ADK (کیت توسعه عامل) گزینه داخلی برای استقرار عامل در Cloud Run دارد. ما باید پارامترهایی مانند شناسه پروژه Google Cloud، منطقه و غیره را مشخص کنیم. برای مسیر برنامه، این اسکریپت فرض میکند که agent_path=./Agent1. ما همچنین یک حساب سرویس جدید با مجوزهای لازم ایجاد میکنیم و آن را به Cloud Run متصل میکنیم. Cloud Run برای اجرای عامل به دسترسی به سرویسهایی مانند Vertex AI و Cloud Storage نیاز دارد.
command = [
"adk", "deploy", "cloud_run",
f"--project={project_id}",
f"--region={location}",
f"--service_name={service_name}",
f"--app_name={app_name}",
f"--artifact_service_uri=memory://",
f"--with_ui",
agent_path,
f"--",
f"--service-account={sa_email}",
]
- اسکریپت deploycloudrun.py را اجرا کنید.**. استقرار باید همانطور که در شکل زیر نشان داده شده است، شروع شود.**
python3 deploycloudrun.py
اگر پیام تأییدی مانند زیر دریافت کردید، برای همه پیامها Y و Enter را فشار دهید. depoycloudrun.py فرض میکند که عامل شما در پوشه Agent1 مانند آنچه در بالا ایجاد شد، قرار دارد.
شکل ۱۶: در حال استقرار عامل در Cloud Run، برای مشاهده پیامهای تأیید، Y را فشار دهید.
- پس از اتمام استقرار، باید URL سرویس مانند https://agent1service-78833623456.us-central1.run.app را مشاهده کنید.
- برای اجرای برنامه، آدرس اینترنتی (URL) را در مرورگر وب خود وارد کنید.
Figure 17: Agent running in Cloud Run
۹. ایجاد یک عامل با زیرعامل و ابزار سفارشی
در بخش قبلی شما یک عامل واحد با ابزار جستجوی گوگل داخلی ایجاد کردید. در این بخش شما یک سیستم چند عامله ایجاد خواهید کرد که در آن به عاملها اجازه میدهیم از ابزارهای سفارشی استفاده کنند.
- ابتدا سرور ADK (Agent Development Kit) را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و اگر سرور هنوز در حال اجرا است ، CTRL+C را برای خاموش کردن آن فشار دهید . برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- برای ایجاد یک Agent جدید، روی دکمه "+" کلیک کنید. در پنجره Agent، عبارت "Agent2" (شکل 18) را وارد کرده و روی "Create" کلیک کنید.
شکل ۱۸: ایجاد یک برنامه عامل جدید.
- در بخش دستورالعملهای Agent2 موارد زیر را وارد کنید.
You are an agent that takes image creation instruction from the user and passes it to your sub agent
- حالا یک زیرعامل به عامل ریشه اضافه خواهیم کرد. برای انجام این کار، روی دکمه "+" در سمت چپ منوی زیرعامل در پایین پنل سمت چپ (شکل 19) کلیک کنید و روی " عامل LLM " کلیک کنید. این کار یک عامل جدید به عنوان یک زیرعامل جدید برای عامل ریشه ایجاد میکند.
شکل ۱۹: یک Sub Agent جدید اضافه کنید.
- در دستورالعملهای مربوط به sub_agent_1 متن زیر را وارد کنید.
You are an Agent that can take instructions about an image and create an image using the create_image tool.
- حالا بیایید یک ابزار سفارشی روی این زیرعامل اضافه کنیم. این ابزار مدل Imagen را برای تولید تصویر با استفاده از دستورالعملهای کاربر فراخوانی میکند. برای انجام این کار، ابتدا روی زیرعامل ایجاد شده در مرحله قبل کلیک کنید و دکمه "+" را در کنار منوی ابزارها کلیک کنید. از لیست گزینههای ابزار، روی " ابزار تابع " کلیک کنید. این ابزار به ما امکان میدهد کد سفارشی خود را به ابزار اضافه کنیم.
شکل ۲۰: برای ایجاد یک ابزار جدید، روی ابزار Function کلیک کنید. ۸. نام ابزار را در کادر محاورهای Agent2.image_creation_tool.create_image قرار دهید. 
شکل ۲۱: نام ابزار را اضافه کنید
- برای ذخیره تغییرات، روی دکمه ذخیره کلیک کنید.
- در ترمینال ویرایشگر Cloud Shell ، کلیدهای Ctrl+S را فشار دهید تا سرور adk خاموش شود.
- در ترمینال دستور زیر را برای ایجاد فایل image_creation_tool.py وارد کنید.
touch ~/adkui/Agent2/image_creation_tool.py
- با کلیک روی image_creation_tool.py تازه ایجاد شده در پنل Explorer ویرایشگر Cloud Shell ، آن را باز کنید. محتوای image_creation_tool.py را با موارد زیر جایگزین کنید و آن را ذخیره کنید (Ctrl+S) .
import os
import io
import vertexai
from vertexai.preview.vision_models import ImageGenerationModel
from dotenv import load_dotenv
import uuid
from typing import Union
from datetime import datetime
from google import genai
from google.genai import types
from google.adk.tools import ToolContext
import logging
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
async def create_image(prompt: str,tool_context: ToolContext) -> Union[bytes, str]:
"""
Generates an image based on a text prompt using a Vertex AI Imagen model.
Args:
prompt: The text prompt to generate the image from.
Returns:
The binary image data (PNG format) on success, or an error message string on failure.
"""
print(f"Attempting to generate image for prompt: '{prompt}'")
try:
# Load environment variables from .env file two levels up
dotenv_path = os.path.join(os.path.dirname(__file__), '..', '..', '.env')
load_dotenv(dotenv_path=dotenv_path)
project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
location = os.getenv("GOOGLE_CLOUD_LOCATION")
model_name = os.getenv("IMAGEN_MODEL")
client = genai.Client(
vertexai=True,
project=project_id,
location=location,
)
response = client.models.generate_images(
model="imagen-3.0-generate-002",
prompt=prompt,
config=types.GenerateImagesConfig(
number_of_images=1,
aspect_ratio="9:16",
safety_filter_level="block_low_and_above",
person_generation="allow_adult",
),
)
if not all([project_id, location, model_name]):
return "Error: Missing GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, or IMAGEN_MODEL in .env file."
vertexai.init(project=project_id, location=location)
model = ImageGenerationModel.from_pretrained(model_name)
images = model.generate_images(
prompt=prompt,
number_of_images=1
)
if response.generated_images is None:
return "Error: No image was generated."
for generated_image in response.generated_images:
# Get the image bytes
image_bytes = generated_image.image.image_bytes
counter = str(tool_context.state.get("loop_iteration", 0))
artifact_name = f"generated_image_" + counter + ".png"
# Save as ADK artifact (optional, if still needed by other ADK components)
report_artifact = types.Part.from_bytes(
data=image_bytes, mime_type="image/png"
)
await tool_context.save_artifact(artifact_name, report_artifact)
logger.info(f"Image also saved as ADK artifact: {artifact_name}")
return {
"status": "success",
"message": f"Image generated . ADK artifact: {artifact_name}.",
"artifact_name": artifact_name,
}
except Exception as e:
error_message = f"An error occurred during image generation: {e}"
print(error_message)
return error_message
- ابتدا سرور ADK (Agent Development Kit) را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و اگر سرور هنوز در حال اجرا است ، CTRL+C را برای خاموش کردن آن فشار دهید . برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- در تب رابط کاربری ADK (کیت توسعه عامل) ، Agent2 را در لیست عاملها انتخاب کنید و دکمه ویرایش (آیکون قلم) را فشار دهید. در ویرایشگر بصری ADK (کیت توسعه عامل) روی دکمه ذخیره کلیک کنید تا تغییرات اعمال شوند.
- حالا میتوانیم Agent جدید را آزمایش کنیم.
- در رابط چت رابط کاربری ADK (کیت توسعه عامل) عبارت زیر را وارد کنید. همچنین میتوانید عبارات دیگری را امتحان کنید. باید نتایج نشان داده شده در شکل ۲۲ را ببینید.
Create an image of a cat
شکل ۲۲: رابط کاربری چت ADK UI
۱۰. یک عامل گردش کار ایجاد کنید
در حالی که مرحله قبلی شامل ساخت یک عامل با یک عامل فرعی و ابزارهای تخصصی ایجاد تصویر بود، این مرحله بر بهبود قابلیتهای عامل تمرکز دارد. ما با اطمینان از بهینهسازی درخواست اولیه کاربر قبل از ایجاد تصویر، این فرآیند را بهبود خواهیم بخشید. برای دستیابی به این هدف، یک عامل ترتیبی در عامل ریشه ادغام خواهد شد تا گردش کار دو مرحلهای زیر را انجام دهد:
- اعلان را از نماینده ریشه دریافت کنید و بهبود اعلان را انجام دهید.
- دستور اصلاحشده را به عامل سازنده تصویر ارسال کنید تا تصویر نهایی را با استفاده از IMAGEN تولید کند.
- ابتدا سرور ADK (Agent Development Kit) را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و اگر سرور هنوز در حال اجرا است ، CTRL+C را برای خاموش کردن آن فشار دهید . برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- از میان گزینههای انتخاب عامل، عامل ۲ را انتخاب کرده و روی دکمه ویرایش (آیکون خودکار) کلیک کنید.
- روی Agent2 (عامل ریشه) کلیک کنید و روی دکمه "+" در کنار منوی Sub Agents کلیک کنید. و از لیست گزینهها روی Sequential Agent کلیک کنید.
- شما باید ساختار عامل را مانند آنچه در شکل 23 نشان داده شده است، ببینید.
شکل ۲۳: ساختار عامل ترتیبی
- حالا اولین عامل را به Sequential Agent اضافه میکنیم که به عنوان یک تقویتکننده اعلان عمل میکند. برای انجام این کار، روی دکمه Add sub-agent در کادر SequentialAgent کلیک کنید و LLM Agent را انتخاب کنید.
- ما باید یک Agent دیگر به دنباله اضافه کنیم، بنابراین مرحله 6 را برای اضافه کردن یک LLM Agent دیگر تکرار کنید ( دکمه + را فشار دهید و LLMAgent را انتخاب کنید).
- روی sub_agent_4 کلیک کنید و با کلیک روی آیکون "+" کنار ابزارها در پنل سمت چپ، یک ابزار جدید اضافه کنید. از بین گزینهها، روی " ابزار تابع " کلیک کنید. در کادر محاورهای، نام ابزار را Agent2.image_creation_tool.create_image بگذارید و روی "ایجاد" کلیک کنید.
- حالا میتوانیم sub_agent_1 را حذف کنیم، زیرا با sub_agent_2 پیشرفتهتر جایگزین شده است. برای انجام این کار، روی دکمه Delete در سمت راست sub_agent_1 در نمودار کلیک کنید.
شکل ۲۴: حذف sub_agent_1 ۱۰. ساختار عامل ما شبیه شکل ۲۵ است.
شکل ۲۵: ساختار نهایی عامل بهبود یافته
- روی sub_agent_3 کلیک کنید و در دستورالعملها موارد زیر را وارد کنید.
Act as a professional AI Image Prompt Engineer. I will provide you
with a basic idea for an image. Your job is to expand my idea into
a detailed, high-quality prompt for models like Imagen.
For every input, output the following structure:
1. **Optimized Prompt**: A vivid, descriptive paragraph including
subject, background, lighting, and textures.
2. **Style & Medium**: Specify if it is photorealistic, digital art,
oil painting, etc.
3. **Camera & Lighting**: Define the lens (e.g., 85mm), angle,
and light quality (e.g., volumetric, golden hour).
Guidelines: Use sensory language, avoid buzzwords like 'photorealistic'
unless necessary, and focus on specific artistic descriptors.
Once the prompt is created send the prompt to the
- روی sub_agent_4 کلیک کنید. دستورالعمل را به صورت زیر تغییر دهید.
You are an agent that takes instructions about an image and can generate the image using the create_image tool.
- روی دکمه ذخیره کلیک کنید
- به پنل Cloud Shell Editor Explorer بروید و فایلهای yaml مربوط به agent را باز کنید. فایلهای agent باید شبیه زیر باشند.
root_agent.yaml
name: Agent2
model: gemini-2.5-flash
agent_class: LlmAgent
instruction: You are an agent that takes image creation instruction from the
user and passes it to your sub agent
sub_agents:
- config_path: ./sub_agent_2.yaml
tools: []
sub_agent_2.yaml
name: sub_agent_2
agent_class: SequentialAgent
sub_agents:
- config_path: ./sub_agent_3.yaml
- config_path: ./sub_agent_4.yaml
sub_agent_3.yaml
name: sub_agent_3
model: gemini-2.5-flash
agent_class: LlmAgent
instruction: |
Act as a professional AI Image Prompt Engineer. I will provide you with a
basic idea for an image. Your job is to expand my idea into a detailed,
high-quality prompt for models like Imagen.
For every input, output the following structure: 1. **Optimized Prompt**: A
vivid, descriptive paragraph including subject, background, lighting, and
textures. 2. **Style & Medium**: Specify if it is photorealistic, digital
art, oil painting, etc. 3. **Camera & Lighting**: Define the lens (e.g.,
85mm), angle, and light quality (e.g., volumetric, golden hour).
Guidelines: Use sensory language, avoid buzzwords like
'photorealistic' unless necessary, and focus on specific artistic
descriptors. Once the prompt is created send the prompt to the
sub_agents: []
tools: []
sub_agent_4.yaml
name: sub_agent_4
model: gemini-2.5-flash
agent_class: LlmAgent
instruction: You are an agent that takes instructions about an image and
generate the image using the create_image tool.
sub_agents: []
tools:
- name: Agent2.image_creation_tool.create_image
- حالا بیایید آن را آزمایش کنیم.
- ابتدا سرور ADK (Agent Development Kit) را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و اگر سرور هنوز در حال اجرا است ، CTRL+C را برای خاموش کردن آن فشار دهید . برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- از لیست agent ها، Agent2 را انتخاب کنید. و عبارت زیر را وارد کنید.
Create an image of a Cat
- در حالی که Agent در حال کار است، میتوانید به ترمینال در ویرایشگر Cloud Shell نگاه کنید تا ببینید در پسزمینه چه اتفاقی میافتد. نتیجه نهایی باید مانند شکل ۲۶ باشد.
شکل ۲۶: آزمایش عامل
۱۱. با استفاده از Agent Builder Assistant یک نماینده ایجاد کنید
دستیار سازنده عامل (Agent Builder Assistant) بخشی از سازنده بصری ADK است که امکان ایجاد تعاملی عاملها را از طریق اعلانها در یک رابط چت ساده فراهم میکند و سطوح مختلفی از پیچیدگی را امکانپذیر میسازد. با استفاده از سازنده بصری ADK ، میتوانید بازخورد بصری فوری در مورد عاملهایی که توسعه میدهید دریافت کنید. در این آزمایش، عاملی خواهیم ساخت که قادر به تولید یک کتاب کمیک HTML از درخواست کاربر است. کاربران ممکن است یک اعلان ساده مانند "ایجاد یک کتاب کمیک درباره هانسل و گرتل" ارائه دهند، یا میتوانند یک داستان کامل را وارد کنند. سپس عامل روایت را تجزیه و تحلیل میکند، آن را به چندین پنل تقسیم میکند و از نانوبانانا برای تولید تصاویر کمیک استفاده میکند و در نهایت نتیجه را در قالب HTML بستهبندی میکند.
شکل ۲۷: رابط کاربری دستیار سازنده عامل
بیایید شروع کنیم!
- ابتدا سرور ADK (Agent Development Kit) را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و اگر سرور هنوز در حال اجرا است ، CTRL+C را برای خاموش کردن آن فشار دهید . برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- در رابط کاربری گرافیکی ADK (کیت توسعه عامل) روی دکمه "+" کلیک کنید تا یک عامل جدید ایجاد شود.
- در کادر محاورهای، عبارت « Agent3 » را وارد کرده و روی دکمه « ایجاد » کلیک کنید.
شکل ۲۸: ایجاد عامل جدید Agent3
- در پنل دستیار (Assistant Pane) در سمت راست، عبارت زیر را وارد کنید. عبارت زیر تمام دستورالعملهای لازم برای ایجاد سیستمی از عاملها برای ایجاد یک عامل مبتنی بر HTML را دارد.
System Goal: You are the Studio Director (Root Agent). Your objective is to manage a linear pipeline of four ADK Sequential Agents to transform a user's seed idea into a fully rendered, responsive HTML5 comic book.
0. Root Agent: The Studio Director
Role: Orchestrator and State Manager.
Logic: Receives the user's initial request. It initializes the workflow and ensures the output of each Sub-Agent is passed as the context for the next. It monitors the sequence to ensure no steps are skipped. Make sure the query explicitly mentions "Create me a comic of ..." if it's just a general question or prompt just answer the question.
1. Sub-Agent: The Scripting Agent (Sequential Step 1)
Role: Narrative & Character Architect.
Input: Seed idea from Root Agent.
Logic: 1. Create a Character Manifest: Define 3 specific, unchangeable visual identifiers
for every character (e.g., "Gretel: Blue neon hair ribbons, silver apron,
glowing boots").
2. Expand the seed idea into a coherent narrative arc.
Output: A narrative script and a mandatory character visual guide.
2. Sub-Agent: The Panelization Agent (Sequential Step 2)
Role: Cinematographer & Storyboarder.
Input: Script and Character Manifest from Step 1.
Logic:
1. Divide the script into exactly X panels (User-defined or default to 8).
2. For each panel, define a specific composition (e.g., "Panel 1:
Wide shot of the gingerbread house").
Output: A structured list of exactly X panel descriptions.
3. Sub-Agent: The Image Synthesis Agent (Sequential Step 3)
Role: Technical Artist & Asset Generator.
Input: The structured list of panel descriptions from Step 2.
Logic:
1. Iterative Generation: You must execute the "generate_image" tool in
"image_generation.py" file
(Nano Banana) individually for each panel defined in Step 2.
2. Prompt Engineering: For every panel, translate the description into a
Nano Banana prompt, strictly enforcing the character identifiers
(e.g., the "blue neon ribbons") and the global style: "vibrant comic book style,
heavy ink lines, cel-shaded, 4k." . Make sure that the necessary speech bubbles
are present in the image representing the dialogue.
3. Mapping: Associate each generated image URL with its corresponding panel
number and dialogue.
Output: A complete gallery of X images mapped to their respective panel data.
4. Sub-Agent: The Assembly Agent (Sequential Step 4)
Role: Frontend Developer.
Input: The mapped images and panel text from Step 3.
Logic:
1. Write a clean, responsive HTML5/CSS3 file that shows the comic. The comic should be
Scrollable with image on the top and the description below the image.
2. Use "write_comic_html" tool in file_writer.py to write the created html file in
the "output" folder.
4. In the "write_comic_html" tool add logic to copy the images folder to the
output folder so that the images in the html file are actually visible when
the user opens the html file.
Output: A final, production-ready HTML code block.
- ممکن است نماینده از شما بخواهد مدل مورد استفاده را وارد کنید که در این صورت از گزینه ارائه شده، gemini-2.5-pro را وارد کنید.
شکل ۲۹: اگر از شما خواسته شد مدل مورد استفاده را وارد کنید، عبارت gemini-2.5-pro را وارد کنید.
- دستیار ممکن است با طرح همراه شود و از شما بخواهد که تأیید کنید که آیا ادامه کار اشکالی ندارد. طرح را بررسی کنید و "OK" را تایپ کنید و "Enter" را فشار دهید.
شکل ۳۰: اگر طرح مناسب به نظر میرسد، تأیید را وارد کنید. ۸. پس از اتمام کار دستیار، باید بتوانید ساختار عامل را مطابق شکل ۳۱ مشاهده کنید.
شکل ۳۱: عامل ایجاد شده توسط دستیار سازنده عامل ۹. در داخل image_synthesis_agent (نام شما میتواند متفاوت باشد) روی ابزار "Agent3.tools.image_generation.gene..." کلیک کنید. اگر بخش آخر نام ابزار image_generation.generate_image نیست، آن را به image_generation.generate_image تغییر دهید. اگر نام از قبل روی آن تنظیم شده است، نیازی به تغییر نام نیست. برای ذخیره آن، دکمه "ذخیره" را فشار دهید.
شکل ۳۲: نام ابزار را به image_generation.generate_image تغییر دهید و ذخیره را فشار دهید.
- درون assembly_agent (نام agent شما میتواند متفاوت باشد)، روی ابزار **Agent3.tools.file_writer.write_comic_...** کلیک کنید. اگر بخش آخر نام ابزار **file_writer.write_comic_html** نیست، آن را به **file_writer.write_comic_html** تغییر دهید.
شکل ۳۳: نام ابزار را به file_writer.write_comic_html تغییر دهید. ۱۱. برای ذخیره Agent جدید ایجاد شده، دکمه Save را در پایین سمت چپ پنل Left فشار دهید. ۱۲. در پنجره Cloud Shell Editor Explorer، پوشه Agent3 را باز کنید و در داخل Agent3/ folder باید پوشه tools وجود داشته باشد. روی Agent3/tools/file_writer.py کلیک کنید تا باز شود و محتوای Agent3/tools/file_writer.py را با کد زیر جایگزین کنید. برای ذخیره، Ctrl+S را فشار دهید. توجه: اگرچه ممکن است دستیار Agent قبلاً کد صحیح را ایجاد کرده باشد، اما برای این آزمایش از کد آزمایش شده استفاده خواهیم کرد.
import os
import shutil
def write_comic_html(html_content: str, image_directory: str = "images") -> str:
"""
Writes the final HTML content to a file and copies the image assets.
Args:
html_content: A string containing the full HTML of the comic.
image_directory: The source directory where generated images are stored.
Returns:
A confirmation message indicating success or failure.
"""
output_dir = "output"
images_output_dir = os.path.join(output_dir, image_directory)
try:
# Create the main output directory
if not os.path.exists(output_dir):
os.makedirs(output_dir)
# Copy the entire image directory to the output folder
if os.path.exists(image_directory):
if os.path.exists(images_output_dir):
shutil.rmtree(images_output_dir) # Remove old images
shutil.copytree(image_directory, images_output_dir)
else:
return f"Error: Image directory '{image_directory}' not found."
# Write the HTML file
html_file_path = os.path.join(output_dir, "comic.html")
with open(html_file_path, "w") as f:
f.write(html_content)
return f"Successfully created comic at '{html_file_path}'"
except Exception as e:
return f"An error occurred: {e}"
- در پنجره Cloud Shell Editor Explorer، پوشه Agent3 را باز کنید و داخل پوشه **Agent3/** باید پوشه tools وجود داشته باشد. برای باز کردن آن، روی Agent3/tools/image_generation.py کلیک کنید و محتوای Agent3/tools/image_generation.py را با کد زیر جایگزین کنید. برای ذخیره، Ctrl+S را فشار دهید. توجه: اگرچه ممکن است دستیار عامل (Agent assistant) قبلاً کد صحیح را ایجاد کرده باشد، اما برای این آزمایش از کد آزمایش شده استفاده خواهیم کرد.
import time
import os
import io
import vertexai
from vertexai.preview.vision_models import ImageGenerationModel
from dotenv import load_dotenv
import uuid
from typing import Union
from datetime import datetime
from google import genai
from google.genai import types
from google.adk.tools import ToolContext
import logging
import asyncio
# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# It's better to initialize the client once and reuse it.
# IMPORTANT: Your Google Cloud Project ID must be set as an environment variable
# for the client to authenticate correctly.
def edit_image(client, prompt: str, previous_image: str, model_id: str) -> Union[bytes, None]:
"""
Calls the model to edit an image based on a prompt.
Args:
prompt: The text prompt for image editing.
previous_image: The path to the image to be edited.
model_id: The model to use for the edit.
Returns:
The raw image data as bytes, or None if an error occurred.
"""
try:
with open(previous_image, "rb") as f:
image_bytes = f.read()
response = client.models.generate_content(
model=model_id,
contents=[
types.Part.from_bytes(
data=image_bytes,
mime_type="image/png", # Assuming PNG, adjust if necessary
),
prompt,
],
config=types.GenerateContentConfig(
response_modalities=['IMAGE'],
)
)
# Extract image data
for part in response.candidates[0].content.parts:
if part.inline_data:
return part.inline_data.data
logger.warning("Warning: No image data was generated for the edit.")
return None
except FileNotFoundError:
logger.error(f"Error: The file {previous_image} was not found.")
return None
except Exception as e:
logger.error(f"An error occurred during image editing: {e}")
return None
async def generate_image(tool_context: ToolContext, prompt: str, image_name: str, previous_image: str = None) -> dict:
"""
Generates or edits an image and saves it to the 'images/' directory.
If 'previous_image' is provided, it edits that image. Otherwise, it generates a new one.
Args:
prompt: The text prompt for the operation.
image_name: The desired name for the output image file (without extension).
previous_image: Optional path to an image to be edited.
Returns:
A confirmation message with the path to the saved image or an error message.
"""
load_dotenv()
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
return "Error: GOOGLE_CLOUD_PROJECT environment variable is not set."
try:
client = genai.Client(vertexai=True, project=project_id, location="global")
except Exception as e:
return f"Error: Failed to initialize genai.Client: {e}"
image_data = None
model_id = "gemini-3-pro-image-preview"
try:
if previous_image:
logger.info(f"Editing image: {previous_image}")
image_data = edit_image(
client=client,
prompt=prompt,
previous_image=previous_image,
model_id=model_id
)
else:
logger.info("Generating new image")
# Generate the image
response = client.models.generate_content(
model=model_id,
contents=prompt,
config=types.GenerateContentConfig(
response_modalities=['IMAGE'],
image_config=types.ImageConfig(aspect_ratio="16:9"),
),
)
# Check for errors
if response.candidates[0].finish_reason != types.FinishReason.STOP:
return f"Error: Image generation failed. Reason: {response.candidates[0].finish_reason}"
# Extract image data
for part in response.candidates[0].content.parts:
if part.inline_data:
image_data = part.inline_data.data
break
if not image_data:
return {"status": "error", "message": "No image data was generated.", "artifact_name": None}
# Create the images directory if it doesn't exist
output_dir = "images"
os.makedirs(output_dir, exist_ok=True)
# Save the image to file system
file_path = os.path.join(output_dir, f"{image_name}.png")
with open(file_path, "wb") as f:
f.write(image_data)
# Save as ADK artifact
counter = str(tool_context.state.get("loop_iteration", 0))
artifact_name = f"{image_name}_" + counter + ".png"
report_artifact = types.Part.from_bytes(data=image_data, mime_type="image/png")
await tool_context.save_artifact(artifact_name, report_artifact)
logger.info(f"Image also saved as ADK artifact: {artifact_name}")
return {
"status": "success",
"message": f"Image generated and saved to {file_path}. ADK artifact: {artifact_name}.",
"artifact_name": artifact_name,
}
except Exception as e:
return f"An error occurred: {e}"
- فایلهای نهایی YAML تولید شده در محیط نویسنده، برای مرجع شما در زیر ارائه شدهاند (لطفاً توجه داشته باشید که فایلهای موجود در محیط شما ممکن است کمی متفاوت باشند). لطفاً مطمئن شوید که ساختار YAML عامل شما با طرحبندی نمایش داده شده در ADK Visual Builder مطابقت دارد.
root_agent.yamlname: studio_director
model: gemini-2.5-pro
agent_class: LlmAgent
description: The Studio Director who manages the comic creation pipeline.
instruction: >
You are the Studio Director. Your objective is to manage a linear pipeline of
four sequential agents to transform a user's seed idea into a fully rendered,
responsive HTML5 comic book.
Your role is to be the primary orchestrator and state manager. You will
receive the user's initial request.
**Workflow:**
1. If the user's prompt starts with "Create me a comic of ...", you must
delegate the task to your sub-agent to begin the comic creation pipeline.
2. If the user asks a general question or provides a prompt that does not
explicitly ask to create a comic, you must answer the question directly
without triggering the comic creation pipeline.
3. Monitor the sequence to ensure no steps are skipped. Ensure the output of
each Sub-Agent is passed as the context for the next.
sub_agents:
- config_path: ./comic_pipeline.yaml
tools: []
comic_pipline.yaml
name: comic_pipeline
agent_class: SequentialAgent
description: A sequential pipeline of agents to create a comic book.
sub_agents:
- config_path: ./scripting_agent.yaml
- config_path: ./panelization_agent.yaml
- config_path: ./image_synthesis_agent.yaml
- config_path: ./assembly_agent.yaml
scripting_agent.yamlname: scripting_agent
model: gemini-2.5-pro
agent_class: LlmAgent
description: Narrative & Character Architect.
instruction: >
You are the Scripting Agent, a Narrative & Character Architect.
Your input is a seed idea for a comic.
**Your Logic:**
1. **Create a Character Manifest:** You must define exactly 3 specific,
unchangeable visual identifiers for every character. For example: "Gretel:
Blue neon hair ribbons, silver apron, glowing boots". This is mandatory.
2. **Expand the Narrative:** Expand the seed idea into a coherent narrative
arc with dialogue.
**Output:**
You must output a JSON object containing:
- "narrative_script": A detailed script with scenes and dialogue.
- "character_manifest": The mandatory character visual guide.
sub_agents: []
tools: []
panelization_agent.yamlname: panelization_agent
model: gemini-2.5-pro
agent_class: LlmAgent
description: Cinematographer & Storyboarder.
instruction: >
You are the Panelization Agent, a Cinematographer & Storyboarder.
Your input is a narrative script and a character manifest.
**Your Logic:**
1. **Divide the Script:** Divide the script into a specific number of panels.
The user may define this number, or you should default to 8 panels.
2. **Define Composition:** For each panel, you must define a specific
composition, camera shot (e.g., "Wide shot", "Close-up"), and the dialogue for
that panel.
**Output:**
You must output a JSON object containing a structured list of exactly X panel
descriptions, where X is the number of panels. Each item in the list should
have "panel_number", "composition_description", and "dialogue".
sub_agents: []
tools: []
image_synthesis_agent.yaml
name: image_synthesis_agent
model: gemini-2.5-pro
agent_class: LlmAgent
description: Technical Artist & Asset Generator.
instruction: >
You are the Image Synthesis Agent, a Technical Artist & Asset Generator.
Your input is a structured list of panel descriptions.
**Your Logic:**
1. **Iterate and Generate:** You must iterate through each panel description
provided in the input. For each panel, you will execute the `generate_image`
tool.
2. **Construct Prompts:** For each panel, you will construct a detailed
prompt for the image generation tool. This prompt must strictly enforce the
character visual identifiers from the manifest and include the global style:
"vibrant comic book style, heavy ink lines, cel-shaded, 4k". The prompt must
also describe the composition and include a request for speech bubbles to
contain the dialogue.
3. **Map Output:** You must associate each generated image URL with its
corresponding panel number and dialogue.
**Output:**
You must output a JSON object containing a complete gallery of all generated
images, mapped to their respective panel data (panel_number, dialogue,
image_url).
sub_agents: []
tools:
- name: Agent3.tools.image_generation.generate_image
assembly_agent.yamlname: assembly_agent
model: gemini-2.5-pro
agent_class: LlmAgent
description: Frontend Developer for comic book assembly.
instruction: >
You are the Assembly Agent, a Frontend Developer.
Your input is the mapped gallery of images and panel data.
**Your Logic:**
1. **Generate HTML:** You will write a clean, responsive HTML5/CSS3 file to
display the comic. The comic must be vertically scrollable, with each panel
displaying its image on top and the corresponding dialogue or description
below it.
2. **Write File:** You must use the `write_comic_html` tool to save the
generated HTML to a file named `comic.html` in the `output/` folder.
3. Pass the list of image URLs to the tool so it can handle the image assets
correctly.
**Output:**
You will output a confirmation message indicating the path to the final HTML
file.
sub_agents: []
tools:
- name: Agent3.tools.file_writer.write_comic_html
- به برگه رابط کاربری ADK (کیت توسعه عامل) بروید، « عامل ۳ » را انتخاب کنید و روی دکمه ویرایش («آیکون قلم») کلیک کنید.
- روی دکمه ذخیره در پایین سمت چپ صفحه کلیک کنید. این کار تمام تغییرات کدی را که در عامل اصلی ایجاد کردهاید، حفظ خواهد کرد.
- حالا میتوانیم تست عامل خود را شروع کنیم!
- تب رابط کاربری ADK (کیت توسعه عامل) فعلی را ببندید و به تب ویرایشگر Cloud Shell برگردید.
- در ترمینال داخل تب Cloud Shell Editor ، ابتدا سرور ADK (Agent Development Kit) را مجدداً راهاندازی کنید. به ترمینالی که سرور ADK (Agent Development Kit) را در آن راهاندازی کردهاید بروید و اگر سرور هنوز در حال اجرا است ، CTRL+C را برای خاموش کردن آن فشار دهید . برای راهاندازی مجدد سرور، دستور زیر را اجرا کنید.
#make sure you are in the right folder.
cd ~/adkui
#start the server
adk web
- Ctrl+Click را روی آدرس اینترنتی (مثلاً http://localhost:8000 ) که روی صفحه نمایش داده میشود، نگه دارید. رابط کاربری گرافیکی ADK (Agent Development Kit) باید روی تب مرورگر نمایش داده شود.
- از لیست Agentها ، Agent3 را انتخاب کنید.
- دستور زیر را وارد کنید
Create a Comic Book based on the following story,
Title: The Story of Momotaro
The story of Momotaro (Peach Boy) is one of Japan's most famous and beloved folktales. It is a classic "hero's journey" that emphasizes the virtues of courage, filial piety, and teamwork.
The Miraculous Birth
Long, long ago, in a small village in rural Japan, lived an elderly couple. They were hardworking and kind, but they were sad because they had never been blessed with children.
One morning, while the old woman was washing clothes by the river, she saw a magnificent, giant peach floating downstream. It was larger than any peach she had ever seen. With great effort, she pulled it from the water and brought it home to her husband for their dinner.
As they prepared to cut the fruit open, the peach suddenly split in half on its own. To their astonishment, a healthy, beautiful baby boy stepped out from the pit.
"Don't be afraid," the child said. "The Heavens have sent me to be your son."
Overjoyed, the couple named him Momotaro (Momo meaning peach, and Taro being a common name for an eldest son).
The Call to Adventure
Momotaro grew up to be stronger and kinder than any other boy in the village. During this time, the village lived in fear of the Oni—ogres and demons who lived on a distant island called Onigashima. These Oni would often raid the mainland, stealing treasures and kidnapping villagers.
When Momotaro reached young adulthood, he approached his parents with a request. "I must go to Onigashima," he declared. "I will defeat the Oni and bring back the stolen treasures to help our people."
Though they were worried, his parents were proud. As a parting gift, the old woman prepared Kibi-dango (special millet dumplings), which were said to provide the strength of a hundred men.
Gathering Allies
Momotaro set off on his journey toward the sea. Along the way, he met three distinct animals:
The Spotted Dog: The dog growled at first, but Momotaro offered him one of his Kibi-dango. The dog, tasting the magical dumpling, immediately swore his loyalty.
The Monkey: Further down the road, a monkey joined the group in exchange for a dumpling, though he and the dog bickered constantly.
The Pheasant: Finally, a pheasant flew down from the sky. After receiving a piece of the Kibi-dango, the bird joined the team as their aerial scout.
Momotaro used his leadership to ensure the three animals worked together despite their differences, teaching them that unity was their greatest strength.
The Battle of Onigashima
The group reached the coast, built a boat, and sailed to the dark, craggy shores of Onigashima. The island was guarded by a massive iron gate.
The Pheasant flew over the walls to distract the Oni and peck at their eyes.
The Monkey climbed the walls and unbolted the Great Gate from the inside.
The Dog and Momotaro charged in, using their immense strength to overpower the demons.
The Oni were caught off guard by the coordinated attack. After a fierce battle, the King of the Oni fell to his knees before Momotaro, begging for mercy. He promised to never trouble the villagers again and surrendered all the stolen gold, jewels, and precious silks.
The Triumphant Return
Momotaro and his three companions loaded the treasure onto their boat and returned to the village. The entire town celebrated their homecoming.
Momotaro used the wealth to ensure his elderly parents lived the rest of their lives in comfort and peace. He remained in the village as a legendary protector, and his story was passed down for generations as a reminder that bravery and cooperation can overcome even the greatest evils.
- در حالی که Agent در حال کار است، میتوانید رویدادها را در ترمینال ویرایشگر Cloud Shell مشاهده کنید.
- ممکن است تولید همه تصاویر کمی طول بکشد، پس لطفاً صبور باشید یا یک قهوه سریع بخورید! وقتی تولید تصویر شروع میشود، باید بتوانید تصاویر مرتبط با داستان را مانند زیر مشاهده کنید.
شکل ۳۴: داستان موموتارو به صورت کمیک استریپ ۲۵. اگر همه چیز به خوبی پیش برود، فایل html تولید شده باید در پوشه html ذخیره شود. اگر میخواهید روی Agent بهبودهایی ایجاد کنید، میتوانید به دستیار Agent برگردید و از آن بخواهید تغییرات بیشتری ایجاد کند!
شکل ۳۵: محتوای پوشه خروجی
- اگر مرحله ۲۵ به درستی اجرا شد و فایل comic.html در پوشه خروجی قرار گرفت، میتوانید مراحل زیر را برای آزمایش آن اجرا کنید. اول از همه، با کلیک روی Terminal>New Terminal از منوی اصلی Cloud Shell Editor ، یک ترمینال جدید باز کنید. این کار باید یک ترمینال جدید باز کند.
#go to the project folder
cd ~/adkui
#activate python virtual environment
source .venv/bin/activate
#Go to the output folder
cd ~/adkui/output
#start local web server
python -m http.server 8080
- Ctrl+Click روی http://0.0.0.0:8080
شکل ۳۶: اجرای وب سرور محلی
- محتوای پوشه باید در تب مرورگر نمایش داده شود. روی فایل html (به نام comic.html) کلیک کنید. کمیک باید مانند زیر نمایش داده شود (خروجی شما ممکن است کمی متفاوت باشد).
شکل ۳۷: اجرا روی localhost
۱۲. تمیز کردن
حالا بیایید چیزی را که تازه ایجاد کردهایم، تمیز کنیم.
- برنامه Cloud Run که تازه ایجاد کردیم را حذف کنید. با دسترسی به Cloud Run به Cloud Run بروید. باید بتوانید برنامهای را که در مرحله قبل ایجاد کردهاید، ببینید. کادر کنار برنامه را علامت بزنید و روی دکمه Delete کلیک کنید.
شکل ۳۸: حذف برنامه Cloud Run ۲. حذف فایلهای موجود در Cloud Shell
#Execute the following to delete the files
cd ~
rm -R ~/adkui
۱۳. نتیجهگیری
تبریک! شما با موفقیت عاملهای ADK (کیت توسعه عامل) را با استفاده از ADK Visual Builder داخلی ایجاد کردید. همچنین یاد گرفتید که چگونه برنامه را در Cloud Run مستقر کنید. این یک دستاورد قابل توجه است که چرخه حیات اصلی یک برنامه مدرن مبتنی بر ابر را پوشش میدهد و پایه محکمی برای استقرار سیستمهای عامل پیچیده شما فراهم میکند.
خلاصه
در این آزمایشگاه یاد گرفتید که:
- ایجاد برنامه چند عامله با استفاده از ADK Visual Builder
- برنامه را روی Cloud Run مستقر کنید
منابع مفید