Кастомные инструменты (HTTP-tools)
Подключите любой внешний API к агенту — CRM, склад, расчёт цен, база знаний. Без правок кода Framix.
Кастомные инструменты (HTTP-tools)
Агент умеет обращаться к вашим собственным API прямо в ходе диалога. Например: проверить наличие товара на складе, получить статус заявки из CRM, посчитать итоговую цену по введённым параметрам, найти анкету специалиста в вашей базе.
Как это работает
- Вы описываете инструмент в настройках агента: название, что он делает, какие параметры принимает, по какому URL вызывать.
- Агент при ответе посетителю вставляет специальный маркер
[[tool:name|{"param":"value"}]]— это его «намерение вызвать инструмент». - Сервер Framix перехватывает маркер, делает HTTP-запрос к вашему API, получает ответ.
- Ответ подмешивается в контекст, и агент формирует итоговое сообщение посетителю.
Весь цикл — до 3 шагов (hop'ов) за один ответ. После третьего шага агент формирует ответ с тем, что уже получил. Это защита от бесконечных петель.
Где настраивается
/account/agents/<id> → вкладка «Инструменты» → кнопка «Добавить инструмент».
Поля инструмента
| Поле | Обязательно | Описание |
|---|---|---|
| Название (name) | Да | ASCII snake_case, уникально в пределах агента. Пример: check_stock, get_price. Именно это имя агент вставляет в маркер вызова — выбирайте понятное. |
| Описание | Да | Свободный текст: «что делает инструмент и когда его звать». Идёт в системный промпт. Чем точнее описание — тем лучше агент понимает, когда использовать этот инструмент. |
| JSON-Schema параметров | Нет | {"type":"object","properties":{"sku":{"type":"string","description":"Артикул товара"}},"required":["sku"]}. Агент заполняет поля из диалога. Если схема пустая — вызов идёт без параметров (GET-запрос без тела). |
| URL эндпоинта | Да | Полный URL вашего API, например https://api.myshop.ru/stock. |
| HTTP-метод | Да | GET или POST. По умолчанию POST. При GET параметры добавляются как query-строка. |
| Заголовки (зашифрованные) | Нет | Заголовки Authorization, X-API-Key и т.п. Хранятся в AES-256-GCM. В UI вводятся как обычный JSON {"Authorization":"Bearer token123"} — Framix шифрует при сохранении. |
| Таймаут | — | По умолчанию 8 секунд. Если API не ответил — агент получает ошибку и сообщает посетителю, что не смог получить данные. |
| Макс. размер ответа | — | По умолчанию 16 КБ. Длинные JSON'ы обрезаются — чтобы не съесть токены и не накрутить биллинг. |
| Grounded URL pattern | Нет | Regex. Если указан — любая ссылка в видимом ответе агента, совпавшая с паттерном, обязана быть в ответе инструмента. Иначе агент её «выдумал» — и она вырезается. Используется для защиты от галлюцинированных ссылок на профили, анкеты, страницы каталога. |
Кнопка «Тест»
На карточке каждого инструмента есть кнопка «Тест». Введите тестовые параметры — система вызовет ваш API прямо из настроек и покажет ответ. Удобно проверить, что URL доступен и заголовки настроены правильно, не заходя в чат.
Пример: проверка наличия на складе
Название: check_stock
Описание: Проверяет наличие товара на складе. Вызывай, когда посетитель спрашивает "есть ли в наличии", "когда будет", "осталось ли". Передавай артикул товара из каталога.
JSON-Schema:
{
"type": "object",
"properties": {
"sku": {
"type": "string",
"description": "Артикул товара из каталога"
}
},
"required": ["sku"]
}
URL: https://api.myshop.ru/stock
Метод: POST
Заголовки: {"Authorization": "Bearer sk_live_xxx"}
После сохранения агент при вопросе «есть ли артикул XYZ в наличии» вставит вызов [[tool:check_stock|{"sku":"XYZ"}]], Framix запросит ваш API и подмешает ответ («В наличии: 15 штук» / «Ожидается 20 июня»).
Несколько инструментов в одном ответе
Агент может вызвать несколько инструментов в одном ответе — каждый своим маркером, каждый выполняется параллельно (если сервер не накопил зависимость hop→hop). Результаты подмешиваются все вместе в следующий шаг.
Безопасность
- Секретные заголовки (
Authorization,X-API-Key) не видны агенту и не уходят в историю диалога — Framix подставляет их сам при каждом HTTP-запросе. - Параметры, которые агент подставляет в вызов (из JSON-Schema), — это то, что он «понял» из диалога. В промпте агента они описаны и агент их заполняет. Не кладите секреты в параметры схемы.
- Ответ вашего API (до 16 КБ) подмешивается в контекст модели — учитывайте это при проектировании ответа. Не возвращайте данные, которые не должны попасть в LLM.
Совмещение со встроенными tools
Кастомные инструменты работают параллельно с встроенными commerce (search_products, create_order) и services (search_services, book_appointment). Все они описаны в системном промпте агента, и агент выбирает нужный по описанию и контексту.