Форма настройки инструмента

Покажите пользователю собственную форму при добавлении инструмента в агента.

Сначала добавьте HTTP-инструмент в конструкторе приложения.

Настройка инструмента при добавлении в агента

Что включить

Настраиваемый инструмент доступен только в режиме «Конструктор». Перед его сохранением укажите основной URL встроенной страницы: по этому адресу откроется форма добавления и редактирования экземпляра. Показывать саму главную страницу приложения в меню проекта необязательно. MCP-инструменты подключаются обычным переключателем и не используют этот конфигуратор.

• «Настройка при добавлении» открывает встроенную страницу перед первым добавлением;
• «Разрешить добавлять несколько раз» доступно только для настраиваемого инструмента и создаёт отдельный экземпляр при каждом добавлении;
• настраиваемость нельзя выключить, пока инструмент добавлен хотя бы одному агенту;
• множественное добавление нельзя выключить, пока у какого-либо агента остаётся больше одного экземпляра.

Для конфигуратора Senler открывает основной URL встроенной страницы. У участника команды приложения при включённом режиме разработчика используется developer URL. API добавляет к URL одноразовый launch_code, а кабинет — bootstrap-параметры версии 2: senler_mode=tool_configurator, senler_theme и senler_language. Полный контекст приходит через Bridge. Client Secret и access token Senler в iframe не отправляются.

Senler Bridge

Для обмена с кабинетом используйте пакет @senlerio/bridge. Он проверяет структуру сообщений, принимает данные только от указанного origin и не требует вручную реализовывать postMessage-протокол.

Bridge устанавливается отдельно и не требует React, Senler UI или подключения CSS:

npm install https://github.com/SenlerBot/senler-bridge/archive/refs/tags/v1.0.1.tar.gz

import { createSenlerBridgeClient } from "@senlerio/bridge";

const allowedParentOrigins = new Set([
  "https://senler.io",
  "https://aibot.local",
]);
const parentOrigin = new URL(document.referrer).origin;
if (!allowedParentOrigins.has(parentOrigin)) {
  throw new Error("Unknown Senler parent origin");
}

const bridge = createSenlerBridgeClient({ parentOrigin });
const context = await bridge.connect();

if (context.launch.type !== "tool_configurator") {
  throw new Error("Expected tool configurator launch");
}

Добавляйте в allowlist только реальные origin кабинета для вашего окружения. connect() сообщает о готовности и возвращает актуальный контекст. По умолчанию Bridge также задаёт lang, класс dark и color-scheme корневому элементу документа; приложение всё равно должно иметь стили для обеих тем. Для реакции на последующие изменения языка, темы или контекста подпишитесь на bridge.onContextChange(...).

В context.launch приходят app_id, project_id, installation_id, agent_id, инструмент, режим create или edit и сохранённый instance при редактировании. Эти данные помогают построить форму, но не являются токеном API. Авторизацию во внешнем сервисе приложение организует самостоятельно.

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

const unsubscribeSubmit = bridge.onToolConfiguratorSubmit(async () => ({
  title: "Основной магазин",
  configuration: {
    account_id: "store-1",
  },
  configured_parameters: [
    {
      name: "customer_id",
      type: "string",
      description: "Идентификатор клиента в основном магазине",
      required: true,
      allowed_values: [],
    },
  ],
  private_data_action: "replace",
  private_data: {
    access_token: "secret-token",
  },
  private_data_required: true,
}));

Если обработчик выбросит Error, кабинет покажет его сообщение и оставит окно открытым. При размонтировании страницы вызовите функции отписки и bridge.destroy().

Iframe конфигуратора разрешает скрипты, формы, модальные окна, загрузки и открытие внешних окон. Он также может запросить у браузера доступ к буферу обмена, полноэкранному режиму и микрофону; фактическое разрешение зависит от браузера и выбора пользователя. Доступ к камере кабинетом не выдаётся.

Что сохраняется

• title — понятное название экземпляра длиной до 160 символов;
• configuration — обычные JSON-настройки до 64 КБ; они возвращаются в instance при редактировании и передаются обработчику при вызове;
• configured_parameters — параметры, которые увидит модель у этого экземпляра. Имена и типы должны совпадать с параметрами исходного инструмента; allowed_values ограничивает допустимые значения, а пустой массив не вводит ограничение;
• private_data — закрытые JSON-данные до 64 КБ. Они хранятся зашифрованно, не возвращаются в instance или API и передаются только обработчику инструмента при вызове;
• private_data_action принимает preserve, replace или clear. При replace поле private_data обязательно; при редактировании используйте preserve, чтобы не затереть уже сохранённый секрет;
• private_data_required: true не даёт агенту вызвать экземпляр без закрытых данных. В кабинете такой экземпляр получает статус «Требуется повторное подключение приватных данных».

В установленном проекте нужные действия включаются отдельно в настройках каждого агента. Отключение инструментов у приложения делает их недоступными агентам, но не отключает встроенный пользовательский интерфейс плагина.