TNWS AI

Гайд · TNWS AI

Как включить Strict Tool Use в Claude API и валидировать аргументы

WindowsmacOSLinuxClaude#Claude API#Strict Tool Use#JSON Schema
7 мин—

Гайд по strict:true в инструментах Claude API: JSON Schema, additionalProperties, enum, разбор tool_use, серверная валидация и тесты некорректного ввода.

Задача и применимость

Этот гайд решает конкретную задачу: получать от Claude аргументы инструмента, соответствующие JSON Schema, чтобы строка вместо числа или лишнее поле не ломали исполнитель. Материал рассчитан на разработчика, который уже умеет запускать Python, но хочет получить воспроизводимую интеграцию, а не демонстрацию «ответ пришёл — значит всё готово». Ниже есть рабочий каркас, реалистичный контрольный пример, негативные сценарии и критерии приёмки.

Сведения сверены с официальной документацией 12 сентября 2026 года. В статье намеренно нет неподтверждённых цен, обещаний доступности из конкретной страны и результатов чужих тестов. Такие параметры зависят от аккаунта, региона, модели и даты. Перед production-развёртыванием повторите smoke-тест из своего окружения.

Что подтверждено официально

  1. strict: true задаётся на верхнем уровне определения tool рядом с name, description и input_schema.
  2. При strict mode поле input блока tool_use следует поддерживаемому подмножеству JSON Schema, а имя инструмента выбирается из предоставленных tools.
  3. В схеме можно использовать обязательные поля, типы и enum; additionalProperties: false явно запрещает незаявленные свойства.
  4. Схемы компилируются в грамматики и временно кешируются; документация указывает срок до 24 часов с последнего использования.
  5. Computer use и browser use toolset entries, перечисленные в актуальной документации, не принимают strict: true.

Первоисточник: официальная документация. Это ссылка на интерфейс, использованный в примере, а не на пересказ стороннего блога. Сохраните дату проверки в change log проекта: при обновлении SDK сравнение станет быстрее.

Что подготовить

Нужны Python-окружение, официальный SDK, ключ нужного сервиса в переменной окружения и небольшой тестовый набор. Ключ нельзя вставлять в браузерный JavaScript, мобильное приложение, публичный notebook или репозиторий. Если код выполняется на сервере, выдайте процессу минимально необходимые права и предусмотрите отзыв секрета.

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

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

  1. Определите минимальный контракт инструмента. Для бронирования нужны destination, дата ISO и целое passengers; не передавайте свободный объект.
  2. Добавьте strict: True и additionalProperties: False. Ограничьте passengers через integer и enum допустимых значений.
  3. Отправьте Messages API запрос с tools. Найдите в response.content блок с type="tool_use" и нужным name.
  4. Даже при strict mode прогоните input через свою Pydantic/JSON Schema модель: это защищает от несовместимости версии и ошибок glue-кода.
  5. До выполнения проверьте авторизацию пользователя, доступность ресурса и бизнес-правила. Schema не знает, можно ли списывать деньги.
  6. Верните результат инструмента как tool_result с соответствующим tool_use_id, затем запросите финальный ответ модели.
  7. Добавьте тесты: passengers="два", дата в свободном формате, лишний ключ admin=true и отсутствующий destination.
  8. При изменении схемы версионируйте tool name или контракт и раскатывайте его одновременно с обработчиком.

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

Копируемый шаблон

tool = {
  "name": "search_flights",
  "description": "Найти рейсы на дату",
  "strict": True,
  "input_schema": {
    "type": "object",
    "properties": {
      "destination": {"type": "string"},
      "departure_date": {"type": "string", "format": "date"},
      "passengers": {"type": "integer", "enum": [1,2,3,4,5,6]}
    },
    "required": ["destination", "departure_date"],
    "additionalProperties": False
  }
}
response = client.messages.create(
  model=os.environ["CLAUDE_MODEL"], max_tokens=512,
  messages=[{"role":"user","content":"Найди рейсы в Токио на 2026-10-05 для двоих"}],
  tools=[tool]
)

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

Реалистичный пример входа и ожидаемого результата

Вход: «Найди рейсы в Токио на 2026-10-05 для двоих». Схема требует passengers integer.

Ожидаемый результат: В tool_use.input значение passengers равно числу 2, дата соответствует строке формата date, лишних свойств нет. После этого сервер всё равно проверяет права и валидирует объект перед вызовом поставщика билетов.

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

Проверка по уровням

1. Транспорт

Проверьте код ответа, таймаут и идентификатор запроса, если провайдер его возвращает. Ошибки авторизации и неверные параметры не следует повторять с backoff: сначала исправьте конфигурацию. Для временных 429/5xx используйте ограниченное число повторов с jitter и идемпотентностью.

2. Контракт

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

3. Смысл

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

4. Побочные эффекты

Если инструмент меняет данные, сначала валидируйте право пользователя и состояние ресурса, затем используйте идемпотентный ключ. После таймаута перепроверьте фактический статус до повтора. Так сеть не превратит один запрос в две оплаты, две рассылки или два удаления.

Негативные тесты

  1. Удалите ключ из окружения: приложение должно завершиться понятной ошибкой до отправки пользовательских данных.
  2. Укажите несуществующую модель: ошибка не должна превращаться в пустой «успешный» ответ.
  3. Передайте вход без обязательного значения и проверьте, что слой приложения его отклоняет.
  4. Имитируйте таймаут после отправки запроса. Повтор допускается только после проверки идемпотентности.
  5. Подмените тип одного поля в mock-ответе: контрактный тест обязан сработать.
  6. Запустите запрещённый или чужой идентификатор: интеграция не должна выполнять действие только потому, что его предложила модель.

Рабочая приёмка

Минимальная приёмка состоит из журнала теста, сохранённой версии зависимостей и таблицы «вход → инварианты → результат». Для каждой ошибки определите владельца: транспорт обслуживает platform-команда, схему — разработчик интеграции, бизнес-правила — продуктовый сервис, качество — владелец данных. Это предотвращает ситуацию, когда некорректный ответ неделями считают «особенностью нейросети».

Перед расширением трафика добавьте метрики количества запросов, отказов, повторов, пустых результатов и ручных отклонений. Не публикуйте выдуманные пороги: базовую линию получите на своей контрольной выборке, а затем зафиксируйте её в runbook. Любое изменение модели или SDK прогоняйте через тот же набор.

Чек-лист финальной проверки

  • Использована официальная документация, проверенная 12 сентября 2026 года.
  • Секрет хранится в переменной окружения и не попадает в клиентский код или логи.
  • Модель/провайдер доступны именно в рабочем аккаунте.
  • Обычный пример возвращает обязательные поля и значения.
  • Граничный и запрещённый примеры дают контролируемый результат.
  • Числа, даты, идентификаторы и отрицания сверяются с источником.
  • Повтор запроса ограничен и безопасен для побочных эффектов.
  • Версия SDK зафиксирована, а контрактный тест запускается в CI.
  • Пользователь видит понятную ошибку вместо ложного успеха.

Ограничения

  • Strict mode гарантирует форму аргументов, но не их истинность, безопасность или наличие ресурса.
  • Поддерживается не весь JSON Schema; сверяйте схему с разделом ограничений документации.
  • Не помещайте персональные медицинские данные в имена свойств, enum, const или regex схемы.

Кроме перечисленного, результат зависит от выбранной модели и входных данных. Не переносите вывод одного smoke-теста на весь поток. Для чувствительных решений используйте человеко-машинный процесс: модель предлагает или извлекает данные, код проверяет контракт, а уполномоченный сервис или сотрудник подтверждает действие.

FAQ

Как понять, что интеграция действительно работает?

Используйте контрольный вход и ожидаемый результат из гайда, затем выполните негативный тест. Для темы «получать от Claude аргументы инструмента, соответствующие JSON Schema, чтобы строка вместо числа или лишнее поле не ломали исполнитель» успехом считается не HTTP 200 сам по себе, а прохождение проверок структуры, содержания и отсутствия побочного эффекта при ошибке.

Можно ли сразу использовать пример в production?

Нет. Пример показывает подтверждённый интерфейс API, но в production нужны секреты в хранилище, таймауты, ограничение повторов, авторизация, журнал решений и тесты на данных вашего домена.

Почему в статье нет фиксированной цены?

Цены, квоты и доступность меняются. На 12 сентября 2026 года в этом руководстве используются только интерфейсы из официальной документации; стоимость проверяйте непосредственно в кабинете и актуальном прайс-листе перед запуском.

Что делать, если поле ответа отличается?

Сначала зафиксируйте версию SDK и сырой ответ без секретов. Затем сверяйте его с официальной документацией и типами установленной версии. Не маскируйте несовместимость универсальным try/catch, который возвращает пустой результат.

Официальный первоисточник

Частые вопросы

Как понять, что интеграция действительно работает?

Используйте контрольный вход и ожидаемый результат из гайда, затем выполните негативный тест. Для темы «получать от Claude аргументы инструмента, соответствующие JSON Schema, чтобы строка вместо числа или лишнее поле не ломали исполнитель» успехом считается не HTTP 200 сам по себе, а прохождение проверок структуры, содержания и отсутствия побочного эффекта при ошибке.

Можно ли сразу использовать пример в production?

Нет. Пример показывает подтверждённый интерфейс API, но в production нужны секреты в хранилище, таймауты, ограничение повторов, авторизация, журнал решений и тесты на данных вашего домена.

Почему в статье нет фиксированной цены?

Цены, квоты и доступность меняются. На 12 сентября 2026 года в этом руководстве используются только интерфейсы из официальной документации; стоимость проверяйте непосредственно в кабинете и актуальном прайс-листе перед запуском.

Что делать, если поле ответа отличается?

Сначала зафиксируйте версию SDK и сырой ответ без секретов. Затем сверяйте его с официальной документацией и типами установленной версии. Не маскируйте несовместимость универсальным try/catch, который возвращает пустой результат.

Читайте также

ГайдыClaude APIPython12 сентября 2026

Как анализировать PDF с таблицами и графиками через Claude API

Как передать PDF в Claude API, задать вопросы по страницам, получить цитаты и проверить числа из таблиц и графиков.

5 мин 
ГайдыClaude APIPython12 сентября 2026

Как добавить цитаты из документов в Claude API и проверить их

Практический гайд по citations в Claude API: передача документа, включение ссылок на фрагменты и ручная верификация.

5 мин 
ГайдыClaude APIPython12 сентября 2026

Как добавить Web Search в Claude API и ограничить источники

Как подключить web_search tool Claude, задать max_uses и домены, собрать цитаты и проверить дату каждого найденного факта.

6 мин 

Подбор

Какую нейросеть выбрать

Пройти опрос

Комментарии

Пока тихо. Скажите первое слово