Claude API: как обрабатывать stop reason

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

RussiaAPI — независимый сторонний API gateway и не является официальным сервисом Anthropic. Поддержку конкретной модели, формата ответа, инструментов и условий проверьте в текущем каталоге и договоре. Ниже описан пример логики приложения, а не гарантия поведения gateway.

Сначала определите контракт

У прямого Anthropic Messages API поле stop_reason описано в документации Anthropic. Однако OpenAI-совместимый маршрут может возвращать другой формат. Не считайте одно поле универсальным для всех endpoints. Зафиксируйте версию контракта, модель, маршрут и дату теста; затем напишите адаптер, который преобразует только документированные значения в внутренние состояния приложения.

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

Разделите завершение и усечение

Если контракт подтверждает нормальное завершение, приложение может показать результат после собственных проверок. Усечённый ответ отмечайте как неполный: например, пользователь должен видеть, что список или код мог оборваться. Автоматическое продолжение увеличивает затраты и может породить дубли; решение зависит от задачи, бюджета и условий конкретного интерфейса.

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

Инструмент не равен разрешению

Если ответ предлагает вызвать инструмент, проверьте имя по allowlist, схему аргументов, права пользователя и бизнес-ограничения. Запись, отправка сообщения или платёж могут иметь побочные эффекты: для них нужна отдельная проверка и, где уместно, подтверждение. Не повторяйте действие только потому, что потерялся ответ сети. Сначала выясните его состояние по собственному идентификатору операции.

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

function nextStep(category) {
  switch (category) {
    case 'complete': return 'show_after_validation';
    case 'truncated': return 'mark_incomplete';
    case 'tool_requested': return 'validate_and_authorize';
    case 'refused': return 'show_refusal';
    default: return 'manual_review';
  }
}
console.log(nextStep('truncated'));

Проверка перед выпуском

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

Как устроить адаптер ответа

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

Например, для прямого Messages API Anthropic документирует end_turn, max_tokens, tool_use и другие значения. Это описание относится к указанному интерфейсу, а не ко всем совместимым шлюзам. При потоковой выдаче следуйте правилам конкретного потока и не делайте вывод по первому фрагменту: итоговую причину нужно получить и обработать согласно документации маршрута. Неизвестный формат, отсутствующее поле или незавершённый поток — отдельные случаи для диагностики.

Сценарий: помощник поддержки

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

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

Набор регрессионных проверок

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

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

Эксплуатация и границы

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

Когда требуется повторная проверка

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

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

FAQ

Можно ли автоматически повторить усечённый ответ?

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

Доступны ли инструменты через любой маршрут?

Нет оснований предполагать это. Сверьте конкретную модель, endpoint и условия с актуальной документацией и проведите тест на staging.

Что делать с неизвестной причиной?

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

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

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