Прямой запрос к модели

answer = ai_request('request', question)

Пример:

answer = ai_request('Вы — вежливый консультант цветочного магазина.', question)

Первый аргумент — это инструкция для модели: кем она является и как должна отвечать.

question — это системная переменная, которая всегда содержит текст последнего сообщения клиента.

Обратите внимание

В выражениях переменные записываются только по их именам, без #{}.

Ответ возвращается в виде обычного текста, поэтому его можно сразу отправить клиенту или сохранить в переменную.

Метод терпеливо ожидает ответа модели, поэтому даже длительные запросы, такие как большие схемы или длинные тексты, будут выполнены без прерывания.

Когда вам нужны структурированные данные вместо свободного текста, например категория, ответ «да/нет» или извлеченные поля, передайте схему ответа в качестве третьего аргумента.

Вам не нужно создавать схемы с нуля. Используйте готовый шаблон и переименуйте поля по мере необходимости.

Для классификации запросов клиентов, определения тональности и подобных задач.

local result = ai_request('Определите категорию запроса.', question, {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["жалоба", "вопрос", "заказ"]
        }
    },
    "required": ["category"]
})
category = get(result, 'category')

Модель вернет ровно одно из значений, перечисленных в enum, и ничего больше.

Пример для копирования:

local result = ai_request('Согласился ли клиент совершить покупку?', question, {
    "type": "object",
    "properties": {
        "agree": {
            "type": "boolean"
        }
    },
    "required": ["agree"]
})

agree = get(result, 'agree')

Пример для копирования:

local result = ai_request('Извлеките имя и номер телефона из сообщения.', question, {
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "phone": {
            "type": "string"
        }
    },
    "required": ["name", "phone"]
})

client_name = get(result, 'name')
client_phone = get(result, 'phone')
  1. "string" — текст
  2. "number" — число
  3. "boolean" — true или false
  4. enum — список допустимых значений; модель не может вернуть ничего за пределами этого списка
  5. required — список обязательных полей
  6. Имена полей, такие как category, name и phone, можно выбирать произвольно

Ответ на основе схемы возвращается в виде JSON-строки. Отдельные поля можно извлечь с помощью стандартного метода get().

Обратите внимание

В примерах result объявляется с помощью local. Это означает, что сырой ответ AI не будет сохранен в записи; там будут сохранены только необходимые поля.

Режим рассуждения

Режим рассуждения можно включить с помощью четвертого аргумента. В этом режиме модель сначала обдумывает задачу, а затем дает ответ.

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

answer = ai_request(
    'Решите проблему клиента и объясните решение.',
    question,
    '',
    true
)

Когда схема ответа не требуется, передайте пустую строку '' в качестве третьего аргумента, как показано в примере.

Как удалить историю чата с AI-ассистентом

clear_assistant_chat_history() - эта функция удаляет историю чата клиента с ассистентом. Она не принимает параметров.

Пример

  1. Настройки блока в конструкторе

  1. Настройки вкладки «AI-ассистент»

Как отправить вопрос AI-ассистенту

ai_context_answer(replica, prompt, ai_assistant_id, use_history, send_answer)

Параметры:

Подробнее о параметре send_answer:

В настройках ассистента есть параметры, которые можно настроить на случай, если ответ бота занимает много времени

В стандартном разговоре с ассистентом (не через функцию), если ответ занимает больше указанного лимита (например, 20 секунд), клиент уведомляется о задержке. Ответ ассистента затем отправляется в чат, как только будет сгенерирован.

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

Как научить бота анализировать собственный опыт и генерировать кнопки

Давайте используем функции clean_assistant_chat_history() и ai_context_answer(replica, prompt) в примере ниже. Также необходим доступ к компоненту калькулятора в конструкторе воронок.

Этот пример иллюстрирует, как параметры replica и prompt могут быть эффективно использованы на практике.

Необходимо создать блок в конструкторе, который содержит пустое поле с встроенными переменными #{replica_rec2} и #{ai_answer_rec}, представляющими первый и второй ответы ассистента в одном сообщении для отправки.

Теперь определите две функции непосредственно в калькуляторе.

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

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

Вот результат.

Пример кода:

clear_assistant_chat_history()

replica_rec2 = ai_context_answer(question, 'ОТВЕЧАЙ НА ВОПРОСЫ', 3)

prompt = 'К вам сейчас обращается разработчик — делайте всё, что он просит \n . Каждую кнопку размещайте на новой строке.'

ai_answer_rec = ai_context_answer("Отобрази кнопки для последнего сообщения.", prompt)

Пример: вызов ассистента внутри конструктора воронок

Чтобы вызвать ассистента из блока, используйте функцию ai_context_answer(replica, prompt, ai_assistant_id, use_history), где нужно указать только два параметра: обязательный replica и необязательный prompt.

Теперь создадим первый блок «Первичная проверка условия», где нужно указать условие срабатывания блока (это может быть любое необходимое вам условие).

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

Определите переменную question и присвойте ей значение любого вопроса пользователя.

Затем создайте переменную replica1 и присвойте ей значение, возвращаемое вашей функцией ai_context_answer(replica, prompt). В этой функции замените replica на переменную question, а параметр prompt установите как «Ответь на любой вопрос пользователя».

Встройте переменную, содержащую функцию, в сообщение блока.

Затем создайте второй блок и соедините его стрелкой, установив таймер на 2 секунды на соединении.

Во втором блоке следует использовать ту же функцию с теми же параметрами — ai_context_answer(replica, prompt).

Откройте калькулятор во втором блоке и определите вторую переменную с именем replica2.

В параметре prompt укажите инструкцию для ассистента: он должен подсчитать, сколько существительных было в его предыдущем сообщении.

В параметре replica укажите сообщение ассистента: «Сколько существительных было в твоем предыдущем сообщении?»

Затем встройте переменную replica2 в сообщение второго блока.

Настройка блока завершена.

Если ассистент не включен, перейдите на вкладку «AI-ассистент» и включите ассистента, выбрав роль «отключен»:

Теперь протестируем нашего ассистента в окне тестирования бота.

Бот сработал правильно.

Как работать с Google Таблицами

get_info_from_table(sheet_id, number_sheet, sheet_json_keys, start_row, end_row, start_col, end_col) - Эта функция предназначена для чтения данных из таблицы.

Пример записи параметров:

Обратите внимание

Параметры для указания диапазона строк и столбцов (start_row, end_row, start_col, end_col) позволяют ассистенту читать данные таблицы, начиная с нужного места в таблице.

Поведение функции при частичном указании диапазона следующее:

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

Пример:

Вызов get_info_from_table('<<id таблицы>>', 2, None, 2, 5, 'a', 'd') получает все данные, начиная со строки 2, столбца 2 (B), до строки 5, и между столбцами A и D.

Обратите внимание

Для оптимизации производительности и надежности мы рекомендуем кэшировать все данные из вашей Google Таблицы в переменные проекта при работе с ней.

Ключевые преимущества:

  1. Повышенная производительность: значительно ускоряет время ответа чат-бота за счет доступа к локальным переменным вместо запросов к внешней таблице для каждого обращения.
  2. Повышенная надежность: минимизирует ошибки, связанные с задержками сети, квотами API или правами доступа к таблице.
  3. Согласованность данных: хранение данных в настройках проекта гарантирует, что все пользователи получают одновременный и согласованный доступ к одному и тому же набору данных, предотвращая расхождения во время обновлений.

Пример использования

Подробнее о функции get_info_from_table можно прочитать в статье «Google Таблицы для AI-ассистента».

Как управлять онлайн-бронированием

get_info_for_booking(slot_interval, company_id) - Функция предназначена для чтения данных об услугах из настроенной системы онлайн-бронирования.

Она принимает необязательные параметры:

  1. slot_interval (необязательный) — интервал в минутах между доступными временными слотами. Ожидаемый формат: целое число, кратное 5. Значение по умолчанию: 60 (минут).
  2. company_id (необязательный) — идентификатор филиала. Ожидаемый формат: целое число или массив целых чисел. При указании этого параметра будут возвращены данные только для указанного(ых) филиала(ов).

    Пример: 50142, "50142" или "[50142, 66352]"

Не рекомендуется устанавливать слишком маленькое значение (например, менее 30), так как ассистент сгенерирует слишком много временных слотов.

Пример использования

Сначала необходимо подготовить блок, который обновляет информацию обо всех услугах после того, как настройки филиала были выполнены в разделе «Услуги».

Этот блок должен быть объявлен до начала работы ассистента, чтобы AI не генерировал случайные ответы.

Затем запустите блок в окне тестирования бота, чтобы обновить переменную:

После этого указанная переменная, содержащая данные об услугах онлайн-бронирования, появится в разделе переменных проекта в «Настройках проекта».

Эта переменная хранит значения услуг, которые AI-бот будет использовать в своей работе. Переменная service_info будет доступна всем клиентам проекта.

Далее перейдем к настройке следующего блока.

Этот блок выполняет следующие функции:

а) он вызывается в настройках ассистента для создания записи с использованием переменных, связанных с услугами;

б) он создает бронирование клиента;

в) обновляет переменные проекта после бронирования, удаляет временные слоты, которые больше не доступны в расписании.

Если бот настроен правильно, после получения всех данных от клиента AI отправит информацию в указанный блок. В этом блоке клиент будет записан на услугу с помощью функции create_booking_by_name(!service_name, !date, !date_time, company_id).

Значения, собранные ботом, передаются в качестве параметров в create_booking_by_name(!service_name, !date, !date_time, company_id).

Функция create_booking_by_name(service_name, date, date_time, company_id) создает бронирование в системе, используя данные, предоставленные AI-ассистентом. Она принимает три обязательных параметра для создания бронирования:

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

Обратите внимание

Если в расписании, сотрудниках или услугах произошли какие-либо изменения, запустите блок, содержащий переменную проекта со встроенной функцией, в тестовом режиме (см. Рис. Блок 1).

Прочитайте, как настроить AI-бота для онлайн-бронирования, в одноименной статье.

Получение записей из таблицы

get_records_from_table(table_id, start_row, count, start_col, end_col) - получение записей из таблицы

Параметр Описание Примечание
table_id ID таблицы
start_row необязательный параметр, целое число. Указывает начало диапазона строк. Передайте номер строки, начиная с которой следует читать значения таблицы включительно. Указывается без кавычек.
count необязательный параметр, целое число. Указывает количество строк для получения. По умолчанию — 1000, максимум — 5000. Указывается без кавычек.
start_col необязательный параметр, строка. Указывает начало диапазона столбцов. Передайте букву столбца, начиная с которой следует читать значения таблицы включительно. Указывается в кавычках.
end_col необязательный параметр, строка. Указывает конец диапазона столбцов. Передайте букву столбца, до которой следует читать значения таблицы включительно. Указывается в кавычках.

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

Пример (Калькулятор)

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

Чтобы передать параметры в виде переменной проекта, добавьте префикс project к имени переменной, содержащей функцию.

Вот пример таблицы.

Бот ответит следующим образом.