# ADR-002: Архитектура системных агентов

**Статус:** принято
**Дата:** 2026-05-10

---

## Контекст

Проект VoIdea требует автоматизации через AI-агентов. Необходимо определить:
- Количество агентов
- Их обязанности
- Взаимодействие между агентами
- Стек реализации

Рассматривались:
- **Один суперагент** — всё в одном, сложно масштабировать
- **Ручное управление** — человек выполняет всё
- **11 отдельных агентов** — модульность, специализация

---

## Решение

**11 системных агентов**, каждый со своей ответственностью.

### Список агентов

| Агент | Ответственность | Триггеры |
|-------|-----------------|----------|
| DocAgent | Документация, комментарии | pre-commit, push, manual |
| AuditAgent | Соблюдение правил, прогресс | pre-commit, daily, manual |
| SecurityAgent | Безопасность, уязвимости | pre-commit, weekly, manual |
| SpecAgent | Спецификации, версионирование | tag creation, push |
| ObserverAgent | Наблюдение за пользователями | continuous, daily report |
| QATesterAgent | Функциональное тестирование | pre-commit, daily, manual |
| FixAgent | Исправление багов | QATesterAgent results |
| UITestAgent | Визуальное тестирование | weekly, manual |
| RolloutAgent | Постепенное развёртывание | after tests, manual |
| EvolutionAgent | Саморазвитие агентов | daily, learning |
| BacklogAgent | Управление задачами | continuous |

---

## Архитектура

### Структура файлов

```
app/agents/
├── __init__.py           # Публичный API
├── base.py               # Базовый класс Agent
├── doc_agent.py          # DocAgent
├── audit_agent.py        # AuditAgent
├── security_agent.py     # SecurityAgent
├── spec_agent.py         # SpecAgent
├── observer_agent.py     # ObserverAgent
├── qa_tester_agent.py    # QATesterAgent
├── fix_agent.py          # FixAgent
├── ui_test_agent.py      # UITestAgent
├── rollout_agent.py      # RolloutAgent
├── evolution_agent.py    # EvolutionAgent
└── backlog_agent.py     # BacklogAgent
```

### Базовый класс

```python
from abc import ABC, abstractmethod
from typing import Any, Optional

class BaseAgent(ABC):
    name: str
    version: str
    
    @abstractmethod
    async def run(self, context: dict) -> AgentResult:
        """Основной метод выполнения"""
        pass
    
    @abstractmethod
    async def health_check(self) -> bool:
        """Проверка работоспособности"""
        pass
    
    async def get_status(self) -> AgentStatus:
        """Текущий статус агента"""
        pass
    
    async def get_metrics(self) -> AgentMetrics:
        """Метрики работы агента"""
        pass
```

---

## Меж-агентское взаимодействие

### Делегирование

```python
class AgentA:
    async def process(self, task):
        if task.requires_agent_b:
            result = await delegate_to(
                target=AgentB,
                task=task,
                timeout=30
            )
        # continue processing
```

### Event-driven

```python
class EventBus:
    async def publish(self, event: AgentEvent):
        await self._handlers[event.type].handle(event)

class AgentB:
    @event_handler(AgentEventTypes.TASK_DELEGATED)
    async def handle_delegated_task(self, event):
        # process task
```

---

## Описание поведения каждого агента

### DocAgent

**Цель:** Поддержание документации в актуальном состоянии.

**Обязанности:**
- Создание README.md для новых модулей
- Обновление docs при изменении кода
- Генерация docstrings
- Ведение Runbook

**Триггеры:**
- Создание нового файла
- Изменение существующего > 50 строк
- Создание новой папки
- Push в main/develop

**Взаимодействие:**
- SpecAgent → обновление спецификаций
- AuditAgent → проверка актуальности docs

---

### AuditAgent

**Цель:** Контроль соблюдения правил проекта.

**Обязанности:**
- Проверка code style (ruff)
- Проверка типизации (mypy)
- Контроль прогресса по плану
- Фиксация отклонений

**Триггеры:**
- pre-commit hook
- Ежедневно 09:00
- По запросу администратора

**Взаимодействие:**
- SecurityAgent → проверка безопасности
- DocAgent → обновление отчётов

---

### SecurityAgent

**Цель:** Обеспечение безопасности проекта.

**Обязанности:**
- Сканирование уязвимостей
- Проверка input валидации
- Контроль зависимостей (safety)
- Соответствие 152-ФЗ

**Триггеры:**
- pre-commit hook
- Еженедельно (полное сканирование)
- При добавлении зависимости

**Взаимодействие:**
- FixAgent → исправление уязвимостей
- RolloutAgent → блокировка при критических уязвимостях

---

### SpecAgent

**Цель:** Управление спецификациями и версионированием.

**Обязанности:**
- Генерация CHANGELOG
- Обновление project.json
- Управление ADR
- Версионирование кода

**Триггеры:**
- Создание git tag
- Push в main
- Изменение спецификаций

**Взаимодействие:**
- DocAgent → обновление docs
- EvolutionAgent → фиксация изменений

---

### ObserverAgent

**Цель:** Сбор и анализ данных о пользователях.

**Обязанности:**
- Сбор метрик использования
- Генерация идей для развития
- Выявление паттернов поведения
- Отчёты для EvolutionAgent

**Триггеры:**
- Непрерывный сбор данных
- Ежедневный отчёт
- По запросу EvolutionAgent

**Метрики (MVP):**
- page_views
- session_duration
- feature_usage_frequency
- conversion_rate

**Взаимодействие:**
- EvolutionAgent → данные для анализа
- RolloutAgent → метрики для решения

---

### QATesterAgent

**Цель:** Функциональное тестирование.

**Обязанности:**
- Создание временных аккаунтов
- Выполнение тестов
- Очистка временных данных
- Генерация отчётов

**Триггеры:**
- pre-commit hook
- Ежедневно в 06:00
- Вручную через админ-панель
- После FixAgent исправления

**Взаимодействие:**
- FixAgent → исправление найденных багов
- UITestAgent → визуальное тестирование
- RolloutAgent → результаты для решения

---

### FixAgent

**Цель:** Автоматическое исправление багов.

**Обязанности:**
- Анализ багов из QATesterAgent
- Генерация исправлений
- Создание PR
- Валидация исправлений

**Триггеры:**
- Результаты QATesterAgent
- Критические ошибки в логах
- По запросу человека

**Взаимодействие:**
- QATesterAgent → повторное тестирование
- DocAgent → обновление документации
- Git → создание PR

---

### UITestAgent

**Цель:** Визуальное тестирование интерфейса.

**Обязанности:**
- Скриншот-тестирование
- Проверка layout
- Accessibility testing
- Кросс-браузерное тестирование

**Триггеры:**
- Еженедельно
- После изменений в UI
- Вручную через админ-панель

**Взаимодействие:**
- QATesterAgent → результаты
- FixAgent → исправление визуальных багов

---

### RolloutAgent

**Цель:** Управление развёртыванием.

**Обязанности:**
- Контроль этапов rollout (3→1%→5%→15%→100%)
- Мониторинг метрик
- Принятие решения о переходе
- Откат при проблемах

**Триггеры:**
- После успешных тестов
- Ежедневный мониторинг
- По решению человека

**Взаимодействие:**
- ObserverAgent → метрики
- FixAgent → исправление проблем
- BacklogAgent → создание задач

---

### EvolutionAgent

**Цель:** Саморазвитие агентов.

**Обязанности:**
- Анализ эффективности агентов
- Генерация предложений по улучшению
- Обновление capabilities
- Обучение на данных

**Триггеры:**
- Ежедневно
- При обнаружении новых паттернов
- По запросу BacklogAgent

**Взаимодействие:**
- ObserverAgent → данные о пользователях
- Все агенты → улучшение работы

---

### BacklogAgent

**Цель:** Управление отложенными задачами.

**Обязанности:**
- Создание задач из предложений
- Приоритизация
- Отслеживание статуса
- Напоминания

**Триггеры:**
- Непрерывный мониторинг
- По предложению других агентов
- Вручную через админ-панель

**Взаимодействие:**
- Все агенты → создание задач
- RolloutAgent → задачи для реализации

---

## Последствия

### Положительные

- Модульность — легко добавлять новых агентов
- Специализация — каждый делает своё
- Тестируемость — можно тестировать отдельно
- Масштабируемость — агенты работают параллельно

### Отрицательные

- Сложность координации
- Возможные конфликты агентов
- Overhead на коммуникацию

---

## Ответственный

**Decision maker:** Owner
**Review date:** При добавлении новых агентов

---

*Создано: 2026-05-10*
*Обновлено при изменениях EvolutionAgent*