Функції AI-асистента

Прямий запит до моделі

answer = ai_request('request', question)

Приклад:

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

Перший аргумент — це інструкція для моделі: ким вона є і як має відповідати.

question — це системна змінна, яка завжди містить текст останнього повідомлення клієнта.

Зверніть увагу

У виразах змінні записуються лише за їхніми назвами, без #{}.

Відповідь повертається у вигляді звичайного тексту, тому її можна одразу надіслати клієнту або зберегти у змінну.

Метод терпляче чекає на відповідь моделі, тому навіть тривалі запити, як-от великі схеми або довгі тексти, будуть виконані без переривань.

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

Вам не потрібно створювати схеми з нуля. Використовуйте готовий шаблон і перейменовуйте поля за потреби.

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

local result = ai_request('Визнач категорію запиту.', question, {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["complaint", "question", "order"]
        }
    },
    "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. Налаштування блоку конструктора

2. Налаштування вкладки 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 буде доступна всім клієнтам проекту.

Далі перейдемо до налаштування наступного блоку.

Цей блок виконує такі функції:

а) він викликається в налаштуваннях асистента для генерації запису за допомогою змінних, пов'язаних з послугами;

b) він створює запис клієнта;

c) оновлює змінні проекту після запису, видаляє слоти часу, які більше не доступні в розкладі.

Якщо бот налаштовано правильно, після отримання всіх даних від клієнта 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 до назви змінної, що містить функцію.

Ось приклад таблиці.

Бот відповість наступним чином.