ReAct-агент

Интеллектуальная система консультирования для e-commerce

Краткое описание решения

ReAct-агент - это интеллектуальная диалоговая система на базе технологии Reasoning + Acting, предназначенная для автоматизации клиентского сервиса в электронной коммерции. Система сочетает возможности обработки естественного языка с доступом к бизнес-данным в реальном времени.

Ответы из кеша60-80%

Время отклика (кеш)<0.1 сек

Экономия на ИИдо 95%

Покрытие запросов99.9%

Инструменты агента14+ базовых + динамические skills

Уровни защиты5 (rate limit → moderation → cache → usage limits → AI)

Позиционирование на рынке

Проблематика существующих решений

Обычные системы с ИИ работают по одному из двух крайних сценариев. Либо вы получаете ответ, который никак не относится к вашему вопросу - шаблонную отписку, не решающую проблему, - и при этом не можете беспрепятственно связаться с живым оператором. Либо наоборот: при малейшем отклонении от скрипта происходит мгновенный перевод на оператора, что полностью обесценивает присутствие бота.

Архитектурное решение

ReAct-агент реализует принципиально иной подход:

Детерминированные ответы - система формирует ответы исключительно на основе верифицированных данных из базы знаний. При отсутствии релевантной информации - корректная эскалация вместо генерации недостоверного контента.
Интеллектуальная маршрутизация - автоматическое определение необходимости подключения оператора на основе анализа контекста диалога, до возникновения фрустрации у клиента.
Максимизация автономного разрешения - полное использование доступного инструментария перед эскалацией: поиск в множественных источниках, уточнение деталей, комбинирование данных.

Техническая архитектура

Агентная модель

В отличие от конвейерных систем RAG, где информация предоставляется модели в фиксированном формате, ReAct-агент функционирует как автономный исследователь. Система самостоятельно определяет необходимые данные и инициирует их получение.

Пример:

При необходимости агент запрашивает полную статью из базы знаний, а не ограничивается предоставленными фрагментами - возможность, недоступная в стандартных RAG-системах.

Модульная система инструментов

Архитектура поддерживает неограниченное количество инструментов (tools). Агент автономно выбирает оптимальный инструмент в зависимости от задачи.

Базовые инструменты (14+):

YouTube и медиа - скачивание видео/аудио, транскрипция речи (99 языков), добавление субтитров с переводом, выполнение FFmpeg команд с GPU-кодированием (NVENC).

Vision и анализ - анализ изображений через LLM Vision, извлечение ключевых кадров и анализ видео.

Поиск и интернет - поиск в интернете, изображений, видео, новостей через Brave Search API, загрузка и парсинг веб-страниц.

Облако и публикация - управление файлами в Nextcloud, публикация длинных статей в Telegraph, отправка файлов пользователю.

Интерактивность - возможность задать уточняющий вопрос, динамическая загрузка специализированных инструкций.

Динамические Skills:

video.md - сжатие видео с GPU-кодированием
pdf.md - создание PDF из HTML/Markdown
documents.md - работа с документами через Docling API (парсинг PDF, Word, PowerPoint)
environment.md - описание возможностей sandbox-контейнера

Цикл обработки запроса (ReAct)

Технология ReAct (Reasoning + Acting) обеспечивает итеративный процесс обработки:

Reasoning (Рассуждение) - анализ запроса и формирование гипотезы о необходимых действиях
Acting (Действие) - выполнение выбранного инструмента с соответствующими параметрами
Observation (Наблюдение) - анализ результата и принятие решения о следующем шаге: продолжение поиска или формирование финального ответа

Система безопасности

Каждый запрос проходит через пятиуровневый периметр защиты:

Rate LimitingЗащита от спама, 10 запросов/мин

Content ModerationИИ-анализ намерений, блокировка abuse

Semantic CacheПоиск похожих запросов, порог 85%

Usage LimitsДневные лимиты, 100 сообщений/день

AI AgentПолноценная обработка

Система кеширования

Трёхуровневая архитектура кеширования обеспечивает экономию до 95% затрат на inference:

Verified Cache - вручную верифицированные ответы, hit rate 20-30%.

Semantic Cache - автоматический по семантической близости, hit rate 60-80%.

Exact Match Cache - точное совпадение запроса, hit rate 5-10%.

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

Семантический поиск

Система использует векторные представления (embeddings) размерностью 1024 для поиска по смыслу:

Векторизация запроса - преобразование текста в числовой вектор, «семантический отпечаток».

Поиск ближайших соседей - идентификация 30 наиболее близких по косинусному расстоянию документов.

Reranking - переранжирование и отбор 8 наиболее релевантных результатов.

Генерация ответа - формирование ответа на основе отобранного контекста.

RAG (Retrieval-Augmented Generation)

Проблема

Стандартный RAG использует только dense embeddings, что приводит к потере точности при поиске по ключевым словам.

Решение

Hybrid Search - комбинация dense и sparse векторов.

Архитектура: Qdrant - векторная база данных, Dense embeddings для семантического поиска, Sparse embeddings для keyword-поиска, Docling API - интеллектуальный парсинг документов (PDF, Word, PPT).

Создание per-project коллекций через команду /project
Автоматический или LLM-based chunking документов
Поиск с учетом как смысла, так и точных терминов
Интеграция с Nextcloud для загрузки документов

Пример:

Запрос "API ключи" найдет как документы с точным упоминанием "API keys", так и семантически похожие с "токены доступа" или "credentials".

Scheduled Research (Отложенные исследования)

Проблема

Пользователю нужен ответ на вопрос, но информация еще недоступна (анонс продукта, выход закона, результаты события).

Решение

Unified Agent - специализированный агент для отложенного поиска.

Создание напоминаний через команду /remind "вопрос"
Три режима: one-time (разовый), until_found (до нахождения), recurring (повторяющийся)
Автоматический ReAct-поиск в указанное время
Live UI с real-time обновлениями (SSE)
Контекст автоматически передается в основной агент

Пример:

Пользователь: /remind "Когда выйдет новая версия модели?" → Система предлагает режимы → Выбран "Еженедельно до нахождения" → Каждую неделю система автоматически ищет информацию → ✅ Найдено! Новая версия модели был анонсирован...

Vision-возможности

analyze_image - распознавание объектов и текста, описание содержимого, ответы на вопросы об изображении, поддержка скриншотов, фото, диаграмм.

analyze_video - извлечение кадров через равные интервалы, анализ каждого кадра через Vision LLM, составление summary содержимого, поиск конкретных моментов.

Пример:

"Найди в видео момент, где показывают график продаж" → агент извлекает кадры, анализирует, находит нужный таймкод.

Nextcloud интеграция

Проблема

Telegram ограничивает размер файлов (50 MB для ботов).

Решение

Автоматическое использование Nextcloud для больших файлов.

Per-user папки /GistiQ/user_{user_id}/
Автоматическая загрузка больших результатов
Создание share-ссылок
Команды: список файлов, загрузка, скачивание

Пример:

Дубляж 200 MB видео → автоматически загружается в Nextcloud → пользователь получает ссылку для скачивания.

Telegraph публикация

Проблема

Telegram сообщения ограничены 4096 символами.

Решение

Автоматическая публикация длинных ответов в Telegraph.

Публикация статей неограниченной длины
Форматирование Markdown → HTML
Встраивание изображений
Постоянные ссылки

Пример:

Агент создает подробное исследование на 10000 слов → публикует в Telegraph → отправляет ссылку.

Документы и парсинг

Docling API - интеллектуальный парсинг документов:

PDF с сохранением структуры (заголовки, списки, таблицы)
Microsoft Word (.docx)
PowerPoint (.pptx)
Извлечение текста и изображений
Распознавание макета документа

Применение:

Загрузить контракт → агент извлекает ключевые пункты → отвечает на вопросы по документу.

Middleware стек для надежности

Система использует 6 middleware для контроля качества:

Автоповтор запросов3 попытки при временных ошибках провайдера

Резервная модельПереключение на backup при полном отказе основной модели

Повтор инструментовАвтоматический retry при ошибке выполнения

Лимит вызовов моделиМаксимум 50, защита от бесконечных циклов

Лимит вызовов инструментовМаксимум 100, защита от избыточного использования

Очистка контекстаПри переполнении >100k токенов удаление промежуточных результатов

Результат: 99.5% uptime даже при нестабильности провайдеров API.

Производительность и экономика

Ответ из кеша0.05-0.1 сек

Простой вопрос1-2 сек

Вопрос с поиском2-5 сек

Комплексный запрос5-10 сек

RAG поиск1-3 сек

Vision анализ3-7 сек

Обработка документа5-15 сек

Стоимость обработки 1000 запросов: без кеширования ~$5.70, с 80% hit rate ~$1.14 (экономия 80%), с semantic + verified cache ~$0.30 (экономия 95%). Факторы экономии: Semantic cache - 60-80% hit rate, Verified cache - 20-30% hit rate, Exact match - 5-10% hit rate, Middleware context cleaning - снижение токенов на 40%.

Новые кейсы применения

Контент-студия - обработка видео для YouTube: скачивание, автоматическая транскрипция и перевод субтитров, сжатие с GPU-кодированием, публикация в Telegraph, загрузка в Nextcloud. Результат: полная автоматизация видео-конвейера.

Корпоративная база знаний - создание RAG-проекта через /project, загрузка документов (PDF, Word, PPT), Hybrid search для точного поиска, ответы со ссылками на источники. Результат: мгновенный доступ к корпоративным знаниям.

Исследовательская работа - Scheduled research для еженедельного мониторинга, Web search + парсинг статей, анализ изменений через историю, автоматические отчеты. Результат: система раннего обнаружения трендов.

Техническая поддержка - RAG по документации, Vision для анализа скриншотов ошибок, семантический кеш для частых вопросов, эскалация на оператора при необходимости. Результат: 80% запросов решаются автоматически.

Медиа-аналитика - скачивание видео через YouTube API, транскрипция содержимого, Vision-анализ ключевых кадров, суммаризация через LLM, публикация отчета в Telegraph. Результат: часы ручной работы → 5 минут автоматики.

Сравнение с альтернативами

Характеристика	Обычные чат-боты	GPT Assistants API	Наша система
Детерминизм	✗ Шаблоны	Может галлюцинировать	✓ RAG + verification
Кеширование	✗ Нет	✗ Нет	✓ 3-уровневое
Экономия на API	0%	0%	95%
Инструменты	✗ Жесткие	Ограниченные	✓ Неограниченные
Модульность	✗ Нет	✗ Нет	✓ Dynamic skills
Эскалация	Тупая	✗ Нет	✓ Интеллектуальная
Vision	✗ Нет	✓	✓
RAG Hybrid search	✗ Нет	✗ Dense only	✓ Dense + Sparse
Scheduled tasks	✗ Нет	✗ Нет	✓ Unified Agent
GPU acceleration	✗ Нет	✗ Нет	✓ NVENC + CUDA
Self-hosted	Иногда	✗ Нет	✓ Полностью

Технологический стек

Backend фреймворки - Telegram бот фреймворк с FSM, агентная платформа (ReAct, checkpointing), high-level агентный фреймворк, FastAPI для API сервисов (dubbing, TTS).

LLM и Embeddings - API доступа к моделям (современная языковая модель, специализированная модель, резервная модель), Dense embeddings для семантического поиска, Sparse embeddings для keyword-поиска, независимая модель для второго мнения.

Обработка медиа - Нейросетевое распознавание речи (99 языков), современная TTS-модель (10+ языков), FFmpeg с NVENC GPU-кодированием, yt-dlp API YouTube downloader, Docling API парсинг документов.

База данных - SQLite (проекты, задачи, новости), Qdrant векторная база (hybrid search), Redis опциональный кеш.

Интеграции - Nextcloud файловое хранилище, Telegraph публикация статей, Exa AI поиск по правовым базам, Brave Search веб-поиск, FireCrawl парсинг веб-страниц.

Изоляция и безопасность - gVisor kernel-level sandbox per-user, Docker Compose оркестрация сервисов, Docker Socket Proxy фильтрация Docker API, APScheduler 3.10+ планирование задач.

Статистика проекта

Код~25,000 строк Python

Файлов126

Модулей8 основных

Агентов3 (General Agent, Legal Assistant, Unified Agent)

Инструментов14+ базовых + динамические skills

Middleware6 уровней контроля

RAG: Hybrid search (Dense + Sparse embeddings), Per-project коллекции, Docling для парсинга. Scheduled Research: 3 режима (one-time, until_found, recurring), Live UI с SSE, автоматическая передача контекста. Медиа: YouTube downloader, нейросетевая транскрипция, современная TTS синтез, GPU NVENC кодирование.

Развитие проекта

Реализовано

ReAct агентная архитектура
3-уровневое кеширование (verified, semantic, exact)
5-уровневая система безопасности
6 middleware для надежности
RAG с hybrid search (Dense + Sparse embeddings)
Scheduled research с unified agent
Vision возможности (image, video)
Nextcloud интеграция
Telegraph публикация
Docling парсинг документов
GPU-ускорение (NVENC, CUDA)
Per-user изоляция через gVisor

В планах

Advanced semantic cache с fine-tuning на domain
Multi-modal RAG (изображения + текст)
Streaming ответов для длинных генераций
A/B тестирование промптов
Analytics dashboard для мониторинга
Voice interface для голосовых запросов

Применение (расширенное)

E-commerce поддержка - ответы на вопросы о товарах через RAG, Vision для анализа фото товаров, Scheduled research для мониторинга цен конкурентов, интеграция с CRM.

Образование и обучение - RAG по учебным материалам, Scheduled напоминания для заданий, Vision для проверки решений, Telegraph для публикации лекций.

Медиа и журналистика - YouTube-обработка видео, нейросетевая транскрипция интервью, Web search для fact-checking, Telegraph публикация статей.

Корпоративный сектор - база знаний на RAG, анализ документов через Docling, Scheduled research для мониторинга индустрии, Vision для анализа презентаций.

Юридические услуги - поиск по правовым базам РФ (5 источников), создание документов (9+ типов), анализ судебной практики, двухуровневая проверка (специализированная модель + независимая модель).

Техническая поддержка - RAG по документации, Vision для анализа скриншотов, Semantic cache для FAQ, эскалация при сложных вопросах.

Заключение

Детерминированность - ответы исключительно на основе верифицированных данных, отсутствие галлюцинаций благодаря RAG, прозрачность источников информации
Интеллектуальная эскалация - автоматическое определение необходимости оператора, максимальное использование инструментария перед эскалацией, контекстная передача оператору
Модульность - 14+ базовых инструментов + неограниченное количество skills, простое добавление новых возможностей, специализация через динамическую загрузку
Производительность - 60-80% ответов за доли секунды (cache), Hybrid search для максимальной точности, GPU-ускорение тяжелых операций (видео, transcription)
Безопасность - 5 уровней защиты, Per-user изоляция через gVisor контейнеры, Content moderation для блокировки abuse
Экономичность - до 95% экономии на inference благодаря кешированию, контроль токенов через middleware, оптимизация промптов
Отказоустойчивость - автоматическое восстановление при ошибках, резервные модели (fallback), 99.5% uptime
Масштабируемость - от одного до тысяч пользователей, готово к внедрению