Все гайды
Продвинутый уровень Продвинутый уровень 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 (на английском).