Инструменты

Инструменты дают ассистенту доступ к вашим данным — без них ассистент отвечает только на основе промпта и своих общих знаний. Доступны три типа: DuckDB-файл, HTTP API и база данных (MySQL/PostgreSQL). Управляются все одинаково — на вкладке «Инструменты» ассистента, можно прикрепить несколько разных типов к одному ассистенту.

Уровень доступа инструмента

У каждого инструмента есть accessLevel, который определяет, в каких чатах он доступен:

Если инструмент помечен Personal, но чат гостевой (нет привязанного покупателя) — ассистент просто не увидит этот инструмент в списке доступных для этого конкретного разговора.

DuckDB-файл

Загружаете файл в разделе «Файлы инструментов» (это база данных DuckDB — компактная встраиваемая аналитическая БД, файл проверяется на валидность при загрузке). Один файл можно подключить к нескольким ассистентам. Ассистент получает возможность выполнять SELECT-запросы к этому файлу в read-only режиме — писать в файл или выполнять запросы к внешним ресурсам инструмент не может.

Пример использования: у вас есть таблица products(id, name, price, in_stock) — ассистент сможет отвечать на вопросы вроде «Сколько стоит товар X?» или «Что есть в наличии дешевле 1000?», самостоятельно формируя SQL-запросы к этой таблице.

HTTP API

Позволяет ассистенту вызывать ваш собственный API (или сторонний) для получения актуальных данных — например, статус заказа, наличие товара, данные из вашей CRM.

Структура

Один инструмент HTTP API содержит:

• Название и описание — для вашей навигации в личном кабинете (модель их не видит напрямую).
• Таймаут и максимум байт ответа — защита от медленных/тяжёлых ответов.
• Один или несколько эндпоинтов — каждый становится отдельной функцией, которую модель может вызвать.
• Заголовки авторизации — общие для всех эндпоинтов этого инструмента (например, Authorization: Bearer …).

Эндпоинт

Пример эндпоинта: «Проверить статус заказа» → GET https://api.example.com/orders/{orderId}, схема параметров {"type":"object","properties":{"orderId":{"type":"string"}}}.

Серверные параметры и приватность покупателя

Серверный параметр — это значение, которое подставляет платформа автоматически, а не модель. Сейчас поддерживается customer_id — идентификатор покупателя из приватного (sk_) чата. Это позволяет сделать эндпоинт вроде «Мои последние заказы», который модель вызывает без параметров, а платформа сама подставляет customer_id того покупателя, который сейчас пишет в чат — модель физически не может подставить туда чужой id, потому что этот параметр ей не виден.

Если серверный параметр не может быть разрешён (например, чат гостевой и покупателя нет) — такой эндпоинт просто не регистрируется для этого разговора, а не вызывается с пустым значением.

Заголовки авторизации — важный нюанс

Значения заголовков (например, API-ключ) шифруются и никогда не возвращаются в открытом виде после сохранения — при просмотре или редактировании инструмента вы увидите только имя заголовка.

При любом изменении набора инструментов ассистента значения всех заголовков авторизации нужно вводить заново — даже если вы меняете только один инструмент из пяти. Это не ошибка интерфейса: раз расшифровать старое значение невозможно, а сохранение заменяет весь список целиком, единственный надёжный способ — попросить ввести секрет заново. Личный кабинет предупреждает об этом перед сохранением и не даст сохранить пустое значение.

База данных (MySQL/PostgreSQL)

Прямой доступ к вашей собственной базе данных — по духу похож на HTTP API: вы задаёте один или несколько именованных запросов заранее, модель никогда не пишет и не видит SQL сама, только подставляет значения объявленных параметров.

Структура

• Тип БД — PostgreSQL или MySQL.
• Хост, порт, база, пользователь, пароль — креды шифруются at rest и никогда не возвращаются в открытом виде (тот же принцип, что заголовки авторизации HTTP API — при любом изменении инструмента их нужно вводить заново).
• Кнопка «Проверить соединение» — проверяет креды до сохранения, без сохранения самих кредов.
• Один или несколько именованных запросов — каждый становится отдельной функцией для модели.

Именованный запрос

Пример: именованный запрос «get_order_status» → SELECT status, updated_at FROM orders WHERE id = @order_id, модель вызывает его с {"order_id": "12345"} — сервер подставляет значение параметром, не текстом, поэтому SQL-инъекция через это поле невозможна.

Что не проверяется на сервере

Наивная проверка «один statement, только SELECT» — не полноценный SQL-парсер, поэтому дополнительно рекомендуем создать отдельного read-only пользователя БД специально для этого подключения (GRANT SELECT ...) — второй эшелон защиты, который сервер технически не может проверить сам.