Инструменты

Чтобы подключить инструменты к Responses API, выберите в каталоге моделей вариант с признаком Инструменты и путем /v1/responses, скопируйте его точный request_model_id и отправьте запрос на POST https://route.smartaipack.ru/v1/responses с Bearer-ключом. AI Gateway маршрутизирует запрос поставщику, но сам инструмент всегда выполняет ваше приложение.

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

Что проверить перед началом

Для работы с инструментами нужны два обязательных условия:

1. У модели или конкретного варианта поставщика в Моделях указан признак supports_tools.
2. У этого же варианта среди доступных путей указан /v1/responses.

Одного признака недостаточно: модель с инструментами только на /v1/chat/completions не становится автоматически совместимой с Responses API. И наоборот, наличие /v1/responses не гарантирует поддержку инструментов. Значение model копируйте из поля request_model_id, не собирайте его вручную и не фиксируйте активную модель по примеру из статьи.

Базовый адрес и авторизация выглядят так:

curl https://route.smartaipack.ru/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
    "input": "Проверь доступность заказа 1042."
  }'

Этот запрос еще не описывает инструмент. Он нужен, чтобы отдельно проверить ключ, маршрут и выбранную модель. Основы запроса разобраны в статьях Обзор Responses API и Базовое использование Responses API.

Базовое описание инструмента

Описание инструмента обычно содержит:

• короткое и стабильное имя;
• точное описание назначения;
• схему допустимых аргументов;
• обязательные поля и ограничения значений.

Ниже приведен условный OpenAI-совместимый пример. Используйте его только для выбранного поставщика, который явно подтверждает именно такую форму tools на /v1/responses. Это не общий контракт AI Gateway:

{
  "model": "<REQUEST_MODEL_ID_ИЗ_КАТАЛОГА>",
  "input": "Проверь доступность заказа 1042.",
  "tools": [
    {
      "type": "function",
      "name": "get_order_status",
      "description": "Возвращает статус заказа, доступного текущему пользователю",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "integer",
            "minimum": 1
          }
        },
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  ]
}

Схема помогает модели сформировать аргументы, но не заменяет проверку на сервере. Даже при строгой схеме приложение должно считать ответ модели недоверенными данными.

Не переносите описание инструмента из Chat Completions без проверки. На /v1/chat/completions часто используется вложенный объект function, тогда как отдельный поставщик Responses API может ожидать другую форму. AI Gateway проксирует выбранный протокол и не обещает преобразование этих форматов друг в друга.

Выбор инструмента

Самый переносимый подход — передать только нужные инструменты и позволить модели решить, требуется ли вызов. Чем меньше список, тем проще проверить решение и тем ниже риск выбора похожей функции.

Некоторые поставщики поддерживают tool_choice, включая автоматический выбор, принудительный выбор конкретного инструмента или отключение вызовов. Это поставщик-зависимое поведение. Добавляйте такое поле только после проверки документации и испытания выбранного request_model_id на /v1/responses.

Условные значения могут выглядеть как "auto", "none" или объект с именем функции, но AI Gateway не гарантирует эти значения для всех поставщиков. Если принудительный выбор не подтвержден, лучше сузить список tools до одной разрешенной функции и явно описать ожидаемое действие во входном тексте. Если нужно отключить инструменты, надежнее не передавать их описание вообще, если контракт поставщика допускает такой запрос.

Несколько инструментов

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

Не создавайте универсальную функцию вроде run_action с произвольной командой. Лучше разделить операции:

• get_order_status только читает один доступный заказ;
• get_delivery_window только возвращает допустимое окно доставки;
• request_order_cancellation создает запрос на отмену, но не списывает деньги и не меняет заказ без отдельного подтверждения.

Каждый возвращенный вызов проверяйте отдельно. Валидный первый вызов не делает второй автоматически безопасным.

Параллельные вызовы

Модель или поставщик могут вернуть несколько вызовов за один ответ, но параллельность не является гарантией AI Gateway. Клиент должен корректно работать и с одним вызовом, и с последовательностью, и с несколькими элементами результата.

Запускайте одновременно только действительно независимые операции. Для каждого вызова отдельно применяйте:

• проверку имени и аргументов;
• авторизацию пользователя и организации;
• собственное ограничение времени;
• ограничение повторов;
• отдельную запись результата и ошибки.

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

Ответ с вызовом инструмента

Ответ поставщика может содержать имя функции, аргументы и идентификатор вызова. Но AI Gateway не устанавливает единые поля function_call, call_id или общий массив output для всех поставщиков Responses API.

Условный OpenAI-совместимый фрагмент может выглядеть так:

{
  "output": [
    {
      "type": "function_call",
      "call_id": "call_example_01",
      "name": "get_order_status",
      "arguments": "{\"order_id\":1042}"
    }
  ]
}

Это только пример формы, которую нужно сверить с контрактом конкретного поставщика. Обработчик не должен считать наличие этих полей универсальным признаком успешного вызова. Сначала проверьте HTTP-статус и Content-Type, затем разберите ответ по правилам выбранного варианта.

Проверка вызова

До выполнения инструмента приложение должно пройти полный набор проверок:

1. Имя есть в локальном списке разрешенных функций.
2. arguments — корректный JSON ожидаемого типа.
3. Данные проходят вашу схему, включая обязательные поля, длины, диапазоны и additionalProperties.
4. Пользователь имеет право читать или изменять указанный объект.
5. Инструмент запускается с минимальными правами и ограниченным временем.
6. Для изменяющей операции задан ключ повторяемости или иной способ не выполнить действие дважды.
7. Результат проверен перед возвратом модели и не содержит секретов или лишних персональных данных.

Проверяйте права по текущему пользователю, а не по формулировке модели. Например, аргумент order_id: 1042 сам по себе не доказывает, что заказ принадлежит этой организации.

Для денежных операций, удаления данных и внешних сообщений добавляйте явное подтверждение пользователя. Не давайте модели функцию с произвольным SQL, путем к файлу, адресом внутренней сети или командой оболочки.

Возврат результата в диалог

После выполнения приложение обычно отправляет результат обратно модели, чтобы получить понятный пользователю ответ. Форма связи результата с исходным вызовом зависит от поставщика.

Например, поставщик с OpenAI-совместимой схемой может принимать function_call_output и call_id:

{
  "model": "<ТОТ_ЖЕ_REQUEST_MODEL_ID>",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_example_01",
      "output": "{\"order_id\":1042,\"status\":\"ready\"}"
    }
  ]
}

Этот фрагмент также условный и применим лишь там, где поставщик явно подтверждает function_call_output и call_id. Не отправляйте его вслепую другой модели. AI Gateway не выполняет автоматический агентский цикл, не хранит за приложение состояние диалога и не подставляет результат инструмента самостоятельно.

Возвращайте минимально достаточный результат. Вместо полной записи заказа передайте разрешенные поля, например статус и ожидаемое время готовности. Мультимодальный вывод инструмента здесь не используется: его поддержка для AI Gateway не подтверждена.

Потоковые вызовы

AI Gateway сохраняет потоковую передачу для совместимых маршрутов, но точные события вызова инструмента определяет поставщик. Не рассчитывайте на конкретные имена событий, порядок фрагментов или то, что JSON-аргументы придут одним сообщением.

Безопасный потоковый обработчик должен:

1. собирать фрагменты только в пределах одного вызова по идентификатору, если он предусмотрен контрактом;
2. ждать подтвержденного завершения аргументов;
3. разобрать полный JSON и применить обычную серверную проверку;
4. не запускать инструмент по первому неполному фрагменту;
5. обрабатывать обрыв соединения без повторного изменения состояния.

Если выбранный поставщик не документирует потоковый вызов инструментов, начните с stream: false. Общая работа с потоком и обрывами описана в статье Потоковые ответы API.

Практический цикл приложения

Независимо от поставщика логика клиента остается одинаковой:

1. Отправить запрос с разрешенными инструментами.
2. Получить ответ и найти запросы на вызов по контракту поставщика.
3. Проверить каждый вызов, права и повторяемость.
4. Выполнить разрешенные функции в приложении.
5. Проверить и сократить результаты.
6. Вернуть результаты модели в формате поставщика.
7. Получить итоговый ответ для пользователя.

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

Рекомендации

• Сверяйте одновременно supports_tools, /v1/responses, request_model_id и цену в каталоге.
• Начинайте с одного инструмента только для чтения и испытательных данных.
• Делайте имена и описания короткими, а схемы аргументов — узкими.
• Не смешивайте контракты Chat Completions и Responses.
• Считайте имя, аргументы и результат недоверенными данными.
• Разделяйте чтение и изменение; опасные операции подтверждайте отдельно.
• Ограничивайте время, число шагов, параллелизм и размер результата.
• Для изменяющих операций обеспечьте повторяемость и журналирование.
• Не передавайте модели ключи, платежные данные, внутренние адреса и лишние персональные данные.
• После испытания проверяйте запрос в Использовании, а токены и стоимость — в Аналитике.

Текущие испытательные проверки проекта подтверждают обычный запрос на /v1/responses, а вызов тестового инструмента — отдельно на /v1/chat/completions. Они не доказывают единый формат вызова инструментов на Responses для всех поставщиков. Перед рабочим запуском нужен собственный испытательный сценарий именно для выбранного request_model_id и обеих фаз: запрос вызова и возврат результата.

Следующие шаги

Сначала выполните минимальный запрос из базового руководства, затем выберите в Моделях совместимый вариант и испытайте один инструмент только для чтения. После каждой фазы проверьте запись в Использовании, стоимость в Аналитике и актуальный тариф на странице Цены.

Для надежной обработки отказов используйте общую статью Ошибки API и будущий разбор Ошибки Responses API. Более широкий сценарий будет описан в практическом руководстве по вызову инструментов. Если ответ не совпадает с контрактом выбранного поставщика, обратитесь в поддержку, указав время запроса, путь и request_model_id, но не отправляйте полный API-ключ.