RubyLab

Что это

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

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

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

Серверные и клиентские инструменты

В разделе «Функции агента» можно создать серверную HTTP(S)-функцию (выполняется на стороне RubyLab) или клиентское определение (только имя, описание и schema — выполнение на вашей стороне, как в OpenAI-compatible API). Серверными функциями можно пользоваться и в веб-чате, и при вызове агента через API.

Для классического клиентского сценария OpenAI — ваше приложение выполняет вызовы по tool_calls. Клиентские определения («только schema») в настройках агента можно включить только при включённом HTTP API у агента; в интерфейсе показывается пояснение без отдельной галочки. Такие функции не выполняются на серверах RubyLab и в веб-чате не предлагаются модели. При запросе к POST /api/v1/chat/completions ответ может содержать tool_calls и finish_reason: tool_calls. Дальше вы отправляете в теле запроса сообщения с ролью tool и продолжаете диалог.

В одном ответе модели нельзя смешивать серверные и клиентские инструменты — разделите вызовы на отдельные шаги.

Поле `tools` в теле `POST /api/v1/chat/completions`

Вы можете передать в запросе OpenAI-совместимый массив tools (объекты с type: "function" и полем function: имя, описание, parameters по JSON Schema). RubyLab объединяет этот список с инструментами агента, настроенными в интерфейсе. Если имя совпадает с функцией агента — для модели используется определение из RubyLab (описание и schema с сервера).

Инструменты, которые есть только в теле запроса и не привязаны к серверному выполнению на агенте, не вызываются на серверах RubyLab: при выборе модели ответ приходит с tool_calls и finish_reason: tool_calls, как для клиентских определений (definition_only). Дальше ваше приложение выполняет вызов локально и продолжает диалог сообщениями с ролью tool.

Ограничения: не более 64 инструментов в одном запросе; без дубликатов имён; невалидный формат массива — ошибка HTTP 400 с фиксированным текстом на английском (см. Swagger и код ответа). Подробная схема — в Swagger: компоненты OpenaiChatCompletionsRequest и OpenaiChatCompletionTool (swagger/v1/swagger.yaml).

Как создать

Откройте Функции агента
Создайте серверную функцию: заполните name, description, api_config и parameters_schema; либо клиентское определение — только name, description и 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_calls с аргументами. Для серверной функции RubyLab выполнит HTTP(S) запрос по вашему api_config и подставит результат в диалог. Для клиентского определения (definition_only) выполнение на стороне RubyLab не происходит; ваше приложение, вызывающее OpenAI-compatible API, само обрабатывает tool_calls и присылает сообщения с ролью tool.

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

Для серверных инструментов (HTTP на стороне RubyLab) в карточке редактирования есть блок «Тестовый вызов». Шаги:

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

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

У клиентских определений (только schema) на сервере нет HTTP-вызова — блока «Тестовый вызов» в интерфейсе нет; проверка выполняется в вашем приложении через API.

Учетные данные (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)