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 Console и создайте новый проект.

• Откройте левую панель, нажмите 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 Console , в правом верхнем углу нажмите кнопку «Активировать Cloud Shell».

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

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

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

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

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

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.

Получите план своего приложения

• Нажмите «Изменить дизайн приложения», чтобы увидеть диаграмму. Нажмите «<> Получить код» на правой верхней панели, чтобы загрузить код 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

👉💻 Попробуйте Gemini в первый раз.

clear
gemini --model=gemini-2.5-flash

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

👉✨ У каждого инструмента Gemini есть описание. Прочитайте его прямо сейчас. В командной строке Gemini введите:

В Gemini CLI

/help

👉✨ Gemini CLI обладает собственным набором встроенных возможностей. Чтобы изучить их:

В Gemini CLI

/tools

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

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

В Gemini CLI

/memory show

В настоящее время он пуст, представляет собой чистый лист.

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

В Gemini 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 проанализировать брифинг и сообщить о своих выводах:

В 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 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

После завершения выключите терминал Gemini CLI с помощью Control+C

——————————————— Необязательно , вы можете перейти к части «Решение» ——————————————–

Теперь проверьте ваши изменения в ADK Web

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

👉💻 Выйдите из Gemini на мгновение, дважды нажав 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 Web

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 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 является императивным. Это означает, что вы, разработчик, пишете точную пошаговую логику Python внутри метода _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

./run_adk_web_persistent.sh

Тестовые случаи можно увидеть на вкладке Eval :

Настройте показатели здесь:

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

Обучение

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

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

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

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

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

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

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

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

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

Что такое Докер?

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

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

Это контейнерное приложение затем можно запустить на любой машине, на которой установлен Docker, что решает классическую проблему «это работает на моей машине».

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

Действия

cd ~/storygen-learning/04a_Manual_Deployment_Ready

Используйте Gemini CLI для создания Dockerfile для бэкэнда: Откройте 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 означает непрерывную интеграцию и непрерывное развертывание . Это метод автоматической сборки, тестирования и развертывания кода при каждом внесении изменений.

• Непрерывная интеграция (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. Операции: Башня управления ИИ

Мы в эфире! Но путешествие ещё не закончено. Это «День второй» — эксплуатация. Вернёмся к 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?

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