397 lines
12 KiB
Markdown
397 lines
12 KiB
Markdown
# 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* |