Иногда готовых узлов не хватает: нужно заглянуть в вашу CRM, посчитать стоимость заказа, проверить остаток на складе или связаться с 1С. Для этого подключается свой скрипт на Python — небольшая программа, написанная руками или ИИ-агентом. Скрипт может стать шагом прямо в разговоре, а может заменить целые части приложения: канал связи, поставщика ИИ, подготовку документов для базы знаний.
Как это выглядит
Скрипты лежат обычными файлами, разложенными по папкам ботов. Их можно править прямо в интерфейсе, во встроенном редакторе, или на сервере в файловой системе — как удобнее. Файлы принадлежат вам, вынести их на другой сервер так же просто, как и сценарий.
Кроме папок отдельных ботов есть одна общая папка — для скриптов, которые относятся ко всему приложению сразу: свой поставщик ИИ, обработка документов для баз знаний, канал, общий для нескольких ботов.
Куда можно подключить скрипт
Мест подключения десять. Часть из них относится к конкретному боту, часть — ко всему приложению целиком.
- Узел «Скрипт» — свой шаг прямо в разговоре: расчёт, запрос в CRM, проверка остатка;
- Обработка входящего сообщения — текст от клиента проходит через скрипт раньше, чем его увидит сценарий: убрать личные данные, пометить контакт, определить тему;
- Разбор вебхука — нестандартное сообщение от внешней системы скрипт превращает в понятные данные для сценария;
- Свой поставщик ИИ — скрипт сам отвечает на запросы к модели;
- Свой поставщик чисел для поиска — то же самое для превращения текста в наборы чисел (векторов), по которым ищет база знаний;
- Подготовка документа базы знаний — перед разбивкой на фрагменты текст документа можно почистить или переписать;
- Уточнение поиска по базе знаний — после поиска скрипт может поменять порядок найденных фрагментов или отбросить лишние;
- Отправка в своём канале — сообщения уходят клиентам через ваш SMS-шлюз, почту, WhatsApp или внутреннюю систему компании;
- Приём из своего канала — ответы и сообщения из этой системы так же попадают в разговор;
- Задача по расписанию — скрипт запускается сам в заданные дни и часы: ночная сводка, выгрузка, напоминание клиентам.
Свой канал связи
Если готовых каналов — Telegram, публичной страницы чата и виджета — не хватает, канал можно сделать скриптом. Один файл описывает и отправку, и приём: например, сообщения уходят клиентам через ваш SMS-шлюз, а их ответы возвращаются в тот же разговор.
Для приёма у такого канала есть отдельный скрытый адрес: внешняя система вызывает его, а скрипт превращает её данные в обычные сообщения бота. Адрес защищён секретом, и если секрет попал не туда, его перевыпускают — старый адрес сразу перестаёт работать.
Свой поставщик ИИ
Кроме сервисов, совместимых с OpenAI, поставщиком можно сделать скрипт на Python. Он получает запрос целиком — какая модель, какое задание, какие сообщения, — и возвращает готовый ответ; при желании сообщает и о расходе токенов. Так подключается модель, которая живёт внутри вашей сети и не умеет разговаривать на общем языке сервисов ИИ. Тем же способом задаётся поставщик для превращения текста в числа в базах знаний.
Если скрипт не справился, в дело вступает обычная запасная модель, а неудача остаётся в журнале запусков — ничего не обрывается и не пропадает молча.
Подготовка документов и поиска
В работу базы знаний тоже можно вмешаться — в двух местах. Перед разбивкой документа на фрагменты текст можно почистить или переписать: пригодится, когда выгрузка приходит с лишней разметкой или мусором. А после поиска — уточнить порядок найденных фрагментов: скрипт может поменять их местами или отбросить лишнее, но не может добавить то, чего в документах нет.
Обмен данными
На вход скрипт получает сведения о боте, клиенте, переменных разговора и текущем сообщении — набор зависит от места, куда он подключён. На выход возвращает ответ клиенту, изменения переменных, следующий узел или признак ошибки. Всё это — в формате JSON, то есть в виде обычного текста с подписанными полями.
Результатом считается последний цельный JSON в выводе, поэтому отладочные строки перед ним не мешают, а пустой вывод — законное «делать ничего не нужно». Если скрипт завершился с ошибкой или вернул не то, разговор спокойно идёт по ветке ошибки, а не обрывается.
Секреты и окружение
Пароли и ключи, которые нужны скрипту, задаются в настройках бота и подставляются ему автоматически. В интерфейсе и в отчётах они никогда не показываются — ни целиком, ни частями. По задумке скрипт работает в чистом окружении: ни настройки сервера, ни ключи самого приложения ему не видны. Если конкретному скрипту нужна серверная переменная, её имя перечисляют в настройках скрипта — только перечисленное он и получит.
Ограничения
- Ограничение по времени. По умолчанию скрипту даётся 60 секунд, для долгих задач лимит можно поднять — до 10 минут. Зависший скрипт останавливается вместе со всеми запущенными им процессами, разговор не застревает навсегда;
- Ограничение объёма вывода. Слишком длинный результат обрезается, чтобы бот отвечал осмысленно; крупные данные скрипт складывает в свою рабочую папку;
- Ограничение числа одновременных запусков. На одного бота выполняется не больше трёх скриптов сразу, на всём сервере — четыре; остальные задания ждут своей очереди. Это защищает сервер от перегрузки, когда клиентов много;
- Аварийный выключатель. Если что-то пошло не так, запуски скриптов отключаются одной настройкой — она вступает в силу сразу, без перезапуска.
Рабочая папка
У каждого скрипта есть своя рабочая папка — постоянное место на диске, где он хранит всё нужное ему самому: промежуточные файлы, отметки о том, что уже обработано, подготовленные выгрузки. Папка переживает и запуски, и перезапуски приложения, поэтому следующий запуск продолжает с того места, где остановился предыдущий.
Дополнительные библиотеки
Если скриптам нужны библиотеки, которых нет в обычной поставке Python, их список кладут в файл scripts-requirements.txt в корне папки настроек. Приложение само собирает для них отдельное окружение и обновляет его, когда список меняется, — вручную устанавливать ничего не нужно.
Панель запуска и настройки
Любой скрипт можно прогнать прямо в разделе «Скрипты», с подготовленными данными: видно, что скрипт вернул, какие были ошибки и сколько заняла работа. Удобно отлаживать по частям, не встраивая скрипт в сценарий и не трогая бота целиком.
Рядом — настройки скрипта: лимит времени, список разрешённых серверных переменных и собственные переменные. Значения-секреты показываются скрыто, и случайно стереть их нельзя.
Журнал запусков
У каждого вызова — в разговоре ли, по расписанию или при обработке входящих — остаётся отдельная строка: что было на входе, что вернулось, сколько заняло и чем закончилось. Журнал фильтруется по состоянию и месту подключения, а новые запуски появляются в нём сразу, без обновления страницы. Если у конкретного клиента что-то пошло не так, по журналу видно, с какими данными скрипт работал и что вернул.
Состояние
Скрипты опираются на окружение Python на сервере, поэтому в разделе «Состояние» есть отдельный блок: найден ли Python, готово ли окружение с библиотеками, включены ли запуски, сколько их было за последние сутки и сколько из них с ошибкой. Если что-то сломалось, приложение не делает вид, что всё в порядке, а прямо показывает, что именно не работает.
Как подключить скрипт к разговору — в разделе Узлы сценария. Как настроить модели — в разделе Модели и промпты, документы базы знаний — в разделе База знаний, а как завести самого бота — в разделе Боты.