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

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

Каждое подключение после создания получает статус: Загрузка, Готов или Ошибка. В сценарии можно использовать только подключения со статусом Готов.

Каталог подключений инструментов

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

Во время диалога Robovoice может обращаться к внешним MCP-серверам для получения информации. Подключение к такому серверу настраивается в этом разделе.
Обратите вниманиеПоддерживаются только MCP-серверы, работающие по HTTP/S. Локальные MCP-серверы STDIO не поддерживаются.
  1. Нажмите Добавить и выберите Готовый MCP.
  2. Заполните Имя, под ним будет видно подключение в списке и в сценарии.
  3. В поле MCP URL укажите URL-адрес MCP-сервера, который начинается с http:// или https://. Обратите внимание, адреса базы данных или страницы Swagger сюда не подходят.
  4. Нажмите Создать.
  5. Если серверу нужны заголовки (например, ключ доступа), добавьте их на карточке в блоке MCP Headers и нажмите Сохранить.

Сразу после создания Robovoice автоматически проверит подключение и покажет один из статусов:

  • Готов — подключение работает, его можно использовать в сценарии;
  • Загрузка — проверка ещё идёт;
  • Ошибка — подключиться не удалось, проверьте адрес и заголовки.

REST API to MCP

Во время диалога с абонентом сценарию может понадобиться обратиться к внешней системе (CRM, учётной системе, сервису записи и так далее) для получения или внесения информации. Вместо того чтобы писать специальную интеграцию и разрабатывать отдельные сервисы, достаточно передать Robovoice описание методов API: по нему платформа сама поймёт, как работать с этим API.

Для работы REST API to MCP нужно предоставить описание методов REST API в одном из форматов: OpenAPI, Swagger или коллекция Postman. Каждый доступный метод становится инструментом LLM модели. Для этого:

  1. Нажмите Добавить и выберите Rest API.
  2. Заполните Имя.
  3. Выберите один источник описания:
    • URL — прямой JSON или YAML либо страница Swagger. Сервис попробует найти спецификацию сам.
    • Файл — локальный OpenAPI, Swagger или коллекция Postman в JSON.
    • cURL — одна команда описывает один метод. Токен из заголовка Authorization не сохраняется. Следующие методы добавляются на карточке.
  4. В Base URL укажите адрес самого REST API. Поле можно оставить пустым, если правильный адрес уже есть в спецификации. Непустое значение — абсолютный http:// или https://.
  5. Нажмите Создать.
  6. Сразу скопируйте ключ X-API-Key. Он показывается один раз и в браузере не сохраняется. Этим ключом клиент обращается к созданному подключению.
  7. Откройте карточку. Ключ самого REST API запишите в заголовки, которые добавляются к запросу в API. При необходимости добавьте параметры адреса, которые уходят с каждым вызовом.
  8. Нажмите Подставить схему авторизации, если спецификация описывает схему. Секреты впишите вручную.
  9. Нажмите Перечитать OpenAPI, чтобы обновить список методов. Для подключения из файла кнопка перечитывает загруженную спецификацию.
  10. В списке методов снимите доступность с методов и аргументов, которые модель не должна видеть. Скрытый метод или аргумент вызвать нельзя.
  11. Нажмите Сохранить.

Кнопка Добавить из cURL есть только у подключения, созданного из файла или cURL. Если источник — адрес спецификации, методы берутся из неё при перечитывании.

Кнопка Сменить ключ MCP выпускает новый X-API-Key. Прежний ключ сразу перестаёт работать. Новый ключ тоже нужно сохранить сразу.

Подключение к табличным данным

В качестве источника данных, к которому Robovoice может обращаться во время диалога, может выступать обычная таблица: файл Excel, документ CSV или таблица Google Sheets в облаке.

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

Excel или CSV
  1. Нажмите Добавить и выберите Таблица.
  2. В поле источника выберите Файл Excel/CSV.
  3. Заполните Имя и выберите файл.
  4. Нажмите Создать и дождитесь статуса Готов.

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

Google Sheets
  1. В Google Cloud включите Google Sheets API, создайте сервисный аккаунт и скачайте ключ JSON.
  2. Нажмите Добавить, затем Таблица и выберите источник Google Sheets.
  3. Заполните Имя.
  4. В поле Идентификатор таблицы вставьте ID или полную ссылку. ID — фрагмент адреса между /d/ и следующим /.
  5. В поле Сервисный аккаунт JSON вставьте содержимое скачанного ключа. Это ключ сервисного аккаунта, а не пароль личного аккаунта Google.
  6. В Google Таблице откройте настройки доступа и выдайте роль читателя адресу из client_email этого JSON. Доступ по ссылке это не заменяет.
  7. Нажмите Создать и дождитесь статуса Готов.

Если поиск не находит строку, в этой таблице нет подходящей записи. В промпте узла LLM попросите при пустом результате обратиться к другому подключённому источнику.

Подключение к базам данных

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

Поддерживаемые СУБД:

  • PostgreSQL;
  • Microsoft SQL Server.

Модель видит только те таблицы и колонки, которые вы оставили ей доступными.

  1. Нажмите Добавить и выберите База данных.
  2. Заполните Имя и выберите Провайдер: PostgreSQL или SQL Server. После создания провайдер не меняется.
  3. Вставьте Строку подключения. Кнопка Вставить пример подставляет шаблон: замените в нём сервер, имя базы, пользователя и пароль. Пример никуда не уходит, пока вы сами не создадите подключение.
  4. Нажмите Создать.

После сохранения строка подключения скрыта. Пустое поле при редактировании оставляет прежнее значение. Новый текст заменяет строку целиком.

Описание структуры базы данных

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

  1. На карточке нажмите Перечитать структуру БД. Уже введённые описания сохраняются.
  2. Откройте Редактор структуры БД.
  3. Для каждой нужной таблицы заполните Описание таблицы: какие данные в ней хранятся и в каких случаях их следует использовать.
  4. Выберите Режим доступа: Только чтение запрещает изменение данных, Чтение и запись разрешает добавление, изменение и удаление.
  5. Снимите признак Доступен модели у таблиц и колонок, которые модель не должна видеть.
  6. Для колонок заполните описание. Кнопка Пример строк показывает несколько строк, чтобы сверить данные.
  7. Сохраните разметку.

Кнопка Создать название и описания полей заполняет пустое название таблицы и колонки без описания. Уже написанный текст она не меняет. Для этого в настройках помощника заранее выберите подключение к LLM для авторазметки.

Встроенные операции: просмотр списка сущностей, описание сущности, выборка, добавление, изменение и удаление. Добавление, изменение и удаление работают только у таблиц с режимом Чтение и запись. Изменение и удаление требуют фильтра.

Именованные инструменты

Именованный инструмент — отдельная команда, которую модель вызывает по имени. Откройте Именованные инструменты.

  1. Нажмите Новый или подставьте пример в форму.
  2. Задайте Имя (MCP) латиницей в нижнем регистре. Имя не должно совпадать со встроенными list_entities, describe_entity, select, insert, update и delete.
  3. Выберите Тип операции: выборка, добавление, изменение или удаление.
  4. В описании объясните, что делает инструмент и когда его вызывать.
  5. Добавьте параметры. Имена — camelCase или snake_case.
  6. В Шаблон команды (JSON) укажите команду с плейсхолдерами в двойных фигурных скобках. Сервер подставит значения параметров.
  7. Оставьте инструмент включённым и сохраните его. Выключенный инструмент остаётся в списке, но модель его не вызывает.

Подключение базы знаний

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

Поддерживаемые форматы: TXT, MD, HTML, PDF, DOC, DOCX, FB2, EPUB. Документ должен содержать текстовый слой.

Обратите вниманиеДокументы без текстового слоя (например, сканы в PDF) сейчас не загружаются. Если нужно загрузить такие документы, обратитесь в техническую поддержку.

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

  1. Нажмите Добавить и выберите Документы.
  2. Заполните Имя и Описание базы знаний. Описание видит модель: кратко напишите, какие документы лежат в базе.
  3. Выберите Профиль эмбеддинга. После первой индексации модель эмбеддинга фиксируется; чтобы сменить её, запустите повторную индексацию.
  4. При необходимости выберите Профиль аннотации. Он придумывает название и краткое содержание документа.
  5. Нажмите Создать.
  6. На карточке нажмите Выбрать файлы и добавьте документы.
  7. Нажмите Загрузить и проиндексировать. Сам выбор файлов ничего не отправляет.
  8. Дождитесь статуса файла Готов. Промежуточные статусы: Ожидает и Индексация. При сбое статус будет Ошибка.

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

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

Выбор и использование настроенного инструмента в LLM-узле при настройке сценария

  1. Убедитесь, что нужный инструмент настроен в разделе AI и его статус Готов.
  2. Откройте сценарий, перейдите в Настройки, выберите вкладку AI и выберите подключение в поле LLM узлов. Сохраните настройки.
  3. На схеме выберите узел LLM.
  4. В поле MCP-серверы нажмите Добавить, выберите подключение из каталога и подтвердите. Одно и то же подключение второй раз в список не добавляется. Лишнюю запись можно удалить.
  5. В промпте объясните, когда вызывать инструмент и что делать, если он вернул пустой или ошибочный результат.
  6. Сохраните узел, сохраните сценарий и нажмите Опубликовать.
  7. В чате задайте вопрос, для ответа на который нужен выбранный инструмент.
Найди заказ по номеру {~Номер заказа~}.
Используй инструмент только для чтения.
Если заказ не найден, сообщи об этом без догадок.

Если каталог недоступен, в свойствах узла появится сообщение «MCP-серверы недоступны», и добавить подключение нельзя. Если каталог пуст — «В каталоге нет MCP-серверов».

Если что-то не работает

СимптомЧто проверить
Подключений нетНажмите Добавить и создайте подключение нужного типа.
Статус Ошибка или ЗагрузкаПроверьте адрес, файл, ключ, спецификацию или строку подключения. Если ошибка не уходит, создайте подключение заново.
Инструмент нельзя выбратьОбновите каталог, убедитесь, что статус Готов, и заново откройте сценарий.
«MCP-серверы недоступны»Каталог сейчас не открывается. Добавить подключение в узел можно будет после его загрузки.
Инструмент не вызываетсяПроверьте подключение в поле LLM узлов, выбранный инструмент, промпт и публикацию сценария.
Ключ REST API потерянX-API-Key показывается один раз. Нажмите Сменить ключ MCP и сохраните новый ключ.
Метод API не виден моделиНа карточке REST API включите доступность метода и нужных аргументов, затем сохраните.
Поиск по таблице пустойВ таблице нет подходящей строки. Проверьте файл или доступ к Google Sheets и при необходимости подключите другой источник.
Строка подключения к БД не виднаПосле сохранения она скрыта. Пустое поле её не меняет. Чтобы заменить доступ, вставьте новую строку целиком.
Модель не видит таблицу базыВ редакторе структуры включите Доступен модели и выберите нужный режим доступа.
Документы выбраны, но не ищутсяНажмите Загрузить и проиндексировать и дождитесь статуса Готов. Повторная индексация новые файлы не добавляет.
Нет вкладки ДокументыИспользование базы знаний на этом стенде недоступно. Обратитесь к ответственному менеджеру или в техническую поддержку.
Робот молчитВ промпте попросите озвучить результат инструмента. Сохраните и опубликуйте сценарий.
Желаем удачи!
Команда Robovoice.
Остались вопросы?
Посмотрите Наши видео-инструкции или отправьте Ваш вопрос менеджеру Robovoice

Общие частые вопросы