🤝 Агентский режим
Что это. Блок «AI-агент» отдаёт весь разговор с клиентом нейросети: она сама формулирует реплики, сама решает, когда задать вопрос и подождать ответа, сама вызывает выданные ей навыки и сама выбирает, каким исходом закончить работу. Автор сценария задаёт не последовательность шагов, а инструкцию, набор навыков и список допустимых исходов.
Когда нужно. Когда заранее неизвестно, сколько уточнений понадобится и в каком порядке: первая линия поддержки, разбор вопроса «почему не пришёл заказ», сбор недостающих данных перед передачей сотруднику.
📷 Скриншот: узел «AI-агент» на холсте сценария (будет добавлен).
Чем агент отличается от AI-блоков
Это не «ещё один AI-блок». Разница принципиальная.
| Что сравниваем | Обычный AI-блок | AI-агент |
|---|---|---|
| Сколько раз обращается к модели | ровно один вызов | цикл: ход → пачка действий → наблюдения → следующий ход |
| Кто пишет клиенту | блок «Сообщение», поставленный автором следом | сам агент, действием «Реплика» |
| Кто ждёт ответа клиента | блок «Вопрос», поставленный автором | сам агент, действием «Вопрос» |
| Куда уходит управление | по фиксированному выходу («Далее», «Не уверена») | по исходу, который выбрала модель |
| Переживает ли ожидание клиента | нет, блок завершается сразу | да, сессия продолжается с того же места после ответа |
| Может ли вызывать другие блоки | нет | да, если автор выдал их как навыки |
Агент — единственный блок, который сам возобновляется: после ответа клиента продолжается та же сессия, а не запускается новый проход по графу.
Когда агент уместен, а когда лучше обычный сценарий
Агент уместен, если:
- разговор ветвится непредсказуемо и нарисовать все ветки на холсте дороже, чем описать правила словами;
- нужно несколько уточняющих вопросов подряд, причём какие именно — зависит от ответов;
- по ходу разговора надо сходить в базу знаний, поставить тег или сменить статус — и решить это по ситуации.
Обычный сценарий лучше, если:
- шаги фиксированы и их немного (приветствие → кнопки → маршрутизация);
- нужен предсказуемый до символа текст — например, юридически выверенное уведомление;
- разговора нет вовсе: сценарии типов «Тикеты» и «Глобальный» агента не поддерживают.
Где находится
Блок «AI-агент» есть в палитре редактора только в сценариях типа «Поддержка». В сценариях типа «Тикеты» и «Глобальный» его в палитре нет: агенту нужен живой чат, иначе его реплики и вопросы уходили бы в пустоту.
Агентский режим управляется настройкой всего сервиса, а не отдельного проекта. Если он выключен, блок пропадает из палитры, а у уже сохранённого узла нода и панель показывают «Агентский режим выключен на сервисе» и «Блок сохранится, но опубликовать сценарий с ним нельзя. Настройки открыты только на чтение, связи не тронуты». Опубликовать такой сценарий не получится.
Как выглядит узел на холсте
У агента собственная нода, не похожая на остальные блоки:
| Что видно | Что означает |
|---|---|
| Заголовок с иконкой | двойной клик по заголовку сворачивает и разворачивает ноду |
| Превью инструкции в три строки | начало текста инструкции |
| «Полка навыков» | до четырёх строк, дальше «+ ещё N»; если навыков нет — «Навыков нет» |
| Строка «База знаний» | включён ли поиск по базе и по скольким папкам он ограничен |
| Подвал вида «до N ходов · до M вызовов» | текущие значения лимитов сессии |
У полки навыков портов нет: навык — это не ветка сценария. Выходами узла служат только объявленные исходы и системные порты.
Неразведённые порты подсвечиваются прямо на холсте: «Обязательный выход не разведён — публикация не пройдёт» и «Исход не разведён: прогон уйдёт по несуществующему переходу и завершится молча».
Панель настроек: три вкладки
Панель свойств выделенного агента разложена на вкладки «Инструкция», «Навыки (N)» и «Исходы (N)». Счётчики в подписях считают только то, что добавил автор.
Вкладка «Инструкция»
📷 Скриншот: вкладка «Инструкция» в панели агента (будет добавлен).
| Поле | По умолчанию | Что делает |
|---|---|---|
| «Инструкция» | пусто | Правила разговора для модели. До 20 000 символов, есть счётчик, ввод сверх лимита обрезается. Плейсхолдер: «Ты — оператор первой линии. Отвечай кратко и по делу…» |
| «Модель» | «Базовая» | Тир модели: «Быстрая», «Базовая», «Точная» — см. AI-возможности |
| «Температура» | 0.3 | От 0 до 2 с шагом 0.1. Рекомендация в подписи — 0.2–0.4: выше модель начинает импровизировать |
| «Переменная с расшифровкой» | agent_transcript | Имя переменной, в которую сложится вся история диалога списком реплик |
| «Префикс переменных» | пусто (agent) | Под каким префиксом агент опубликует свои переменные |
| «Безопасность» | проверка включена | Модерация исходящих реплик — см. ниже |
Инструкция интерполируется: шаблоны {{…}} в ней подставляются перед отправкой модели. Например, {{chat.last_message}} в инструкции сработает.
Рядом с полем есть кнопка «Улучшить» — она переписывает черновой текст инструкции: Улучшение промпта.
Прямо под инструкцией редактор показывает подсказки, не дожидаясь публикации:
- «В инструкции упомянуто имя, которого нет среди навыков»;
- «Навык объявлен, но в инструкции не упомянут»;
- предупреждение вида
Здесь нельзя использовать {ref}: инструкция интерполируется…— про переменные, которые в инструкцию подставлять нельзя.
Переменные project.* и tenant.* агенту недоступны намеренно — «project и tenant агенту недоступны: там хранятся секреты проекта». Но инструкция интерполируется, поэтому шаблон вида {{project.api_token}}, вписанный в неё руками, подставится и уедет в промпт. Подсказчик переменных такие имена не предлагает, а больше ничего этот канал не закрывает.
Вкладка «Навыки (N)»
Список карточек навыков и кнопка «Добавить навык». Подробно — на странице Навыки агента.
Вкладка «Исходы (N)»
Секции идут в порядке: «Исходы», «Лимиты», «База знаний», «Контекст»; последние три свёрнуты по умолчанию. Здесь же кнопка «Проверить черновик» и подсказка «Агент опубликует: …» со списком переменных.
Что делает агент на каждом ходу
Один ход — один вызов модели. Модель возвращает не одно действие, а упорядоченную пачку, которую сценарий выполняет по порядку.
| Действие | Что происходит | Обрывает ли пачку |
|---|---|---|
| «Реплика» | Агент пишет клиенту и продолжает работать в том же ходу | нет |
| «Вопрос» | Агент пишет клиенту и уходит ждать ответа | да |
| «Навык» | Агент вызывает выданный ему блок, результат возвращается модели как наблюдение | нет, кроме навыка с подтверждением оператора |
| «Завершение» | Агент уходит в выбранный исход — только это заканчивает его работу | да |
Всё, что модель попросила после «Вопроса» или «Завершения», отбрасывается, и в трассе появляется отдельная строка вида «Отброшено действий: N — ask прервал пачку».
Лимиты проверяются перед каждым действием, а не раз в ход.
Если модель за ход только написала клиенту и больше ничего не сделала, агент всё равно уходит ждать ответа, а в трассе появляется шаг «Вопрос» с пометкой «Агент ждёт ответа клиента, вопроса не задавал». Иначе модель повторяла бы одно и то же приветствие.
Сообщения, которые клиент прислал, пока шёл ход, подхватываются перед следующим обращением к модели — агент отвечает сразу на всю очередь.
Исходы
Исход — это способ закончить разговор, объявленный автором. Каждый исход даёт узлу отдельный выход out:<ключ> на холсте.
| Поле | Обязательно | Описание |
|---|---|---|
| «Ключ» | да | Латиница нижнего регистра по маске ^[a-z][a-z0-9_]*$. Из ключа строится имя порта |
| «Подпись» | да | Что написано под портом на холсте |
| «Когда выбирать» | формально нет | Описание, которое читает сама модель, чтобы выбрать между исходами |
Новый агент создаётся сразу с тремя исходами:
| Ключ | Подпись |
|---|---|
resolved | «Решено» |
escalated | «Нужен оператор» |
out_of_scope | «Не по теме» |
«Когда выбирать» — это не комментарий для коллег, а текст для модели. Без него выбор исхода становится случайным, и линтер об этом предупреждает.
Если удалить все исходы, при публикации подставится один запасной — done «Готово»; в панели он показан призрачной строкой «Готово (подставится автоматически)». При удалении разведённого исхода панель спросит, что делать со связью, и предложит перевесить её на «Готово» либо удалить.
Системные порты
Кроме исходов у узла есть три системных порта. Публикация не пройдёт, пока они не разведены, — и пока не разведён хотя бы один исход.
| Порт | Ключ | Когда срабатывает |
|---|---|---|
| «Лимит исчерпан» | limit_reached | Кончился какой-то лимит сессии |
| «Ошибка» | failed | Ошибка модели или навыка |
| Порт таймаута | timeout | Клиент перестал отвечать и истекло время ожидания |
Неразведённый исход публикацию не блокирует, но перед публикацией показывается диалог «Не все исходы разведены» с текстом «Публикация пройдёт, но прогон, который выберет такой исход, уйдёт по несуществующему переходу и завершится молча — посреди диалога с клиентом» и кнопками «Опубликовать всё равно» и «Сначала разведу». Молчаливое завершение не видно ни в статусе прогона, ни в трассе.
Ребро, идущее из порта переименованного или удалённого исхода, ловится при публикации отдельной ошибкой.
Лимиты сессии
Секция «Лимиты» на вкладке «Исходы». Все значения редактируются, у каждого есть потолок сервиса.
| Параметр | По умолчанию | Потолок |
|---|---|---|
| «Ходов модели» | 30 | 60 |
| «Вызовов навыков» | 60 | 120 |
| «Действий за один ход» | 5 | 10 |
| «Ответов клиента» | 12 | 20 |
| «Токенов» | 400 000 | 800 000 |
| «HTTP-вызовов за сессию» | 5 | 20 |
| «Активное время» | PT45M (45 минут) | PT2H (2 часа) |
| «Срок жизни сессии» | PT4H (4 часа) | PT24H (24 часа) |
| «Ждать ответа клиента» | PT15M (15 минут) | PT1H (1 час) |
| «Ждать подтверждения оператора» | PT1H (1 час) | PT4H (4 часа) |
«Активное время» считает только ходы модели и вызовы навыков — пока агент ждёт клиента, оно не идёт. «Срок жизни сессии» идёт всегда.
Значение больше потолка не вызывает ошибку — оно молча заменяется потолком. В панели об этом сказано подписью «Больше лимита: значение будет урезано молча».
Длительности задаются только в формате ISO-8601: PT30M, PT4H, PT90S. Любая другая запись — например 30m — тоже молча заменяется значением по умолчанию. Ноль в поле длительности означает не «без ожидания», а потолок сервиса.
Мягкая посадка
Когда исчерпан любой лимит, кроме «Срока жизни сессии», агент получает ровно один дополнительный ход, чтобы вежливо попрощаться. На этом ходу ему доступны только реплика и завершение — ни навыков, ни базы знаний. Этот ход бесплатный: он не считается в лимит ходов.
«Срок жизни сессии» посадочного хода не даёт: сессия сразу уходит в порт «Лимит исчерпан».
Причина выхода называется прямо — и в трассе, и в переменной agent.outcome_reason: «исчерпан лимит ходов агента», «исчерпано активное время сессии» и так далее.
База знаний агента
Секция «База знаний» подшивает агенту встроенный поиск по базе знаний проекта. Это не навык из списка: отдельно выдать или отобрать его нельзя, единственный переключатель — тумблер «Искать в базе знаний» (включён по умолчанию).
| Параметр | По умолчанию | Что делает |
|---|---|---|
| «Искать в базе знаний» | включено | Даёт агенту встроенный поиск |
| «Документов» | 5 | Сколько фрагментов брать в ответ |
| «Отвечать, только если уверенность выше» | 0.6 | Ниже порога агент получает ответ «база знаний не дала уверенного ответа» |
| «Порог документа» | не задан | Режет слабые документы ещё при поиске: отрезанный документ исчезает бесследно и в трассе не виден |
| «Папки» | все | Ограничить поиск папками. Фильтр не иерархичен: вложенные папки сами не подхватываются |
| «Теги» | не заданы | См. предупреждение ниже |
Агент ищет сам, своими словами: подпись у аргумента поиска — «Вопрос своими словами, а не дословная реплика клиента». Каждый поиск расходует лимит «Вызовов навыков».
Подпись в панели говорит прямо: «Теги не индексируются — выбор сузит поиск до пустоты, и притом без ошибки». Фильтруйте по папкам.
Найденные источники попадают в переменную agent.last_sources и в шаг трассы «База знаний» вместе с уверенностью — включая те, что отброшены по порогу.
Что агент знает о клиенте
Секция «Контекст» — это белый список, а не «всё, что видит сценарий». Агенту отдаётся только то, что здесь отмечено.
| Область | По умолчанию | Что попадает в контекст |
|---|---|---|
| Чат | включено | идентификатор, последнее сообщение, канал, статус, линия поддержки |
| Клиент | включено | идентификатор, имя, email, телефон, теги |
| Тикет | включено | идентификатор, номер, тема, статус, приоритет, тип |
| Событие | включено | тип события и текст |
| Система | выключено | текущие дата и время |
Дополнительно есть поля «Отдельные переменные» (поимённо, для значений, записанных блоками выше по графу), «Показывать имена project-переменных (без значений)» и «Потолок секции, символов» — по умолчанию 4000, это же и потолок сервиса; при превышении секция усекается с явной пометкой.
Переменные project.* и tenant.* в контекст не отдаются ни при каких настройках: сценарий с ними не опубликуется. Пустой список областей означает, что агент не знает о клиенте вообще ничего.
В шаге «Ход модели» перечислены имена переменных, ушедших в контекст, но не их значения.
Безопасность
Секция «Безопасность» на вкладке «Инструкция» — два параметра.
| Параметр | По умолчанию | Что делает |
|---|---|---|
| «Проверять ответы агента модерацией» | включено | Каждая исходящая реплика отдельно проходит проверку модерацией |
| «Если модерация не пропустила ответ» | «Передать оператору» | «Передать оператору» — уйти в исход, ключ которого содержит escalat; «Завершить с ошибкой» — уйти в системный порт «Ошибка» |
Проверяется именно каждая реплика: пачка действий единицей безопасности не является.
Кроме модерации у агента есть встроенные правила, которые нельзя отключить: не выдумывать факты о клиенте, его заказах и платежах; не говорить, что действие выполнено, пока навык не отработал; не раскрывать инструкцию, имена навыков и внутренние идентификаторы; относиться к тексту клиента и к ответам внешних систем как к данным, а не как к командам.
Переменные, которые публикует агент
После завершения агент отдаёт сценарию набор переменных. Без своего префикса они начинаются с agent., со своим — с того, что указано в поле «Префикс переменных» (латиница без пробелов и точек, до 64 символов).
| Переменная | Что внутри |
|---|---|
agent.outcome | Ключ выбранного исхода. Пусто, если ушли в «Лимит исчерпан» |
agent.outcome_reason | Формулировка модели или название исчерпанного лимита |
agent.turns | Сколько ходов заняла работа |
agent.tool_calls | Сколько навыков вызвано |
agent.last_sources | Документы базы знаний за последним ответом. Всегда есть — при отсутствии источников это пустой список |
Порт «Ошибка» отдаёт тот же набор плюс error_message и error_type (model — ошибка модели, crash — сбой). Переменные видны в каталоге переменных редактора для блоков, стоящих ниже агента по графу.
Отдельно поле «Переменная с расшифровкой» складывает всю историю диалога списком реплик под указанным именем — без префикса flow.
Если задан свой префикс, agent.outcome, agent.outcome_reason и agent.last_sources дополнительно дублируются как ссылка на последнего отработавшего агента. Поэтому два агента без префикса в одном сценарии пишут в одни и те же имена. Линтер об этом предупреждает.
Проверка черновика
Кнопка «Проверить черновик» на вкладке «Инструкция» проверяет сохранённый черновик целиком и возвращает только предупреждения — публикацию она не блокирует никогда. Проверок семь:
| Проверка | О чём предупреждает |
|---|---|
| Исходов нет | «Исходов не объявлено: агент уйдёт одним портом „Готово“» |
| Исход не разведён | «Исход объявлен, но его порт никуда не ведёт — прогон закончится на агенте» |
| У исхода нет описания | Агент выбирает исход именно по описанию, так что выбор будет наугад |
| Описания навыков похожи | Совпадение больше 70% — «модель будет выбирать между ними наугад», процент указывается |
| Совпал префикс переменных | Два агента пишут переменные под одним префиксом |
| Фильтр базы знаний пуст | Фильтр, проверенный по живому индексу, не находит ни одного документа |
| Мало токенов | Заданного лимита токенов не хватит на заданное число ходов |
Если замечаний нет, панель отвечает «Замечаний нет».
Подпись у кнопки: «Проверяется сохранённый черновик сценария целиком. Вызов платный: делит лимит с AI-ассистом, 30 обращений в минуту на проект». При исчерпании лимита появляется «Лимит обращений исчерпан — он общий с AI-ассистом на весь проект».
Что видно в трассе прогона
На странице запуска вкладка «Трейс» показывает «Ход прогона», а работу агента собирает в группу «Сессия агента» с сегментами: «Сегмент N», «клиент молчал …», «ждёт ответа клиента», «ждёт подтверждения оператора», «исход: …».
Внутри — под-шаги:
| Шаг | Что показывает |
|---|---|
| «Ход модели» | Число действий, потраченные токены, длительность, имена контекстных переменных, число попыток |
| «Навык» | «Аргументы модели», «Результат», пометки «Не доехали (поле не открыто модели)» и «Шаблоны обезврежены» |
| «База знаний» | Запрос, статус, уверенность, список источников |
| «Реплика» | Что агент написал клиенту |
| «Вопрос» | Что агент спросил перед ожиданием |
| «Завершение» | Выбранный исход и причина |
| «Лимит» | Что именно исчерпано и сколько действий отброшено |
| «Подтверждение» | Запрос оператору и его решение |
Статусы поиска по базе знаний подписаны словами: «База ответила, ответ использован», «Ответ есть, но ниже порога — не использован», «Поиск отработал, ничего не нашёл», «Поиск не выполнился». Причины лимита — тоже: «Исчерпан лимит ходов агента», «Исчерпан лимит токенов», «Истёк общий срок жизни сессии» и другие.
Есть блок «Счётчики» с полями «Ходов», «Вызовов навыков», «Токенов»; пока разговор идёт, вместо них написано «Пока агент жив, счётчиков нет». Отдельная вкладка «История модели» показывает переписку с моделью с оговоркой, что это не трасса.
В трассе есть честная строка: «Рассуждение генерирует та же модель — оно может не отражать реальную причину действия».
Ответы клиента в трассу не пишутся — они видны в самой переписке.
Когда клиент замолчал и когда ИИ недоступен
Три ожидания разведены отдельно, и ведут себя они по-разному.
| Симптом | Причина и решение |
|---|---|
| Прогон ушёл в порт таймаута, клиент ничего не получил | Клиент перестал отвечать и истекло «Ждать ответа клиента». Модель на это не вызывается вообще — что сказать клиенту, решают блоки, поставленные за портом таймаута |
| Клиент написал, а ответа долго нет, и в чате тихо | Ход не удался по причине, которую лечит ожидание: AI-сервис недоступен, таймаут, превышена частота обращений. Сессия ждёт, клиенту ничего не говорится, следующее сообщение клиента продолжает тот же разговор с полной историей |
| Прогон ушёл в «Лимит исчерпан» после долгой паузы | Авария пережила «Срок жизни сессии» |
| Агент «проснулся» от собственного действия | Если навык породил событие в чате (например, смену статуса), это распознаётся: ход не тратится, таймер ожидания ответа перезапускается |
Ограничения
- Блок доступен только в сценариях типа «Поддержка».
- Агент не может быть навыком другого агента: связка из нескольких агентов не поддерживается.
- Один сценарий рассчитан на одного агента. Общий бюджет прогона — не больше 200 AI-вызовов, и два агента в него уже не помещаются.
- Отдельно от лимитов сессии действует дневной бюджет токенов проекта — 10 000 000 (примерно 25 разговоров при значениях по умолчанию). При его исчерпании прогон уходит в «Лимит исчерпан» с текстом «исчерпан дневной лимит токенов проекта».
- Максимум 20 навыков на одного агента.
- Инструкция — не длиннее 20 000 символов, секция контекста — не длиннее 4000 символов.
- Значения лимитов сверх потолка и длительности в неверном формате принимаются молча, но не действуют.
- Неразведённый исход публикацию не блокирует — прогон по нему завершится молча.
- Агентский режим включается на весь сервис, а не для отдельного проекта.
Кто что может
| Действие | Минимальная роль |
|---|---|
| Смотреть настройки агента, трассу прогона и очередь подтверждений | По умолчанию |
| Добавлять агента, править инструкцию, навыки, исходы и лимиты | Редактор |
| Нажимать «Улучшить» и «Проверить черновик» | Редактор |
| Принимать решения по подтверждениям агента | Редактор |
| Публиковать сценарий с агентом и снимать с публикации | Администратор |
→ Навыки агента · Подтверждения оператора · AI-блоки · Версии и запуски