AI Agent End to End - کارگاه آموزشی

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

AI Agent Vibe Full Stack

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

این کارگاه یک روش ساختاریافته و قابل تکرار برای مشارکت با هوش مصنوعی در هر مرحله از چرخه عمر توسعه نرم افزار حرفه ای (SDLC) ارائه می دهد. شما از یک کدنویس خط به خط به یک مدیر فنی تبدیل خواهید شد – یک معمار با دید و یک پیمانکار عمومی که از هوش مصنوعی برای اجرای آن چشم انداز با دقت استفاده می کند. 🚀

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

• یک ایده سطح بالا را با استفاده از هوش مصنوعی به معماری ابری ترجمه کرد.
• یک بک‌اند کامل پایتون با اعلان‌های هدفمند و خاص ایجاد کرد.
• از هوش مصنوعی به عنوان برنامه نویس جفتی برای اشکال زدایی و رفع کد استفاده کرد.
• ایجاد تست های واحد، از جمله ساختگی، را به هوش مصنوعی محول کرد.
• زیرساخت آماده تولید به عنوان کد (IaC) با Terraform.
• یک خط لوله کامل CI/CD در GitHub Actions با یک اعلان ایجاد کرد.
• برنامه زنده خود را با استفاده از ابزارهای عملیاتی مبتنی بر هوش مصنوعی نظارت و مدیریت کرد.

شما نه تنها با یک اپلیکیشن کارآمد، بلکه با طرحی برای توسعه با هوش مصنوعی ترک خواهید کرد. بیایید شروع کنیم!

2. پیش نیازها و راه اندازی

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

یک حساب GCP جدید ایجاد کنید و صورتحساب خود را پیوند دهید

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

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

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

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

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

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

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

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

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

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

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

• یک کلید API جدید برای شما ایجاد خواهد شد.

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

احراز هویت GitHub

مطمئن شوید که از همان حساب جیمیل برای GitHub و پروژه Google Cloud خود استفاده می کنید.

Cloud Shell را باز کنید، با رفتن به Google Cloud Console ، در دکمه بالا سمت راست "Activate Cloud Shell".

مرحله 1: Cloud Shell را باز کنید

👉روی "فعال کردن پوسته ابری" در بالای کنسول Google Cloud کلیک کنید (این نماد شکل ترمینال در بالای صفحه Cloud Shell است)،

👉روی دکمه "Open Editor" کلیک کنید (به نظر می رسد یک پوشه باز با مداد است). با این کار ویرایشگر کد Cloud Shell در پنجره باز می شود. در سمت چپ یک فایل کاوشگر خواهید دید.

👉زمانی که ویرایشگر را باز کردید، ترمینال را در IDE ابری باز کنید،

👉💻 در ترمینال، با استفاده از دستور زیر بررسی کنید که قبلا احراز هویت شده اید و پروژه به ID پروژه شما تنظیم شده است:

gcloud auth list

مرحله 2: با GitHub & Fork احراز هویت

احراز هویت با GitHub:

👉💻 دستور را در ترمینال ابری خود کپی و پیست کنید:

gh auth login

• "در کجا از GitHub استفاده می کنید"، "GitHub.com" را انتخاب کنید.
• "پروتکل ترجیحی شما برای عملیات Git در این میزبان چیست؟"، "HTTPS" را انتخاب کنید
• «Git را با اعتبار GitHub خود تأیید کنید؟»، «بله» را انتخاب کنید.
• «چگونه می‌خواهید GitHub CLI را تأیید کنید؟»، «ورود با مرورگر وب» را انتخاب کنید.

مهم !! هنوز "ورود" را فشار ندهید

توجه داشته باشید که برای باز کردن صفحه تأیید اعتبار GitHub باید پیوند را از ترمینال کپی و جایگذاری کنید.

کد را از ترمینال برای تأیید ورود به صفحه کپی کنید

هنگامی که وارد کردن کد را تمام کردید، به ترمینال Cloud Shell خود برگردید، برای ادامه، "Enter" را فشار دهید.

مرحله 4: مخزن را فورک و کلون کنید:

👉💻 دستور را در ترمینال ابری خود کپی و پیست کنید:

gh repo fork cuppibla/storygen-learning --clone=true

3. معماری: از ایده تا طرح اولیه با Cloud Assist

هر پروژه بزرگ با یک چشم انداز روشن شروع می شود. ما از کمک خلبان هوش مصنوعی خود، Cloud Assist، برای طراحی معماری اپلیکیشن خود استفاده خواهیم کرد.

اقدامات

• Google Cloud Console را باز کنید: [https://console.cloud.google.com](Google Cloud Console)
• در گوشه سمت راست بالا، روی «باز کردن Cloud Assist Chat» کلیک کنید.

Cloud Assist را فعال کنید

• روی 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.

برنامه BluePrint خود را دریافت کنید

• کلیک کنید: "ویرایش طراحی برنامه"، نمودار را مشاهده خواهید کرد. برای دانلود کد Terraform روی پانل بالای سمت راست "<> دریافت کد" کلیک کنید.
• Cloud Assist یک نمودار معماری ایجاد می کند. این طرح تصویری ماست.

هیچ اقدامی با این کد لازم نیست. برای توضیح بیشتر زیر را بخوانید

درک کد Terraform تولید شده شما به تازگی مجموعه کاملی از فایل های Terraform را از Cloud Assist دریافت کرده اید. در حال حاضر هیچ اقدامی با این کد مورد نیاز نیست، اما بیایید به سرعت توضیح دهیم که چیست و چرا اینقدر قدرتمند است.

Terraform چیست؟ Terraform یک ابزار زیرساخت به عنوان کد (IaC) است. به آن به عنوان طرحی برای محیط ابری خود فکر کنید که با کد نوشته شده است. به‌جای کلیک دستی از طریق کنسول Google Cloud برای ایجاد سرویس‌ها، فضای ذخیره‌سازی و مجوزها، همه آن منابع را در این فایل‌های پیکربندی تعریف می‌کنید. Terraform سپس نقشه شما را می خواند و دقیقاً آن محیط را به طور خودکار برای شما می سازد.

از Visual Plan تا کد اجرایی. نمودار معماری Cloud Assist ارائه شده طرح بصری شما است. کد Terraform نسخه قابل خواندن ماشین از همان طرح است. این پیوند حیاتی است که یک مفهوم طراحی را به یک واقعیت تکرارپذیر و خودکار تبدیل می کند. با تعریف زیرساخت خود در کد، می توانید:

• ایجاد خودکار: به طور قابل اعتماد همان محیط را بارها و بارها بسازید.
• از کنترل نسخه استفاده کنید: تغییرات زیرساخت خود را در Git، درست مانند کد برنامه خود، ردیابی کنید.
• جلوگیری از خطاها: از اشتباهات دستی که ممکن است هنگام کلیک کردن روی یک رابط وب رخ دهد، اجتناب کنید.

برای این کارگاه، نیازی نیست خودتان این کد Terraform را اجرا کنید. آن را به‌عنوان طرحی حرفه‌ای – «کلید پاسخ» – برای زیرساختی که در مراحل آتی خواهید ساخت و اجرا خواهید کرد، در نظر بگیرید.

4. توسعه: مقدمه ای بر Gemini CLI

👉💻 در ترمینال Cloud Shell خود، به فهرست راهنمای شخصی خود بروید.

cd ~/storygen-learning

👉💻 Gemini را برای اولین بار امتحان کنید.

clear
gemini --model=gemini-2.5-flash

اگر از شما بپرسد Do you want to connect Cloud Shell editor to Gemini CLI? NO را انتخاب کنید.

👉✨ هر ابزار جمینی توضیحاتی دارد. اکنون آنها را بخوانید. در اعلان Gemini، تایپ کنید:

در جمینی CLI

/help

👉✨ Gemini CLI مجموعه ای از توانایی های داخلی خود را دارد. برای بازرسی آنها:

در جمینی CLI

/tools

لیستی از جمله ReadFile ، WriteFile و GoogleSearch خواهید دید. اینها تکنیک های پیش فرضی هستند که می توانید بدون نیاز به استفاده از یک زرادخانه خارجی از آنها استفاده کنید.

👉✨ Gemini Blade می تواند "آگاهی تاکتیکی" (زمینه) را برای هدایت اقدامات خود نگه دارد.

در جمینی CLI

/memory show

در حال حاضر خالی است، یک لوح سفید.

👉✨ ابتدا یک پرسونا به حافظه نماینده اضافه کنید. این حوزه تخصص آن را مشخص می کند:

در جمینی CLI

/memory add "I am master at python development"

برای تأیید اینکه تیغه شما این دانش را جذب کرده است، دوباره /memory show اجرا کنید.

👉✨ برای نشان دادن نحوه ارجاع فایل‌ها با نماد @، اجازه دهید ابتدا یک فایل "مشخصه ماموریت" ایجاد کنیم.

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

!echo "## Mission Objective: Create Imagen ADK Agent for Story Book" > mission.md

👉✨اکنون، به Gemini CLI خود دستور دهید تا جلسه توجیهی را تجزیه و تحلیل کند و یافته های آن را گزارش کند:

در جمینی CLI

Explain the contents of the file @mission.md

سلاح اصلی شما اکنون از هدف خود آگاه است.

👉💻 Ctrl+C را دوبار فشار دهید تا از Gemini CLI خارج شوید

یادگیری:

چگونه Gemini CLI ابرقدرت های خود را بدست می آورد: gemini.md قبل از ادامه، مهم است که بدانیم چگونه Gemini CLI را می توان برای یک پروژه خاص تنظیم کرد. در حالی که می توانید از آن به عنوان یک ابزار چت همه منظوره استفاده کنید، قدرت واقعی آن از یک فایل پیکربندی خاص می آید: gemini.md.

هنگامی که فرمان gemini را اجرا می کنید، به طور خودکار به دنبال یک فایل gemini.md در دایرکتوری فعلی می گردد. این فایل به عنوان یک دستورالعمل پروژه خاص برای هوش مصنوعی عمل می کند. می تواند سه چیز کلیدی را تعریف کند:

• Persona: شما می توانید به هوش مصنوعی بگویید که چه کسی باید باشد. به عنوان مثال، "شما یک توسعه دهنده متخصص پایتون هستید که در Google Cloud تخصص دارد." این پاسخ ها و سبک آن را متمرکز می کند.
• ابزارها: می‌توانید به آن اجازه دسترسی به فایل‌های خاص (@file.py) یا حتی جستجوهای Google (@google) بدهید. این موضوع زمینه ای را برای هوش مصنوعی فراهم می کند که برای پاسخ به سوالات مربوط به کد پروژه شما نیاز دارد.
• حافظه: شما می توانید حقایق یا قوانینی را ارائه دهید که هوش مصنوعی باید همیشه برای این پروژه به خاطر بسپارد، که به حفظ ثبات کمک می کند.

با استفاده از یک فایل gemini.md ، مدل عمومی Gemini را به یک دستیار تخصصی تبدیل می کنید که قبلاً در مورد اهداف پروژه شما توضیح داده شده است و به اطلاعات مناسب دسترسی دارد.

5. توسعه: ساخت ADK با Gemini CLI

پیکربندی محیط

به Cloud Shell خود بروید، روی دکمه "Open Terminal" کلیک کنید.

1. الگوی محیط را کپی کنید:

   cd ~/storygen-learning
   cp ~/storygen-learning/env.template ~/storygen-learning/.env
   

اگر .env را پیدا نکردید، فایل مخفی را در ویرایشگر مشاهده کنید

• در نوار منوی بالا روی View کلیک کنید.
• Toggle Hidden Files را انتخاب کنید.

👉شناسه پروژه Google Cloud خود را پیدا کنید:

• پیوند Google Cloud Console را باز کنید
• پروژه ای را که می خواهید برای این کارگاه استفاده کنید از منوی کشویی پروژه در بالای صفحه انتخاب کنید.
• شناسه پروژه شما در کارت اطلاعات پروژه در داشبورد نمایش داده می شود

👉نام کاربری GitHub خود را پیدا کنید:

• به GitHub خود بروید و نام کاربری GitHub خود را پیدا کنید

ویرایش فایل .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 استفاده کنیم:**

cd ~/storygen-learning/01a_First_Agent_Ready

Gemini CLI را باز کنید

gemini

در داخل پنجره Gamini CLI، دستور زیر را امتحان کنید:

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

پس از اتمام کار، ترمینال CLI Gemini را با Control+C خاموش کنید

—————————————— اختیاری است ، می توانید به بخش راه حل بروید———————————————

اکنون تغییر خود را در وب ADK تأیید کنید

cd ~/storygen-learning/01a_First_Agent_Ready/backend

source ../../.venv/bin/activate

adk web --port 8080

برای ادامه، به یک خط فرمان نیاز دارید.

می توانید یک پنجره ترمینال جدید باز کنید یا با فشار دادن Ctrl+C وب سرور ADK فعلی را متوقف کنید.

چرخش وب سایت

cd ~/storygen-learning/01a_First_Agent_Ready

./start.sh

اگر تغییر شما جواب نداد، انتظار دارید خطاهایی را در ADK Web UI و Website ببینید.

———————————————– راه حل از اینجا شروع می شود ————————————————

راه حل

فرآیند قبلی را با 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 UI را می بینید که در آن می توانید از نماینده سوال بپرسید

قبل از رفتن به بخش بعدی، Ctrl+C را فشار دهید تا فرآیند پایان یابد.

6. توسعه: Building ADK با Gemini CLI - (Context Engineering Way)

راه اندازی اولیه

مطمئن شوید که فایل عاملی را که قبلاً تولید کرده‌ایم، در 01a_First_Agent_Ready/backend/story_agent/agent.py حذف کرده‌ایم:

برو به 01a_First_Agent_Ready بیایید از Gemini CLI برای ایجاد عامل ADK استفاده کنیم:**

cd ~/storygen-learning/01a_First_Agent_Ready/backend

Gemini CLI را باز کنید

gemini

در داخل پنجره Gamini CLI، دستور زیر را امتحان کنید:

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 CLI را از دایرکتوری shadowblade دوباره راه اندازی کنید:

cd ~/storygen-learning/01a_First_Agent_Ready/backend
clear
gemini

👉✨ اکنون، از 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.

پس از اتمام کار، ترمینال CLI Gemini را با Control+C خاموش کنید

—————————————— اختیاری است ، می توانید به بخش راه حل بروید———————————————

اکنون تغییر خود را در وب ADK تأیید کنید

cd ~/storygen-learning/01a_First_Agent_Ready/backend

source ../../.venv/bin/activate

adk web --port 8080

برای ادامه، به یک خط فرمان نیاز دارید.

می توانید یک پنجره ترمینال جدید باز کنید یا با فشار دادن Ctrl+C وب سرور ADK فعلی را متوقف کنید.

چرخش وب سایت

cd ~/storygen-learning/01a_First_Agent_Ready

./start.sh

اگر تغییر شما جواب نداد، انتظار دارید خطاهایی را در ADK Web UI و Website ببینید.

———————————————– راه حل از اینجا شروع می شود ————————————————

راه حل

فرآیند قبلی را با 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 UI را می بینید که در آن می توانید از نماینده سوال بپرسید

قبل از رفتن به بخش بعدی، Ctrl+C را فشار دهید تا فرآیند پایان یابد.

7. توسعه: نماینده سفارشی خود را با 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 تأیید کنید

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 Web UI و Website ببینید.

———————————————- راه حل از اینجا شروع می شود ————————————————

راه حل

فرآیند قبلی را با 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 UI را می بینید که در آن می توانید سوالات خود را از نماینده بپرسید:

قبل از رفتن به بخش بعدی، Ctrl+C را فشار دهید تا فرآیند پایان یابد.

یادگیری

اولین عامل ما در تولید متن عالی بود، اما اکنون باید تصاویر تولید کنیم. برای این کار به کنترل مستقیم بیشتری نیاز داریم. ما نمی خواهیم LLM تصمیم بگیرد که آیا یک تصویر ایجاد کند یا خیر. ما می خواهیم به آن دستور دهیم که این کار را مستقیما انجام دهد. این کار عالی برای BaseAgent است.

برخلاف LlmAgent اعلانی، BaseAgent ضروری است. این بدان معناست که شما، توسعه دهنده، منطق دقیق پایتون را گام به گام در متد _run_async_impl بنویسید. شما کنترل کاملی بر جریان اجرا دارید.

در صورت نیاز، BaseAgent را انتخاب می کنید:

منطق قطعی : عامل باید دنباله ای مشخص و غیرقابل تغییر از مراحل را دنبال کند.

اجرای مستقیم ابزار : شما می خواهید ابزاری را مستقیماً بدون دخالت LLM فراخوانی کنید.

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

برای برنامه خود، از BaseAgent برای دریافت توضیحات صحنه از اولین عامل استفاده می کنیم و مستقیماً با ابزار Imagen تماس می گیریم تا تضمین کنیم که برای هر صحنه یک تصویر تولید می شود.

8. تست: ارزیابی عامل

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

اقدامات

cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend

از Gemini CLI برای نوشتن تست های جامع استفاده کنید:

Gemini CLI را باز کنید

gemini

در داخل پنجره Gamini CLI، دستور زیر را امتحان کنید:

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 Web UI را باز کنید

./run_adk_web_persistent.sh

می توانید موارد تست را از تب Eval مشاهده کنید:

معیارها را در اینجا تنظیم کنید:

نتیجه اجرای eval را در اینجا مشاهده کنید:

یادگیری

یک عامل می تواند از این نظر "کار کند" که بدون خطا اجرا می شود، اما چگونه بفهمیم که خروجی درستی تولید می کند؟ داستانش خوبه؟ آیا فرمت JSON درست است؟ اینجاست که چارچوب ارزیابی ADK وارد می شود.

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

evalset.json : این مجموعه آزمون اصلی شماست. هر «مورد eval» داخل این فایل حاوی یک مکالمه نمونه (مثلاً یک درخواست کاربر) و پاسخ ایده‌آل و «طلایی» است که انتظار دارید نماینده ارائه دهد.

test_config.json : این فایل قوانین موفقیت را تعریف می کند. شما در اینجا معیارهایی را تعیین می کنید، مانند:

answer_match_score : پاسخ نماینده چقدر باید با پاسخ "طلایی" مطابقت داشته باشد؟ (امتیاز 1.0 به این معنی است که باید یکسان باشد).

custom_evaluators : می توانید قوانین خود را ایجاد کنید، مانند "پاسخ باید JSON معتبر باشد" یا "داستان باید بیش از 100 کلمه داشته باشد."

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

9. زیرساخت به عنوان کد (IaC): ساختن خانه در ابر

کد ما تست شده است، اما نیاز به یک خانه آماده برای تولید دارد. ما از "زیرساخت به عنوان کد" برای تعریف محیط خود استفاده خواهیم کرد.

داکر چیست؟

Docker پلتفرمی برای ایجاد و اجرای برنامه ها در کانتینرها است. به یک کانتینر مانند یک کانتینر حمل و نقل استاندارد برای نرم افزار فکر کنید. همه چیزهایی را که برنامه شما برای اجرا نیاز دارد در یک بسته مجزا و مجزا جمع می کند:

• خود کد برنامه
• زمان اجرا مورد نیاز (به عنوان مثال، نسخه خاص پایتون)
• تمام ابزارهای سیستم و کتابخانه ها

سپس این برنامه کانتینری را می توان بر روی هر دستگاهی که Docker نصب کرده است اجرا کرد و مشکل کلاسیک "این روی ماشین من کار می کند" را حل می کند.

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

اقدامات

cd ~/storygen-learning/04a_Manual_Deployment_Ready

از Gemini CLI برای ایجاد یک Dockerfile برای Backend استفاده کنید: Gemini CLI را باز کنید

Gemini

در داخل Gemini CLI، دستور زیر را امتحان کنید:

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

شما باید نتایج استقرار و ایجاد زیرساخت را ببینید

10. اتوماسیون (CI/CD): خط مونتاژ دیجیتال

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

CI/CD مخفف Continuous Integration and Continuous Deployment است. این روشی برای ساخت خودکار، آزمایش و استقرار کد شما در هر بار تغییر است.

• یکپارچه سازی مداوم (CI) : این مرحله "ساخت و آزمایش" است. به محض اینکه یک توسعه‌دهنده تغییر کد را به یک مخزن مشترک (مانند GitHub) فشار می‌دهد، یک سیستم خودکار وارد می‌شود. برنامه را می‌سازد و همه آزمایش‌ها (مانند ارزیابی‌های عاملی که ایجاد کردیم) را اجرا می‌کند تا مطمئن شود کد جدید به درستی ادغام می‌شود و هیچ اشکالی ایجاد نمی‌کند.
• استقرار مداوم (CD) : این مرحله "آزادسازی" است. اگر مرحله CI با موفقیت بگذرد، سیستم به طور خودکار نسخه آزمایش شده و جدید برنامه را برای تولید مستقر می کند و آن را برای کاربران زنده می کند.

این خط لوله خودکار یک "خط مونتاژ دیجیتال" ایجاد می کند که کد را از ماشین توسعه دهنده به سرعت، ایمن و قابل اطمینان می برد. در این بخش، از دستیار هوش مصنوعی خود می خواهیم که این خط مونتاژ را با استفاده از GitHub Actions و Google Cloud Build برای ما بسازد.

اقدامات

cd ~/storygen-learning/05a_CICD_Pipeline_Ready

از Gemini CLI برای ایجاد خط لوله CI/CD خود با GitHub استفاده کنید:

Gemini CLI را باز کنید

Gemini

در داخل Gemini CLI، دستور زیر را امتحان کنید:

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 را ببینید

گردش کار را راه اندازی کنید: کد خود را متعهد کنید و به حالت اصلی فشار دهید. توجه داشته باشید که باید ایمیل و نام GitHub خود را تنظیم کنید تا مجوز اجازه داده شود.

git add .
git commit -m "feat: Add backend, IaC, and CI/CD workflow"
git push origin main

برای تماشای اجرای خودکار پیاده‌سازی خود، به تب «اقدامات» در مخزن GitHub خود بروید.

11. عملیات: برج کنترل هوش مصنوعی

ما زنده هستیم! اما سفر تمام نشده است این "روز 2" است - عملیات. بیایید به Cloud Assist برای مدیریت برنامه در حال اجرا خود برگردیم.

اقدامات

1. به سرویس Cloud Run خود در کنسول Google Cloud بروید. برای ایجاد ترافیک و گزارش با برنامه زنده خود تعامل داشته باشید.
2. پنجره 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?

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