Руководство пользователя

Программный комплекс «RAGu MAX» — корпоративная платформа оркестрации ИИ-агентов

Правообладатель: ООО «Ресетлаб» Версия ПО: 1.0.0

Настоящее руководство описывает работу с веб-интерфейсом ПО «RAGu MAX»: вход в систему, ведение диалогов с ИИ-ассистентами, работу с файлами и документами, каталог ассистентов и настройки профиля.

Уведомление

Снимки экрана выполнены в тестовом контуре. Состав доступных ассистентов, моделей и внешних провайдеров входа зависит от конфигурации, выполненной администратором при установке (см. «Инструкцию по установке»).

1. Вход в систему

Откройте в браузере адрес портала (выдаётся администратором, например http://ragu.local). При первом обращении выполняется перенаправление на страницу входа сервера ключей (Keycloak).

Введите имя пользователя и пароль, выданные администратором.
Нажмите «Войти».
Язык страницы входа переключается кнопкой выбора языка в правом верхнем углу (русский / английский).
Если администратором подключены внешние провайдеры идентификации, доступны кнопки VK ID и Яндекс для входа через корпоративные/внешние учётные записи.

После успешной аутентификации открывается главный экран портала.

2. Главный экран

Главный экран содержит:

Элемент	Назначение
Боковая панель (слева)	Кнопка «Новый диалог», кнопка «Поиск», список недавних диалогов, имя пользователя внизу
Панель режимов	Тумблер «Теги» (поиск по `@` только по тегам либо по названиям и описаниям), режимы «Диалог» / «План» / «Пуск», тумблер «Адаптивный» и кнопка `\\|>` (в режимах «План»/«Пуск»), выбор модели
Поле ввода сообщения	Текст запроса с поддержкой `@`-упоминаний
Кнопки ввода	Загрузить файл, добавить изображение, отправить сообщение

2.1. Режимы работы

Режим	Описание
Диалог	Ответы на вопросы: чтение файлов, поиск по базам знаний, анализ. Файлы не изменяются
План	Составление пошагового плана выполнения задачи. Система строит план и показывает его карточку для проверки и правки до запуска
Пуск	Режим внесения изменений в файлы и исполнения плана

Упрощённая схема выбора режима:

flowchart TD
    subgraph Диалог
    A -.->|Агенты|K(Многошаговая сессия)
    end
    U(Запрос пользователя) e1@--> R{Режим<br>}
    R e2@-->|Диалог| A(Ответ модели:<br>чтение, поиск, анализ)
    R e3@--> P(Составление плана)
    R e6@-->|Пуск| E{Сложный?}
    
    subgraph План
    P e4@-->|План| G(Карточка плана:<br>проверка / правка)
    G e5@-->|Согласовано| D(Пошаговое исполнение)
    end
    subgraph Пуск
    E e7@-->|Нет| H(Простая операция)
    E e8@-->|Да| D
    end
    R -.->|"@a ▷ @b (конвейер)"| D
    
   classDef animate stroke-dasharray: 9,5,stroke-dashoffset: 900,animation: dash 25s linear infinite;
    class e1,e2,e3,e4,e5,e6,e7,e8 animate

Режим «План» всегда показывает план перед исполнением — его можно отредактировать или принять; после принятия система сама переходит к исполнению.
Режим «Пуск» исполняет задачу сразу: простые задачи выполняются напрямую, для составных (или заданных конвейером |>, см. п. 4.3) строится пошаговый план.
Явная цепочка @a |> @b минует проверку плана в любом режиме — указанный порядок шагов сам является утверждением.

2.2. Адаптивное исполнение и контроль (HITL)

Рядом с переключателем режимов в режимах «План» и «Пуск» отображаются:

тумблер «Адаптивный» — включает адаптивную политику исполнения (микропланирование);
кнопка |> — вставка оператора конвейера (см. п. 4.3).

Адаптивное исполнение (микропланирование). В статическом режиме сбой шага останавливает выполнение. В адаптивном режиме система при ошибке шага или сигнале модели о необходимости пересмотра корректирует оставшиеся шаги плана и продолжает исполнение. В режиме «Пуск» адаптивность дополнительно включает автопланирование: длинные составные запросы классифицируются как многошаговые и для них автоматически строится план (короткие запросы исполняются напрямую).

Контроль со стороны пользователя (Human-in-the-Loop). Система привлекает пользователя в трёх точках:

Карточка плана — в режиме «План» план можно проверить и отредактировать до запуска;
Вопросы в ходе исполнения — если агенту требуется уточнение, выполнение приостанавливается, вопрос показывается в диалоге; после ответа исполнение продолжается;
Подтверждение правок файлов — изменения документов показываются в виде отличий (diff) и применяются только после утверждения пользователем.

2.3. Выбор модели

Раскрывающийся список справа от режимов позволяет выбрать языковую модель из числа настроенных администратором.

3. Боковая панель и меню пользователя

Боковая панель сворачивается и разворачивается кнопкой ☰ у левого края. В развёрнутом виде панель показывает раздел «Недавние» со списком последних диалогов — название формируется автоматически по первому сообщению.

Щелчок по имени пользователя внизу панели открывает меню:

Пункт	Назначение
Язык интерфейса	Переключение языка интерфейса (русский / английский)
Тема оформления	Переключение между светлой и тёмной темой
Настройки	Профиль и смена пароля (раздел 7)
Ассистенты	Каталог ассистентов (раздел 6)
Файлы	Репозиторий файлов (раздел 5)
Выйти	Завершение сеанса

Тёмная тема оформления:

3.1. Управление диалогами

У каждого диалога в списке есть контекстное меню (кнопка ⋯ при наведении):

Действие	Результат
Изменить имя	Переименование диалога (по умолчанию название формируется из первого сообщения)
Закрепить	Диалог переносится в раздел «Закреплённые» вверху списка; повторный выбор открепляет
Добавить в проект	Привязка диалога к одному или нескольким проектам
Удалить	Удаление диалога (с подтверждением)

Закреплённые диалоги отображаются отдельной группой над разделом «Недавние»:

3.2. Поиск

Кнопка «Поиск» на боковой панели открывает диалог поиска по диалогам и сообщениям.

4. Ведение диалога

4.1. Упоминания `@`

Ввод символа @ в поле сообщения открывает меню упоминаний — способ привязать к запросу ассистента, навык, файл, диалог или сообщение.

Категория	Что привязывается к запросу
Ассистенты	Конкретный ассистент (чат, база знаний или агент), которому адресуется запрос
Навыки	Навык — отдельная функция/инструмент, доступная модели
Файлы	Документ из репозитория файлов
Диалоги	Поиск по всем сообщениям пользователя
Сообщения	Конкретное сообщение (также доступно по синтаксису `@#N`, где `N` — номер сообщения)

Категория «Диалоги» работает как поиск по содержимому: в ней выбирается пункт «Все диалоги», после чего в сообщении дописывается текст поискового запроса. Система находит релевантные сообщения во всех диалогах пользователя и добавляет их в контекст ответа — так можно ссылаться на результаты прошлых обсуждений, не открывая старые диалоги.

При выборе категории «Ассистенты» отображается список доступных ассистентов:

Выбранное упоминание отображается в поле ввода в виде тега (например, @rl), после которого вводится текст запроса:

4.2. Отправка и ответ

Сообщение отправляется клавишей Enter или кнопкой отправки. Ответ формируется потоково; в ходе ответа отображаются вызовы инструментов (например, чтение файла read_file), что позволяет видеть, какие данные использует ассистент.

Под ответом доступны:

Ссылка на сообщение (@2, @3, …) — номер, по которому можно сослаться на ответ в следующих запросах через @#N;
Копирование текста ответа;
«Откатить» под своим сообщением — отмена последнего шага диалога.

4.3. Конвейер шагов `|>`

Оператор |> задаёт явную последовательность исполнения: каждый фрагмент между операторами — отдельный шаг, результат предыдущего шага передаётся следующему.

@sql_bot понедельные данные продаж |> динамика продаж @vega

В этом примере ассистент @sql_bot извлекает данные продаж за неделю, а результат передаётся следующему шагу — @vega, который строит график динамики продаж.

Особенности:

Оператор вставляется вручную или кнопкой |> на панели ввода (доступна в режимах «План» и «Пуск»);
Явная цепочка не требует проверки плана — система исполняет шаги в указанном порядке сразу;
Внутри каждого сегмента действует обычный текст запроса с @-упоминаниями ассистентов, навыков и файлов.

4.4. Навыки

Навык — самостоятельный инструмент, выполняемый в изолированной среде (отдельный микроконтейнер): входные данные передаются навыку, а результатом становится текст и/или файл-артефакт, который возвращается в диалог и сохраняется в репозитории файлов.

Навык вызывается через упоминание @ → «Навыки» либо назначается ассистенту администратором как доступный инструмент.

Пример — навык pptx (работа с презентациями PowerPoint):

В поле ввода: @ → «Навыки» → выбрать pptx;
Сформулировать задачу: «создай презентацию из 5 слайдов о результатах квартала» или передать файл и попросить «добавь титульный слайд»;
Навык исполняется в изолированном контуре (создание и правка .pptx, конвертация в PDF, проверка результата);
Готовый файл возвращается как артефакт — его можно скачать или открыть в репозитории файлов.

Набор доступных навыков зависит от того, что зарегистрировал администратор (каждый навык поставляется отдельным образом и описывается файлом инструкций SKILL.md, который читает модель при вызове).

4.5. Работа с агентом в режиме сессии

Агенты (тип «Агент» в каталоге) ведут собственную многошаговую беседу. Когда агент отвечает на запрос, интерфейс автоматически переходит в режим сессии: в поле ввода появляется зелёный тег с именем агента — например, @suliko ×.

Диалог с агентом @suliko в режиме сессии

Пока тег активен:

каждое следующее сообщение автоматически адресуется этому агенту — упоминание @ вводить не нужно;
агент сохраняет собственный контекст беседы (в примере @suliko помнит, о каких ресторанах шла речь, и продолжает диалог);
остальные сообщения диалога также видны, но отвечает именно агент сессии.

Как работать в сессии (на примере @suliko — агента бронирования столиков):

Введите запрос с упоминанием: @suliko где находятся ваши рестораны?;
Агент отвечает — под его ответом появляется кнопка «Продолжить сессию», а в поле ввода — зелёный тег @suliko;
Продолжайте диалог обычным текстом («забронируй столик на двоих на вечер») — сообщения автоматически уходят тому же агенту;
Чтобы выйти из сессии, нажмите × на зелёном теге — диалог вернётся в обычный режим.

Возврат в сессию. Если сессия была завершена или вы открыли диалог заново, вернуться к ней можно кнопкой «Продолжить сессию» под любым ответом этого агента — агент продолжит с того места, где остановились.

Уведомление

В режиме сессии не добавляйте @-упоминание того же агента вручную — иначе в сообщении окажется два тега, и система покажет карточку выбора «Можно вызвать только один ресурс за сообщение».

5. Работа с файлами

5.1. Загрузка файлов

Файл прикрепляется к диалогу кнопкой «Загрузить файлы» (стрелка вверх) в поле ввода либо через @-упоминание «Файлы». Загруженный документ отображается тегом в сообщении (@reglament.md) и одновременно открывается во встроенном редакторе.

Поддерживаемые форматы и ограничения:

Группа	Форматы
Текст и документы	`md`, `txt`, `qmd`, `pdf`, `docx`, `xlsx`, `pptx`, `csv`, `json`, `xml`, `html`
Изображения	`png`, `jpg`, `jpeg`, `gif`, `webp`
Архивы	`zip` (распаковывается, до 100 файлов)

Максимальный размер файла — 50 МБ.

Как обрабатываются документы (OCR). Офисные документы и PDF автоматически преобразуются в Markdown-копию, которая используется как рабочий текст при ответах (оригинал при этом сохраняется). Сканированные документы и страницы-изображения проходят распознавание текста OCR (русский и английский языки); формулы переводятся в LaTeX, таблицы сохраняют структуру, а найденные в документе иллюстрации извлекаются отдельными файлами и подключаются к Markdown-копии. Пока идёт обработка, файл имеет статус «обработка», по завершении — «загружен».

Изображения для модели (VLM). Кнопка с иконкой изображения прикрепляет картинки непосредственно к сообщению — они передаются модели с функцией зрения и анализируются как часть вопроса (скриншоты, схемы, фото документов). Ограничения: до 4 изображений на сообщение, не более 5 МБ каждое и 20 МБ суммарно. Прикреплённые изображения сохраняются вместе с сообщением и автоматически подключаются при ссылке на него через @#N.

5.2. Репозиторий файлов

Пункт меню «Файлы» открывает репозиторий всех файлов пользователя.

Элемент	Назначение
Загрузить	Загрузка файла с компьютера
Создать	Создание нового документа
Удалить	Удаление выбранных файлов
Привязать…	Привязка файла к проекту или чату
Добавить	Добавление файла в текущий контекст
Фильтр по проекту или чату	Отбор файлов по месту привязки
Строка поиска	Поиск по имени и содержимому; переключатель Regex включает поиск по регулярному выражению

В таблице отображаются: имя файла, теги, тип источника, объём в токенах, дата обновления, версия и статус обработки («загружен» — файл доступен для использования в диалогах).

Меню действий файла

Кнопка ⋯ в конце строки файла открывает меню операций:

Пункт	Действие
Открыть	Открыть файл в редакторе
Показать оригинал	Открыть исходный файл в исходном формате (для конвертированных документов)
Скачать	Скачать файл на компьютер
Показать версии	Список зафиксированных версий файла
Изменить метаданные	Имя, описание и теги файла
Переименовать	Быстрое переименование
Поделиться (копировать ссылку)	Ссылка на файл для другого пользователя
Назначить проекту	Привязка файла к проекту
Убрать из проекта	Снятие привязки к проекту
Отвязать от чата	Снятие привязки к диалогу
Удалить	Удаление файла

Метаданные и теги

Пункт «Изменить метаданные» открывает диалог с полями «Имя файла», «Описание» и «Теги»:

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

5.3. Редактор документов

Щелчок по тегу файла в диалоге открывает документ в панели редактора справа; щелчок по имени файла в репозитории открывает его в полноэкранном режиме (возврат — кнопка «Back to Chat»).

Элемент	Назначение
Документ / Код	Переключение между визуальным представлением и исходным текстом (Markdown)
Счётчик токенов	Объём документа в токенах (важно для контекста модели)
Сохранить	Сохранение правок
Снимок	Фиксация версии документа
История	История версий и правок
Экспорт	Выгрузка документа
Панель форматирования	Заголовки, списки, таблицы, полужирный/курсив, ссылки и др.

AI-обработка выделенного фрагмента

Когда файл открыт в панели редактора внутри диалога, выделение текста вызывает всплывающее меню форматирования с кнопкой «AI»:

Кнопка «AI» передаёт выделенный фрагмент в поле ввода как ссылку на фрагмент файла (@файл#L…-L…) — дальше остаётся дописать инструкцию («перепиши официальным стилем», «переведи», «сократи») и отправить. Так модель получает точный контекст без копирования текста вручную.

Правки, предложенные моделью

Когда ассистент вносит изменения в файл (режим «Пуск»), они не применяются сразу, а отображаются в редакторе как ожидающие правки: изменённый текст подсвечивается, над документом появляется панель «N ожидающих правок LLM».

Элемент	Действие
Плашка над правкой (`replace`, `L6–6`, `−15+15`)	Тип правки, диапазон строк и оценка изменения в токенах
▶ old	Показать исходный текст до правки
✓ (зелёная)	Принять правку
✓ (жёлтая)	Принять правку и оставить текст подсвеченным (`==текст==`) — например, чтобы обсудить его дальше
✗ (красная)	Отклонить правку — в документе останется исходный текст
‹ Назад / Вперёд ›	Переход между ожидающими правками
К правке	Прокрутка документа к правке
Принять все / Отклонить все	Массовое согласование

При нажатии «Сохранить» или «Снимок» с непринятыми правками система предупреждает, что все ожидающие правки будут приняты автоматически. Отклонённые правки из документа исключаются.

Сложные объекты: таблицы, диаграммы, графики

Редактор отображает сложные блоки документа в интерактивном виде:

Таблицы редактируются визуально — как в табличном редакторе: добавление и удаление строк и столбцов, правка ячеек (кнопки работы с таблицей — в панели форматирования).
Блоки mermaid отображаются готовой диаграммой. При наведении на блок доступны: копирование исходного кода, редактирование кода диаграммы в полноэкранном режиме с предпросмотром, удаление блока.
Блоки vega-lite отображаются построенным графиком. Кнопка ⚙ открывает диалог «Оформление графика» — ширина и высота, авторазмер, заголовок, подписи осей, сетка, позиция легенды и цветовая палитра с предпросмотром; по кнопке «Применить» изменения записываются обратно в код блока:

Когда документ открыт внутри диалога, у блоков mermaid и vega-lite дополнительно есть кнопка «Отправить ИИ» — она передаёт код блока в поле ввода вместе со ссылкой на его строки, чтобы модель могла скорректировать диаграмму или график по запросу.

История правок

Кнопка «История» открывает панель «История правок» со списком зафиксированных версий документа:

У версии с изменениями показывается счётчик правок (например, −1 +1) и встроенный просмотр отличий: удалённый текст зачёркивается, добавленный — подсвечивается; ссылка «Развернуть всё» показывает документ целиком;
«Восстановить» возвращает документ к выбранной версии;
«Удалить» удаляет версию (доступно только для последней);
новая версия создаётся кнопкой «Снимок»; кнопка «Сохранить» записывает правки без создания версии.

6. Каталог ассистентов

Пункт меню «Приложения» открывает каталог зарегистрированных в системе приложений, которы включает ассистентов внешней системы, внесенные контрибьютором и навыки (skills), зарегистрированные администратором.

Колонка	Назначение
Название	Имя приложения
Описание	Краткое назначение
Тег	Тег для упоминания в сообщениях (`@тег`)
Тип	`Чат` — диалоговое приложение; `БЗ` — база знаний; `Агент` — исполняющий агент
Закреплено	Закрепление ассистента (кнопка с канцелярской кнопкой) для быстрого доступа
Доступ	Область видимости («Публичный» — доступен всем)
Владелец	Учётная запись создателя

Заголовки колонок содержат поля поиска и фильтры для отбора по названию, типу, доступу и владельцу.

Закрепление и открепление ассистентов

Закрепление персональное — каждый пользователь сам определяет, какие ассистенты ему нужны. Кнопка с канцелярской кнопкой в колонке «Закреплено» переключает состояние:

Закреплённый ассистент доступен для вызова: он отображается в меню упоминаний @ и учитывается при планировании;
Откреплённый ассистент скрывается из меню упоминаний и исключается из кандидатов при построении плана в режиме «План» — система не будет предлагать его в качестве шага, даже если он подходит по смыслу.

Открепление удобно для сокращения списка упоминаний и повышения точности автопланирования: остаются только реально используемые ассистенты. Ассистент остаётся в каталоге — вернуть его можно повторным нажатием на кнопку закрепления.

7. Настройки профиля

Пункт меню «Настройки» открывает окно с двумя вкладками.

7.1. Вкладка «Профиль»

Настройки — Профиль

Аватар — загрузка изображения профиля;
Отображаемое имя — имя, показываемое в интерфейсе;
Email — адрес из учётной записи (не редактируется);
«Сохранить» — применение изменений.

7.2. Вкладка «Пароли»

Смена пароля: текущий пароль → новый пароль → подтверждение → «Изменить пароль».

8. Выход из системы

Для завершения сеанса выберите «Выйти» в меню пользователя. При повторном открытии портала потребуется вход по учётным данным.

Приложение А. Поддерживаемые элементы ввода

Синтаксис	Действие
`@`	Открытие меню упоминаний (ассистенты, навыки, файлы, диалоги, сообщения)
`@#N`	Ссылка на сообщение с номером `N` в текущем диалоге
`\|>`	Оператор конвейера — явная цепочка шагов (режимы «План»/«Пуск»)
Enter	Отправка сообщения

1. Вход в систему

2. Главный экран

2.1. Режимы работы

2.2. Адаптивное исполнение и контроль (HITL)

2.3. Выбор модели

3. Боковая панель и меню пользователя

3.1. Управление диалогами

3.2. Поиск

4. Ведение диалога

4.1. Упоминания @

4.2. Отправка и ответ

4.3. Конвейер шагов |>

4.4. Навыки

4.5. Работа с агентом в режиме сессии

5. Работа с файлами

5.1. Загрузка файлов

5.2. Репозиторий файлов

Меню действий файла

Метаданные и теги

5.3. Редактор документов

AI-обработка выделенного фрагмента

Правки, предложенные моделью

Сложные объекты: таблицы, диаграммы, графики

История правок

6. Каталог ассистентов

Закрепление и открепление ассистентов

7. Настройки профиля

7.1. Вкладка «Профиль»

7.2. Вкладка «Пароли»

8. Выход из системы

Приложение А. Поддерживаемые элементы ввода

4.1. Упоминания `@`

4.3. Конвейер шагов `|>`