Руководство контрибьютора

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

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

Настоящее руководство описывает функции роли контрибьютор: подключение внешней платформы (RAGFlow / RAGu BASE), регистрация и публикация приложений — чат-ассистентов, баз знаний и агентов, управление доступом к ним. Базовые функции портала (диалоги, файлы, профиль) описаны в «Руководстве пользователя», установка и первичная настройка — в «Инструкции по установке», функции администратора — в «Руководстве администратора».

1. Роль и область доступа

Роль contributor назначается учётной записи администратором в сервере ключей (Keycloak), realm ragu. После назначения достаточно перезайти на портал (или дождаться обновления сессии).

Роль открывает дополнительную вкладку «Ассистенты» в окне «Настройки» (меню пользователя → «Настройки»):

Роль Назначение Вкладки в «Настройках»
user Обычный пользователь портала «Профиль», «Пароли»
contributor Публикация собственных приложений, управление подключениями к внешней платформе + «Ассистенты»

Роль проверяется и на стороне интерфейса (видимость вкладки), и на стороне API (запросы без роли отклоняются с кодом 403).

2. Вкладка «Ассистенты»

Вкладка предназначена для подключения внешней платформы (RAGFlow / RAGu BASE) и регистрации её объектов — чат-ассистентов, баз знаний и агентов — в качестве приложений портала. Содержит две подвкладки: «Подключения» и «Доступ».

Предварительное условие: API-ключ внешней платформы

Для подключения сервера потребуется API-ключ учётной записи во внешней платформе. Получение ключа выполняется до начала настройки в RAGu MAX:

  1. Войдите в веб-интерфейс внешней платформы (RAGFlow / RAGu BASE).
  2. Откройте Профиль → пункт меню «API».
  3. В карточке «RAGu API» (на примере RAGu BASE) скопируйте адрес API Server — это значение поля «URL» подключения (п. 2.1) — и получите/скопируйте API KEY — это значение поля «Токен пользователя».

API-ключ во внешней платформе

API-ключ во внешней платформе

2.1. Подключения к серверу

Аватар пользователя -> Настройки -> Ассистенты -> Подключения -> Добавить подключение

Подключения к серверу

Подключения к серверу

Раздел «Подключения» хранит учётные привязки (credential bindings) к серверам внешней платформы. API-токен сохраняется через Credential Broker и не отображается после сохранения.

Добавление подключения:

  1. Нажмите «Добавить подключение».

  2. Заполните поля:

    Поле Описание
    URL Адрес сервера внешней платформы (например, https://ragflow.example.com)
    ID экземпляра Логическое имя сервера — на него ссылаются приложения (например, rf_default)
    Токен пользователя API-ключ учётной записи во внешней платформе

  3. Подтвердите — подключение появится в таблице.

В таблице подключений отображаются URL, Имя сервера и Статус:

Статус Значение
Активен Подключение проверено и работает
Недействителен Токен отклонён сервером — обновите API-ключ
Отозван Токен отозван во внешней платформе
Ожидает обновления Требуется повторная проверка

Действия со строкой подключения: «Проверить» (валидация токена запросом к серверу), «Изменить» (URL, имя сервера, новый API-ключ — поле ключа оставьте пустым, чтобы сохранить текущий), «Удалить».

2.2. Регистрация приложений

Аватар пользователя -> Настройки -> Ассистенты -> Подключения -> Добавить приложение

Регистрация приложений

Регистрация приложений

Раздел «Регистрация приложений» связывает объект внешней платформы с приложением портала. Зарегистрированные приложения появляются в каталоге «Приложения» и становятся доступны для @-упоминаний и маршрутизации.

Добавление приложения:

  1. Нажмите «Добавить приложение».

  2. Заполните поля:

    Поле Описание
    Тип Чат — диалоговый ассистент; Поиск — база знаний; Агент — исполняющий агент. Тип Скилл зарезервирован для навыков платформы — они создаются администратором во вкладке «Инструменты → Навыки»
    Название приложения Отображаемое имя в каталоге
    ID ассистента Идентификатор объекта во внешней платформе (chat_id / dataset_id / agent_id)
    Имя сервера Подключение из п. 2.1, через которое выполняются вызовы
    Описание Краткое назначение — показывается в каталоге и учитывается при маршрутизации
    Тег Короткий тег для упоминания (@тег); приводится к допустимому виду автоматически
    Видимость Публичный — доступен всем пользователям; Ограниченный — только группам с доступом (п. 2.5)
    Маршрутизация по запросу Участвует ли приложение в автоматическом выборе ассистента по смыслу запроса

  3. Подтвердите — приложение появится в таблице с владельцем «вы».

Действия со строкой приложения:

Действие Результат
Изменить Правка типа, названия, описания, тега, видимости и маршрутизации
Переменные Только для типа Агент — настройка входных переменных (п. 2.3)
Опубликовать / Снять Публикация версии приложения (п. 2.4)
Удалить Снятие регистрации приложения с портала
Тумблер MCP Публикация приложения как MCP-инструмента (п. 2.4)

2.3. Переменные агента

Аватар пользователя -> Настройки -> Ассистенты -> Подключения -> Переменные (в строке приложения типа Агент)

Переменные агента

Переменные агента

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

  1. Нажмите «Найти переменные» — система запросит DSL агента во внешней платформе и заполнит списки:
    • Begin-переменные — входные параметры Begin-узла агента, заполняются при запуске;
    • Переменные разговора — параметры узлов UserFillUp, запрашиваемые у пользователя в ходе диалога.
  2. Проверьте переключатель «Потоковая передача». Если у агента есть переменные разговора, рекомендуется отключить потоковую передачу для корректной обработки mid-conversation запросов (об этом выводится предупреждение).
  3. Нажмите «Сохранить».

2.4. Публикация и MCP

Аватар пользователя -> Настройки -> Ассистенты -> Подключения -> Опубликовать / тумблер MCP (в строке приложения)

Публикация приложения и тумблер MCP

Публикация приложения и тумблер MCP

Публикация фиксирует версию приложения: в диалоге «Опубликовать» укажите «ID замороженной версии агента» (frozen version id из внешней платформы) и при необходимости «Метку версии». Опубликованное приложение помечается в колонке «Опубликовано» и доступно пользователям в соответствии с видимостью. Кнопка «Снять» отзывает публикацию.

Тумблер MCP (доступен только для опубликованных приложений) переводит приложение в режим инструмента: оно исключается из маршрутизации по запросу и становится доступно модели как навык/инструмент. Повторное переключение возвращает приложение в маршрутизацию.

Совет

Наиболее явным кандидатом использования ассистента в режиме инструмента является база знаний. В этом случае LLM может корректировать формулировки пользователя при вызове поиска по базе данных и использовать несколько попыток поиска необходимой информации

2.5. Доступ по группам

Аватар пользователя -> Настройки -> Ассистенты -> Доступ -> Управление группами (в строке приложения)

Доступ к приложению по группам

Доступ к приложению по группам

Подвкладка «Доступ» показывает приложения с видимостью Ограниченный:

  1. Нажмите «Управление группами» в строке приложения.
  2. В диалоге выберите группу Keycloak и нажмите «Предоставить» — пользователи группы увидят приложение в каталоге и смогут его использовать.
  3. Отзыв доступа выполняется кнопкой удаления гранта в том же диалоге.

Диалог управления групповым доступом

Диалог управления групповым доступом
Уведомление

Список групп загружается из Keycloak. Если список пуст — проверьте конфигурацию Keycloak Admin API (см. «Инструкцию по установке»).