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

• Перейдите в 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

Откройте Cloud Shell, перейдя в Google Cloud Console, в правом верхнем углу нажмите кнопку «Активировать Cloud Shell».

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

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

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

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

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

👉Откройте терминал в облачной IDE,

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

gcloud auth list

Шаг 2: Аутентификация с помощью GitHub и Fork

Авторизуйтесь с помощью GitHub:

👉💻

gh auth login

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

Форк и клонирование репозитория: 👉💻

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

3. Архитектура: от идеи до чертежа с Cloud Assist

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

Действия

• Откройте консоль Google Cloud: https://console.cloud.google.com
• В правом верхнем углу нажмите «Открыть 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 создаст архитектурную схему. Это наш визуальный план.

Ключевой момент обучения: ИИ превосходно справляется с проектированием систем высокого уровня. Он может мгновенно преобразовать простые требования в профессиональную визуальную архитектуру.

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

Начальная настройка

Обязательно используем Gemini CLI для создания репозитория и подготовки рабочего пространства:

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

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

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

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

Просмотреть скрытый файл в редакторе, если вы не нашли .env

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

Редактирование файла .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

Раскрутить сайт

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

5. Разработка: создайте своего собственного агента с помощью 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, чтобы завершить процесс.

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

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

Действия

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 :

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

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

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

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

Действия

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

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

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

Развёртывание приложения вручную — дело медленное и рискованное. Давайте попросим наш ИИ написать полноценный конвейер непрерывной интеграции и непрерывной доставки (CI/CD) с помощью GitHub Actions.

Действия

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

Ключевой момент обучения: весь конвейер CI/CD — сложная и критически важная часть DevOps — может быть создан с помощью ИИ.

9. Операции: Башня управления ИИ

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