Усі гайди
Досвідчений рівень Досвідчений рівень 30 хв читання

Кастомні Client Tools

Дайте AI-агенту кастомні функції: запити до БД, виклики сторонніх API, бізнес-логіка.

Що роблять client tools

Client tools дають вашому голосовому AI-агенту змогу діяти на вашому сайті просто під час розмови. Це JavaScript-функції на вашій сторінці, які агент може викликати, поки говорить: він передає значення, почуті від відвідувача, і озвучує результат. Типові приклади: пошук у каталозі, застосування промокоду, перехід до потрібного розділу, додавання товару в кошик.

Client tools працюють із провайдером Web SDK каналу Calls, тобто з голосовою кнопкою в браузері, для якої не потрібен номер телефону. Виконуються вони в браузері відвідувача, а не на ваших серверах, а обробник — це ваш власний код сторінки, наприклад логіка кошика.

Що потрібно заздалегідь

  • Агент з інструкціями та базою знань. Голосовий агент збирається з них у момент підключення каналу.
  • Доступ до HTML сайту або JavaScript-збірка, якщо зручніше працювати через npm.
  • Короткий перелік дій на сторінці й точна функція, яку має запускати кожна з них.
  • Браузер із мікрофоном для перевірки. Відвідувачі мають дозволити доступ до мікрофона.

Дзвінки через Web SDK потрапляють у чат клієнта з транскриптом і записом і тарифікуються за тими самими ставками, що й телефонні.

Налаштування крок за кроком

  1. Відкрийте Channels, виберіть агента й відкрийте канал Calls.
  2. У полі Provider виберіть Web SDK.
  3. Оберіть голос у Voice (Optional) (прослухайте через Play preview) і налаштуйте спільні параметри: First Message, LLM, Speech Speed, Max Call Duration (minutes), Additional languages.
  4. Натисніть Create SDK Agent і скопіюйте Agent ID з блоку Connection Details.
  5. Увімкніть Connect agent to this channel. Нові канали Calls створюються вимкненими.
  6. Вставте код вбудовування на сторінку: тег зі скриптом calls.js і виклик MyChatBotCalls.mount з вашим agent_id та, за бажанням, name.
  7. Додайте до виклику об’єкт client_tools. Кожен ключ у ньому — назва інструмента, наприклад applyDiscountCode, з двома частинами: definition (опис description і parameters) та handler — функція, що отримує параметри й повертає результат.
  8. Відкрийте сторінку, натисніть кнопку мікрофона й попросіть уголос виконати дію. Переконайтеся, що сторінка зреагувала.

Якщо ви налаштовували агента через конектор MyChatBot у Claude, попросіть у Claude код вбудовування: він поверне його вже з вашим справжнім Agent ID.

Важливі параметри

  • Parameters — плоский об’єкт. Кожна назва параметра відповідає набору type, description і required, де type — string, number або boolean. JSON Schema з типом object і properties відхиляється, а сторінка працює далі, ніби нічого не сталося: дзвінок з’єднується, але агент так і не отримує інструмент.
  • Повертайте коротке підтвердження. Усе, що повертає обробник, озвучується в розмові, тож поверніть щось на кшталт Applied SPRING10, 10% off, а не порожнє значення.
  • Точні описи. Агент читає definition, тому поясніть, що робить інструмент і що означає кожен параметр.
  • Параметри вбудовування. Усе, крім agent_id, необов’язкове: color, position (bottom-right або bottom-left), target для показу всередині елемента, transcript (collapsed, open або off), а також колбеки onCallStart і onCallEnd.
  • npm. У JavaScript-збірці встановіть @mychatbot/client і передайте ті самі інструменти як clientTools у start(), з ідентифікатором абонента з defaultCallerId().

Типові проблеми та рішення

  • Агент не користується інструментом. Спершу перевірте формат parameters: JSON Schema замість плоского об’єкта мовчки прибирає інструмент. Потім зробіть опис конкретнішим.
  • Інструмент спрацьовує, але агент нічого корисного не каже. Обробник нічого не повертає. Додайте коротке підтвердження.
  • Дія на сторінці не виконується. Перевірте, що обробник інструмента пов’язаний із відповідною функцією сторінки, наприклад кошика чи навігації.
  • Дзвінок не починається. Сторінка має залишатися відкритою, а відвідувач — дозволити мікрофон. Також перевірте, що Connect agent to this channel увімкнено, а Agent ID збігається з Connection Details.
  • Агент відповідає за старими інструкціями. Після змін натисніть Sync Agent. База знань — це знімок на момент створення каналу, тож щоб змінити інтеграції, які живлять агента, канал Calls доведеться створити заново.
  • Вам потрібні передача дзвінка оператору, автоматичний повторний дзвінок або вихідні дзвінки. Це можливо лише для телефонії: використовуйте SIP Trunk або Twilio Account.

Що почитати далі

Повна документаціяДокладніше в документації на docs.mychatbot.app (англійською).