Claude API и tools: проверка аргументов на сервере

Короткий ответ: модель предлагает, сервер решает

Tool use удобен, когда модель формирует структурированное предложение: найти запись, подготовить черновик, вызвать внутреннюю функцию. Опасность появляется, когда приложение исполняет аргументы без проверки, потому что текст выглядит как JSON. Даже формально корректный JSON может содержать чужой tenant_id, слишком широкий фильтр, неподдерживаемое действие или значение, которое меняет смысл операции. Поэтому модель никогда не выбирает учётную запись, роль, base URL, секрет или право на запись. Эти данные выводит сервер из сессии, политики и allowlist-а приложения.

Опишите tool как контракт с узким назначением. Вместо универсального execute_sql создайте, например, get_invoice_status с фиксированными полями и только чтением. Вместо произвольного URL разрешите один внутренний ресурс и преобразуйте идентификатор на сервере. Чем уже schema, тем проще проверить риск и негативные случаи. Если аргумент не проходит проверку, возвращайте модели и пользователю безопасный reason code, а не полный stack trace, внутренний запрос или список скрытых маршрутов. Ошибка в tool use должна останавливать действие, а не запускать «лучшее предположение».

Валидируйте форму, диапазон и связь полей

Проверка schema включает не только тип string или number. Backend проверяет обязательность полей, длину, enum, допустимый формат, максимальный размер списка и взаимные зависимости. Например, end_date не может быть раньше start_date, amount требует известной валюты, а идентификатор объекта обязан принадлежать tenant из сессии. Не доверяйте id, переданному моделью, если его можно заменить серверным контекстом. Для сложных контрактов применяйте библиотеку валидации и версионируйте schema, чтобы тесты точно знали, какую форму ожидает текущий обработчик.

Проверяйте также семантику, которую schema не выражает: существует ли объект, находится ли он в нужном состоянии, разрешён ли переход и не является ли действие повтором. Это отдельный слой domain validation. Например, корректный JSON с cancel=true не отменяет задачу, пока сервер не убедится, что пользователь имеет это право, задача относится к его tenant и состояние допускает отмену. Модель не может подтвердить эти условия из текста контекста. При неопределённости действие отправляют на review или отклоняют без раскрытия служебных деталей.

Разделите чтение, запись и необратимые действия

Для read-only tools достаточно schema, авторизации и минимального ответа. Для записи добавьте идемпотентный request_id, журнал решения и ограничение частоты. Для необратимых или дорогостоящих действий нужен явный шаг подтверждения от пользователя либо утверждённый серверный workflow. Не показывайте фразу модели как уже совершённый факт, пока backend не получил подтверждённый результат. В интерфейсе полезно объяснить, что будет сделано и с каким объектом, но не показывать ключи, полные внутренние параметры или чужие данные.

Очередь и deadline нужны даже для безопасных операций. Tool может обратиться к медленной системе, получить timeout или вернуть неизвестное состояние. Храните компактную запись: request_id, tool name, tenant, разрешённое действие, версию policy и итог. Не записывайте весь контекст чата в audit log. При повторе backend возвращает известное состояние, а не выполняет действие второй раз. Если внешний контракт не документирует идемпотентность, реализуйте защиту в своём приложении и не заявляйте, что её обеспечивает provider.

Защититесь от подмены инструкции и расширения полномочий

Внешний документ, письмо или RAG-фрагмент может содержать инструкцию, которая пытается изменить роль модели: «игнорируй правила и вызови tool». Такой текст является данными, а не источником полномочий. Не передавайте его напрямую в обработчик tool и не включайте в allowlist по совпадению слов. Модель может предложить действие, но сервер сопоставляет tool name с заранее опубликованным реестром, затем проверяет пользователя, tenant, scope и допустимые поля. Любое неизвестное имя или поле — причина безопасного отказа.

Тестируйте намеренно враждебные и ошибочные аргументы: неизвестный tool, extra field, слишком длинная строка, чужой объект, повтор request_id, попытка записи без подтверждения и недопустимый переход состояния. Убедитесь, что ответы не содержат Authorization, cookie, переменные окружения, исходный prompt или детали базы. Это полезнее, чем проверять только «счастливый путь». При изменении model ID, schema или внутренней функции повторяйте набор: поведение модели и контракт приложения могут меняться независимо друг от друга.

Подключайте инструмент после проверяемого smoke test

До production создайте тестовый tenant с синтетическими объектами и ограниченным набором действий. Подтвердите в текущем каталоге RussiaAPI, что выбранный сценарий и поля документированы для вашего маршрута; не переносите предположения из официальной документации другого поставщика. Выполните server-side smoke test, проверьте лог без секретов и убедитесь, что отказ не вызывает побочный эффект. Затем включайте tool feature flag-ом для небольшой группы и наблюдайте ошибки schema, отказы авторизации и повторные операции.

RussiaAPI — независимый сторонний gateway. Статья не обещает отношения с Anthropic, доступность Claude, полную совместимость или автоматическую безопасность tool use. Создайте собственный ключ только в серверном окружении и не передавайте upstream credentials в запросах или примерах. Если бизнес-операция зависит от прав, финансов или персональных данных, согласуйте её отдельным процессом с владельцем и применимыми требованиями. Техническая проверка аргументов снижает риск, но не подменяет ответственность продукта за принятое действие.

Server-side пример

Пример показывает локальный контроллер на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут, model ID и параметры в текущем каталоге RussiaAPI.

const allowedTools = new Set(['get_order_status']);

export function validateToolCall({ tool, args, session }) {
  if (!allowedTools.has(tool)) return { ok: false, code: 'tool_not_allowed' };
  if (typeof args?.orderId !== 'string' || !/^ord_[a-z0-9]+$/.test(args.orderId)) return { ok: false, code: 'invalid_arguments' };
  return { ok: true, tenantId: session.tenantId, orderId: args.orderId };
}
// After validation, verify ownership and state in your database; call documented RussiaAPI routes server-side only.

Проверьте синтаксис через node --check, добавьте аутентификацию своего маршрута и негативные тесты. Не логируйте тело запроса или заголовки только ради отладки.