# Шаг «AI-агент» в конструкторе сценариев

Source: https://docs.botman.pro/a/178-shag-ai-agent-v-konstruktore-stsenariev

## Чем шаг «AI-агент» отличается от AI-агента канала

В Botman есть два похожих, но разных инструмента:

- **AI-агент** (раздел «AI-агенты» в общих настройках) — это самостоятельный помощник, который отвечает пользователям в подключённом канале в свободном диалоге, опираясь на базу знаний и темы. Он работает «сам по себе», вне какого-то конкретного сценария, и включается только тогда, когда пользователь не находится ни в одном сценарии.
- **Шаг «AI-агент»** — это тот же самый AI-агент, но встроенный в конкретное место конкретного сценария. Он подключается только пока пользователь находится именно на этом шаге, и только для того, чтобы выполнить конкретную локальную задачу (проконсультировать, собрать данные, уточнить запрос), а затем передать пользователя дальше по сценарию.

Проще говоря: **AI-агент канала** — это «дежурный на весь канал», который берётся отвечать, когда сценарий пользователя не ведёт. **Шаг «AI-агент»** — это тот же тип агента, но «вставленный» внутрь конкретного сценария как один из его шагов, со своей локальной задачей и условием завершения.

Один и тот же AI-агент (созданный в разделе «AI-агенты») можно использовать и как агента канала, и как агента шага в сценарии — это не два разных агента, а два разных места, где он может работать.

---

## Как это работает «на пальцах» (приоритеты)

Каждое входящее сообщение получает только один обработчик:

- Если пользователь сейчас находится в сценарии (в том числе на шаге вопроса, меню или на шаге «AI-агент») — сообщение обрабатывает сценарий (и, соответственно, агент этого шага, если пользователь на нём). Агент канала в это время молчит.
- Если пользователь **не** в сценарии и его сообщение не запустило ни один сценарий — сообщение достаётся агенту канала.
- Пока пользователь на шаге «AI-агент», за диалог отвечает именно агент шага — до тех пор, пока не выполнится условие «Когда завершить работу», указанное в настройках шага.

То есть при использовании шага «AI-агент» вам не нужно ничего отдельно настраивать «на канале» — на время шага он и так забирает управление у агента канала.

---

## Как добавить и настроить шаг

**1️⃣ Добавьте шаг в сценарий**

В конструкторе сценариев добавьте шаг «AI-агент» в нужном месте воронки

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/9fea711aabda2fa5430b0ec69f47e74a80215877c9a7380fdebf98d91eabbf8e.png)

**2️⃣ Выберите или создайте агента**

В блоке **«Агент»** откройте список и выберите уже существующего AI-агента, либо нажмите **«+ Создать нового агента»**, если подходящего ещё нет. Агент, добавленный прямо из сценария, сразу получает статус «Активен» — донастраивать его отдельно не обязательно.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/ea98716db4941489dd62a492d12fa9a256abca7ac8824d97687a4b74e9cff2b2.png)

**3️⃣ Настройте «Начало диалога» — кто пишет первым**

- **«Пишет первым»** (стоит по умолчанию) — агент сам инициирует разговор сразу при входе пользователя на этот шаг. Используйте, если хотите, чтобы бот сам поздоровался, задал вопрос или что-то предложил.
- **«Ждёт клиента»** — агент не пишет первым, а ждёт сообщения от пользователя и только потом отвечает. Используйте, если шаг должен просто «подхватить» уже идущий разговор.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/4a8e52ec83948f0e04208e9997a23e32fe7a9cb526159b1ce358604880ac1cca.png)

**4️⃣ Опишите «Когда завершить работу»**

Это текстовое условие (до 512 символов), при выполнении которого агент сам решает, что задача сделана, и передаёт управление обратно в сценарий. Например: *«Получил ответ на вопрос и не задаёт новых»* или *«Уточнил город и дату доставки»*.

Важно понимать:

- Это условие передаётся агенту как часть его инструкций — агент сам, по смыслу диалога, определяет момент, когда оно выполнено.
- Если оставить поле пустым, агент **не будет** завершать шаг самостоятельно и останется в диалоге бесконечно — заканчивать шаг тогда придётся другим способом (например, отдельной кнопкой/условием в сценарии).

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/3e85eee55a9454c290046e8ab98704166238a9d702aef02d0b3340b0b23d498f.png)

**6️⃣ При необходимости добавьте функцию «Сбор данных»**

Если агенту на этом шаге нужно не просто поговорить, а получить и сохранить конкретные данные (имя, телефон, город и т.п.):

Нажмите **«+ Добавить функцию»** → выберите **«Сбор данных»**.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/3b8ffd7971a94130f6600a0647203ec37b0ba88ac4f99d29b3a4c6df7d83c0e6.png)

Заполните три поля:

- **«Что собираем»** — короткий технический ключ, например `имя`, `телефон`, `город`. Обязательное поле.
- **«Инструкция для агента»** — это **не** вопрос, который увидит пользователь, а подсказка самому агенту: что и как спрашивать, как трактовать ответ. Например: *«Уточни город и дату доставки»*. Агент сам сформулирует вопрос пользователю на основе этой инструкции. Обязательное поле, до 4000 символов.
- **«Переменная для записи»** — куда сохранить полученное значение. Поле необязательное: если переменную не выбрать, агент всё равно соберёт данные (сможет их использовать в диалоге), но никуда их не сохранит.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/198d32a4cfd6cee646f47c35845197f4f2be2c7d847c570d66fc32cf15f3f9b8.png)

Чтобы собрать несколько разных полей (например, и имя, и телефон) — добавьте столько же отдельных блоков «Сбор данных» через «+ Добавить функцию», по одному блоку на каждое поле.

![](https://storage.yandexcloud.net/botman-knowledge-prod/kb/6aec5304d3ac9dc31d82ccf6/91c0f4b4530cf741aa1d13d3c0609c4dc997c154abdb2296748ef825094d4aed.png)

> ⚠️ Все поля, добавленные через «Сбор данных», по умолчанию обязательны: агент не завершит шаг, пока не получит их все, даже если условие из «Когда завершить работу» по смыслу уже выполнено.

> 💡 Если после сбора данных диалог должен пойти по разным веткам в зависимости от ответа — добавьте после этого шага шаг «Условие», сам шаг «AI-агент» ветвление не делает.