Пользовательские инструменты

Пользовательский инструмент (OpenAPI) позволяет подключить к агенту собственный HTTP‑API и использовать его прямо в диалоге. Вы описываете свой сервис в виде спецификации OpenAPI (или Swagger), а платформа автоматически превращает каждую операцию из спецификации в отдельный инструмент, который агент сможет вызывать во время ответа — например, узнать погоду, проверить статус заказа или создать заявку в вашей системе.

Раздел находится в меню Инструменты → вкладка «Пользовательские».

Добавлять, изменять и удалять пользовательские инструменты может только администратор или владелец рабочего пространства. Остальные участники видят готовые инструменты и могут подключать их к агентам.

Что понадобится

Перед добавлением инструмента подготовьте:

Спецификацию вашего API в формате OpenAPI 3.x или Swagger 2.0 (в виде текста JSON/YAML либо ссылки на файл спецификации). Платформа также понимает манифест плагина в формате OpenAI (`ai-plugin.json`).
Базовый адрес сервиса — он должен быть указан в спецификации в поле servers. Без него схему сохранить не получится.
Ключ доступа (при необходимости) — если ваш API требует авторизации, приготовьте API‑ключ или токен.

Как добавить инструмент

Откройте раздел добавления
Перейдите в Инструменты, выберите вкладку «Пользовательские» и нажмите «Добавить инструмент». Откроется окно «Создать пользовательский инструмент».
Задайте имя и иконку
В блоке «Имя и иконка» (обязательное поле) укажите понятное название инструмента и, при желании, выберите иконку или эмодзи. Название помогает вам ориентироваться в списке инструментов; в самом рабочем пространстве оно должно быть уникальным.
Вставьте спецификацию
В блоке «Схема» (обязательное поле) добавьте спецификацию вашего API одним из способов:
- Вставить вручную — скопируйте текст спецификации (JSON или YAML) в поле «Введите свою схему».
- Импортировать из URL — нажмите «Импортировать из URL», укажите ссылку на файл спецификации (адрес должен начинаться с http:// или https://) и нажмите «ОК». Платформа сама загрузит и подставит содержимое.
- Взять пример — нажмите «Примеры» и выберите один из готовых шаблонов: «Погода (JSON)», «Зоомагазин (YAML)» или «Пустой шаблон». Удобно, если нужно посмотреть структуру и заполнить её по образцу.
Платформа поддерживает OpenAPI 3.x и Swagger 2.0 (спецификация Swagger автоматически преобразуется в OpenAPI). Формат определяется по содержимому — указывать его вручную не нужно.
Если схему не удалось распознать, поле подсветится красным и появится сообщение «Не удалось распознать схему. Проверьте, что это корректная спецификация OpenAPI или Swagger.» До исправления ошибки кнопка «Сохранить» будет недоступна. Частые причины разобраны в разделе Возможные проблемы.

Проверьте список операций

Как только схема распознана, в блоке «Доступные инструменты» появится таблица со всеми операциями из спецификации. Для каждой показаны:

Столбец	Что означает
Название	Идентификатор операции (`operationId` из спецификации) — под этим именем к ней обращается агент.
Описание	Пояснение из поля `description`/`summary` операции.
Метод	HTTP‑метод: `GET`, `POST`, `PUT`, `DELETE` и т. д.
Путь	Путь запроса относительно базового адреса.
Действия	Кнопка «Тест» для проверки операции (см. Проверка операции).

Убедитесь, что в таблице присутствуют все нужные операции и у каждой понятное описание — именно по описанию агент решает, когда вызвать инструмент.

Настройте авторизацию
В блоке «Метод авторизации» выберите, как платформа будет авторизоваться в вашем API:
- Нет — API открыт и не требует ключа.
- Заголовок — ключ передаётся в HTTP‑заголовке. После выбора откроется окно настройки:
  - Тип авторизации — как оформить значение ключа: «Базовый» (Basic <ключ>), «Bearer» (Bearer <ключ>) или «Пользовательский» (значение отправляется как есть).
  - Ключ — название заголовка. По умолчанию Authorization; можно оставить как есть или задать своё.
  - Значение — сам API‑ключ или токен.
- Параметр запроса — ключ передаётся в строке запроса (query‑параметром):
  - Параметр запроса — имя параметра (по умолчанию key), например key в адресе https://example.com/test?key=API_KEY.
  - Значение — сам API‑ключ.
Значение ключа хранится в зашифрованном виде и не показывается повторно.
Сохраните инструмент
Нажмите «Сохранить». Кнопка становится доступной, только когда заполнены имя и корректная схема. После сохранения инструмент появится на вкладке «Пользовательские».

Проверка операции

Ещё до сохранения можно убедиться, что операция действительно работает. Нажмите «Тест» в строке нужной операции — откроется окно проверки:

при необходимости переопределите метод авторизации только для этого теста;
в таблице «Параметры и значение» заполните значения входных параметров;
нажмите «Тест» — платформа выполнит реальный запрос к вашему API;
результат появится в блоке «Результаты теста». Если сервис вернёт ошибку, здесь же отобразится её текст.

Тест выполняет настоящий вызов вашего API с указанными параметрами и ключом. Проверяйте операции на тестовых данных, если запрос что‑то изменяет на стороне сервиса.

Подключение инструмента к агенту

Созданный инструмент сам по себе агенту не назначается. Чтобы агент начал им пользоваться:

Откройте нужного агента и перейдите к настройке инструментов.
В списке инструментов найдите свой пользовательский инструмент (по заданному имени и иконке).
Добавьте его агенту и сохраните изменения.

После этого агент сможет вызывать операции инструмента во время диалога, самостоятельно подставляя параметры на основе запроса пользователя.

Требования к спецификации

Чтобы схема распозналась и корректно работала, проверьте, что в ней:

Есть блок **servers** с базовым адресом сервиса — по нему строятся все запросы. Без него появится ошибка вида «сервер не найден».
Есть операции (**paths**) — хотя бы одна.
У каждой операции задан **operationId** — это имя, под которым операция отображается и вызывается. Если operationId не указан, для OpenAPI платформа сформирует его автоматически из пути и метода, а для Swagger 2.0 он обязателен.
У операций заполнены **summary**/**description** — по описанию агент понимает назначение операции. Операции без описания будут работать, но агенту сложнее выбрать правильную.
Не больше 100 операций в одной спецификации.

Поддерживаются параметры в пути, строке запроса, заголовках и теле запроса (application/json, application/x-www-form-urlencoded, а также загрузка файлов через multipart/form-data).

Пример минимальной спецификации

{
  "openapi": "3.1.0",
  "info": {
    "title": "Погода",
    "description": "Получение текущей погоды по городу",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://api.example.com" }
  ],
  "paths": {
    "/weather": {
      "get": {
        "operationId": "getCurrentWeather",
        "summary": "Текущая погода",
        "description": "Возвращает текущую погоду для указанного города",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "description": "Название города",
            "schema": { "type": "string" }
          }
        ]
      }
    }
  }
}

Из этой спецификации платформа создаст один инструмент getCurrentWeather — операцию GET /weather с параметром city.

Управление инструментами

На вкладке «Пользовательские» каждый инструмент отображается карточкой. Здесь его можно:

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

Возможные проблемы

«Не удалось распознать схему» — проверьте, что это корректный JSON или YAML и что структура соответствует OpenAPI/Swagger. Убедитесь, что в схеме присутствуют блоки servers и paths.
Ошибка про отсутствие сервера — в спецификации нет блока servers с базовым адресом. Добавьте его.
Ошибка про отсутствие **operationId** (для Swagger 2.0) — проставьте operationId каждой операции.
Импорт из URL не срабатывает — ссылка должна начинаться с http:// или https:// и вести напрямую на файл спецификации; сервис должен быть доступен из интернета.
Тест возвращает ошибку 401/403 — проверьте метод авторизации, название заголовка/параметра и корректность ключа.
Кнопка «Сохранить» неактивна — не заполнено имя или схема ещё не распознана. Исправьте ошибку в схеме и дождитесь, пока появится таблица «Доступные инструменты».

Инструменты

MCP-сервер