AI Agent End to End — семинар

1. Чему вы научитесь

AI Agent Vibe Full Stack

Добро пожаловать! Вы вот-вот освоите следующий важнейший навык в разработке программного обеспечения: как эффективно управлять искусственным интеллектом для создания, тестирования и развертывания программного обеспечения производственного уровня. Генеративный ИИ — это не «автопилот», а мощный помощник, которому нужен опытный руководитель.

Этот семинар предлагает структурированную, воспроизводимую методологию сотрудничества с ИИ на каждом этапе профессионального жизненного цикла разработки программного обеспечения (SDLC). Вы перейдете от написания кода построчно к роли технического директора — архитектора с видением и генерального подрядчика, использующего ИИ для точной реализации этого видения. 🚀

По завершении этого урока вы получите:

• Преобразовал высокоуровневую идею в облачную архитектуру с использованием искусственного интеллекта.
• Разработал полноценный бэкэнд на Python с целевыми, специфическими запросами.
• Использовал ИИ в качестве партнера по программированию для отладки и исправления кода.
• Создание модульных тестов, включая заглушки, было поручено искусственному интеллекту.
• Создана готовая к использованию в производственной среде инфраструктура как код (IaC) с помощью Terraform.
• Создал полноценный конвейер CI/CD в GitHub Actions с помощью одного запроса.
• Осуществляйте мониторинг и управление вашим работающим приложением с помощью инструментов управления на основе искусственного интеллекта.

Вы уйдете не просто с работающим приложением, а с планом разработки приложений с использованием искусственного интеллекта. Давайте начнем!

2. Предварительные условия и настройка

Прежде чем начать, давайте подготовим рабочее место. Это важнейший шаг для обеспечения бесперебойного проведения мастер-класса.

Создайте новую учетную запись GCP и свяжите с ней свою платежную систему.

Для работы наших ИИ-агентов нам необходимы две вещи: проект Google Cloud, который обеспечит основу, и ключ API Gemini для доступа к мощным моделям Google.

Шаг 1: Активируйте платежный аккаунт

• Для развертывания вам потребуется пополнить свой платежный аккаунт на 5 долларов. Убедитесь, что вы активировали свою учетную запись Gmail .

Кредитная карта или оплата не требуются — вы получите 5 долларов бесплатных кредитов. Это займет меньше 2 минут, просто введите свое имя и примите кредиты.

Шаг 2: Создайте новый проект GCP.

• Перейдите в консоль Google Cloud и создайте новый проект.

• Откройте левую панель, нажмите Billing , проверьте, связана ли учетная запись для выставления счетов с этой учетной записью GCP.

Если вы видите эту страницу, перейдите в раздел manage billing account , выберите пробную версию Google Cloud Trial One и свяжите её с этим аккаунтом.

Шаг 3: Сгенерируйте свой API-ключ Gemini

Прежде чем получить ключ, вам необходимо его иметь.

• Перейдите в Google AI Studio: https://aistudio.google.com/
• Войдите в систему, используя свою учетную запись Gmail .
• Нажмите кнопку «Получить ключ API» , которая обычно находится в левой панели навигации или в правом верхнем углу.
• В диалоговом окне «Ключи API» нажмите «Создать ключ API в новом проекте».
• Выберите новый созданный вами проект, в котором настроен платежный аккаунт.

• Для вас будет сгенерирован новый API-ключ.

Немедленно скопируйте этот ключ и сохраните его во временном безопасном месте (например, в менеджере паролей или в надежной заметке). Это значение вы будете использовать на следующих шагах.

Аутентификация GitHub

Убедитесь, что вы используете один и тот же аккаунт Gmail для своего проекта на GitHub и в Google Cloud.

Чтобы открыть Cloud Shell, перейдите в консоль Google Cloud и в правом верхнем углу нажмите кнопку «Активировать Cloud Shell».

Шаг 1: Откройте Cloud Shell

👉Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud (это значок терминала в верхней части панели Cloud Shell).

👉Нажмите на кнопку «Открыть редактор» (она выглядит как открытая папка с карандашом). Это откроет редактор кода Cloud Shell в окне. Слева вы увидите файловый менеджер.

👉После открытия редактора откройте терминал в облачной IDE.

👉💻 В терминале убедитесь, что вы уже авторизованы и что проект настроен на ваш идентификатор проекта, используя следующую команду:

gcloud auth list

Шаг 2: Аутентификация через GitHub и создание форка.

Аутентификация через GitHub:

👉💻 Скопируйте и вставьте команду в свой облачный терминал:

gh auth login

• В поле "Где вы используете GitHub?" выберите "GitHub.com".
• «Какой протокол вы предпочитаете использовать для операций Git на этом хосте?», выберите «HTTPS».
• «Аутентифицировать Git с помощью учетных данных GitHub?», выберите «Да».
• «Как вы хотите авторизовать GitHub CLI?», выберите «Войти через веб-браузер».

Важно!! Пока не нажимайте клавишу «Enter».

Обратите внимание, что для открытия страницы авторизации GitHub вам необходимо скопировать и вставить ссылку из терминала.

Скопируйте код с терминала на страницу подтверждения входа.

После ввода кода вернитесь в терминал Cloud Shell и нажмите Enter, чтобы продолжить.

Шаг 4: Создайте форк и клонируйте репозиторий:

👉💻 Скопируйте и вставьте команду в свой облачный терминал:

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

3. Архитектура: от идеи до чертежа с помощью облачных технологий.

Каждый великий проект начинается с четкого видения. Мы будем использовать нашего помощника по искусственному интеллекту, Cloud Assist, для проектирования архитектуры нашего приложения.

Действия

• Откройте консоль Google Cloud: [https://console.cloud.google.com](Консоль Google Cloud)
• В правом верхнем углу нажмите «Открыть чат Cloud Assist».

Включить 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.

Получите план разработки вашего приложения

• Нажмите «Редактировать дизайн приложения», и вы увидите диаграмму. Нажмите на кнопку в правом верхнем углу «<> Получить код», чтобы загрузить код Terraform.
• Cloud Assist сгенерирует архитектурную схему. Это наш визуальный план.

Этот код не требует никаких действий. Подробнее см. ниже.

Разбираемся в сгенерированном коде Terraform. Вы только что получили полный набор файлов Terraform от Cloud Assist. Пока никаких действий с этим кодом не требуется, но давайте быстро разберем, что это такое и почему он так важен.

Что такое Terraform? Terraform — это инструмент «Инфраструктура как код» (IaC). Представьте его как план вашей облачной среды, написанный на коде. Вместо того чтобы вручную создавать сервисы, хранилище и права доступа через консоль Google Cloud, вы определяете все эти ресурсы в конфигурационных файлах. Затем Terraform считывает ваш план и автоматически создает именно такую ​​среду.

От визуального плана к исполняемому коду. Архитектурная диаграмма, предоставленная Cloud Assist, — это ваш визуальный план. Код Terraform — это машиночитаемая версия того же плана. Это важнейшее звено, которое превращает концепцию проектирования в воспроизводимую, автоматизированную реальность. Определив свою инфраструктуру в коде, вы можете:

• Автоматизация создания: Надежно создавайте одну и ту же среду снова и снова.
• Используйте систему контроля версий: отслеживайте изменения в вашей инфраструктуре в Git так же, как и в коде вашего приложения.
• Предотвращение ошибок: Избегайте ошибок, которые могут возникнуть при работе с веб-интерфейсом.

Для этого мастер-класса вам не потребуется самостоятельно запускать этот код Terraform. Воспринимайте его как профессиональный план — «ключ к ответам» — для инфраструктуры, которую вы будете создавать и развертывать на следующих этапах.

4. Разработка: Введение в Gemini CLI

👉💻 В терминале Cloud Shell перейдите в свой личный каталог.

cd ~/storygen-learning

👉💻 Попробуйте знак зодиака Близнецы впервые.

clear
gemini --model=gemini-2.5-flash

Если система спросит: Do you want to connect Cloud Shell editor to Gemini CLI? , выберите «НЕТ» .

👉✨ У каждого инструмента для Близнецов есть описание. Ознакомьтесь с ним прямо сейчас. В командной строке Близнецов введите:

В Gemini CLI

/help

👉✨ Интерфейс командной строки Gemini обладает собственным набором встроенных возможностей. Чтобы ознакомиться с ними:

В Gemini CLI

/tools

Вы увидите список, включающий ReadFile , WriteFile и GoogleSearch . Это стандартные методы, которые вы можете использовать, не прибегая к внешним инструментам.

👉✨ Клинок «Близнецы» способен удерживать «тактическую осведомленность» (контекст) для управления своими действиями.

В Gemini CLI

/memory show

Сейчас оно пустое, чистый лист.

👉✨ Сначала добавьте в память агента персону. Это определит его область компетенции:

В Gemini CLI

/memory add "I am master at python development"

Запустите команду /memory show еще раз, чтобы убедиться, что ваш модуль Blade усвоил эти данные.

👉✨ Чтобы продемонстрировать, как ссылаться на файлы с помощью символа @, давайте сначала создадим файл «краткого описания задания».

Откройте новое окно терминала и выполните следующую команду, чтобы создать файл задания:

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

👉✨Теперь отдайте команду Gemini CLI на анализ брифинга и отправку отчета о результатах:

В Gemini CLI

Explain the contents of the file @mission.md

Ваше основное оружие теперь знает свою цель.

👉💻 Нажмите Ctrl+C дважды, чтобы выйти из Gemini CLI.

Обучение:

Как Gemini CLI обретает свои сверхспособности: gemini.md Прежде чем продолжить, важно понять, как Gemini CLI можно адаптировать под конкретный проект. Хотя его можно использовать как универсальный инструмент для чата, его настоящая мощь заключается в специальном конфигурационном файле: gemini.md.

При запуске команды gemini она автоматически ищет файл gemini.md в текущем каталоге. Этот файл служит инструкцией по эксплуатации ИИ, специфичной для данного проекта. В нем можно определить три ключевых параметра:

• Персонаж: Вы можете указать ИИ, кем он должен быть. Например: «Вы — опытный разработчик на Python, специализирующийся на Google Cloud». Это сфокусирует его ответы и стиль.
• Инструменты: Вы можете предоставить ему доступ к определенным файлам (@file.py) или даже к поисковым запросам Google (@google). Это обеспечит ИИ необходимый контекст для ответа на вопросы о коде вашего проекта.
• Память: Вы можете указать факты или правила, которые ИИ должен всегда помнить для этого проекта, что помогает поддерживать согласованность.

Используя файл gemini.md , вы превращаете стандартную модель Gemini в специалиста-помощника, который уже ознакомлен с целями вашего проекта и имеет доступ к необходимой информации.

5. Разработка: Создание ADK с помощью Gemini CLI

Конфигурация среды

Откройте Cloud Shell и нажмите кнопку «Открыть терминал».

1. Скопируйте шаблон среды:

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

Если вы не нашли файл .env, отобразите его в редакторе (см. скрытый файл).

• Нажмите на кнопку «Вид» в верхней панели меню.
• Выберите «Отключить отображение скрытых файлов» .

👉Найдите идентификатор своего проекта Google Cloud:

• Откройте консоль Google Cloud: [ссылка]
• Выберите проект, который вы хотите использовать для этого мастер-класса, из выпадающего списка проектов в верхней части страницы.
• Идентификатор вашего проекта отображается в карточке с информацией о проекте на панели управления.

👉Найдите своё имя пользователя на 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

Open Gemini CLI

gemini

В окне командной строки 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.

cd ~/storygen-learning/01a_First_Agent_Ready/backend

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

adk web --port 8080

Для продолжения вам потребуется командная строка.

Вы можете либо открыть новое окно терминала, либо остановить текущий веб-сервер ADK, нажав Ctrl+C .

Запустите веб-сайт

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, чтобы завершить процесс.

6. Разработка: Создание ADK с помощью Gemini CLI (метод контекстной инженерии)

Первоначальная настройка

Убедитесь, что мы удалили файл агента, который мы сгенерировали ранее в файле 01a_First_Agent_Ready/backend/story_agent/agent.py:

Перейдите к 01a_First_Agent_Ready. Давайте воспользуемся Gemini CLI для создания агента ADK:**

cd ~/storygen-learning/01a_First_Agent_Ready/backend

Open Gemini CLI

gemini

В окне командной строки Gamini попробуйте ввести следующее:

Summarize the design doc @design.md for me, do not attempt to create file just yet. 

👉💻 Чтобы ненадолго выйти из режима «Близнецы», дважды нажмите Ctrl+C .

👉💻 В терминале выполните следующую команду, чтобы записать файл с инструкциями.

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

👉✨ Теперь попросите Близнецов показать вам, о чём они думают. Руны прочитаны.

/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.

cd ~/storygen-learning/01a_First_Agent_Ready/backend

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

adk web --port 8080

Для продолжения вам потребуется командная строка.

Вы можете либо открыть новое окно терминала, либо остановить текущий веб-сервер ADK, нажав Ctrl+C .

Запустите веб-сайт

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, чтобы завершить процесс.

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 и на веб-сайте.

——————————————— Решение начинается здесь ————————————————

Решение

Завершите предыдущий процесс, нажав 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 является императивным. Это означает, что вы, разработчик, пишете точную пошаговую логику на Python внутри метода _run_async_impl. Вы полностью контролируете поток выполнения.

Вы выберете BaseAgent, когда вам потребуется:

Детерминированная логика : Агент должен следовать определенной, неизменяемой последовательности шагов.

Прямой запуск инструмента : Вы хотите вызвать инструмент напрямую, без вмешательства LLM.

Сложные рабочие процессы : Процесс включает в себя пользовательскую обработку данных, вызовы API и логику, слишком сложную для того, чтобы магистр права мог надежно понять ее, опираясь только на запрос.

В нашем приложении мы будем использовать BaseAgent для получения описаний сцен от первого агента и прямого вызова инструмента Imagen, чтобы гарантировать генерацию изображения для каждой сцены.

8. Тестирование: Оценка агента

Наше приложение работает, но нам необходима автоматизированная система проверок. Эту задачу идеально поручить нашему ИИ-помощнику.

Действия

cd ~/storygen-learning/03a_Agent_Evaluation_Ready/backend

Используйте Gemini CLI для написания комплексных тестов:

Open Gemini CLI

gemini

В окне командной строки 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 :

Здесь можно настроить параметры:

Результаты оценочного запуска можно посмотреть здесь:

Обучение

Агент может «работать», то есть выполняться без ошибок, но как узнать, выдает ли он правильный результат? Хороша ли история? Правилен ли формат JSON? Вот тут-то и пригодится оценочная платформа ADK.

Система оценки агентов — это автоматизированная система тестирования, предназначенная для измерения качества и корректности ответов вашего агента. Вместо простой проверки ошибок в коде, она проверяет, соответствует ли поведение агента вашим ожиданиям. В основе фреймворка лежат несколько ключевых файлов:

evalset.json : Это ваш основной набор тестов. Каждый «тестовый случай» в этом файле содержит пример диалога (например, запрос пользователя) и идеальный, «золотой» ответ, который, как вы ожидаете, выдаст агент.

test_config.json : Этот файл определяет правила успешного выполнения. Здесь вы задаете критерии, например:

response_match_score : Насколько точно ответ агента должен соответствовать «эталонному» ответу? (Оценка 1,0 означает, что ответ должен быть идентичен).

custom_evaluators : Вы можете создавать собственные правила, например, «Ответ должен быть в формате JSON» или «Рассказ должен содержать более 100 слов».

Проведя оценку, вы можете автоматически протестировать своего агента в десятках сценариев, гарантируя, что изменения в ваших подсказках или инструментах случайно не нарушат его основную функциональность. Это мощная система безопасности для создания готовых к использованию в производстве ИИ-агентов.

9. Инфраструктура как код (IaC): создание дома в облаке

Наш код протестирован, но ему нужна готовая к использованию в производственной среде среда. Для определения среды мы будем использовать концепцию «Инфраструктура как код».

Что такое Docker?

Docker — это платформа для создания и запуска приложений в контейнерах. Представьте себе контейнер как стандартный транспортный контейнер для программного обеспечения. Он объединяет все необходимое для работы вашего приложения в один изолированный пакет:

• Сам код приложения
• Необходимая среда выполнения (например, конкретная версия Python)
• Все системные инструменты и библиотеки

Затем это контейнеризированное приложение можно запустить на любой машине, на которой установлен Docker, решая классическую проблему "у меня всё работает".

В этом разделе мы попросим Gemini сгенерировать Dockerfile, который представляет собой просто рецепт или план для создания образа контейнера нашего приложения.

Действия

cd ~/storygen-learning/04a_Manual_Deployment_Ready

Используйте Gemini CLI для создания Dockerfile для бэкенда: Откройте 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

Вы должны увидеть результаты развертывания и создания инфраструктуры.

10. Автоматизация (CI/CD): цифровая сборочная линия

Развертывание приложения вручную — отличный способ понять его работу, но это медленно, требует ручных усилий и может привести к человеческим ошибкам. В профессиональной разработке программного обеспечения весь этот процесс автоматизируется с помощью метода, называемого CI/CD.

CI/CD расшифровывается как непрерывная интеграция и непрерывное развертывание . Это метод автоматической сборки, тестирования и развертывания кода при каждом внесении изменений.

• Непрерывная интеграция (CI) : это фаза «сборки и тестирования». Как только разработчик отправляет изменения в код в общий репозиторий (например, GitHub), запускается автоматизированная система. Она собирает приложение и запускает все тесты (например, созданные нами оценки агентов), чтобы убедиться, что новый код корректно интегрируется и не содержит ошибок.
• Непрерывная непрерывная интеграция (CD) : это фаза «выпуска». Если фаза CI проходит успешно, система автоматически развертывает новую, протестированную версию приложения в производственной среде, делая ее доступной для пользователей.

Этот автоматизированный конвейер создает «цифровую сборочную линию», которая быстро, безопасно и надежно доставляет код с компьютера разработчика в продакшн. В этом разделе мы попросим нашего ИИ-помощника построить эту сборочную линию для нас, используя GitHub Actions и Google Cloud Build.

Действия

cd ~/storygen-learning/05a_CICD_Pipeline_Ready

Используйте Gemini CLI для создания конвейера CI/CD с помощью GitHub:

Open Gemini CLI

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.

Запуск рабочего процесса: зафиксируйте изменения и отправьте свой код в основную ветку. Обратите внимание, что вам необходимо указать свой адрес электронной почты и имя пользователя 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?

Ключевой момент обучения: Жизненный цикл разработки программного обеспечения с использованием ИИ — это непрерывный цикл. Тот же самый «второй пилот» ИИ, который помогал создавать приложение, становится незаменимым партнером для мониторинга, устранения неполадок и оптимизации его работы в производственной среде.