Сценарии

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

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

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

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

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

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

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

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

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

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

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

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

Четвёртый путь — попросить агента в любом чате с включённым режимом «Агент»: он создаст черновик из опубликованного шаблона после карточки согласования или соберёт граф по вашему описанию, объяснит существующий сценарий и назовёт замечания компилятора, из-за которых сценарий не публикуется. Публикацию, откат, архив и импорт агент не выполняет. Как формулировать просьбы — в главе «Агент». Если агент правит черновик, который у вас открыт в редакторе, редактор покажет конфликт ревизий — перезагрузите черновик, прежде чем продолжать.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Масштаб доступен от 10% до 200% и сохраняется при повторном открытии сценария. Кнопка «Вписать» подбирает масштаб для обзора графа в пределах этого диапазона.

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

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

Поля с инструкцией для модели показывают счётчик длины под текстом. Инструкции полей узла принимают до 20 000 символов, промпт узла Сгенерировать HTML — до 50 000. Текст сверх предела не обрезается: счётчик становится красным и подсказывает, сколько символов лишние.

Откуда узел берёт языковую модель

Модель узел берёт из источника, который вы выбираете полем Источник модели у узлов Шаг ИИ и Агент и полем Источник модели ответа у узла Поиск по знаниям на вкладке RAG, в блоке Формирование ответа. Набор значений у всех трёх узлов одинаковый, а умолчание разное.

Поле выбора модели в инспекторе появляется только при значении Модель узла: у Шаг ИИ и Агент это поле Модель, у Поиск по знаниям — Языковая модель ответа.

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

Карточка узла Агент на холсте показывает источник в строке Модель / backend подписями По умолчанию, Основная и Fast-path; при значении Модель узла она показывает имя модели или Не выбрана.

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

Сколько времени узел ждёт ответ модели

Сколько времени узел ждёт ответ модели, задаёт поле Таймаут LLM-вызова, сек на вкладке Параметры в инспекторе узла. Допустимое значение — от 1 до 3600 секунд; у Шаг ИИ поле по умолчанию пусто, а редактор показывает подсказку о бюджете раздела Настройки агента.

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

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

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

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

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

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

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

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

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

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

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

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

Двойной клик по узлу открывает инспектор шага.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сценарий не импортируется

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

• поле Источник модели в узлах Шаг ИИ и Агент исходного сценария: выберите Модель узла или Основная модель агента и заново выполните Экспортировать в буфер обмена;
• поле Источник модели ответа на вкладке RAG узла Поиск по знаниям: оно задаёт источник тем же списком значений;
• версию платформы принимающей инсталляции: обновление до версии исходной инсталляции снимает ограничение, его выполняет администратор.

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

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

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

Что дальше

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