Агенты на холсте
Компоненты визуального конструктора, переменные, тестовый запуск и отладка, шаблоны, автоматизации по расписанию и подтверждение действий в Telegram.
Агент в Semantix описывается как граф компонентов, связанных направленными переходами. Вы собираете его на холсте без кода: поиск, модель, условия, обработка, вывод. Эта статья описывает компоненты, переменные, запуск и отладку, а также как агент становится автоматизацией.
Создание агента
В разделе «Агент» нажмите «Создать агента». Два пути: «Создать из шаблонов», где готовые сценарии (например, отчёт по базе знаний или глубокое исследование) копируются в вашу организацию, и «Создать агента с нуля». После выбора открывается холст с компонентом «Начало»; остальные компоненты добавляются кнопкой «+» на узле.
Шаблон после копирования нужно проверить: ссылки на базы знаний и модели должны указывать на ресурсы вашей организации, а изменяющие инструменты должны быть выключены либо одобрены.
Компоненты
| Компонент | Что делает | Ключевые настройки |
|---|---|---|
| Начало (Begin) | Единственная точка входа. Режим «диалог» с приветствием или «задача» без диалога | Глобальные переменные: текст, абзац, список, число, флаг, файл; обязательные и необязательные |
| Поиск (Retrieval) | Извлекает фрагменты из баз знаний | Переменная запроса (по умолчанию sys.query), базы с одной моделью эмбеддинга, порог сходства, вес ключевых слов, число фрагментов, реранкер, текст при пустом результате |
| Агент (Agent) | Модель с системным промптом, инструментами и субагентами | Модель и параметры генерации, промпт, инструменты (в том числе «Поиск» и MCP), число раундов рассуждения, повторы при ошибке |
| Категоризация (Categorize) | Модель относит вход к одной из категорий | Категории с описанием и примерами; примеры важнее описания |
| Условие (Switch) | Ветвление по правилам без модели | Случаи с условиями: равно, содержит, больше, пусто и другие; связка И или ИЛИ |
| Сообщение (Message) | Выводит результат пользователю | Текст с подстановкой переменных; из нескольких вариантов выбирается случайный |
| Код (Code) | Выполняет Python или JavaScript | Входные переменные, функция main, возвращаемые переменные |
| Итерация (Iteration) | Разбивает текст по разделителю и выполняет вложенный сценарий для каждой части | Разделитель; внутренний узел IterationItem как вход вложенного сценария |
| Ожидание ответа (Await response) | Останавливает сценарий и запрашивает у пользователя данные формой | Поля формы, как в «Начале» |
Categorize полагается на модель и подходит для распознавания намерения пользователя. Switch работает по правилам и подходит для детерминированных проверок: статус документа, сумма больше порога, пустой результат поиска.
Для действий во внешних системах есть компоненты шлюза: узлы ожидания события, паузы и одобрения человеком, которые позволяют сценарию ждать часы и дни, переживая перезапуски.
Переменные
Стрелки на холсте задают только порядок выполнения, а данные передаются через переменные. Выход каждого компонента получает имя и доступен ниже по графу. В полях ввода нажмите (x) или введите /, чтобы выбрать переменную: sys.query (запрос пользователя), переменные из «Начала», выходы компонентов. В промпте «Агента» переменные указывают, какие данные модель должна учесть; сам по себе предшествующий узел входом не является.
Глобальные переменные сценария включают запрос, пользователя, номер хода диалога и прикреплённые файлы. Файл, загруженный как переменная, передаётся модели текстом без обработки и без попадания в базу знаний; если текст длиннее контекста модели, он обрезается.
Запуск и отладка
Кнопка «Тестовый запуск» выполняет сценарий на контрольных данных. Заполните поля «Начала», наблюдайте ход узлов и сообщения об ошибках, затем откройте итоговый результат и журнал. В журнале видны путь выполнения, значения переменных и трассировка вызовов инструментов: имя, аргументы, результат, время. Для компонента «Поиск» отдельно проверяются найденные фрагменты.
Правила отладки:
- менять один параметр за раз и повторять полный контрольный набор: положительный, отрицательный и ошибочный ввод;
- при ошибке компонента задать переход на альтернативную ветку или значение по умолчанию;
- для изменяющего действия отдельно проверять внешнюю систему и не повторять запуск, пока не выяснено, выполнилось ли первое действие частично.
Холст хранит версии, поэтому рабочий сценарий можно вернуть к предыдущему состоянию.
Автоматизации
Агент становится автоматизацией в разделе «Автоматизации». У автоматизации есть триггер, цель и доставка:
- Триггер: расписание, вебхук, событие коннектора или опрос инструмента MCP, который срабатывает только при изменении ответа.
- Цель: агент, агентное задание с бюджетом по числу элементов и вызовов модели, сценарий на холсте или долгий сценарий с паузами.
- Доставка: беседа, Telegram (в том числе в несколько чатов), Bitrix24 или другая подключённая система.
Пример: каждый день в 18:00 собрать новые платёжные документы из 1С и прислать сводку в Telegram. Автоматизацию можно создать и из чата: ассистент с включённым копилотом автоматизаций заводит её по просьбе, но всегда выключенной. Проверьте её в разделе «Автоматизации», включите и только затем регистрируйте адрес вебхука во внешней системе.
Примечание
Первое срабатывание по расписанию происходит в следующем слоте после включения, а не сразу.
Подтверждения
Любая запись во внешнюю систему требует подтверждения человека. На холсте узел одобрения паркует выполнение до решения; долгий сценарий переживает перезапуск и продолжается с того же узла. В чате ассистент останавливает ход и показывает карточку с описанием действия, объектом и параметрами; карточка действует ограниченное время, затем действие нужно запросить заново.
Если агент доставляет результат в Telegram, подтверждение приходит туда же сообщением с кнопками «Подтвердить» и «Отклонить». Отдельный пользователь, которого ждёт решение, видит статус «ожидает подтверждения», а не бесконечную печать. Отказ и отмена фиксируются, повторная отправка одного и того же действия не приводит к двойному эффекту.
Перед подтверждением проверьте целевую систему, объект, новое значение и обратимость, а после выполнения откройте внешнюю систему и убедитесь в фактическом результате.
Что дальше
- MCP-серверы: откуда у агента инструменты.
- API-ключ и SDK: запуск агента через
POST /agents/{id}/completionsс входными параметрами. - Сценарии автоматизации для отделов: страница Автоматизация.
Спросить Сему