# ИИ-диалог

Блок **ИИ-диалог** позволяет боту вести с пользователем многоходовой разговор на естественном языке: задавать вопросы, собирать данные, уточнять детали — и по завершении передавать собранную информацию в следующую ноду.

---

## Как это работает

1. Бот входит в блок ИИ-диалога.
2. ИИ отправляет первое сообщение согласно системному промпту.
3. Пользователь отвечает — ответ передаётся ИИ как новое сообщение.
4. ИИ продолжает диалог, накапливая ответы в объекте `data`.
5. Когда все нужные данные собраны, диалог завершается, бот переходит к следующей ноде.

История диалога хранится в базе данных и восстанавливается при повторном входе пользователя в блок.

---

## Настройки блока

### Подключение

| Поле | Описание |
|---|---|
| **Сервис ИИ** | Нейросеть для диалога: OpenAI, Claude, Gemini, Grok, YandexGPT, OpenRouter, Kimi |
| **Подключение** | Сохранённый API-ключ из раздела «Интеграции» |
| **Модель** | Конкретная модель (например, `gpt-4o`). Можно указать переменную |

### Диалог

| Поле | Описание |
|---|---|
| **Системный промпт** | Инструкция для ИИ: задача, стиль общения, что собирать |
| **Разрешённые типы сообщений** | Что ИИ может отправлять: текст, inline-кнопки, reply-кнопки, опросы |
| **JSON-схема** | Структура данных, которые нужно собрать (ключ → тип). ИИ накапливает их в `data` |
| **Префикс переменных результата** | Куда сохраняются итоги диалога. При `ai_result` и поле `name` → `{{ai_result.name}}` |
| **Инструменты ИИ** | Команды бота, которые ИИ может вызвать во время разговора. Число рядом с кнопкой показывает количество подключённых инструментов |
| **Подключить базу знаний бота** | Разрешает этому блоку искать ответы в документах и записях выбранного бота |

### Завершение

| Поле | Описание |
|---|---|
| **Перейти к ноде** | Нода, куда бот переходит после `final_state: true` |

### Расширенные настройки

| Поле | Описание |
|---|---|
| **Лимит сообщений в истории** | Сколько последних сообщений передаётся ИИ (по умолчанию 50) |
| **Хранить историю (часов)** | TTL истории диалога. После паузы дольше этого времени история сбрасывается |
| **Макс. токенов ответа** | Лимит токенов в одном ответе ИИ (по умолчанию 2048) |
| **Шифровать данные** | История диалога хранится в БД в зашифрованном виде |
| **Стриминговый режим** | Ответ ИИ отображается в чате по мере генерации (только для текстовых ответов) |

---

## JSON-схема

Схема определяет, какие данные должен собрать ИИ. Формат — JSON-объект, где ключи — имена полей, значения — типы:

```json
{
  "name": "string",
  "phone": "string",
  "age": "number",
  "agree_terms": "boolean"
}
```

ИИ накапливает значения в объекте `data` по ходу диалога. Как только все поля заполнены — ИИ завершает диалог и передаёт данные дальше.

После завершения диалога каждое поле доступно как переменная:

```
{{ai_result.name}}
{{ai_result.phone}}
{{ai_result.age}}
```

---

## Системный промпт

Промпт — главная инструкция для ИИ. Правила JSON-формата ответа добавляются автоматически — их писать не нужно. Укажите:

- **Задачу**: что нужно собрать или выяснить
- **Стиль общения**: тон, язык, формат вопросов
- **Дополнительные правила**: порядок вопросов, как реагировать на нестандартные ответы

**Пример промпта:**

```
Ты помощник по записи на приём. Вежливо собери у пользователя:
— имя
— номер телефона
— удобное время (утро/день/вечер)

Задавай по одному вопросу за раз. Если пользователь даёт неполный ответ — уточни.
Не начинай запись, пока не получишь все три ответа.
```

В промпте доступны переменные бота: `{{user.first_name}}`, `{{переменная}}` и т.д.

---

## Инструменты ИИ

Инструменты позволяют ИИ вызывать команды бота прямо во время диалога: запрашивать данные из API, проверять наличие товара, рассчитывать стоимость, создавать заявку или запускать готовую цепочку сообщений.

### Принцип работы

1. ИИ решает, что ему нужна информация или действие.
2. Отправляет пользователю короткое сообщение (например, «Ищу данные, подождите...»).
3. Вызывает указанную команду, передавая ей параметры через переменные `{{tool_input.*}}`.
4. Команда выполняется выбранным способом: возвращает переменную в ИИ или полностью выполняет все свои действия и сообщения.
5. ИИ получает результат выполнения и продолжает диалог.

За один ход диалога ИИ может вызвать до 3 инструментов подряд.

### Настройка инструмента

Нажмите **Инструменты ИИ** в блоке ИИ-диалога, затем **Добавить инструмент**. Можно выбрать существующую команду или создать новую прямо из окна настройки.

| Поле | Описание |
|---|---|
| **Название** | Уникальный идентификатор в snake_case, например `get_weather` |
| **Описание для ИИ** | Объясняет ИИ, что делает инструмент и когда его вызывать |
| **Режим выполнения** | Определяет, нужно вернуть результат команды в ИИ или выполнить команду целиком |
| **Команда** | Нода-команда, которую выполняет инструмент |
| **Переменная результата** | Переменная, из которой читается ответ команды. Показывается только в режиме «Вернуть результат в ИИ» |
| **Параметры** | Данные, которые ИИ передаёт в команду |

Имя `search_knowledge_base` зарезервировано для встроенного поиска по базе знаний и недоступно для пользовательских инструментов.

### Режимы выполнения

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

**Выполнить команду целиком** — запускается вся команда, включая её сообщения и другие действия. Команда сама показывает результат пользователю, а ИИ после выполнения продолжает диалог. Переменная результата в этом режиме не нужна. Используйте его, например, для отправки карточки товара, готовой инструкции или цепочки сообщений.

### Параметры инструмента

Параметры — это значения, которые ИИ подставляет в переменные `{{tool_input.имя}}` внутри блоков связанной команды.

**Как настроить:**

1. Откройте связанную команду и вставьте `{{tool_input.имя_параметра}}` в нужные поля — URL, тело запроса, текст и т. д.:
   ```
   https://api.example.com/weather?city={{tool_input.city}}&units={{tool_input.units}}
   ```
2. Вернитесь в редактор инструмента и выберите эту команду. Параметры `city` и `units` появятся автоматически.
3. Укажите описание каждого параметра, чтобы ИИ понимал, какое значение передать.
4. Выберите тип (`string`, `number` или `boolean`) и отметьте обязательные параметры.

Если вы изменили команду после выбора, нажмите **Пересканировать** рядом с полем «Команда». Параметры также можно добавлять и удалять вручную.

### Переменная результата

В режиме **Вернуть результат в ИИ** команда должна записать нужное значение в указанную переменную. Например, если API-запрос сохраняет ответ в `api_response`, укажите `api_response` в поле «Переменная результата».

> **Отличие от «Префикса результата» блока диалога:** переменная результата инструмента — временный ответ одной команды, который ИИ использует в текущем разговоре. Префикс результата блока содержит итоговые данные всего диалога для следующих нод сценария.

### Пример: поиск по каталогу

**Команда `search_catalog`:**

- API-запрос: `GET https://mystore.com/api/search?q={{tool_input.query}}&limit={{tool_input.limit}}`
- Ответ сохраняется в переменную `search_result`

**Инструмент в ИИ-диалоге:**

- Название: `search_catalog`
- Описание: «Поиск товаров в каталоге по запросу пользователя»
- Режим: «Вернуть результат в ИИ»
- Команда: `search_catalog`
- Переменная результата: `search_result`
- Параметры: `query` (string, обязательный) и `limit` (number)

В системном промпте можно написать: «Используй инструмент `search_catalog`, когда пользователь ищет товар».

---

## База знаний

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

### Как подключить

1. Откройте **Настройки бота → База знаний**. Также можно нажать ссылку **базу знаний бота** под кнопкой «Инструменты ИИ» — страница откроется в новой вкладке.
2. Загрузите документы или добавьте текстовые записи.
3. Дождитесь статуса **Готово** хотя бы у одного документа.
4. При необходимости откройте вкладку **Тест** и проверьте, какие фрагменты находятся по вашему вопросу.
5. Вернитесь в нужный блок ИИ-диалога и включите **Подключить базу знаний бота**.
6. Сохраните изменения сценария.

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

Переключатель недоступен, если база знаний не входит в тариф или в ней ещё нет ни одного готового документа. Документы со статусами «В очереди», «Обработка» или «Ошибка» не учитываются.

### Как ИИ использует базу

- ИИ сам решает, когда выполнить поиск по вопросу пользователя.
- Поиск выполняется только по базе выбранного бота.
- Найденные фрагменты передаются ИИ вместе с названием источника, после чего он формирует ответ.
- Создавать отдельную команду для поиска не нужно: встроенный инструмент подключается автоматически.
- Документы добавляются, тестируются и удаляются только в разделе **Настройки бота → База знаний**.

В системном промпте можно уточнить правила ответа, например:

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

---

## Анализ промпта и тестирование моделей

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

### 1. Анализ промпта (вкладка «Анализ»)

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

### 2. Тестирование вопросов (вкладка «Тестирование»)

Позволяет создать набор контрольных вопросов с ключевыми словами и автоматически прогнать их через ИИ в изолированном тестовом режиме (без отправки реальным клиентам):

- **Создание и сохранение тестов**: можно создать несколько сценариев тестирования (например, «Консультация по тарифам», «Оформление заказа», «Вопросы по доставке»).
- **Добавление вопросов**:
  - Вручную, указывая вопрос и ожидаемые ключевые слова через запятую.
  - Автоматической генерацией вопросов по содержимому вашего сайта (по URL).
  - Импортом из переписок бота с реальными клиентами.
  - Загрузкой готового файла CSV (до 100 Кб).
- **Проверка точности**: система проверяет, содержит ли ответ ИИ ожидаемые слова, выделяет совпавшие и пропущенные термины и рассчитывает итоговый процент успеха (например, `Результат: 100% (12/12)`).
- **Прозрачность базы знаний**: если подключена база знаний, под каждым ответом ИИ выводятся бейджи с названиями документов и точными цитатами, на основании которых нейросеть сформировала ответ.
- **Исправление ответов на месте**:
  - Если ответ неверный, нажмите **«Исправить»**.
  - **«Править промпт»** — ИИ сам проанализирует ошибку и дополнит системную инструкцию нужным правилом.
  - **«В базу знаний»** — сохранит пару «вопрос — правильный ответ» прямо в базу знаний бота, не перегружая системный промпт.

### 3. Мульти-тестирование сразу нескольких нейросетей

В верхней панели можно подключить до 5 различных моделей (например, *OpenAI GPT-4o-mini*, *Claude Sonnet*, *Google Gemini Flash*, *Kimi* и др.) и одновременно запустить тест на одном наборе вопросов:

- **Сравнение качества**: переключайтесь между вкладками моделей, чтобы наглядно сравнить ответы разных нейросетей на одни и те же вопросы.
- **Сравнение скорости**: в результатах отображается точное общее время прохождения теста (например, `45 сек` или `1 мин 23 сек`).
- **Сравнение расхода токенов и стоимости**: плашка результатов показывает количество затраченных токенов и расчетную стоимость тестирования в долларах (например, `2 579 токенов • $0.0026`), вычисляемую по актуальным ценам за токен.
- **Применение лучшей модели в один клик**: выбрав модель с наилучшим балансом точности, скорости и стоимости, нажмите **«Применить для блока»**, и она сразу будет установлена в настройках блока.

---

## Связи на канвасе

- **Фиолетовое ребро** → нода после завершения диалога
- **Серые пунктирные рёбра 🛠️** → команды, вызываемые инструментами ИИ

---

## Советы

- **Один блок = одна задача.** Не пытайтесь собрать в одном диалоге слишком много разных данных.
- **Описывайте параметры точно.** От описания зависит, насколько правильно ИИ заполнит значение.
- **Тестируйте инструменты отдельно.** Убедитесь, что команда-инструмент корректно работает с тестовыми данными до подключения к ИИ.
- **Проверяйте базу знаний через вкладку «Тест».** Так можно заранее увидеть найденный текст и его источник.
- **Тестируйте несколько моделей.** Небольшие и быстрые модели (например, GPT-4o-mini, Gemini Flash или Kimi) часто справляются с задачами не хуже флагманских моделей, при этом работая быстрее и в разы дешевле.
- **Ограничение в 3 вызова.** За один ход ИИ может вызвать не более 3 инструментов подряд — чтобы избежать зацикливания.
- **Стриминг несовместим с кнопками и опросами.** Если разрешены inline/reply-кнопки или опросы — стриминговый режим отключается автоматически.
