Custom actions виджета

customActions объявляют действия, которые выполняет ваш сайт: открыть заказ, показать тариф, запустить собственный сценарий или получить данные для ответа агента. По умолчанию действие выполняется через кнопку. Флаг returnsResult: true разрешает агенту вызвать обработчик как инструмент и получить его результат. Сначала реализуйте и защитите действие на стороне сайта, затем объявите его виджету.

Отдельной формы для customActions в кабинете нет: сайт передаёт их при SenlerWidget.init(...) или позже через SenlerWidget.registerAction(name, definition). Поэтому здесь приведён пример интеграции, а внешний вид кнопки посетителя показан в статье «Интерфейс виджета».

Обработчик выполняется в браузере на открытой странице. Наличие токена в localStorage не добавляет его к запросу автоматически: обработчик должен явно передать нужный заголовок; cookies зависят от адреса запроса и настройки credentials. Если агент должен обращаться к установленному MCP с пользовательским токеном через серверную интеграцию, используйте авторизацию пользователя сайта в MCP.

Выберите способ выполнения

• Кнопки с действиями: посетитель нажимает кнопку, сайт выполняет обработчик.
• Действия с результатом: агент вызывает обработчик как инструмент и получает JSON для ответа.

Опишите входные данные

Имя берётся из ключа объекта customActions. Оно должно начинаться с латинской буквы, быть не длиннее 120 символов и может содержать латинские буквы, цифры, _, ., : и -.

В одном контексте можно объявить до 20 действий. title ограничен 80 символами, description — 240 символами. Сам payloadSchema должен быть обычным объектом схемы. Корневое поле type можно опустить; если оно задано, поддерживается только "object". Глубина схемы — не более 8 уровней, сериализованный размер одной схемы — не более 1200 символов, а всех передаваемых описаний действий вместе — не более 6000 символов. В общий размер входят имена, заголовки, описания и схемы.

Поддерживается ограниченное подмножество JSON Schema: типы object, string, number, integer, boolean, array, null и поля properties, required, additionalProperties, items, enum, title, description, default, examples, minLength, maxLength, pattern, minimum, maximum, minItems, maxItems. Другие поля отклоняются при инициализации. Не передавайте секреты в schema, description или payload.

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

Чтобы агент добавлял кнопки, включите у него создание кнопок в ответах. Для действия с returnsResult: true это не требуется: оно доступно агенту в разговоре через виджет, когда сайт передал его описание. Переключатель «Управлять элементами сайта через виджет» относится к работе с элементами страницы и не включает или выключает ваши customActions.

Обновление действий при навигации

Регистрируйте действия страницы без пересоздания виджета:

const unregister = SenlerWidget.registerAction("openProduct", {
  description: "Открыть товар по ID",
  payloadSchema: {
    type: "object",
    properties: { productId: { type: "string" } },
    required: ["productId"],
  },
  handler: ({ payload }) => openProductAfterValidation(payload),
});
SenlerWidget.configure({ customActionsLanguage: "ru" });
// При уходе со страницы:
unregister();

openProductAfterValidation обозначает проверку прав и переход, реализованные вашим сайтом. Описания передаются агенту, а handler остаётся в браузере.

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

Чем custom action отличается от действий по элементам

Custom action объявляет собственную бизнес-операцию сайта и вызывает ваш handler. Действия по элементам (highlight, click, fill и другие) работают с размеченным DOM по data-ai-context-id. Не используйте custom action только ради подсветки обычной кнопки.

Что подключать дальше

Если действие должно не просто открыть страницу или изменить состояние сайта, а подготовить AI-правку конкретного поля с просмотром до применения, используйте inline-правки. Полный список runtime-параметров и событий находится в справочнике Public API.