angel/voidea
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
688d043dad82ade759c0f4480eaa186c5f1b13f0
voidea/docs/adr/002-eleven-agents.md
T

12 KiB
Raw Blame History

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

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

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

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

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

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

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

Reference in New Issue View Git Blame Copy Permalink