Инструменты агента

Настройка инструментов агента

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

Выбор способа подключения

Выберите один режим для всего приложения:

• «Конструктор» — приложение содержит один или несколько HTTP-инструментов с отдельными URL и параметрами;
• «MCP-сервер» — приложение подключает готовый MCP endpoint, а список его инструментов загружается с сервера.

После смены режима нажмите «Сохранить». Установленные проекты получают только текущий сохранённый режим.

MCP-сервер

В MCP-режиме укажите URL сервера и, если требуется, имя и значение заголовка авторизации. Сохранённый секрет повторно не показывается: его можно заменить новым значением или отметить удаление сохранённого значения, а затем сохранить настройки.

Конструктор HTTP-инструментов

Нажмите «Добавить». В форме инструмента сначала заполните представление для пользователя.

На вкладке «Русский» укажите название и краткое описание. В необязательном поле «Описание ответа» поясните, какие данные вернёт инструмент после выполнения.

На вкладке English заполните английское название и английское описание. Если описание ответа заполнено на русском, добавьте его английскую версию в поле «Описание ответа».

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

Затем задайте технические параметры:

• системное имя, например find_customer;
• URL обработчика с http или https;
• по умолчанию агент использует русское краткое описание. Включите «Техническое описание для агента» и заполните описание для агента, только если модели нужны дополнительные условия вызова, которых не должен видеть пользователь;

• в списке параметров задайте имя, тип string, number или boolean, понятное описание и обязательность каждого аргумента.

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

Для каждого нового аргумента нажмите «Добавить параметр». У каждого параметра есть кнопка удаления.

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

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

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

При вызове обработчик получает JSON такого вида:

{
  "event_id": "019d0000-0000-7000-8000-000000000001",
  "event_type": "tool_call",
  "timestamp": "2026-07-30T12:00:00.000Z",
  "app_id": "app-id",
  "installation_id": "installation-id",
  "project_id": "project-id",
  "agent_id": "agent-id",
  "dialog_id": "dialog-id",
  "lead_id": "lead-id",
  "tool_name": "find_customer",
  "tool_instance_id": "tool-instance-id",
  "arguments": {
    "customer_id": "123"
  },
  "configuration": {
    "account_id": "store-1"
  },
  "private_data": {
    "access_token": "write-only-token"
  }
}

agent_id и dialog_id передаются всегда, а lead_id — только когда диалог связан с лидом. tool_instance_id отличает независимо настроенные экземпляры одного инструмента. configuration содержит обычные настройки экземпляра, private_data — расшифрованные закрытые данные для выполнения вызова; не записывайте их в открытые логи и ответы. Для обычного ненастраиваемого инструмента оба объекта пустые.

Вызов подписывается единым секретом всех webhook приложения. Проверьте свежесть X-Webhook-Timestamp, соответствие X-Webhook-Event-Id полю event_id и X-Webhook-Signature по тем же правилам, что и для публичных webhook приложения. Не выполняйте действие до успешной проверки подписи.

Используйте event_id как ключ идемпотентности: автоматический или ручной повтор может отправить то же действие снова.

Режимы выполнения и повторы

В режиме выполнения выберите:

• «Мгновенное выполнение» — агент ждёт один HTTP-ответ и получает его тело как результат инструмента; автоматических повторов нет;
• «Ожидание результата» — запрос ставится в очередь, агент приостанавливает этот шаг и продолжает после успешного результата;
• «Фоновая операция» — запрос ставится в очередь, но агент не ждёт и не использует ответ для продолжения текущего шага.

Одна попытка ждёт ответ 10, 30, 60 или не более 120 секунд — значение выбирается в поле «Таймаут HTTP-попытки». Для двух асинхронных режимов выберите окно повторов:

• 5 минут — 5 попыток: сразу, через 15 секунд, 1, 3 и 5 минут;
• 3 часа — 8 попыток: сразу, через 1, 5, 15, 30 минут, 1, 2 и 3 часа;
• 1 день — 12 попыток: сразу, через 1, 5, 15, 30 минут, 1, 2, 4, 8, 12, 18 и 24 часа.

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

Что включить

Настраиваемый инструмент доступен только в режиме «Конструктор». Перед его сохранением укажите основной 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

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

import { createSenlerBridgeClient } from "@senler/ui/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 не даёт агенту вызвать экземпляр без закрытых данных. В кабинете такой экземпляр получает статус «Требуется повторное подключение приватных данных».

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