Тарифы Standard & Pro
Обзор
Пользовательские инструменты позволяют вашему AI-агенту вызывать ваши собственные API-эндпоинты во время разговора, чтобы получать актуальные данные, относящиеся к конкретному запросу, — статус заказа, отслеживание доставки, наличие конкретного SKU, сведения об аккаунте и многое другое.
Asyntai предлагает три способа передавать AI актуальные или относящиеся к клиенту данные. Пользовательские инструменты — правильный выбор, когда нужное AI значение появляется только во время разговора:
- Поток данных в реальном времени — загружает один фиксированный набор данных (например, весь ваш каталог товаров) в каждый разговор. Лучше всего подходит для общих данных, одинаковых для всех посетителей.
- Контекст пользователя — ваш сайт передаёт данные, которые он уже знает о текущем посетителе (например, имя авторизованного клиента, тариф или недавние заказы), в начале чата. Лучше всего подходит, когда посетитель идентифицирован заранее.
- Пользовательские инструменты — AI вызывает ваш эндпоинт по требованию, передавая значения, которые он извлекает из чата. Лучше всего подходит, когда значение неизвестно до тех пор, пока клиент его не введёт, — например, номер заказа от анонимного посетителя.
Например, когда клиент спрашивает «Где мой заказ #10294?», AI извлекает номер заказа, вызывает с ним ваш эндпоинт и отвечает на основе проверенного ответа. Контекст пользователя сам по себе не охватывает этот случай, поскольку номер заказа неизвестен до середины разговора, — именно здесь и нужны пользовательские инструменты. (Многие магазины используют Контекст пользователя для авторизованных посетителей и пользовательский инструмент для разовых запросов.)
AI решает, когда вызывать инструмент, на основе написанного вами описания. Вы решаете, что делает инструмент, указав ему ваш эндпоинт. Asyntai выполняет вызов на стороне сервера — вам не нужно писать код или размещать промежуточное ПО.
Как это работает
- Вы определяете инструмент — имя, описание, URL вашего эндпоинта и параметры, которые AI должен отправлять.
- AI вызывает его при необходимости — когда разговор соответствует вашему описанию, AI вызывает инструмент со значениями, которые он извлекает из сообщения клиента.
- Asyntai вызывает ваш эндпоинт — наш сервер выполняет HTTP-запрос к вашему URL и передаёт ответ обратно AI.
- AI отвечает — используя проверенные данные, которые вернул ваш эндпоинт.
Код не требуется: вам нужен только эндпоинт, который уже возвращает ваши данные. Всё остальное вы настраиваете в форме на панели управления — не нужно создавать никаких колбэков, вебхуков или браузерных скриптов.
Примеры использования
Статус заказа
Найти заказ по номеру и вернуть его текущий статус
Отслеживание доставки
Вернуть последнее состояние отслеживания по трек-номеру
Проверка наличия
Вернуть актуальную доступность для конкретного товара или SKU
Поиск аккаунта
Вернуть сведения об аккаунте или подписке по идентификатору
Настройка
1
Откройте «Пользовательские инструменты»
Перейдите в /custom-tools/ и нажмите Добавить инструмент
2
Опишите инструмент
Задайте имя, понятное описание и URL вашего эндпоинта
3
Определите параметры
Добавьте входные данные, которые AI должен извлекать и отправлять (например, order_number)
4
Сохранить & протестировать
Сохраните, затем задайте боту подходящий вопрос, чтобы увидеть работу инструмента
Поля
- Имя — идентификатор функции (буквы, цифры, подчёркивания), например
get_order_status. AI видит это имя.
- Описание — самое важное поле. Оно сообщает AI, когда вызывать инструмент. Будьте конкретны: «Вызывай его всякий раз, когда клиент упоминает номер заказа. Не запрашивай подтверждение».
- URL эндпоинта — публичный HTTPS-URL, который будет вызывать Asyntai.
- Метод HTTP —
GET (только чтение, рекомендуется) или POST (может изменять данные — см. раздел «Безопасность» ниже).
- Параметры — входные данные, которые AI извлекает из разговора и отправляет. У каждого есть имя, тип, описание и флаг обязательности. Для
GET они отправляются как параметры строки запроса; для POST — как тело JSON.
- Заголовок авторизации (необязательно) — имя заголовка + значение, отправляемые при каждом вызове, например
X-API-Key. Используйте его, если вашему эндпоинту требуется ключ.
Параметры необходимы, чтобы AI мог передать какое-либо значение. Если вашему эндпоинту требуется входное значение (например, номер заказа), вы обязаны добавить для него параметр — без него у AI нет места, куда поместить значение, и он вызовет эндпоинт пустым. Важны две вещи:
- Имя параметра должно точно совпадать с тем, что ожидает ваш эндпоинт. Параметр с именем
order_number отправляется как ?order_number=... (GET) или {"order_number": "..."} (POST). Если ваш эндпоинт читает id, назовите параметр id.
- Вы никогда не вводите значение сами — вы только объявляете параметр. AI заполняет его во время вызова на основе того, что написал клиент.
Разобранный пример: поиск статуса заказа
Предположим, что ваш магазин предоставляет такой эндпоинт:
GET https://yourstore.com/api/order-status?order_number=10294
…который возвращает JSON вида:
{
"found": true,
"status": "Accepted, preparing for shipment",
"carrier": "DHL",
"customer_message": "Your order has been accepted and is being prepared for shipment."
}
Вы настроили бы инструмент так:
- Имя:
get_order_status
- Описание: «Найти статус заказа клиента. Вызывай это сразу же, как только клиент укажет номер заказа, — не запрашивай дополнительное подтверждение. Используй возвращённое customer_message в своём ответе».
- URL эндпоинта:
https://yourstore.com/api/order-status
- Метод:
GET
- Параметр:
order_number (строка, обязательный) — «Номер заказа клиента, обычно от 8 цифр».
Когда клиент пишет «Как мой заказ #10294?», AI вызывает get_order_status(order_number=10294), Asyntai обращается к вашему URL с ?order_number=10294, и AI отвечает на основе полученного ответа.
Совет: AI отправляет значения, которые сам определяет, — вы никогда не заполняете их заранее. Делайте имена и описания параметров понятными, чтобы модель точно знала, что извлекать.
Что получает ваш эндпоинт и что должен возвращать
- Запрос:
GET с вашими параметрами в строке запроса или POST с телом JSON. Любой настроенный вами заголовок авторизации включается в запрос.
- Ответ: возвращайте JSON (предпочтительно) или обычный текст. Asyntai передаёт тело обратно AI. Поле, которое AI может цитировать напрямую, — например
customer_message, — работает хорошо.
- Не найдено / ошибки: возвращайте понятный ответ (например, объект JSON с
found: false и customer_message), чтобы AI мог отвечать правдиво, а не строить догадки.
Тестирование вашего инструмента
У каждого инструмента есть встроенная панель Протестировать этот инструмент на странице конфигурации, поэтому вы можете убедиться, что он работает, прежде чем им воспользуется какой-либо клиент, — и без отправки сообщения через бота.
- Введите примеры значений для параметров инструмента (например, реальный номер заказа).
- Нажмите Запустить тест. Asyntai вызывает ваш эндпоинт точно так же, как это сделал бы AI, — та же строка запроса или тело JSON, тот же заголовок авторизации, тот же 5-секундный таймаут и те же проверки безопасности.
- Вы сразу увидите результат: метку успеха/неудачи, статус HTTP, время ответа, точный URL, который мы вызвали, и необработанный ответ вашего эндпоинта (с форматированием, если это JSON).
Это работает и для несохранённых изменений, поэтому вы можете изменять URL, параметры или заголовок авторизации и повторно тестировать, пока эндпоинт не вернёт ожидаемый результат.
Примечание: тестирование инструмента POST действительно вызывает ваш эндпоинт и может изменить данные — панель тестирования предупреждает вас перед запуском. Для инструментов GET только для чтения беспокоиться не о чем.
Безопасность — обязательно прочитайте
Границей безопасности является ваш эндпоинт, а не AI. Виджет чата публичен, и посетитель может манипулировать AI, чтобы тот вызвал инструмент с любыми значениями. Это справедливо для любой системы вызова инструментов AI. Проектируйте ваш эндпоинт соответствующим образом:
- Предпочитайте GET / только чтение. Запросы на поиск (статус заказа, наличие, отслеживание) безопасно открывать. Именно поэтому GET используется по умолчанию.
- POST требует подтверждения. Поскольку POST может изменять данные, инструмент POST можно сохранить только после того, как вы установите флажок, подтверждающий, что вы единолично отвечаете за защиту и авторизацию запросов на вашем собственном эндпоинте. Никогда не подключайте возвраты, отмены, смену паролей или перемещение денежных средств, если только ваш эндпоинт самостоятельно не проверяет запрос.
- Защищайтесь от перебора. Если ключ поиска можно угадать (например, последовательные номера заказов), требуйте второй фактор — например, номер заказа и электронную почту из заказа, и проверяйте их совпадение, — чтобы посетитель не мог прочитать данные других клиентов, подбирая номера.
- Никогда не доверяйте аргументам AI. Проверяйте и авторизуйте каждый запрос на стороне сервера так, как будто он пришёл от анонимного злоумышленника, — потому что фактически так и может быть.
Проверка реальных вызовов
Как только ваш инструмент станет активным, каждый реальный вызов из разговора записывается в журнал. Для каждого вызова мы фиксируем имя инструмента, аргументы, отправленные AI, точный URL, к которому мы обратились, статус HTTP, ответ и длительность. Это позволяет вам убедиться, что инструмент сработал в реальном чате, и увидеть, что вернул ваш эндпоинт, не разбирая собственные журналы сервера. (Панель Протестировать этот инструмент выше предназначена для самостоятельной проверки настройки; этот журнал фиксирует то, что происходит во время реальных разговоров с клиентами.)
Ограничения & меры защиты
- До 10 инструментов на сайт.
- 5-секундный таймаут на вызов; размер ответов ограничен 10 КБ.
- Эндпоинты должны быть публичными URL-адресами
http(s). Частные, локальные (loopback) и адреса внутренней сети блокируются.
- Доступно на тарифах Standard и Pro.
- Тарификация: каждый вызов инструмента считается как одно дополнительное сообщение в вашем тарифе. Обычный ответ использует 1 сообщение; ответ, в котором ИИ вызывает инструмент, использует 2 (ответ плюс вызов инструмента), поскольку вызов инструмента требует дополнительного запроса к ИИ.
- Если вызов инструмента не удаётся (таймаут, ошибка, блокировка), AI получает об этом информацию и отвечает корректно — это не нарушит разговор.