Интеграции, навыки и инструменты

Группа Интеграции и API собирает четыре раздела уровня инсталляции: пакеты интеграций, навыки платформы, инструменты MCP и страницу «Документация API». Группа открывается по пути Администрирование → Интеграции и API и видна только пользователям с глобальной ролью admin. Каталог пополняете вы: рабочие пространства берут из него готовые возможности, но сами ничего в каталог не добавляют. Программный доступ снаружи — персональные токены и вебхук-триггеры — настраивается отдельно и описан в главе Публичный API, токены и вебхуки.

Что вам понадобится

глобальная роль admin: без неё все четыре раздела возвращают отказ в доступе;
право integrations:manage в рабочем пространстве — чтобы устанавливать пакеты из каталога в это пространство;
право integrations:mcp:manage — чтобы управлять инструментами MCP;
архив пакета в формате .zip — если планируете импорт готовой интеграции;
активная языковая модель (LLM) — если планируете собирать черновик пакета в LLM-конвейере.

Раздел «Интеграции»: четыре плитки счётчиков сверху, вкладка «Каталог» с карточками «Vendor MCP», «Интеграции» и «Типы подключений» — **Раздел «Интеграции»: счётчики каталога и карточки источников**. Каталог интеграций инсталляции. Счётчики в шапке показывают, сколько объектов каждого типа зарегистрировано.

Чем отличаются навык, интеграция и инструмент MCP

Три сущности группы решают разные задачи и не заменяют друг друга. Навык меняет то, как агент рассуждает; интеграция добавляет платформе готовые операции; инструмент MCP даёт доступ к внешней системе по сетевому протоколу. Общее у них одно: администратор регистрирует объект на уровне инсталляции, а рабочее пространство подключает его к себе отдельным действием.

Сущность	Что это	Где регистрируется	Кто исполняет
Навык	Инструкция, которая подмешивается ответу агента	Интеграции и API → Навыки	Языковая модель в режиме Агент
Интеграция	Версионируемый пакет операций, типов подключений и вложенных навыков	Интеграции и API → Интеграции	Платформа при вызове операции
Инструмент MCP	Отдельный инструмент внешнего MCP-сервера	Интеграции и API → Инструменты MCP	Внешний сервер по протоколу MCP

Разделить их помогает вопрос о результате. Нужно повторяемое поведение в свободной переписке — это навык. Нужен вызов чужого API с фиксированным контрактом, секретами и версионированием — это интеграция. Нужны живые данные внешней системы, которая уже отдаёт их по MCP, — это инструмент MCP. Пользовательская сторона навыков описана в главе Навыки и конструктор навыков.

Примечание. В интерфейсе раздела Интеграции навык называется английским словом Skill — это тот же объект, что и навык в остальном интерфейсе платформы.

Что показывает раздел «Интеграции»

Раздел Интеграции (/settings/administration/integrations/catalog) — реестр пакетов инсталляции; страница называется «Integrations, Skills и MCP». Четыре плитки в шапке показывают счётчики: Интеграции, Skills, «Типы подключений», «Vendor MCP». Ниже идут три вкладки: Каталог со всем зарегистрированным содержимым, «Студия интеграций» с ручным редактором манифеста и LLM-конвейер со сборкой черновика по описанию.

Вкладка Каталог состоит из четырёх карточек.

Карточка	Что показывает
«Import / Export Integrations»	Загрузка архива интеграции в инсталляцию
«Vendor MCP»	MCP-серверы, синхронизированные из поставки: версия, уровень доверия, транспорт, версия протокола, статус и базовый адрес
Интеграции	Пакеты интеграций: версия, уровень доверия, источник, число операций и вложенных навыков
«Типы подключений»	Контракты подключений, по которым рабочее пространство хранит адреса и секреты

Карточка каждой интеграции даёт две кнопки: Экспорт выгружает пакет архивом, «Загрузить в форму» открывает манифест в студии для правки. Пакеты из поставки платформы приходят с источником local и путём к исходной папке; пакеты, опубликованные из студии, — с источником upload.

Как пополнить каталог интеграций

Каталог пополняется тремя способами: синхронизацией пакетов из поставки, импортом архива и публикацией манифеста из студии. Первые два способа переносят готовое, третий создаёт новое.

Синхронизировать пакеты из поставки

Синхронизация перечитывает пакеты, которые лежат в файловой системе инсталляции, и регистрирует их версии в каталоге. Запускайте её после обновления платформы и после ручной подкладки пакета на диск.

Откройте Администрирование → Интеграции и API → Интеграции.
Нажмите «Синхронизировать локальные integration packages» — платформа обойдёт пакеты интеграций и навыков.
Нажмите «Синхронизировать Vendor MCP» — платформа обновит реестр MCP-серверов поставки.

После каждой операции появляется уведомление с числом обработанных пакетов и числом ошибок. Счётчики в шапке и карточки вкладки Каталог обновляются сразу.

Импортировать и выгрузить архив

Архив интеграции содержит манифест и описание релиза, но не содержит секретов и подключений рабочих пространств: после импорта в инсталляции остаётся зарегистрировать подключение заново.

На вкладке Каталог в карточке «Import / Export Integrations» выберите файл в поле «Архив интеграции».
Нажмите «Импортировать архив».

Платформа принимает .zip с файлами integration.json и release.json размером до 10 МБ. Обратная операция — кнопка Экспорт в карточке интеграции: браузер скачивает архив с именем вида <идентификатор>-<версия>.zip.

Опубликовать пакет из студии

Вкладка «Студия интеграций» содержит две подвкладки — «Integration Package» и Skill. Верхний блок обеих подвкладок заполняется одинаково: ID, Версия, Название, Категория, Описание, Автор, «URL автора», «Email автора» и Иконка. Поле Видимость принимает значения private, workspace, public. Поле «Trust level» со значениями trusted и untrusted есть только на подвкладке «Integration Package».

Дальше подвкладки расходятся. «Integration Package» описывает пакет операций полями Permissions JSON, Compatibility JSON, Connection Types JSON, Capabilities JSON, Operations JSON, Bundled Skills JSON, Events JSON, Templates JSON, Executor Bindings JSON и Metadata JSON. Skill описывает навык полем Instruction с текстом инструкции и полями Permissions JSON, Compatibility JSON, Trigger Hints JSON, Allowed Capabilities JSON, Input Schema JSON, Output Schema JSON, Examples JSON, Tests JSON и Metadata JSON.

Кнопка «Опубликовать интеграцию» на подвкладке «Integration Package» и кнопка «Опубликовать skill» на подвкладке Skill проверяют JSON и создают новую версию пакета. Некорректный JSON платформа отклоняет до отправки и называет поле в уведомлении. Кнопка «Очистить форму» сбрасывает черновик.

Собрать черновик в LLM-конвейере

Вкладка LLM-конвейер превращает описание чужого API в черновик манифеста: вы задаёте промпт и источники, языковая модель собирает структуру, а вы правите её вручную. Черновик не попадает в каталог сам — публикацию подтверждает человек.

Выберите «Тип артефакта»: Plugin или Skill.
Выберите Модель из списка доступных языковых моделей.
Заполните «Промпт для агента-сборщика» и, если нужно, поле «Вставка описания API или требований»; спецификацию можно приложить файлом в поле Файлы.
Нажмите «Собрать draft».

Готовый черновик появляется в списке Черновики со статусом. Откройте его и правьте на вкладке Структура по полям или на вкладке «Raw JSON» целиком. Блок «Тестовый прогон» запускает проверку без побочных эффектов: укажите ключ операции, конфигурацию и секреты подключения, затем нажмите «Проверить draft» — результат придёт в блок «Последняя валидация». Дальше идут три кнопки в порядке применения: «Сохранить правки», Согласовать, Опубликовать.

Вкладка «LLM-конвейер»: слева форма с полями «Тип артефакта», «Модель» и «Промпт для агента-сборщика», справа список черновиков со статусами — **Вкладка «LLM-конвейер»: форма сборки артефакта и список черновиков**. Сборка черновика пакета по описанию API. Публикация в каталог всегда подтверждается вручную.

Какие навыки показывает раздел «Навыки»

Раздел Навыки (/settings/administration/integrations/skills) — витрина системных навыков, которые поставляются вместе с платформой. Навыки показаны карточками с названием, описанием и версией; изменить или удалить их нельзя, они обновляются вместе с платформой. Навыки, созданные участниками в рабочих пространствах, в этот список не попадают — они живут в разделе Настройки → Рабочее пространство → Навыки.

Карточка навыка несёт один или два бейджа.

Бейдж	Значение
`System`	Навык из поставки платформы
`Admin`	Служебный конструктор пакетов для административного чата, не предназначенный конечным участникам

По умолчанию карточка подписана «Только просмотр»: содержимое навыка закрыто. Если в инсталляции включён режим отладки, в шапке появляется бейдж «Режим отладки», а на карточках — кнопка «Заглянуть внутрь», которая открывает манифест навыка: подсказки срабатывания, разрешённые возможности и инструкцию SKILL.md. Режим отладки включается переменной окружения UNICA_SKILLS_INSPECT_ENABLED и предназначен для проверки поставки, а не для повседневной работы.

Примечание. Гейт режима отладки работает и на сервере: при выключенном режиме запрос содержимого системного навыка возвращает отказ, даже если обратиться к нему напрямую.

Раздел «Навыки»: карточка-пояснение «Что такое навык» и сетка карточек системных навыков с бейджами System и Admin — **Раздел «Навыки»: карточки системных навыков платформы**. Каталог системных навыков инсталляции. Бейдж `Admin` отмечает служебные конструкторы, закрытые для конечных участников.

Что делает раздел «Инструменты MCP»

Раздел Инструменты MCP (/settings/administration/integrations/mcp-tools) — обзорная витрина MCP-серверов. Витрина показывает, какие внешние источники данных доступны платформе, к какой категории относятся, как быстро обновляют данные и сколько инструментов приносит каждый сервер. Четыре плитки сверху дают сводку: «MCP-серверов в каталоге», «Подключено сейчас», «Пилотные подключения», «Средний SLA обновления».

Сузить витрину помогают поиск по названию, провайдеру и описанию, список Категория (Госданные, Финансы, Логистика, Коммерция, Операции, Коммуникации) и список Срез со значениями «Весь каталог», «Только подключенные», «Только российские».

Карточка сервера показывает провайдера, статус, набор возможностей, интервал обновления данных и число инструментов. У серверов со статусом Подключен есть переключатель Активен; переключатель доступен участникам с правом integrations:mcp:manage и помечает сервер в текущей сессии браузера, не изменяя настроек инсталляции.

Фактический реестр MCP-серверов, с которым работает платформа, лежит в карточке «Vendor MCP» раздела Интеграции и пополняется кнопкой «Синхронизировать Vendor MCP». Серверы поставки работают по транспорту streamable_http и по версии протокола, указанной в манифесте.

Параметр инструмента	Значения	Что задаёт
Уровень доступа	`read`, `write`, `admin`	Насколько инструмент вмешивается в чужую систему
Подтверждение	`never`, `ask`, `always`	Спрашивать ли согласие перед вызовом
Доступность агенту	включено, выключено	Видит ли инструмент агент в чате
Статус установки	`draft`, `ready`, `error`, `disabled`	Готовность подключения рабочего пространства

Важно. Уровень доступа admin вместе с подтверждением always означает, что вызов инструмента меняет данные во внешней системе и требует согласия участника.

Раздел «Инструменты MCP»: четыре плитки сводки, строка фильтров и сетка карточек MCP-серверов со статусами «Подключен» и «Доступен» — **Раздел «Инструменты MCP»: сводка и карточки серверов**. Витрина MCP-серверов. Число инструментов и интервал обновления помогают оценить нагрузку до подключения.

Что показывает раздел «Документация API»

Раздел Документация API (/settings/administration/integrations/api-docs) — встроенная справка по программному доступу, доступная администраторам внутри инсталляции. Полный состав и подробное описание методов публичного API на текущий момент предоставляются по запросу: обратитесь к вашей команде сопровождения Уники с задачей интеграции — вы получите актуальную спецификацию нужных методов. Персональные токены и вебхук-триггеры сценариев (workflow) описаны в главе Публичный API, токены и вебхуки.

Частые вопросы

Почему в меню нет группы «Интеграции и API»

Группа открыта только глобальной роли admin. Проверьте:

у вашей учётной записи стоит роль Админ в разделе Администрирование → Доступ → Пользователи;
вы вошли под учётной записью с этой ролью, а не под тестовой;
прямой переход по адресу /settings/administration/integrations/catalog возвращает экран отказа — значит, роли действительно нет.

Почему каталог интеграций пуст

Пакеты из поставки не зарегистрированы в базе: платформа читает их с диска только по команде. Проверьте:

нажата ли кнопка «Синхронизировать локальные integration packages» после развёртывания или обновления;
для реестра MCP-серверов нажата ли отдельная кнопка «Синхронизировать Vendor MCP»;
в уведомлении о синхронизации нет строки с числом ошибок.

Почему импорт архива не проходит

Архив не соответствует формату или превышает лимит. Проверьте:

внутри .zip лежат файлы integration.json и release.json;
размер файла не больше 10 МБ;
пакет с таким идентификатором и версией ещё не опубликован.

Почему на карточке навыка нет кнопки «Заглянуть внутрь»

Режим отладки выключен, и содержимое системных навыков закрыто. Это штатное состояние рабочей инсталляции: включать переменную UNICA_SKILLS_INSPECT_ENABLED нужно только для разбора поставки.

Почему навык из рабочего пространства не появился в разделе «Навыки»

Раздел показывает только навыки из поставки платформы. Навыки рабочего пространства остаются в самом пространстве и настраиваются в разделе Настройки → Рабочее пространство → Навыки.

Что дальше

Публичный API, токены и вебхуки — выпустить токен и запустить сценарий снаружи.
Навыки и конструктор навыков — как участники создают и привязывают навыки.
Интеграция ассистента без кода — отдать обработку сообщений внешнему сервису без публикации пакета.
Раздел администрирования — карта остальных групп настроек инсталляции.