DeepSeek API: schema для tools перед server-side действием

Tool payload не является авторизацией

Структура, похожая на вызов инструмента, не даёт модели право менять данные, отправлять письмо или публиковать результат. На сервере сначала известны пользователь, tenant, роль и тип разрешённой операции; только затем payload может пройти проверку. Даже «правильное» имя инструмента не заменяет локальную policy.

Считайте неизвестное поле, тип или операцию поводом остановиться. Не исправляйте payload догадкой и не расширяйте права ради удобства демо. Для операции с внешним эффектом безопасный default — review или явное подтверждение назначенного человека, а не скрытый вызов за одним ответом модели.

Опишите компактную схему

Схема должна быть небольшой и привязанной к конкретной операции: обязательные поля, типы, допустимые значения, длины и границы. Отключите дополнительные свойства, если они не нужны. Такая JSON Schema или эквивалентная серверная проверка делает изменение формата заметным до того, как оно попадёт в бизнес-логику.

Не помещайте в схему реальные секреты, адреса приватных сервисов или произвольные URL. Если инструменту требуется ресурс, выбирайте его по серверной allowlist либо внутреннему ID. Валидация формы не доказывает право доступа, поэтому после схемы требуется проверка роли, владельца и состояния локальной операции.

Свяжите payload с operation ID

Создайте собственную operation до запроса и храните ожидаемый инструмент, владельца и состояние в своей системе. Когда приходит payload, проверьте его связь с этой операцией, срок действия и отсутствие повторной обработки. Это предотвращает смешение одновременных сценариев и двойной эффект после повторной доставки.

Внешний request ID полезен для диагностики, но не должен быть единственным доказательством. В журнал добавляйте локальный operation ID, версию схемы и категорию решения. Не сохраняйте полный prompt, tool payload, заголовки и ключи лишь для удобства отладки.

Составьте allowlist по роли

Глобальный список инструментов слишком широк. Разрешайте конкретный tool только нужной роли, tenant и среде, а для опасных действий добавляйте отдельное подтверждение. Чтение статуса и изменение доступа — разные классы риска; их нельзя объединять только потому, что оба действия вызываются из одного UI.

Allowlist также помогает безопасно пережить обновление: новый инструмент не станет доступным автоматически, пока команда не опишет его схему, тест и rollback. Если модель предложила незнакомое имя, верните предсказуемый отказ. Не подменяйте его «похожим» инструментом и не отправляйте данные во внешнюю сеть без решения policy.

Покройте негативные тесты

На staging проверьте пустой payload, лишнее поле, недопустимое перечисление, чужой operation ID, повтор и отсутствие роли. У каждого теста должен быть безопасный исход без side effect. Добавьте также отказ подтверждения и сетевой timeout после того, как локальная операция уже создана.

Связанные материалы: совместимость DeepSeek и OpenAI, валидация аргументов tools и проверка tool result. Они описывают общий подход к приложению, а не гарантируют поведение API DeepSeek.

Начните с локальной границы

До интеграции определите, какое решение остаётся за приложением: доступ пользователя, разрешённая модель, схема результата или публикация побочного действия. Ответ модели, HTTP-статус и имя маршрута не заменяют это решение. Явная граница не даёт превратить пример кода в несуществующую гарантию поставщика.

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

Тестируйте изменения на staging

Минимальный тест различает корректный ответ, ошибку валидации, отказ в доступе, временную сеть и неизвестный итог. Для каждого состояния заранее назначьте действие: остановка, ручной review или безопасное повторение. Бесконечный retry не исправляет неверный контракт и не доказывает, что внешняя операция не была выполнена.

Фиксируйте дату, версию клиента и условия теста. Если меняются SDK, каталог или формат ответа, повторите небольшой контрактный тест до расширения трафика. Один удачный вызов показывает только наблюдаемый сценарий в конкретной конфигурации, а не постоянную совместимость или качество модели.

Минимизируйте технические данные

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

Пример ниже выполняет только локальную проверку: он не вызывает сеть, не содержит ключей и не подтверждает поддержку endpoint. Используйте только собственный ключ RussiaAPI на сервере и сверяйте актуальный контракт и каталог в аккаунте перед реальным вызовом.

Сохраняйте обратимый путь

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

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

Безопасный server-side пример

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

export function validateToolCall(call, operation, actor) {
  if (!operation || call?.operationId !== operation.id || operation.state !== 'awaiting_tool') return { ok: false, code: 'operation_mismatch' };
  if (!actor?.permissions?.includes(call.name) || !operation.allowedTools.includes(call.name)) return { ok: false, code: 'tool_not_allowed' };
  const args = call.arguments;
  if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).some((key) => !['recordId', 'mode'].includes(key))) return { ok: false, code: 'invalid_schema' };
  return typeof args.recordId === 'string' && ['preview', 'apply'].includes(args.mode) ? { ok: true, action: args.mode === 'apply' ? 'require_confirmation' : 'preview' } : { ok: false, code: 'invalid_schema' };
}

Источники и границы

DeepSeek API documentation · OWASP Input Validation Cheat Sheet

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

FAQ

Достаточно ли JSON Schema?

Нет. Схема проверяет форму, но не право пользователя и не состояние операции. После неё нужны operation ID, allowlist по роли и отдельное подтверждение для side effect.

Можно ли передать URL из tool payload напрямую?

Не стоит. Произвольный URL расширяет поверхность риска. Выбирайте разрешённый ресурс на сервере по внутреннему ID или allowlist и проверяйте право доступа.

Нужно ли логировать payload?

По умолчанию нет. Для диагностики обычно достаточно локального operation ID, версии схемы и категории результата. Не записывайте ключи, заголовки, полный prompt или чувствительные аргументы.

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

Откройте RussiaAPI, подтвердите маршрут в своём аккаунте и проверьте синтетический сценарий на staging. Затем продолжите с материалами: Совместимость DeepSeek и OpenAI · Валидация аргументов tools · Проверка tool result.