[English](https://hb3-accelerator.com/gitea/VC-HB3-Accelerator/Docs/src/branch/main/docs.en/back-docs/multi-agent-architecture.md) | **Русский**

# 🏗️ Архитектура множественных ИИ-агентов в DLE

> **Концепция**: Создание отдельных специализированных агентов для разных задач, использующих одну локальную модель Ollama, но с разными системными промптами, правилами и интерфейсами.

---

## 📋 Содержание

1. [Концепция архитектуры](#концепция-архитектуры)
2. [Типы агентов](#типы-агентов)
3. [Архитектура системы](#архитектура-системы)
4. [Настройка агентов](#настройка-агентов)
5. [Интерфейсы агентов](#интерфейсы-агентов)
6. [База знаний для агентов](#база-знаний-для-агентов)
7. [Процесс работы агентов](#процесс-работы-агентов)

---

## 🎯 Концепция архитектуры

### Основные принципы

1. **Одна модель, множество агентов**
   - Все агенты используют одну локальную модель Ollama (qwen2.5:7b)
   - Различие между агентами — в системных промптах и правилах
   - Каждый агент имеет свою специализацию и роль

2. **Изоляция агентов**
   - Каждый агент имеет свои настройки (системный промпт, правила, RAG таблицы)
   - Агенты не влияют друг на друга
   - Можно создавать, редактировать и удалять агентов независимо

3. **Специализация по задачам**
   - Агент поддержки — отвечает на вопросы пользователей
   - Агент-редактор — создает контент по запросу
   - Возможность создания дополнительных агентов (аналитик, переводчик и т.д.)

4. **Отдельные интерфейсы**
   - Каждый агент имеет свой интерфейс доступа
   - Интерфейсы адаптированы под задачи агента
   - Разные права доступа для разных агентов

---

## 🤖 Типы агентов

### 1. Агент поддержки (Support Agent)

**Роль**: Отвечать на сообщения пользователей

**Задачи**:
- Обработка входящих сообщений от пользователей
- Поиск ответов в базе знаний (FAQ, документация)
- Генерация ответов на основе найденной информации
- Эскалация сложных вопросов к операторам

**Характеристики**:
- Использует RAG для поиска в FAQ и документах
- Системный промпт: "Вы — профессиональный ассистент службы поддержки"
- Правила: строгий режим (только из базы знаний, минимум генерации)
- Интерфейс: встроен в чат (web, telegram, email)

**База знаний**:
- FAQ таблицы
- Документация продукта
- База знаний для клиентов

---

### 2. Агент-редактор (Content Editor Agent)

**Роль**: Создавать контент по запросу пользователя

**Задачи**:
- Создание постов для социальных сетей
- Написание статей для блога
- Генерация email-рассылок
- Создание рекламных текстов

**Характеристики**:
- Использует RAG для поиска инструкций платформ и стиля компании
- Системный промпт: "Вы — профессиональный контент-маркетолог и редактор"
- Правила: креативный режим (больше генерации, использование примеров)
- Интерфейс: отдельная страница "Редактор контента"

**База знаний**:
- Инструкции платформ (ВК, Telegram, Instagram и т.д.)
- Стиль компании (tone of voice, запрещенные слова)
- Примеры контента (референсы)
- Ключевые слова и хэштеги
- CTA блоки

---

### 3. Потенциальные дополнительные агенты

**Агент-аналитик**:
- Анализ данных и создание отчетов
- Выявление трендов
- Прогнозирование

**Агент-переводчик**:
- Перевод контента на разные языки
- Локализация материалов
- Адаптация под культурные особенности

**Агент-закупщик**:
- Поиск поставщиков
- Анализ условий
- Рекомендации по выбору

---

## 🏛️ Архитектура системы

### Компоненты системы

```
┌─────────────────────────────────────────────────────────┐
│              Единая модель Ollama                        │
│              (qwen2.5:7b)                               │
└────────────────┬────────────────────────────────────────┘
                 │
                 ├─────────────────┬───────────────────────┐
                 │                 │                       │
                 ↓                 ↓                       ↓
    ┌────────────────────┐  ┌──────────────────┐  ┌──────────────┐
    │  Агент поддержки   │  │ Агент-редактор  │  │ Другие агенты│
    │                    │  │                  │  │              │
    │ • Системный промпт │  │ • Системный      │  │ • Свои       │
    │ • Правила (строгие)│  │   промпт         │  │   настройки  │
    │ • RAG: FAQ         │  │ • Правила        │  │              │
    │ • Интерфейс: чат   │  │   (креативные)   │  │              │
    │                    │  │ • RAG: инструкции │  │              │
    │                    │  │ • Интерфейс:     │  │              │
    │                    │  │   редактор       │  │              │
    └────────────────────┘  └──────────────────┘  └──────────────┘
```

### Хранение настроек агентов

**Таблица `ai_agents`**:
- `id` — уникальный идентификатор агента
- `name` — название агента (например, "Агент поддержки", "Агент-редактор")
- `role` — роль агента (support, content_editor, analyst и т.д.)
- `description` — описание назначения агента
- `system_prompt_encrypted` — системный промпт (зашифрован)
- `rules_id` — ссылка на правила агента (из таблицы `ai_assistant_rules`)
- `selected_rag_tables` — массив ID таблиц для RAG поиска
- `enabled_channels` — на каких каналах активен (web, telegram, email)
- `interface_route` — маршрут для интерфейса агента
- `permissions_required` — требуемые права доступа
- `is_active` — активен ли агент
- `created_at`, `updated_at` — даты создания и обновления

**Связь с правилами**:
- Каждый агент может использовать набор правил из `ai_assistant_rules`
- Правила определяют поведение: temperature, maxTokens, searchRagFirst и т.д.
- Можно создавать правила специально для каждого агента

**Связь с RAG таблицами**:
- Каждый агент может использовать свои RAG таблицы
- Агент поддержки: FAQ, документация
- Агент-редактор: инструкции платформ, стиль компании, примеры

---

## ⚙️ Настройка агентов

### Создание нового агента

**Шаг 1: Базовая информация**
- Название агента
- Роль (support, content_editor и т.д.)
- Описание назначения

**Шаг 2: Системный промпт**
- Определяет роль и поведение агента
- Указывает, как агент должен работать
- Содержит контекст о компании и стиле

**Шаг 3: Правила (Rules)**
- Создание или выбор существующих правил
- Настройка параметров генерации (temperature, maxTokens)
- Настройка поведения RAG (searchRagFirst, generateIfNoRag)

**Шаг 4: База знаний (RAG таблицы)**
- Выбор таблиц для поиска информации
- Агент поддержки: FAQ, документация
- Агент-редактор: инструкции, стиль, примеры

**Шаг 5: Интерфейс**
- Определение маршрута для доступа к агенту
- Настройка прав доступа
- Выбор каналов (web, telegram, email)

**Шаг 6: Активация**
- Включение/выключение агента
- Тестирование работы агента

### Примеры настроек

**Агент поддержки**:
- Системный промпт: "Вы — профессиональный ассистент службы поддержки..."
- Правила: строгий режим (temperature: 0.3, searchRagFirst: true, generateIfNoRag: false)
- RAG таблицы: FAQ, Документация продукта
- Интерфейс: встроен в чат
- Каналы: web, telegram, email

**Агент-редактор**:
- Системный промпт: "Вы — профессиональный контент-маркетолог и редактор..."
- Правила: креативный режим (temperature: 0.7, searchRagFirst: true, generateIfNoRag: true)
- RAG таблицы: Инструкции платформ, Стиль компании, Примеры контента
- Интерфейс: отдельная страница /content-editor
- Каналы: только web (для редакторов)

---

## 🖥️ Интерфейсы агентов

### Агент поддержки — интерфейс чата

**Расположение**: Встроен в основной чат (HomeView)

**Особенности**:
- Автоматическая активация при получении сообщения от пользователя
- Показ статуса генерации ответа
- Возможность отключения AI для конкретного сообщения
- История диалога с контекстом

**Права доступа**:
- Доступен всем пользователям
- Автоматически отвечает на сообщения

---

### Агент-редактор — интерфейс редактора

**Расположение**: Отдельная страница `/content-editor`

**Особенности**:
- Поле для ввода запроса на создание контента
- Выбор типа контента (пост ВК, статья блога, email и т.д.)
- Выбор платформы (ВКонтакте, Telegram, Instagram и т.д.)
- Показ процесса генерации
- Редактирование сгенерированного контента
- Сохранение готового контента
- История созданного контента

**Права доступа**:
- Только для пользователей с ролью Editor
- Требуется авторизация

**Функционал интерфейса**:
1. **Форма запроса**:
   - Текстовое поле для описания задачи
   - Выбор типа контента (выпадающий список)
   - Выбор платформы (чекбоксы или выпадающий список)
   - Дополнительные параметры (тон, длина, ключевые слова)

2. **Процесс генерации**:
   - Индикатор загрузки
   - Показ найденных инструкций
   - Показ процесса генерации

3. **Результат**:
   - Готовый контент в редактируемом поле
   - Кнопка "Сохранить"
   - Кнопка "Перегенерировать"
   - Кнопка "Экспортировать" (копировать, скачать)

4. **История**:
   - Список созданного контента
   - Фильтры по типу, платформе, дате
   - Возможность редактирования и удаления

---

## 📚 База знаний для агентов

### Структура базы знаний

**Для агента поддержки**:
- Таблица "FAQ" — часто задаваемые вопросы
- Таблица "Документация" — описание функций продукта
- Таблица "База знаний для клиентов" — расширенная информация

**Для агента-редактора**:
- Таблица "Инструкции платформ" — правила размещения контента
- Таблица "Стиль компании" — tone of voice, запрещенные слова
- Таблица "Примеры контента" — референсы для разных типов контента
- Таблица "Ключевые слова" — семантическое ядро, хэштеги
- Таблица "CTA блоки" — призывы к действию

### Как агенты используют базу знаний

1. **RAG поиск**:
   - Пользователь задает вопрос/запрос
   - Агент выполняет векторный поиск в своих RAG таблицах
   - Находит релевантную информацию

2. **Контекст для генерации**:
   - Найденная информация передается в LLM как контекст
   - LLM генерирует ответ/контент на основе контекста
   - Системный промпт направляет, как использовать контекст

3. **Фильтрация по роли**:
   - Агент поддержки ищет только в FAQ и документации
   - Агент-редактор ищет только в инструкциях и примерах
   - Изоляция данных между агентами

---

## 🔄 Процесс работы агентов

### Агент поддержки — процесс ответа

1. **Получение сообщения**:
   - Пользователь отправляет сообщение в чат
   - Система определяет, что нужно использовать агента поддержки

2. **RAG поиск**:
   - Агент ищет ответ в своих RAG таблицах (FAQ, документация)
   - Использует векторный поиск для семантического поиска

3. **Генерация ответа**:
   - Если найден ответ в базе знаний → использует его
   - Если не найден → в строгом режиме предлагает связаться с оператором
   - Генерирует ответ с учетом системного промпта и правил

4. **Отправка ответа**:
   - Ответ отправляется пользователю в чат
   - Сохраняется в истории диалога

---

### Агент-редактор — процесс создания контента

1. **Получение запроса**:
   - Редактор открывает интерфейс `/content-editor`
   - Вводит запрос: "Создай пост для ВКонтакте о новой функции"
   - Выбирает тип контента и платформу

2. **RAG поиск инструкций**:
   - Агент ищет инструкции для выбранной платформы
   - Ищет стиль компании
   - Ищет примеры похожего контента
   - Ищет релевантные ключевые слова

3. **Генерация контента**:
   - Агент генерирует контент на основе:
     - Системного промпта (роль редактора)
     - Найденных инструкций платформы
     - Стиля компании
     - Примеров контента
     - Ключевых слов

4. **Результат**:
   - Готовый контент показывается в интерфейсе
   - Редактор может редактировать контент
   - Сохранить или экспортировать

---

## 🎯 Преимущества архитектуры

### 1. Специализация
- Каждый агент решает свою задачу оптимально
- Не нужно жертвовать качеством для универсальности

### 2. Гибкость
- Легко создавать новых агентов для новых задач
- Можно настраивать каждого агента независимо

### 3. Изоляция
- Агенты не мешают друг другу
- Можно тестировать и обновлять агентов независимо

### 4. Масштабируемость
- Легко добавлять новых агентов
- Каждый агент использует одну модель, нет перегрузки

### 5. Контроль
- Четкое разделение ответственности
- Легко отслеживать, какой агент что делает

---

## 📊 Сравнение с единым агентом

| Характеристика | Единый агент | Множественные агенты |
|----------------|--------------|----------------------|
| **Специализация** | Универсальный, но менее точный | Специализированный, более точный |
| **Настройка** | Один набор настроек для всех задач | Отдельные настройки для каждой задачи |
| **База знаний** | Все таблицы для всех задач | Изолированные таблицы для каждой задачи |
| **Интерфейс** | Один интерфейс | Отдельные интерфейсы для каждой задачи |
| **Гибкость** | Сложно адаптировать под разные задачи | Легко создавать новых агентов |
| **Производительность** | Одна модель для всех | Одна модель, но разные промпты |

---

## 🚀 Следующие шаги

1. **Создание таблицы `ai_agents`** в базе данных
2. **Создание сервиса для управления агентами**
3. **Модификация AI Assistant для работы с несколькими агентами**
4. **Создание интерфейса для агента-редактора**
5. **Настройка агента поддержки (уже существует, нужно адаптировать)**
6. **Создание базы знаний для агента-редактора**
7. **Тестирование работы обоих агентов**

---

**© 2024-2026 Тарабанов Александр Викторович. Все права защищены.**

**Последнее обновление**: Январь 2026
