Claude API: проверка tool result перед побочным действием

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

Tool result, текст модели и структура, похожая на команду, приходят на границу вашего приложения как недоверенные данные. Они не дают модели право изменить запись, отправить письмо, опубликовать файл или вызвать внутренний сервис. Разрешение остаётся у server-side policy, где известны пользователь, tenant, текущая роль и допустимая операция.

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

Свяжите ответ с operation ID

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

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

Валидируйте схему и allowlist

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

Allowlist должен быть привязан к роли и контексту. Например, чтение статуса может быть доступно оператору, а публикация — только после отдельного подтверждения. Не делайте список инструментов глобальным разрешением: доступ одного tenant или среды не переносится на другой. При неизвестной комбинации выбирайте review.

Требуйте подтверждение для side effect

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

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

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

На staging проверьте как минимум пустой result, лишнее поле, чужой operation ID, повтор того же результата, отсутствие роли и отказ подтверждения. Каждый случай должен иметь предсказуемый безопасный исход без вызова side effect. Синтетические fixtures дают полезнее доказательство, чем один успешный production-диалог.

Читайте также валидацию аргументов tools, обработку stop reason и корреляцию нескольких tool result. Это связанные инженерные страницы, а не подтверждение API-функций Anthropic или RussiaAPI.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

export function validateToolResult(result, operation, actor) {
  if (!operation || operation.id !== result?.operationId || operation.state !== 'awaiting_result') return { ok: false, action: 'stop' };
  if (!actor?.permissions?.includes(result.tool) || !operation.allowedTools.includes(result.tool)) return { ok: false, action: 'review' };
  if (!result.payload || typeof result.payload !== 'object') return { ok: false, action: 'invalid_schema' };
  return { ok: true, action: operation.sideEffect ? 'require_confirmation' : 'continue' };
}

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

Anthropic tool use documentation · OWASP Input Validation Cheat Sheet

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

FAQ

Можно ли исполнять tool result сразу?

Нет. Результат нужно рассматривать как недоверенный вход: проверить локальную схему, operation ID, права и правило подтверждения. Текст модели не является авторизацией.

Достаточно ли request ID внешнего API?

Нет. Нужен собственный operation ID с владельцем, ожидаемым действием и состоянием в вашей системе. Он помогает не смешать и не повторить операции.

Следует ли отправлять ключ в tool result?

Нет. Секреты не должны попадать в tool result, prompt, браузер или логи. Используйте только собственный ключ RussiaAPI на сервере через секрет-хранилище.

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

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