Сценарии

Сценарий (workflow) — схема из связанных узлов, по которой платформа обрабатывает обращение пользователя: принять файл, распознать текст, проверить его по правилам и собрать документ. Сценарии живут в разделе Настройки пространства → Сценарии (/settings/preferences/workflows), а вы подключаете их к ассистенту: пользователь пишет в обычный чат, а под ответом отрабатывает ваша схема. Сценарий даёт повторяемость: одинаковый вход всегда проходит одни и те же шаги. Взамен схему нужно собрать явно: то, что не нарисовано узлами, сценарий не сделает.

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

• уровень доступа Workflow-сценарии → Просмотр для чтения, Редактирование для сборки и отладки, Публикация для выпуска версии, копий и удаления;
• включённая функция сценариев в рабочем пространстве: без неё пункт меню скрыт;
• ассистент, к которому вы привяжете готовый сценарий;
• шаблон .docx организации, если сценарий собирает документы по шаблону.

Когда выбирать сценарий, а когда агента

Сценарий подходит регламентному процессу, у которого известен порядок шагов и цена ошибки высока: подготовка протокола, проверка комплекта документов, расчёт по фиксированным правилам. Агент подходит разовой задаче, сформулированной словами, когда порядок действий заранее неизвестен и его выбирает языковая модель (LLM).

Сценарий и агент не исключают друг друга. Узел Агент внутри сценария отдаёт модели ровно один шаг с ограниченным набором инструментов, лимитом шагов и таймаутом — свободное решение остаётся там, где оно уместно, а остальной маршрут остаётся жёстким.

Режим обработки вы выбираете в настройках ассистента: Внутри платформы (модель и поиск по знаниям) или Сценарий (весь ответ строит выбранная схема). Подробности режима — в главе Ассистенты.

Как пройти путь от черновика до рабочей версии

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

Чтобы создать сценарий:

1. Откройте Настройки пространства → Сценарии.
2. Нажмите Создать сценарий для пустой схемы или Из шаблона, чтобы скопировать опубликованный глобальный шаблон в своё пространство.
3. Задайте название сценария в шапке редактора.
4. Соберите схему из узлов палитры и соедините их связями.

Третий путь — перенос готовой схемы из другого рабочего пространства. В редакторе исходного сценария выберите Экспортировать в буфер обмена, а в списке целевого пространства нажмите Импортировать и вставьте пакет. Платформа создаёт черновик и просит проверить привязки к ресурсам: базы знаний, действия и подключения чужого пространства в пакет не попадают.

Платформа сохраняет черновик автоматически: индикатор сохранения стоит рядом с названием. Отмените или повторите последние изменения кнопками в шапке, Ctrl+Z, Ctrl+Y или Ctrl+Shift+Z. Историю правок редактор хранит в открытой вкладке и теряет при её закрытии.

Кнопка Опубликовать открывает окно «Публикация сценария» с необязательным полем Описание выпуска. Рядом с кнопкой стоит бейдж версии — Черновик до первой публикации, дальше номер вида v3, — а наведение на бейдж раскрывает состояние публикации.

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

Важно. Ассистент подхватывает последнюю опубликованную версию автоматически, отдельного действия «применить» нет.

Кнопка История изменений открывает панель История версий: список опубликованных снимков с описанием выпуска, числом изменений и составом. У каждой версии есть Просмотр, а в меню строки — Экспортировать и Восстановить как новую версию. Откат требует заполнить поле Причина отката: платформа не переписывает историю, а создаёт из выбранного снимка новую опубликованную версию и переключает сценарий на неё.

Пункт Сбросить черновик в меню «⋯» работает иначе: платформа не создаёт новую версию, а возвращает черновик к содержимому активной опубликованной версии. В том же меню лежат Свойства (название и описание сценария), Дублировать, Экспортировать в буфер обмена, Журнал событий сценария и Архивировать. Архивный сценарий доступен только для чтения, пока его не восстановят.

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

Какие узлы есть в палитре

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

Отдельного слова заслуживают узлы, которые дают сценарию точность.

• Источники документов объявляет именованные слоты входных файлов — например, «протокол» и «приложение» — и раскладывает вложения чата по слотам правилами по имени файла, а не по порядку отправки. Для каждого слота узел извлекает текст.
• Грундированное извлечение достаёт объявленные поля из текста и подтверждает каждое значение дословной цитатой источника. Неподтверждённое значение узел помечает на ручную проверку, а не подставляет молча.
• Генерация под ограничениями порождает текст под заданные длину, стиль и запреты и посегментно отмечает, что подтверждено источником, а что — редакторский синтез.
• Проверка по чек-листу прогоняет данные прогона по пунктам чек-листа и выдаёт одну строку отчёта на каждый пункт, поэтому пропущенных проверок в отчёте не бывает.
• Гейт финализации читает состав собранного документа и выдаёт вердикт качества — успех, частичный результат или отказ — со списком полей на ручную проверку.
• Справочник отдаёт данные утверждённого справочника инсталляции платформы без поиска по базе знаний и без модели, фиксируя версию справочника в записи прогона.
• Маршрутизатор проверяет одно явно заданное значение по правилам сверху вниз и уводит прогон в первую подходящую ветку, а при отсутствии совпадений — в ветку Иначе.

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

Узел Код (JavaScript) выполняет ваш скрипт в изолированной песочнице и доступен только при отдельном уровне доступа: администратор может закрыть его на всю инсталляцию платформы.

Как добавлять и перемещать узлы на холсте

Узел на холст вы ставите из палитры или из контекстного меню. Левая кнопка мыши занята рамкой выделения, поэтому холст перемещают средней кнопкой и модификаторами.

В рамку выделения попадают задетые узлы и связи, у которых внутри рамки оба конца. Перетаскивание любого выбранного узла двигает всю группу вместе со связями.

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

Как собрать готовый документ внутри сценария

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

Связка «продюсер — потребитель» разделяет ответственность: узел Сгенерировать HTML отвечает за содержание и оформление, узлы HTML → PDF и HTML → PNG — только за формат файла. Размер страницы, ориентацию и поля задаёт сама вёрстка, а переключатель Страница по контенту подгоняет габарит под фактический размер содержимого — так делают обложки, этикетки и чеки.

Сборка .docx идёт по шаблону, который вы загружаете в узел Типизированный шаблон. Платформа находит в шаблоне плейсхолдеры и предлагает слот на каждую переменную, а вы указываете источник значения: константу, ссылку на результат предыдущего узла или ручной ввод. Если между сборкой и рендером стоит Форма в чате, платформа накладывает правки человека поверх собранных значений.

Примечание. Узлы HTML → PDF и HTML → PNG работают, пока в инсталляции платформы подключён движок рендера; без него узел завершается предупреждением, а не ошибкой.

Как отладить сценарий по шагам

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

1. Нажмите Отладка в шапке редактора.
2. Если у сценария несколько точек входа, выберите канал в окне «Слушать вызов»: чат или вебхук.
3. Отправьте тестовое обращение в выбранный канал.
4. Нажимайте Шаг, чтобы исполнить ровно один узел, или До конца, чтобы докатить прогон до завершения либо следующей паузы.
5. Завершите сессию кнопкой Завершить — черновик сценария при этом не меняется.

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

Двойной клик по узлу открывает инспектор шага. Слева — вкладка Переменные с деревом значений прогона: вход сценария, данные канала, тело вебхука, глобальные переменные. По центру — вкладка Параметры самого узла. Справа — вкладка Выход с живым результатом в виде таблицы или JSON.

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

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

Важно. Закреплённые значения действуют только в отладке: на опубликованные версии и живые прогоны они не влияют.

Прогоны отладки не попадают в историю запусков сценария — история остаётся чистой и показывает только реальную работу. Историю запусков вы открываете на вкладке Запуски правой панели редактора.

Как запустить сценарий и что видит пользователь

У сценария три точки входа, и выбор точки входа определяет способ запуска.

Узел Webhook сам владеет адресом: поле URL вебхука в параметрах узла показывает готовую ссылку вида https://<ваш-домен>/api/public/workflows/triggers/<slug> и копирует её кнопкой Скопировать. В поле Авторизация выберите Bearer personal token — тогда вызывающая система передаёт персональный токен доступа в заголовке Authorization — либо Без авторизации. Персональный токен вы выпускаете в разделе Профиль → Безопасность.

Поле Режим ответа решает, что получит вызывающая система:

• Асинхронный — платформа отвечает сразу, подтверждая приём вызова, а прогон идёт в фоне;
• Синхронный — соединение держится до завершения прогона, и ответ формирует узел Ответ на вебхук с нужным кодом, заголовками и телом.

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

Встроенного планировщика у сценариев нет. Регулярный запуск вы настраиваете на стороне внешней системы, которая вызывает вебхук сценария по своему расписанию.

Пользователь чата видит прогон карточкой прогресса под своим сообщением: линия шагов, счётчик пройденных шагов и статус каждого узла. Клик по шагу раскрывает его результат во вкладках Кратко, Таблица и JSON — те же данные, что видит автор в отладке, но с закрытыми секретами.

Пока прогон активен или ждёт ответа в форме, поле ввода в чате заблокировано. Подробное описание карточки — в главе Чаты.

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

Почему в настройках пространства нет пункта «Сценарии»

Пункт скрыт, если у вашей роли нет уровня Workflow-сценарии → Просмотр или функция сценариев выключена для пространства. Проверьте:

• уровень доступа в разделе Настройки пространства → Роли, вкладка Права доступа;
• включена ли функция сценариев — это настраивает администратор платформы.

Ассистент не видит нужный сценарий в списке

В списке ассистента видны только сценарии с опубликованной версией, и один сценарий занимает одного ассистента. Проверьте:

• у сценария есть хотя бы одна опубликованная версия, а не только черновик;
• сценарий не занят другим ассистентом — занятая строка помечена его именем;
• сценарий не переведён в архив.

Кнопка «Опубликовать» неактивна

Публикацию блокируют либо права, либо проверки. Проверьте:

• уровень доступа Workflow-сценарии → Публикация у вашей роли;
• вкладку Проверка в правой панели: блокирующие ошибки нужно исправить;
• не открыт ли системный шаблон — платформа обновляет его вместе с релизом, а править можно только копию.

Сценарий не удаляется

Платформа отвечает «Нельзя удалить сценарий, пока есть активные запуски». Дождитесь завершения прогонов или остановите их, а затем повторите удаление. Удаление требует уровня доступа Workflow-сценарии → Публикация.

Кнопка «Отладка» недоступна

Отладка захватывает вызов и потому требует точки входа, которую можно вызвать: узла Старт или узла Webhook. Проверьте:

• в схеме есть стартовый узел одного из этих двух типов;
• у вашей роли уровень доступа Workflow-сценарии → Редактирование или выше;
• сценарий не в архиве и не открыт в режиме просмотра.

Импортированный сценарий не работает

Импорт создаёт черновик и не переносит ресурсы чужого пространства. Проверьте:

• ссылки на базы знаний, действия и подключения в узлах импортированной схемы;
• сценарий опубликован после проверки — импорт сам версию не публикует.

Что дальше

• Ассистенты — подключить готовый сценарий к ассистенту и выбрать режим обработки.
• Чаты — как выглядит прогон сценария, форма проверки и карточка документа со стороны пользователя.
• Базы знаний — подготовить источники для узла Поиск по знаниям.
• Роли и права доступа — выдать команде уровни доступа к сценариям.
• Рабочие пространства — где лежит раздел Сценарии среди остальных настроек пространства.