RubyLab

Что это

Инструмент API (Custom) — это функция, которая выполняет HTTP(S) запрос на указанный URL. Бот может сам вызвать эту функцию, когда посчитает это нужным, и подставить аргументы согласно вашей schema.

Сценарии использования:

Вызов собственного бекенда (поиск, создание заявки, получение статуса)
Интеграция с внешним API без разработки отдельного провайдера

Как создать

Откройте Инструменты API
Создайте инструмент: заполните name, description, api_config и parameters_schema
Перейдите в настройки бота и включите функцию в разделе «Функции»
Проверьте вызов в тестовом чате бота

Schema (JSON) для параметров

Schema хранится в parameters_schema и используется как parameters в tool definition. Минимальная форма:

{
  "type": "object",
  "properties": {
    "q": { "type": "string", "description": "Что искать" }
  },
  "required": ["q"]
}

Важно: у каждого параметра в properties обязателен description. Это то, как модель понимает, что означают поля.

Примеры невалидных schema

1) Нет description у параметра

{
  "type": "object",
  "properties": { "q": { "type": "string" } },
  "required": ["q"]
}

Будет ошибка валидации: отсутствует description для $.properties.q.

2) Нет description у вложенного поля

{
  "type": "object",
  "properties": {
    "payload": {
      "type": "object",
      "description": "Данные",
      "properties": { "id": { "type": "string" } }
    }
  }
}

Будет ошибка валидации: отсутствует description для $.properties.payload.properties.id.

Как выглядит tool-call для модели

Когда бот отправляет запрос в модель, мы передаём массив tools. Для вашего инструмента это выглядит так:

{
  "type": "function",
  "function": {
    "name": "my_custom_api_call",
    "description": "Выполнить запрос к моему API",
    "parameters": { ...ваш parameters_schema... }
  }
}

Далее модель может вернуть tool_call с аргументами, и приложение выполнит HTTP(S) запрос.

Тестовый вызов

Каждый инструмент API можно протестировать прямо из интерфейса без участия бота:

Откройте инструмент в режиме редактирования
Справа найдите блок «Тестовый вызов»
Укажите Payload (JSON), например: {"q":"пример запроса"}
Нажмите «Выполнить тест»

Результат HTTP вызова отобразится ниже в JSON-формате. При ошибке вы увидите текст ошибки (например, проблема с URL, таймаутом или учетными данными).

Учетные данные (Custom)

Чтобы не хранить секреты в api_config, используйте Учетные данные типа Custom (API).

Создайте учетные данные в разделе Учетные данные
Выберите провайдера Custom (API)
Заполните JSON с секретами, например: {"api_key":"..."}
В инструменте API выберите эти учетные данные в поле «Учетные данные (Custom)»

Подстановка секретов работает только в заголовках и выглядит так:

{
  "headers": {
    "Authorization": "Bearer {{api_key}}"
  }
}

Если плейсхолдер {{api_key}} указан, но такого ключа нет в учетных данных, запрос завершится ошибкой.

Безопасность

Разрешены только http:// и https://.
В продакшене запрещены localhost и приватные/служебные IP диапазоны (SSRF защита). В development localhost разрешён.
Таймаут запроса: 4 секунды.
Максимальный размер ответа: 200 KB (лишнее будет обрезано).

Инструменты API (Custom)