Как настроить tool calling в OpenRouter Responses API

Этот сценарий полезен разработчику backend, владельцу чат-бота или команде автоматизации, которой нужен наблюдаемый результат. Ключевой принцип: проверять не только текст модели, но и метаданные маршрутизации, структуру ответа, учет токенов и негативный путь. HTTP 200 означает, что транспорт сработал; он не доказывает, что модель соблюла бизнес-формат.

Подтвержденные факты

• Инструмент задается объектом type:function с name, description и parameters.
• tool_choice:auto разрешает модели выбирать между ответом и вызовом.
• Аргументы функции считаются недоверенным вводом и валидируются по схеме.
• Опасные действия требуют серверной авторизации и, при необходимости, подтверждения человека.

Параметры OpenRouter задаются на двух разных уровнях. model, messages, response_format относятся к запросу генерации. Объект provider управляет выбором upstream-endpoint. Плагины маршрутизаторов передаются в plugins. Не переносите поле из одного уровня в другой: JSON останется синтаксически корректным, но настройка может не дать ожидаемого эффекта.

Пошаговая настройка

1. Сформулируйте проверяемый результат. Для запроса «как использовать tool calling OpenRouter» не принимайте субъективное «вроде работает»: заранее запишите ожидаемый формат и признаки ошибки.
2. Создайте отдельный API-ключ для тестового приложения и передавайте его через переменную окружения OPENROUTER_API_KEY. Не вставляйте секрет в клиентский JavaScript, мобильный APK, скриншот или репозиторий.
3. Соберите минимальный запрос из примера ниже. Он изолирует именно механизм статьи; дополнительные фреймворки, ретраи и бизнес-логику добавляйте после первого успешного ответа.
4. Отправьте запрос на https://openrouter.ai/api/v1/chat/completions. При ошибке сначала сохраните HTTP-код, тело ответа и request id, а уже затем решайте, допустим ли повтор.
5. Сравните результат с контрольным ожиданием: Модель возвращает структурированный вызов get_weather с location=Смоленск. Сервер валидирует аргументы, вызывает доверенный погодный API и только затем передает результат модели.
6. Прогоните положительный и отрицательный тест. Отрицательный тест должен доказать, что приложение не принимает невалидный формат, запрещенную модель или ослабленную политику после fallback.
7. Только после этого добавьте таймаут, ограниченный retry с jitter, метрики и безопасное логирование. Повторяйте лишь идемпотентные операции или используйте собственный ключ идемпотентности.

Минимальный рабочий пример

{"model":"<TOOL_CAPABLE_MODEL>","input":[{"type":"message","role":"user","content":[{"type":"input_text","text":"Какая погода в Смоленске?"}]}],"tools":[{"type":"function","name":"get_weather","description":"Получить текущую погоду","parameters":{"type":"object","properties":{"location":{"type":"string"},"unit":{"type":"string","enum":["celsius"]}},"required":["location"],"additionalProperties":false}}],"tool_choice":"auto"}

Значения в угловых скобках — не реальные идентификаторы. Их нужно заменить slug из актуальной страницы модели OpenRouter. Такой шаблон безопаснее статьи с быстро устаревающим списком моделей или провайдеров. Токен доступа в пример намеренно не включен.

Готовый тестовый промпт

Задача: проверь конфигурацию «как использовать tool calling OpenRouter».
Верни только результат в указанном формате, без вступления.
Если входных данных недостаточно, верни явную ошибку INPUT_MISSING и перечисли недостающие поля.
Не придумывай факты и не изменяй ограничения запроса.

Промпт нужен для проверки дисциплины ответа, но он не заменяет параметры API. Например, просьба «верни JSON» не дает тех же гарантий, что response_format; фраза «не сохраняй данные» не заменяет ZDR-фильтр; просьба «выбери быструю модель» не заменяет настройки маршрутизации. Управляющие ограничения следует задавать структурированными полями запроса, а затем повторно проверять в приложении.

Контрольный вход и ожидаемый результат

Контрольный вход уже встроен в пример. Не меняйте одновременно prompt, модель и маршрутизацию: иначе невозможно понять причину различий. Сначала выполните запрос пять раз с одной конфигурацией, сохраните HTTP-код, id, model, finish_reason, usage и длительность. Затем измените ровно один параметр и повторите серию.

Ожидаемый результат: Модель возвращает структурированный вызов get_weather с location=Смоленск. Сервер валидирует аргументы, вызывает доверенный погодный API и только затем передает результат модели.

Если текст формально правильный, но отсутствует model или usage, не подменяйте их нулями без отдельного статуса. Различайте «ноль», «поле не поддерживается» и «финальное событие не было прочитано». Для JSON-ответов применяйте декодер и схему. Для обычного текста проверяйте длину, обязательные маркеры и отсутствие служебных фрагментов.

Критерии приемки

• имя есть в allowlist
• аргументы прошли схему
• таймаут инструмента ограничен
• результат инструмента не содержит секреты
• цикл имеет лимит шагов