۱. آنچه یاد خواهید گرفت
پشته کامل هوش مصنوعی Agent Vibe
خوش آمدید! شما در شرف یادگیری مهارت حیاتی بعدی در توسعه نرمافزار هستید: چگونه هوش مصنوعی را به طور مؤثر برای ساخت، آزمایش و استقرار نرمافزار در سطح تولید هدایت کنید. هوش مصنوعی مولد یک «خلبان خودکار» نیست؛ بلکه یک کمکخلبان قدرتمند است که به یک مدیر ماهر نیاز دارد.
این کارگاه یک روششناسی ساختاریافته و تکرارپذیر برای همکاری با هوش مصنوعی در هر مرحله از چرخه حیات توسعه نرمافزار حرفهای (SDLC) ارائه میدهد. شما از یک کدنویس خط به خط به یک مدیر فنی تبدیل خواهید شد - یک معمار با چشمانداز و یک پیمانکار عمومی که از هوش مصنوعی برای اجرای دقیق آن چشمانداز استفاده میکند. 🚀
در پایان این آموزش، شما موارد زیر را خواهید داشت:
- با استفاده از هوش مصنوعی، یک ایده سطح بالا را به معماری ابری تبدیل کردم.
- یک بکاند کامل پایتون با دستورات هدفمند و خاص ایجاد کرد.
- از هوش مصنوعی به عنوان یک برنامهنویس دونفره برای اشکالزدایی و اصلاح کد استفاده شد.
- ایجاد تستهای واحد، از جمله نمونههای آزمایشی (mocks)، را به هوش مصنوعی واگذار کرد.
- زیرساخت آماده برای اجرا به صورت کد (IaC) با Terraform تولید شد.
- یک خط لوله کامل CI/CD را در GitHub Actions با یک اعلان واحد ایجاد کرد.
- با استفاده از ابزارهای عملیاتی مبتنی بر هوش مصنوعی، برنامه زنده شما را نظارت و مدیریت کردم.
شما نه تنها با یک برنامه کاربردی، بلکه با یک طرح اولیه برای توسعه مبتنی بر هوش مصنوعی، این دوره را ترک خواهید کرد. بیایید شروع کنیم!
۲. پیشنیازها و تنظیمات
قبل از شروع، بیایید محیط شما را آماده کنیم. این یک گام اساسی برای اطمینان از یک تجربه کارگاهی روان است.
یک حساب GCP جدید ایجاد کنید و صورتحساب خود را پیوند دهید
برای توانمندسازی عوامل هوش مصنوعی خود، به دو چیز نیاز داریم: یک پروژه ابری گوگل برای فراهم کردن پایه و اساس و یک کلید API Gemini برای دسترسی به مدلهای قدرتمند گوگل.
مرحله ۱: فعال کردن حساب صورتحساب
- برای فعال کردن حساب صورتحساب خود با اعتبار ۵ دلاری، به آن برای استقرار خود نیاز خواهید داشت. حتماً به حساب جیمیل خود وارد شوید.
مرحله 2: ایجاد یک پروژه GCP جدید
- به کنسول ابری گوگل بروید و یک پروژه جدید ایجاد کنید.
- پنل سمت چپ را باز کنید، روی
Billingکلیک کنید، بررسی کنید که آیا حساب billing به این حساب gcp مرتبط است یا خیر.
اگر این صفحه را مشاهده کردید، manage billing account بررسی کنید، نسخه آزمایشی Google Cloud را انتخاب کنید و به آن لینک دهید.
مرحله 3: کلید API Gemini خود را ایجاد کنید
قبل از اینکه بتوانید کلید را ایمن کنید، باید یکی داشته باشید.
- به استودیوی هوش مصنوعی گوگل بروید: https://aistudio.google.com/
- با حساب جیمیل خود وارد شوید.
- روی دکمهی «دریافت کلید API» که معمولاً در پنل ناوبری سمت چپ یا گوشهی بالا سمت راست قرار دارد، کلیک کنید.
- در کادر محاورهای «کلیدهای API» ، روی «ایجاد کلید API در پروژه جدید» کلیک کنید.
- پروژه جدیدی که ایجاد کردهاید و حساب پرداخت در آن تنظیم شده است را انتخاب کنید.
- یک کلید API جدید برای شما ایجاد خواهد شد.
این کلید را فوراً کپی کنید و آن را به طور موقت در جایی امن (مانند یک برنامه مدیریت رمز عبور یا یک یادداشت امن) ذخیره کنید. این مقداری است که در مراحل بعدی از آن استفاده خواهید کرد.
احراز هویت گیتهاب
با رفتن به کنسول ابری گوگل ، در بالا سمت راست، دکمه «فعال کردن ابر پوسته» را بزنید و Cloud Shell را باز کنید.
مرحله ۱: باز کردن Cloud Shell
👉 روی «فعالسازی پوسته ابری» در بالای کنسول گوگل کلود کلیک کنید (این آیکون به شکل ترمینال در بالای پنل پوسته ابری قرار دارد)، 
👉 روی دکمهی «باز کردن ویرایشگر» کلیک کنید (شبیه یک پوشهی باز شده با مداد است). با این کار ویرایشگر کد Cloud Shell در پنجره باز میشود. یک فایل اکسپلورر در سمت چپ خواهید دید. 
👉 وقتی ویرایشگر را باز کردید، ترمینال را در cloud IDE باز کنید،
👉💻 در ترمینال، با استفاده از دستور زیر تأیید کنید که از قبل احراز هویت شدهاید و پروژه روی شناسه پروژه شما تنظیم شده است:
gcloud auth list
مرحله ۲: احراز هویت با GitHub و Fork
احراز هویت با گیتهاب:
👉💻 دستور را کپی و در ترمینال ابری خود جایگذاری کنید:
gh auth login
- «از گیتهاب کجا استفاده میکنید؟»، «GitHub.com» را انتخاب کنید.
- «پروتکل مورد نظر شما برای عملیات گیت روی این میزبان چیست؟»، «HTTPS» را انتخاب کنید.
- «آیا گیت را با اعتبارنامههای گیتهاب خود تأیید میکنید؟»، «بله» را انتخاب کنید.
- «چگونه میخواهید GitHub CLI را احراز هویت کنید؟»، «ورود با مرورگر وب» را انتخاب کنید.
مهم!! هنوز دکمهی "اینتر" را فشار ندهید 
کد را از صفحه تأیید ترمینال برای ورود کپی کنید
پس از اتمام وارد کردن کد، به ترمینال Cloud Shell خود برگردید و برای ادامه، "enter" را فشار دهید.
مرحله ۴: فورک و کلون کردن مخزن:
👉💻 دستور را کپی و در ترمینال ابری خود جایگذاری کنید:
gh repo fork cuppibla/storygen-learning --clone=true
۳. معماری: از ایده تا طرح اولیه با Cloud Assist
هر پروژه بزرگی با یک چشمانداز روشن آغاز میشود. ما از دستیار هوش مصنوعی خود، یعنی Cloud Assist، برای طراحی معماری اپلیکیشن خود استفاده خواهیم کرد.
اقدامات
- کنسول ابری گوگل را باز کنید: [https://console.cloud.google.com](کنسول ابری گوگل)
- در گوشه بالا سمت راست، روی «باز کردن چت دستیار ابری» کلیک کنید
فعال کردن دستیار ابری
-
Get Gemini Assistکلیک کنید، سپسEnable Cloud Assist at no cost. - و شروع به چت کردن کنید!
دستورالعمل دقیق زیر را به Cloud Assist ارائه دهید:
ایده خود را وارد کنید
Generate a Python web application that uses AI to generate children's stories and illustrations. It has Python backend and React frontend host separately on Cloudrun. They communicate through Websocket. It needs to use a generative model for text and another for images. The generated images must be used by Imagen from Vertex AI and stored in a Google Cloud Storage bucket so that frontend can fetch from the bucket to render images. I do not want any load balancer or a database for the story text. We need a solution to store the API key.
طرح اولیه برنامه خود را دریافت کنید
- روی «ویرایش طراحی برنامه» کلیک کنید، نمودار را مشاهده خواهید کرد. برای دانلود کد Terraform، روی پنل سمت راست بالای صفحه «<> دریافت کد» کلیک کنید.
- Cloud Assist یک نمودار معماری ایجاد میکند. این طرح اولیه بصری ماست.
با این کد نیازی به انجام کاری نیست. برای توضیح بیشتر، ادامه مطلب را بخوانید.
درک کد Terraform تولید شده. شما به تازگی مجموعه کاملی از فایلهای Terraform را از Cloud Assist دریافت کردهاید. فعلاً نیازی به انجام کاری با این کد نیست، اما بیایید به سرعت توضیح دهیم که چیست و چرا اینقدر قدرتمند است.
Terraform چیست؟ Terraform یک ابزار Infrastructure as Code (IaC) است. آن را به عنوان یک طرح اولیه برای محیط ابری خود در نظر بگیرید که به صورت کد نوشته شده است. به جای اینکه به صورت دستی در کنسول Google Cloud برای ایجاد سرویسها، فضای ذخیرهسازی و مجوزها کلیک کنید، تمام این منابع را در این فایلهای پیکربندی تعریف میکنید. Terraform سپس طرح اولیه شما را میخواند و دقیقاً همان محیط را به طور خودکار برای شما میسازد.
از طرح بصری تا کد اجرایی. نمودار معماری ارائه شده توسط Cloud Assist، طرح بصری شماست. کد Terraform نسخه قابل خواندن توسط ماشین از همان طرح است. این حلقه حیاتی است که یک مفهوم طراحی را به یک واقعیت خودکار و قابل تکرار تبدیل میکند. با تعریف زیرساخت خود در کد، میتوانید:
- خودکارسازی خلق: به طور قابل اعتمادی محیط یکسانی را بارها و بارها بسازید.
- استفاده از کنترل نسخه: تغییرات زیرساخت خود را در گیت، درست مانند کد برنامه خود، پیگیری کنید.
- جلوگیری از خطاها: از اشتباهات دستی که ممکن است هنگام کلیک کردن در رابط وب رخ دهد، جلوگیری کنید.
برای این کارگاه، نیازی نیست خودتان این کد Terraform را اجرا کنید. آن را به عنوان طرح اولیه حرفهای - "کلید پاسخ" - برای زیرساختی که در مراحل بعدی خواهید ساخت و مستقر کنید، در نظر بگیرید.
۴. توسعه: مقدمهای بر رابط خط فرمان Gemini
👉💻 در ترمینال Cloud Shell خود، به دایرکتوری شخصی خود بروید.
cd ~/storygen-learning
👉💻 برای اولین بار جمینی را امتحان کنید.
clear
gemini --model=gemini-2.5-flash
اگر از شما پرسیده شد Do you want to connect Cloud Shell editor to Gemini CLI? خیر را انتخاب کنید.
👉✨ هر ابزار Gemini توضیحاتی دارد. همین حالا آنها را بخوانید. در اعلان Gemini، تایپ کنید:
در رابط خط فرمان Gemini
/help
👉✨ رابط خط فرمان Gemini مجموعهای از قابلیتهای داخلی خود را دارد. برای بررسی آنها:
در رابط خط فرمان Gemini
/tools
لیستی شامل ReadFile ، WriteFile و GoogleSearch را مشاهده خواهید کرد. اینها تکنیکهای پیشفرضی هستند که میتوانید بدون نیاز به استفاده از یک ابزار خارجی، از آنها استفاده کنید.
👉✨ شمشیر جمینی میتواند «آگاهی تاکتیکی» (زمینه) را برای هدایت اقدامات خود در اختیار داشته باشد.
در رابط خط فرمان Gemini
/memory show
در حال حاضر خالی است، یک لوح سفید.
👉✨ ابتدا، یک شخصیت به حافظهی عامل اضافه کنید. این کار حوزهی تخصص او را تعریف میکند:
در رابط خط فرمان Gemini
/memory add "I am master at python development"
برای تأیید اینکه تیغه شما این دانش را جذب کرده است، دوباره دستور /memory show اجرا کنید.
👉✨ برای نشان دادن نحوه ارجاع به فایلها با نماد @، ابتدا یک فایل «خلاصه ماموریت» ایجاد میکنیم.
یک ترمینال جدید باز کنید و دستور زیر را برای ایجاد فایل ماموریت خود اجرا کنید:
!echo "## Mission Objective: Create Imagen ADK Agent for Story Book" > mission.md
👉✨حالا، به رابط خط فرمان Gemini خود دستور دهید تا خلاصه را تجزیه و تحلیل کرده و یافتههای خود را گزارش دهد:
در رابط خط فرمان Gemini
Explain the contents of the file @mission.md
سلاح اصلی شما اکنون از هدف خود آگاه است.
👉💻 برای خروج از رابط خط فرمان Gemini، دو بار Ctrl+C را فشار دهید.
یادگیری:
چگونه رابط خط فرمان Gemini قدرتهای فوقالعاده خود را به دست میآورد: gemini.md قبل از ادامه، مهم است که بدانیم چگونه میتوان رابط خط فرمان Gemini را برای یک پروژه خاص تنظیم کرد. در حالی که میتوانید از آن به عنوان یک ابزار چت عمومی استفاده کنید، قدرت واقعی آن از یک فایل پیکربندی ویژه به نام gemini.md ناشی میشود.
وقتی دستور gemini را اجرا میکنید، به طور خودکار به دنبال فایل gemini.md در دایرکتوری فعلی میگردد. این فایل به عنوان یک دفترچه راهنمای خاص پروژه برای هوش مصنوعی عمل میکند. این فایل میتواند سه چیز کلیدی را تعریف کند:
- پرسونا: شما میتوانید به هوش مصنوعی بگویید که چه کسی باید باشد. برای مثال، «شما یک توسعهدهنده پایتون متخصص در گوگل کلود هستید.» این کار بر پاسخها و سبک آن تمرکز میکند.
- ابزارها: میتوانید به آن دسترسی به فایلهای خاص (@file.py) یا حتی جستجوهای گوگل (@google) را بدهید. این کار زمینه لازم را برای هوش مصنوعی فراهم میکند تا به سوالات مربوط به کد پروژه شما پاسخ دهد.
- حافظه: شما میتوانید حقایق یا قوانینی را ارائه دهید که هوش مصنوعی باید همیشه برای این پروژه به خاطر بسپارد، که به حفظ ثبات کمک میکند.
با استفاده از یک فایل gemini.md ، شما مدل عمومی Gemini را به یک دستیار متخصص تبدیل میکنید که از قبل در مورد اهداف پروژه شما توجیه شده و به اطلاعات صحیح دسترسی دارد.
۵. توسعه: ساخت ADK با Gemini CLI
پیکربندی محیط
به Cloud Shell خود بروید، روی دکمهی «باز کردن ترمینال» کلیک کنید.
- الگوی محیط را کپی کنید:
cd ~/storygen-learning cp ~/storygen-learning/env.template ~/storygen-learning/.env
اگر فایل .env را پیدا نکردید، فایل مخفی را در ویرایشگر مشاهده کنید
- در نوار منوی بالا روی گزینه View کلیک کنید.
- گزینهی «فایلهای مخفی را تغییر وضعیت دهید» را انتخاب کنید.
👉شناسه پروژه گوگل کلود خود را پیدا کنید:
- کنسول ابری گوگل را باز کنید: لینک
- پروژهای را که میخواهید برای این کارگاه استفاده کنید، از منوی کشویی پروژه در بالای صفحه انتخاب کنید.
- شناسه پروژه شما در کارت اطلاعات پروژه در داشبورد نمایش داده میشود.
👉 نام کاربری گیتهاب خود را پیدا کنید:
- به گیتهاب خود بروید و نام کاربری گیتهاب خود را پیدا کنید.
ویرایش فایل .env 2. مقادیر زیر را در .env جایگزین کنید:
GOOGLE_API_KEY=[REPLACE YOUR API KEY HERE]
GOOGLE_CLOUD_PROJECT_ID=[REPLACE YOUR PROJECT ID]
GITHUB_USERNAME=[REPLACE YOUR USERNAME]
GENMEDIA_BUCKET=[REPLACE YOUR PROJECT ID]-bucket
به عنوان مثال اگر شناسه پروژه شما: testproject است، باید GOOGLE_CLOUD_PROJECT_ID=testproject و GENMEDIA_BUCKET=testproject-bucket را قرار دهید.
اسکریپتهای راهاندازی
به 00_Starting_Here بروید یک ترمینال جدید باز کنید (نه در Gemini CLI)
cd ~/storygen-learning/00_Starting_Here
تنظیمات کامل را اجرا کنید:
./setup-complete.sh
شما باید نتایج تنظیمات را در ترمینال ببینید
اولین نماینده خود را بسازید
به 01a_First_Agent_Ready بروید. بیایید از Gemini CLI برای ایجاد ADK agent استفاده کنیم:**
cd ~/storygen-learning/01a_First_Agent_Ready
رابط خط فرمان Gemini را باز کنید
gemini
درون پنجرهی رابط خط فرمان (CLI) گامینی (Gamini)، دستور زیر را اجرا کنید:
I need you to help me create a Google ADK (Agent Development Kit) agent for story generation. I'm working on a children's storybook app that generates creative stories with visual scenes.
Please create a complete `agent.py` file that implements an LlmAgent using Google's ADK framework. The agent should:
**Requirements:**
1. Use the `google.adk.agents.LlmAgent` class
2. Use the "gemini-2.5-flash" model (supports streaming)
3. Be named "story_agent"
4. Generate structured stories with exactly 4 scenes each
5. Output valid JSON with story text, main characters, and scene data
6. No tools needed (images are handled separately)
**Agent Specifications:**
- **Model:** gemini-2.5-flash
- **Name:** story_agent
- **Description:** "Generates creative short stories and accompanying visual keyframes based on user-provided keywords and themes."
**Story Structure Required:**
- Exactly 4 scenes: Setup → Inciting Incident → Climax → Resolution
- 100-200 words total
- Simple, charming language for all audiences
- Natural keyword integration
**JSON Output Format:**
{
"story": "Complete story text...",
"main_characters": [
{
"name": "Character Name",
"description": "VERY detailed visual description with specific colors, features, size, etc."
}
],
"scenes": [
{
"index": 1,
"title": "The Setup",
"description": "Scene action and setting WITHOUT character descriptions",
"text": "Story text for this scene"
}
// ... 3 more scenes
]
}
**Key Instructions for the Agent:**
- Extract 1-2 main characters maximum
- Character descriptions should be extremely detailed and visual
- Scene descriptions focus on ACTION and SETTING only
- Do NOT repeat character appearance in scene descriptions
- Always respond with valid JSON
Please include a complete example in the instructions showing the exact format using keywords like "tiny robot", "lost kitten", "rainy city".
The file should start with necessary imports, define an empty tools list, include a print statement for initialization, and then create the LlmAgent with all the detailed instructions.
Can you create this agent in backend/story_agent/agent.py
پس از اتمام، ترمینال Gemini CLI را با استفاده Control+C خاموش کنید.
——————————————— اختیاری ، میتوانید به بخش راهحل بروید————————————————–
اکنون تغییر خود را در ADK Web تأیید کنید
cd ~/storygen-learning/01a_First_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
برای ادامه، به یک خط فرمان نیاز دارید.
وبسایت را ارتقا دهید
cd ~/storygen-learning/01a_First_Agent_Ready
./start.sh
اگر تغییر شما کار نکند، انتظار میرود خطاهایی در رابط کاربری وب ADK و وبسایت مشاهده کنید.
——————————————– راه حل از اینجا شروع می شود ———————————————–
راه حل
با استفاده از Control+C فرآیند قبلی را پایان دهید یا میتوانید یک ترمینال دیگر باز کنید:
cd ~/storygen-learning/01b_First_Agent_Done
وبسایت را ارتقا دهید:
./start.sh
وبسایت را مشاهده خواهید کرد:
رابط کاربری ADK را امتحان کنید: یک ترمینال دیگر باز کنید:
cd ~/storygen-learning/01b_First_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
رابط کاربری ADK را مشاهده خواهید کرد که در آن میتوانید از نماینده سوال بپرسید.
قبل از رفتن به بخش بعدی، برای پایان دادن به فرآیند، Ctrl+C را فشار دهید.
۶. توسعه: ساخت ADK با Gemini CLI - (روش مهندسی متن)
راهاندازی اولیه
مطمئن شوید که فایل agent که قبلاً در 01a_First_Agent_Ready/backend/story_agent/agent.py ایجاد کردهایم را حذف میکنیم:
به 01a_First_Agent_Ready بروید. بیایید از Gemini CLI برای ایجاد ADK agent استفاده کنیم:**
cd ~/storygen-learning/01a_First_Agent_Ready/backend
رابط خط فرمان Gemini را باز کنید
gemini
درون پنجرهی رابط خط فرمان (CLI) گامینی (Gamini)، دستور زیر را اجرا کنید:
Summarize the design doc @design.md for me, do not attempt to create file just yet.
👉💻 با دو بار فشردن Ctrl+C برای لحظهای از Gemini خارج شوید.
👉💻 در ترمینال خود، دستور زیر را برای نوشتن فایل راهنما اجرا کنید.
cat << 'EOF' > GEMINI.md
### **Coding Guidelines**
**1. Python Best Practices:**
* **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
* **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or
Google Style.
* **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
* **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
* **Naming Conventions:**
* `snake_case` for variables, functions, and methods.
* `PascalCase` for classes.
* `UPPER_SNAKE_CASE` for constants.
* **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.
**2. Web APIs (FastAPI):**
* **Data Validation:** Use `pydantic` models for request and response data validation.
* **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
* **Error Handling:** Implement centralized error handling using middleware or exception handlers.
* **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md
با قوانین ثبت شده، بیایید دوباره شریک هوش مصنوعی خود را احضار کنیم و شاهد جادوی این مصنوع باشیم.
👉💻 رابط خط فرمان Gemini را از دایرکتوری shadowblade مجدداً اجرا کنید:
cd ~/storygen-learning/01a_First_Agent_Ready/backend
clear
gemini
👉✨ حالا، از جوزا بخواهید به شما نشان دهد که به چه چیزی فکر میکند. رونها خوانده شدهاند.
/memory show
👉✨ این تنها دستور قدرتمندی است که عامل شما را میسازد. همین حالا آن را اجرا کنید:
You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.
Analyze the design document at `@design.md` and generate the corresponding Python code for `agent.py`.
I need you to generate a Python script based on the provided design document and reference examples. Follow these requirements:
Read the design document carefully - it contains the complete technical specification for the code you need to write
Follow the structure and patterns shown in the reference context files
Adhere to all Python best practices specified in the coding standards document
Implement every requirement mentioned in the design document exactly as specified
Use the exact variable names, function names, and string values mentioned in the specifications
The design document describes the complete architecture, dependencies, configuration, and logic flow. Your generated code must match these specifications precisely while following professional Python coding standards.
Generate clean, production-ready Python code that can be used immediately without modifications.
پس از اتمام، ترمینال Gemini CLI را با استفاده Control+C خاموش کنید.
——————————————— اختیاری ، میتوانید به بخش راهحل بروید————————————————–
اکنون تغییر خود را در ADK Web تأیید کنید
cd ~/storygen-learning/01a_First_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
برای ادامه، به یک خط فرمان نیاز دارید.
وبسایت را ارتقا دهید
cd ~/storygen-learning/01a_First_Agent_Ready
./start.sh
اگر تغییر شما کار نکند، انتظار میرود خطاهایی در رابط کاربری وب ADK و وبسایت مشاهده کنید.
——————————————– راه حل از اینجا شروع می شود ———————————————–
راه حل
با استفاده از Control+C فرآیند قبلی را پایان دهید یا میتوانید یک ترمینال دیگر باز کنید:
cd ~/storygen-learning/01b_First_Agent_Done
وبسایت را ارتقا دهید:
./start.sh
وبسایت را مشاهده خواهید کرد:
رابط کاربری ADK را امتحان کنید: یک ترمینال دیگر باز کنید:
cd ~/storygen-learning/01b_First_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
رابط کاربری ADK را مشاهده خواهید کرد که در آن میتوانید از نماینده سوال بپرسید.
قبل از رفتن به بخش بعدی، برای پایان دادن به فرآیند، Ctrl+C را فشار دهید.
۷. توسعه: با Imagen، عامل سفارشی خود را بسازید
ابزار Imagen (عامل دوم) را تولید کنید
cd ~/storygen-learning/02a_Image_Agent_Ready
از Gemini CLI برای ایجاد عامل تولید تصویر استفاده کنید:
gemini generate "I need you to help me create a custom Google ADK (Agent Development Kit) agent for image generation. This is different from the story agent - this one handles image generation directly using the BaseAgent pattern for full control over tool execution.
Please create a complete `agent.py` file that implements a custom image generation agent. The agent should:
**Requirements:**
1. Use the `google.adk.agents.BaseAgent` class (NOT LlmAgent)
2. Be named "custom_image_agent"
3. Directly execute the ImagenTool without LLM intermediation
4. Handle JSON input with scene descriptions and character descriptions
5. Store results in session state for retrieval by main.py
6. Use async generators and yield Events
**Key Specifications:**
- **Class Name:** CustomImageAgent (inherits from BaseAgent)
- **Agent Name:** "custom_image_agent"
- **Tool:** Uses ImagenTool for direct image generation
- **Purpose:** Bypass LLM agent limitations and directly call ImagenTool
**Input Format:**
The agent should handle JSON input like:
{
"scene_description": "Scene action and setting",
"character_descriptions": {
"CharacterName": "detailed visual description"
}
}
**Core Method:** `async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:`
- Extract user message from `ctx.user_content.parts`
- Parse JSON input or fallback to plain text
- Extract scene_description and character_descriptions
- Build image prompt with style prefix: "Children's book cartoon illustration with bright vibrant colors, simple shapes, friendly characters."
- Include character descriptions for consistency
- Call `await self.imagen_tool.run()` directly
- Store results in `ctx.session.state["image_result"]`
- Yield Event with results
**Session State:**
- Store JSON results in `ctx.session.state["image_result"]`
- Include success/error status
- Store actual image URLs or error messages
Expected Output Structure:
- Successful results stored as JSON with image URLs
- Error results stored as JSON with error messages
- Results accessible via session state in main.py
Can you create this agent in backend/story_image_agent/agent.py
"
——————————————— اختیاری ، میتوانید به بخش راهحل بروید————————————————–
اکنون تغییر خود را در ADK Web تأیید کنید
cd ~/storygen-learning/02a_Image_Agent_Ready/backend
source ../../.venv/bin/activate
adk web --port 8080
وبسایت را ارتقا دهید
cd ~/storygen-learning/02a_Second_Agent_Ready
./start.sh
اگر تغییر شما کار نکند، انتظار میرود خطاهایی در رابط کاربری وب ADK و وبسایت مشاهده کنید.
——————————————- راه حل از اینجا شروع می شود ———————————————–
راه حل
با استفاده از Control+C فرآیند قبلی را پایان دهید یا میتوانید یک ترمینال دیگر باز کنید:
# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done
وبسایت را ارتقا دهید:
./start.sh
وبسایت را مشاهده خواهید کرد:
رابط کاربری ADK را امتحان کنید: یک ترمینال دیگر باز کنید:
# Open new terminal
cd ~/storygen-learning/02b_Image_Agent_Done/backend
source ../../.venv/bin/activate
adk web --port 8080
رابط کاربری ADK را مشاهده خواهید کرد که در آن میتوانید از نماینده سوالاتی بپرسید:
قبل از رفتن به بخش بعدی، برای پایان دادن به فرآیند، Ctrl+C را فشار دهید.
یادگیری
اولین عامل ما در تولید متن عالی بود، اما حالا باید تصاویر را تولید کنیم. برای این کار، به کنترل مستقیم بیشتری نیاز داریم. ما نمیخواهیم LLM تصمیم بگیرد که آیا یک تصویر ایجاد کند یا خیر؛ ما میخواهیم مستقیماً به آن دستور دهیم که این کار را انجام دهد. این کار برای یک BaseAgent عالی است.
برخلاف LlmAgent اعلانی، BaseAgent امری است. این بدان معناست که شما، به عنوان توسعهدهنده، منطق پایتون را گام به گام و دقیق درون متد _run_async_impl مینویسید. شما کنترل کاملی بر جریان اجرا دارید.
شما زمانی که به موارد زیر نیاز دارید، BaseAgent را انتخاب میکنید:
منطق قطعی : عامل باید یک توالی مشخص و غیرقابل تغییر از مراحل را دنبال کند.
اجرای مستقیم ابزار : شما میخواهید یک ابزار را مستقیماً و بدون دخالت LLM فراخوانی کنید.
گردشهای کاری پیچیده : این فرآیند شامل دستکاری دادههای سفارشی، فراخوانیهای API و منطقی است که برای یک LLM بسیار پیچیده است که بتواند به طور قابل اعتمادی از یک اعلان به تنهایی استنباط کند.
برای برنامه خود، از یک BaseAgent برای دریافت توضیحات صحنه از اولین agent استفاده خواهیم کرد و مستقیماً ابزار Imagen را فراخوانی میکنیم تا تضمین شود که برای هر صحنه یک تصویر ایجاد میشود.
۸. آزمایش: ارزیابی عامل
اپلیکیشن ما کار میکند، اما به یک شبکه ایمنی خودکار از تستها نیاز داریم. واگذاری این وظیفه به کمکخلبان هوش مصنوعیمان، عالی است.
اقدامات
cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend
از Gemini CLI برای نوشتن تستهای جامع استفاده کنید:
رابط خط فرمان Gemini را باز کنید
gemini
درون پنجرهی رابط خط فرمان (CLI) گامینی (Gamini)، دستور زیر را اجرا کنید:
I need you to create comprehensive test files for my backend/story_agent in Google ADK. I need three specific JSON files that match the testing structure used in ADK evaluation.
**Context:**
- The story agent generates structured JSON stories with exactly 4 scenes
- It uses LlmAgent with no tools, just direct LLM responses
- Input: Keywords
- Output: JSON with story, main_characters, and scenes arrays
**Files to Create:**
### 1. `story_agent_eval.evalset.json` (Comprehensive Integration Tests)
Create a comprehensive evaluation set with:
- **eval_set_id**: "story_agent_comprehensive_evalset"
- **name**: "Story Agent Comprehensive Evaluation Set"
- **description**: "Comprehensive evaluation scenarios for story_agent covering various keyword combinations, edge cases, and story quality metrics"
Each eval_case should include:
- Full conversation arrays with invocation_id, user_content, final_response
- Complete expected JSON responses with detailed stories, characters, and 4 scenes
- session_input with app_name "story_agent"
- All fields: story (narrative text), main_characters (with detailed visual descriptions), scenes (with index, title, description, text)
### 2. `story_generation.test.json` (Unit Tests)
Create basic generation tests with:
- **eval_set_id**: "story_agent_basic_generation_tests"
- **name**: "Story Agent Basic Generation Tests"
- **description**: "Unit tests for story_agent focusing on JSON structure compliance, scene generation, and keyword integration"
### 3. `test_config.json` (Evaluation Configuration)
Create test configuration with:
- **criteria**: response_match_score: 0.7, tool_trajectory_avg_score: 1.0
- **custom_evaluators**:
- json_structure_validator (validates required fields, scene count, character fields)
- story_quality_metrics (word count 80-250, keyword integration threshold 0.8)
- **evaluation_notes**: Story agent specifics and trajectory expectations
**Important Requirements:**
1. All responses must be valid, parseable JSON
2. Stories must have exactly 4 scenes with indices 1-4
3. Each scene must have: index, title, description, text
4. Main characters must have detailed visual descriptions
5. No tool_uses expected (empty arrays) since story agent uses direct LLM
6. Word count should be 100-200 words total
7. Keywords must be naturally integrated into the narrative
Please generate all three files with realistic example stories and comprehensive test coverage matching the ADK evaluation format.
——————————————— اختیاری ، میتوانید به بخش راهحل بروید————————————————–
برای مشاهده ارزیابی:
./run_adk_web_persistent.sh
به برگه eval در رابط کاربری ADK بروید.
شما باید رابط کاربری وب ADK را با قابلیتهای تست مداوم ببینید.
لحظه کلیدی یادگیری: هوش مصنوعی شریک قدرتمندی در خودکارسازی تضمین کیفیت است. میتواند از پسِ نوشتن متنهای تکراری و خستهکنندهی تست برآید و شما را آزاد کند تا روی ساخت ویژگیها تمرکز کنید.
——————————————– راه حل از اینجا شروع می شود ———————————————–
راه حل
- به پوشه راه حل بروید:
cd ~/storygen-learning/03b_Agent_Evaluation_Done/backend
- رابط کاربری وب ADK را باز کنید
./run_adk_web_persistent.sh
میتوانید موارد آزمایش را از تب Eval مشاهده کنید:
معیارها را اینجا تنظیم کنید:
نتیجه اجرای eval را اینجا ببینید:
یادگیری
یک عامل میتواند «کار کند» به این صورت که بدون خطا اجرا شود، اما چگونه بفهمیم که خروجی درست را تولید میکند؟ آیا داستان خوب است؟ آیا فرمت JSON صحیح است؟ اینجاست که چارچوب ارزیابی ADK وارد عمل میشود.
ارزیابی عامل یک سیستم تست خودکار است که برای اندازهگیری کیفیت و صحت پاسخهای عامل شما طراحی شده است. به جای اینکه فقط خطاهای کد را بررسی کند، بررسی میکند که آیا رفتار عامل مطابق انتظارات شما است یا خیر. این چارچوب در درجه اول از چند فایل کلیدی استفاده میکند:
evalset.json : این مجموعه تست اصلی شماست. هر "مورد eval" درون این فایل شامل یک مکالمه نمونه (مثلاً یک درخواست کاربر) و پاسخ ایدهآل و "طلایی" است که انتظار دارید عامل تولید کند.
test_config.json : این فایل قوانین موفقیت را تعریف میکند. شما در اینجا معیارهایی مانند موارد زیر را تعیین میکنید:
response_match_score : پاسخ عامل چقدر باید با پاسخ «طلایی» مطابقت داشته باشد؟ (امتیاز ۱.۰ به این معنی است که باید یکسان باشد).
custom_evaluators : شما میتوانید قوانین خودتان را ایجاد کنید، مانند «پاسخ باید JSON معتبر باشد» یا «داستان باید بیش از ۱۰۰ کلمه داشته باشد».
با اجرای یک ارزیابی، میتوانید به طور خودکار عامل خود را در برابر دهها سناریو آزمایش کنید و اطمینان حاصل کنید که تغییرات در اعلان یا ابزارهای شما به طور تصادفی عملکرد اصلی آن را مختل نمیکند. این یک شبکه ایمنی قدرتمند برای ساخت عاملهای هوش مصنوعی آماده برای تولید است.
۹. زیرساخت به عنوان کد (IaC): ساختن خانهای در فضای ابری
کد ما آزمایش شده است، اما به یک محیط آماده برای اجرا نیاز دارد. ما از «زیرساخت به عنوان کد» برای تعریف محیط خود استفاده خواهیم کرد.
داکر چیست؟
داکر پلتفرمی برای ایجاد و اجرای برنامهها در کانتینرها است. به یک کانتینر مانند یک کانتینر حمل و نقل استاندارد برای نرمافزار فکر کنید. داکر هر آنچه را که برنامه شما برای اجرا نیاز دارد، در یک بسته واحد و ایزوله قرار میدهد:
- خود کد برنامه
- زمان اجرای مورد نیاز (مثلاً نسخه خاص پایتون)
- تمام ابزارها و کتابخانههای سیستم
این برنامهی کانتینر شده میتواند روی هر دستگاهی که داکر روی آن نصب شده باشد، اجرا شود و مشکل قدیمی «روی دستگاه من کار میکند» را حل کند.
در این بخش، از Gemini میخواهیم که یک Dockerfile تولید کند، که به سادگی دستورالعمل یا طرح اولیه برای ساخت تصویر کانتینر برنامه ما است.
اقدامات
cd ~/storygen-learning/04a_Manual_Deployment_Ready
استفاده از Gemini CLI برای ایجاد یک Dockerfile برای backend: باز کردن Gemini CLI
Gemini
در داخل رابط خط فرمان Gemini، دستور زیر را اجرا کنید:
Create a manual deployment plan for my StoryGen app with Google Cloud Platform. I have a Next.js frontend, Python backend, and Terraform infrastructure.
Generate these deployment files:
1. **01-setup.sh** - Environment setup and authentication
2. **02-build-images.sh** - Build and push Docker images to Google Container Registry
3. **03-deploy-infrastructure.sh** - Deploy with Terraform and configure services
4. **load-env.sh** - Load environment variables for deployment
**Requirements:**
- Use Google Cloud Run for both frontend and backend
- Configure Imagen API and storage buckets
- Set up proper IAM permissions
- Use environment variables from .env file
- Include error handling and status checks
Keep scripts simple, well-commented, and production-ready for manual execution.
راه حل :
cd ~/storygen-learning/04b_Manual_Deployment_Done
اجرا:
source ../.venv/bin/activate
./01-setup.sh
./02-build-images.sh
./03-deploy-infrastructure.sh
شما باید نتایج استقرار و ایجاد زیرساخت را ببینید
۱۰. اتوماسیون (CI/CD): خط مونتاژ دیجیتال
استقرار دستی برنامه ما راهی عالی برای درک بخشهای متحرک است، اما کند است، نیاز به تلاش دستی دارد و میتواند منجر به خطای انسانی شود. در توسعه نرمافزار حرفهای، کل این فرآیند با استفاده از روشی به نام CI/CD خودکار میشود.
CI/CD مخفف عبارت Continuous Integration (ادغام مداوم) و Continuous Deployment (استقرار مداوم) است. این روشی برای ساخت، آزمایش و استقرار خودکار کد شما هر بار که تغییری ایجاد میکنید، میباشد.
- ادغام مداوم (CI) : این مرحله "ساخت و آزمایش" است. به محض اینکه یک توسعهدهنده تغییر کد را به یک مخزن مشترک (مانند GitHub) ارسال میکند، یک سیستم خودکار شروع به کار میکند. این سیستم برنامه را میسازد و تمام آزمایشها (مانند ارزیابیهای عامل که ما ایجاد کردیم) را اجرا میکند تا اطمینان حاصل شود که کد جدید به درستی ادغام میشود و هیچ اشکالی ایجاد نمیکند.
- استقرار مداوم (CD) : این مرحله، مرحله "انتشار" است. اگر مرحله CI با موفقیت پشت سر گذاشته شود، سیستم به طور خودکار نسخه جدید و آزمایش شده برنامه را در محیط عملیاتی مستقر میکند و آن را برای کاربران فعال میسازد.
این خط تولید خودکار، یک «خط مونتاژ دیجیتال» ایجاد میکند که کد را از دستگاه توسعهدهنده به سرعت، ایمن و قابل اعتماد به محیط تولید میبرد. در این بخش، از دستیار هوش مصنوعی خود میخواهیم که این خط مونتاژ را با استفاده از GitHub Actions و Google Cloud Build برای ما بسازد.
اقدامات
cd ~/storygen-learning/05a_CICD_Pipeline_Ready
از Gemini CLI برای ساخت خط تولید CI/CD خود با GitHub استفاده کنید:
رابط خط فرمان Gemini را باز کنید
Gemini
در داخل رابط خط فرمان Gemini، دستور زیر را اجرا کنید:
Create a CI/CD pipeline for my StoryGen app using Google Cloud Build and GitHub integration.
Generate these automation files:
1. **cloudbuild.yaml** (for backend) - Automated build, test, and deploy pipeline
2. **GitHub Actions workflow** - Trigger builds on push/PR
3. **Deployment automation scripts** - Streamlined deployment process
**Requirements:**
- Auto-trigger on GitHub push to main branch
- Build and push Docker images
- Run automated tests if available
- Deploy to Google Cloud Run
- Environment-specific deployments (staging/prod)
- Notification on success/failure
Focus on fully automated deployment with minimal manual intervention. Include proper secret management and rollback capabilities.
——————————————– راه حل از اینجا شروع می شود ———————————————–
راه حل :
cd ~/storygen-learning/06_Final_Solution/
# Copy the GitHub workflow to parent folder
cp -r 06_Final_Solution/.GitHub ../../../.GitHub
به پوشه 06_Final_Solution برگردید و اسکریپت را اجرا کنید:
cd ~/storygen-learning/06_Final_Solution/
./setup-cicd-complete.sh
شما باید تکمیل راهاندازی خط لوله CI/CD را ببینید.
راهاندازی گردش کار: کد خود را کامیت و به main ارسال کنید. توجه داشته باشید که برای صدور مجوز باید ایمیل و نام GitHub خود را تنظیم کنید.
git add .
git commit -m "feat: Add backend, IaC, and CI/CD workflow"
git push origin main
برای مشاهدهی اجرای خودکارِ استقرار، به برگهی «اقدامات» در مخزن گیتهاب خود بروید.
۱۱. عملیات: برج کنترل هوش مصنوعی
ما زندهایم! اما سفر هنوز تمام نشده است. این «روز دوم» است - عملیات. بیایید برای مدیریت برنامه در حال اجرا به Cloud Assist برگردیم.
اقدامات
- به سرویس Cloud Run خود در کنسول Google Cloud بروید. با برنامه زنده خود تعامل داشته باشید تا ترافیک و گزارشها را ایجاد کنید.
- پنل Cloud Assist را باز کنید و از آن به عنوان یک کمک خلبان عملیاتی با دستورالعملهایی مانند این استفاده کنید:
تحلیل لاگ:
Summarize the errors in my Cloud Run logs for the service 'genai-backend' from the last 15 minutes.
تنظیم عملکرد:
My Cloud Run service 'genai-backend' has high startup latency. What are common causes for a Python app and how can I investigate with Cloud Trace?
بهینهسازی هزینه:
Analyze the costs for my 'genai-backend' service and its GCS bucket. Are there any opportunities to save money?
لحظه کلیدی یادگیری: هوش مصنوعی SDLC یک حلقه پیوسته است. همان دستیار هوش مصنوعی که به ساخت برنامه کمک کرده است، شریکی ضروری برای نظارت، عیبیابی و بهینهسازی آن در مرحله تولید است.