Wiki › База знаний

Как создать ИИ-агента на SamBot

Представьте ситуацию. Клиент пишет в чат: «Расскажите про мой заказ номер 12345», «Какой у меня остаток на счёте?», «Запишите меня на стрижку в субботу», «Подпишите на рассылку». Обычный ИИ-чат на это не ответит: знания модели и промпт не дают ей ни доступа к данным в ваших системах, ни возможности что-то изменить.

Это решают функции. Каждая — понятный инструмент с человекочитаемым описанием. Один — чтобы запросить данные у вашего API (заказ, остаток, расписание). Другой — чтобы записать состояние клиента в SamBot (обновить параметр, поставить метку). Третий — чтобы передать диалог менеджеру. ИИ сам решает, какой инструмент применить и с какими аргументами, выполняет его, и формулирует финальный ответ с учётом результата. Это превращает ИИ-чат в ИИ-агента: бот не только говорит, но и делает.

Эта возможность работает в интеграции OpenAI Assistants. Если используете другую интеграцию ИИ — функции ему недоступны, но ИИ-сообщение продолжит работать как раньше.

Что такое функция

Функция — это бизнес-действие, которое вы даёте в распоряжение ИИ. У каждой есть название (короткое имя для ИИ), описание словами — что она делает (по описанию ИИ понимает, когда её вызывать), и опционально — список аргументов, которые ИИ может передать в функцию.

В SamBot два типа функций:

  • Внешняя — ИИ обращается к вашему сайту/API. Например, узнать остаток товара по запросу к вашей CRM. Возвращает данные, которые ИИ использует в ответе.
  • Внутренняя — ИИ действует прямо в SamBot, без вашего сервера. Имеет до трёх независимых эффектов — любая комбинация:
    • Сохранить параметры пользователя — записать значения в параметры клиента сразу, ещё до ответа ИИ.
    • Запустить реакцию в фоне — дополнительные действия (уведомление менеджеру или в другой чат, цепная реакция, метки). ИИ не ждёт её завершения.
    • Ответ ИИ — заранее заготовленный текст с подстановками, который уйдёт обратно в модель.

Две схемы дополняют друг друга: внешняя — чтобы получить актуальные данные из ваших систем, внутренняя — чтобы дать ИИ управлять состоянием клиента в SamBot без своего сервера.

Аргументы функции

ИИ может передать в функцию аргументы — если вы их объявите. Каждый аргумент: имя, тип (строка / число / целое / булево), описание словами и флаг обязательный. Описание подсказывает ИИ, какое значение туда подставить.

Где использовать значения аргументов:

  • В URL внешней функции: https://api.example.com/orders/{arg:order_id} — значения подставляются в адрес автоматически.
  • В значении сохраняемого параметра пользователя: например, в параметр cart_total можно записать {arg:total}.
  • В тексте ответа ИИ: «Товар {arg:item_name} добавлен в корзину».

Что происходит при срабатывании

Поток одинаков, мессенджер не имеет значения:

  1. Клиент пишет произвольное сообщение.
  2. SamBot отправляет сообщение ИИ и вместе с ним передаёт список ваших функций — названия, описания и аргументы.
  3. ИИ решает: ответить просто текстом или сначала вызвать функцию. Если решает вызвать — сообщает SamBot, какую именно и с какими аргументами.
  4. Дальше зависит от типа функции:
    • Если внешняя — SamBot подставляет аргументы в URL, отправляет HTTP-запрос и получает ответ.
    • Если внутренняя — SamBot сразу записывает заявленные параметры пользователя (значения с подстановкой {arg:NAME}), запускает реакцию в фоне и формирует текст ответа из шаблона.
  5. Полученный результат уходит обратно в ИИ — и тот формулирует финальный ответ клиенту, учитывая результат вызова.

Ключевой момент: блок «Сохранить параметры пользователя» применяется синхронно — значения уже в БД, когда SamBot формирует текст ответа ИИ. Поэтому в ответе можно безопасно использовать {user:NAME} — ИИ увидит свежее значение.

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

Полезные паттерны

1. Параметр + ответ

Внутренняя функция сохраняет параметр пользователя и возвращает ИИ свежее значение в ответе. Классический пример — взять у клиента телефон для обратной связи:

  • Название: save_callback_phone
  • Описание: «Сохраняет номер телефона клиента, на который ему перезвонить»
  • Аргументы: phone (строка, обязательный) — номер в формате, который написал клиент
  • Сохранить параметры: callback_phone — режим «Хранить последнее значение», значение {arg:phone}
  • Ответ ИИ: «Записал номер {user:callback_phone}, менеджер свяжется в течение часа»

Клиент: «Перезвоните мне на 8-900-123-45-67». ИИ: «Записал номер 8-900-123-45-67, менеджер свяжется в течение часа». Параметр callback_phone сохранён в карточке клиента — дальше он виден на странице пользователей и доступен в других реакциях.

2. Действие в фоне

Реакция запускается в фоне для дополнительных действий — уведомление менеджеру или в другой чат, цепная реакция. ИИ ответ ИИ — подтверждение клиенту:

  • Название: escalate_to_manager
  • Описание: «Передаёт диалог менеджеру — когда клиент просит человека или жалуется»
  • Вызвать реакцию: «Уведомить менеджера» (отправляет в управляемый чат)
  • Ответ ИИ: «Передал ваш вопрос менеджеру — он скоро подключится»

Клиент: «Хочу поговорить с живым человеком». ИИ: «Передал ваш вопрос менеджеру — он скоро подключится. Пока могу ответить на другие вопросы». Параллельно менеджер получает уведомление в чате.

3. Справочная функция

Без действий, только заготовленный текст для ИИ. Полезно для FAQ-данных, которые меняются редко:

  • Название: get_company_info
  • Описание: «Возвращает контакты и адрес компании»
  • Ответ ИИ: «Адрес: Казань, Баумана 12. Телефон: 8-800-000-00-00. Часы работы: пн-пт 9–19»

Клиент: «А где вы находитесь и до скольки работаете?». ИИ получает данные и отвечает в натуральной формулировке — на языке клиента, с учётом контекста разговора.

4. Внешняя функция с аргументами

ИИ передаёт значения в ваш сервис, тот возвращает данные:

  • Название: find_order
  • Описание: «Находит заказ клиента по номеру»
  • Аргументы: order_id (строка, обязательный)
  • URL: https://crm.example.com/api/orders/{arg:order_id}

Клиент: «Где мой заказ 12345?». ИИ обращается к https://crm.example.com/api/orders/12345, получает статус и формулирует ответ.

Когда какую делать

  • Нужны данные из вашей системы (CRM, ERP, склад, своё API) — делайте внешнюю.
  • Нужно обновить состояние клиента в SamBot или запустить готовый сценарий (реакцию) — делайте внутреннюю.
  • Часто полезно несколько функций сразу — ИИ сам выберет нужную или вызовет несколько последовательно.

Сборка по шагам

  1. В разделе «Интеграции» создайте интеграцию OpenAI — Assistants: API-ключ и ID ассистента.
  2. В нужной реакции включите действие «4.1. Отправить сообщение» и добавьте сообщение типа «+ИИ», выберите эту интеграцию.
  3. В настройках ИИ-сообщения включите галку «Обработать функции».
  4. Нажмите «Добавить обработку функции» — откроется окно.
  5. Заполните Название (например, add_to_cart) и Описание словами.
  6. Если функции нужны входные данные от ИИ — нажмите «Добавить аргумент»: имя, тип, описание (для ИИ), флаг «Обязательный». Подставлять значения в другие поля можно будет через {arg:NAME} — из списка подстановок (группа «Аргументы функции» появляется наверху).
  7. Выберите Тип — «Внешняя» или «Внутренняя».
  8. Для «Внешней» укажите URL веб-сервиса (можно с {arg:NAME}).
  9. Для «Внутренней» включите нужные галки — любую комбинацию:
    • «Сохранить параметры пользователя» — список параметров с значениями (можно с {arg:NAME}). Применяются сразу.
    • «Вызвать реакцию» — реакция из списка. Запустится в фоне, ИИ её завершения не ждёт.
    • «Ответить ИИ» — текст с подстановками ({arg:NAME}, {user:NAME} и т. д.).
  10. Сохраните. Можно добавить несколько функций — ИИ сам выберет нужную в момент диалога.

Главное правило: описание функции — это инструкция для ИИ, когда её вызывать. Чем понятнее описание, тем чаще и точнее ИИ использует функцию. Если ИИ не вызывает функцию, хотя по контексту должен — сделайте описание подробнее.

Что хорошо работает как внутренняя функция

Любые быстрые действия, после которых вы либо обновили состояние клиента, либо запустили готовый сценарий:

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

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

Примеры применения

  • Поддержка — find_ticket (внешняя, в вашу систему тикетов), escalate_to_manager (внутренняя, передача в управляемый чат), mark_priority_client (внутренняя, метка приоритета).
  • Запись на услуги — check_slot_available (внешняя, проверка свободных слотов), book_slot (внешняя, оформляет бронь), cancel_appointment (внешняя, отмена).
  • Магазин — find_product (внешняя, поиск в каталоге), get_delivery_info (справочная функция со статичным текстом), subscribe_newsletter (внутренняя, метка для рассылок).
  • Образование — get_homework (внешняя, по API школы), mark_lesson_completed (внутренняя, метка), request_certificate (внутренняя, заявка в админский чат).

Один промпт «ты консультант магазина X, при просьбе оформить заказ вызывай create_order» заменяет десятки реакций по ключевым словам. Бот понимает синонимы, парафразы, сложные контексты, а не только заранее прописанные шаблоны.

Похожие статьи