OpenAI-compatible API: проверка tool call перед действием

Считайте вывод модели недоверенным входом

Tool call похож на JSON от внешнего клиента: его нужно проверить до исполнения. Не вызывайте функцию прямо по имени, которое вернула модель, и не позволяйте ей выбирать произвольный URL, команду или доступ к данным. Сервер поддерживает короткий allowlist инструментов для конкретного сценария. У каждого имени есть ожидаемая схема, требуемая роль пользователя, допустимый tenant и набор бизнес-ограничений.

Даже корректный JSON не превращает действие в разрешённое. Например, запрос на изменение заказа должен пройти проверку существования заказа, статуса, владельца, лимита операции и текущего согласия пользователя. Инструмент поиска в базе знаний также должен фильтровать документы по доступу, а не доверять параметру tenant из model output. Такое разделение не зависит от названия модели и защищает приложение при изменении prompt, SDK или внешнего контракта.

Валидируйте имя, схему и семантику аргументов

Первый фильтр — точное имя из allowlist. Второй — JSON Schema или эквивалентная строгая серверная проверка типов, обязательных полей, диапазонов и лишних свойств. Третий — семантика: значение должно существовать в текущем tenant, дата быть допустимой, а операция не конфликтовать с состоянием объекта. Сообщение модели «срочно» не должно обходить ни один из уровней.

Проверяйте аргументы после нормализации и никогда не добавляйте недостающие чувствительные поля из prompt. Если модель вернула неизвестное свойство, неправильный тип или ссылку на чужой объект, остановите исполнение и сохраните только безопасную категорию ошибки. Не отправляйте пользователю сырой stack trace или полный ответ внешнего API. Для диагностики достаточно локального operation ID, версии схемы и статуса валидации.

Требуйте подтверждение перед побочным эффектом

Чтение разрешённого справочного материала и отправка денег, письма или изменения доступа имеют разный риск. Для операции, которую нельзя легко отменить, покажите пользователю конкретное действие, существенные параметры и кнопку подтверждения, сформированную вашим сервером. Подтверждение должно относиться к текущему объекту и сроку, а не быть общим согласием «на всё, что предложит ИИ».

Не подменяйте подтверждение текстом модели. Сервер создаёт одноразовый intent, связывает его с аутентифицированным пользователем и проверенными параметрами, затем выполняет действие только после явного шага интерфейса. Если состояние объекта изменилось между предложением и подтверждением, запрашивайте повторную проверку. Такой flow уменьшает риск, что хороший на вид tool call выполнит устаревшую или чужую операцию.

Используйте идемпотентность и честные состояния

После сетевого обрыва нельзя автоматически предполагать, что действие не произошло. Для side effect назначайте application-owned operation ID и idempotency key, храните переходы состояния и сначала сверяйте локальный результат. Повтор разрешён только там, где ваша бизнес-логика доказала безопасность. Потеря ответа от внешнего маршрута — повод для проверки, а не команда создать вторую запись, оплату или рассылку.

Интерфейс должен различать «предложено», «ожидает подтверждения», «выполнено», «не выполнено» и «требует проверки». Не показывайте успех, пока backend не получил достаточное подтверждение из своего контура. Успех генерации текста или прием tool call не означает успех конечной операции. Храните минимальную историю решений без ключей, полных prompt и лишних персональных данных, чтобы оператор мог разобрать конфликт.

Покройте негативные случаи в staging и CI

Синтетический набор должен включать неизвестный tool name, дополнительные поля, неверный тип, доступ к чужому tenant, истёкшее подтверждение, повторный request и сетевой обрыв после начала операции. Проверьте, что код не делает настоящий платёж, не отправляет письмо и не меняет production-данные. Заглушка инструмента должна возвращать наблюдаемый локальный результат, а тест — фиксировать версию схемы и адаптера.

После изменения prompt, tool schema, SDK, роли или маршрута прогоните набор снова. Если внешний API начал возвращать новую структуру, переведите её в безопасную ветку ручного разбора, пока не обновите контракт и тесты. Не считайте отсутствие ошибки доказательством того, что tools поддерживаются всем каталогом. Поддержку конкретной модели и endpoint проверяйте по действующим условиям RussiaAPI и вашим staging-проверкам.

Пример безопасной server-side проверки

Пример ниже иллюстрирует только логику приложения. Он не делает сетевой вызов, не содержит реальных ключей и не доказывает поддержку конкретного endpoint. Проверьте актуальный договор и API-контракт перед подключением рабочего маршрута.

const allowed = new Set(['lookup_order', 'draft_reply']);

export function validateToolCall(call, viewer) {
  if (!call || !allowed.has(call.name)) return { status: 'rejected' };
  if (!call.arguments || typeof call.arguments !== 'object') return { status: 'rejected' };
  if (!viewer.canUseTools) return { status: 'forbidden' };
  return { status: 'needs_business_validation', operationId: crypto.randomUUID() };
}

// Validate JSON Schema, tenant ownership and confirmation separately before
// invoking any side-effecting service. This example sends no network request.

Граница ответственности и данных

Это инженерный шаблон для вашего приложения, а не гарантия возможностей внешнего API. Не помещайте в браузер, тикет, статью или обычный журнал API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt или персональные данные. Условия обработки данных, права на контент и применимые требования проверяются по политике вашей организации, договору и с ответственным специалистом.

Контроль перед выпуском

Перед release проверьте синтетический сценарий, запреты на секреты и персональные данные в логах, роли и tenant boundary, понятное сообщение для пользователя и ручную ветку для неизвестного результата. Сохраните дату, версию адаптера и результат теста. При обновлении SDK, модели, schema или маршрута повторите проверку; не переносите выводы старого теста на новый контракт.

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

Полезные материалы

OWASP: Authorization Cheat Sheet · OWASP: Input Validation Cheat Sheet

FAQ

Можно ли сразу выполнить tool call, если JSON валиден?

Нет. Валидный JSON подтверждает только форму данных. Сервер ещё должен проверить allowlist имени, роль пользователя, tenant, состояние объекта, бизнес-правила и при необходимости получить явное подтверждение действия.

Нужна ли кнопка подтверждения для каждого инструмента?

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

Что делать при timeout после запуска действия?

Не повторяйте автоматически. Сначала проверьте локальный operation ID и идемпотентное состояние. Затем выберите честный статус: выполнено, не выполнено или требуется ручная проверка, не создавая дубликат операции.

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

Продолжите с материалами: Проверка tool call на сервере · MCP server: allowlist и права · Claude API: проверка аргументов tools. Затем проверьте текущие условия и безопасно протестируйте интеграцию на staging перед production-трафиком.