Проверка префикса для блоков размышлений

К каждому запросу, который отправляет “thinking blocks” (блоки размышлений) обратно модели с сохранёнными размышлениями, применяется “prefix check” (проверка префикса). Проверка префикса не пройдена, если system, tools или более раннее сообщение изменились после того, как Claude создал блок. Она также не пройдена, если блок размышлений, находящийся между другими, был пропущен или перемещён.

Провал проверки префикса может привести, а может и не привести к ошибке 400 в зависимости от модели, поэтому обрабатывайте оба случая.

На кого влияет проверка префикса

Вам ничего не нужно менять, если верно одно из следующего:

• Историей вашего разговора управляет Claude Code, claude.ai или Claude Managed Agents.
• Историей управляет Claude Agent SDK, а “system prompt” (системная подсказка), которую вы передаёте SDK, остаётся неизменной.
• Ваш код следует трём привычкам интеграции по принципу «только добавление», и ничто не переписывает его запросы по пути.
• Вы не вызываете ни одну модель с сохранёнными размышлениями.

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

Что должно оставаться неизменным и почему

Сделайте свою интеграцию append-only (по принципу «только добавление»). Для этого достаточно трёх привычек:

1. Отправляйте каждый ход ассистента обратно точно в том виде, в каком его вернул API, включая блоки размышлений с пустым текстом.
2. Формируйте system и tools один раз для каждого разговора и каждый раз отправляйте эту копию.
3. Помещайте каждое обновление в новое сообщение в конце и оставляйте его там.

Рассуждения в каждом блоке размышлений относятся именно к тому, что было до него: system, tools и все более ранние сообщения. Это содержимое является префиксом блока, и именно его сравнивает проверка префикса.

Проверка префикса похожа на “prompt caching” (кэширование подсказок), за исключением того, что изменение делает размышления после него недействительными, а не просто приводит к промаху кэша.

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

Изменение делает недействительными только те размышления, которые уже следуют за ним. Размышления до него и размышления, которые Claude создаёт после, остаются действительными.

Если ваш код изменяет системную подсказку, инструменты или историю

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

Что делает каждая модель, когда проверка префикса не пройдена

В Claude API и на некоторых облачных платформах результат провала проверки префикса, когда настройка prefix_mismatch_behavior не указана, зависит от модели:

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

Для этих моделей вы можете проверить, какой случай получает запрос, но обрабатывайте оба случая.

Элементы Message Batches, в которых настройка prefix_mismatch_behavior не указана, не получают ошибки, и API может отбросить блоки, не прошедшие проверку префикса.

Обрабатывайте оба случая

Чтобы получать один результат для каждого запроса, сделайте свою интеграцию работающей по принципу «только добавление» или задайте prefix_mismatch_behavior. В противном случае ваш код должен обрабатывать оба варианта поведения.

• «Только добавление»: при соблюдении трёх привычек ваш код не приводит к тому, что запрос не проходит проверку префикса.
• Настройка: при значении "error" в каждом запросе каждый провал проверки префикса — это ошибка 400, и вы перехватываете её в коде.
• Оба варианта поведения: если вы не указываете настройку, перехватывайте ошибку 400 и отслеживайте размышления, не прошедшие проверку префикса и дошедшие до Claude.

После ошибки 400 отправляйте "drop_block" в последующих запросах этого разговора, чтобы восстановить его. У этого есть цена: см. Во что обходится отбрасывание размышлений. Не отправляйте это значение во всех своих разговорах, чтобы скрыть ошибки.

Технические подробности

Как работает проверка префикса

Модели с сохранёнными размышлениями записывают отпечаток префикса каждого блока размышлений в его signature. В справочнике API проверка префикса называется проверкой разговора (conversation check), а ошибка 400 сообщает, что блок, не прошедший проверку префикса, is bound to a different conversation.

Какие модели выполняют проверку префикса

Проверка префикса выполняется в Claude API и на некоторых облачных платформах. Она проверяет блоки размышлений, созданные моделью с сохранёнными размышлениями, в запросах к одной из этих моделей. В Claude API другие модели, например Claude Opus 5, её не выполняют, и она не распространяется на их блоки.

Что считается изменением

• Каждый блок проверяется по собственной записи. API сравнивает то, что находится перед блоком в этом запросе, с тем, что записала его подпись, когда Claude его создал. Ваш предыдущий запрос роли не играет. Проверка префикса смотрит только на содержимое, а не на сеансы, идентификаторы или пользователей. То же самое содержимое в новом запросе или ответвлении (fork) её проходит.
• Проверка префикса сравнивает то, что вы отправили, а не то, что прочитал Claude. Сжатие контекста при достижении порога токенов и редактирование контекста изменяют только то, что читает Claude, поэтому они никогда не учитываются. После блока сжатия по порогу API сравнивает только сообщения начиная с этого блока, а также system и tools. У сжатия по запросу свои условия: см. Условия, при которых сохранённые размышления остаются действительными. Для файла, отправленного по URL, и, в Claude API, для списка инструментов MCP API вместо этого сравнивает то, что он получил.
• Отправляемые вами размышления должны идти непрерывной последовательностью. Блоки размышлений не сравниваются как содержимое. Но у каждого отправляемого вами блока, кроме первого, должен быть тот же предыдущий блок размышлений, что и тогда, когда Claude его создал. Поэтому вы можете пропустить самые старые, самые новые или все блоки, но не один из промежуточных.

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

Что не учитывается

Задайте prefix_mismatch_behavior

Бета-заголовок thinking-binding-controls-2026-08-01 добавляет настройку thinking.block_binding.prefix_mismatch_behavior и массив input_transformations в ответе.

Блоки, не прошедшие проверку префикса, остаются недействительными в каждом последующем запросе, который их отправляет, пока изменение сохраняется. Настройка действует на тот единственный запрос, который её содержит. При выключенных размышлениях ("disabled" или "between_tools") её отправка приводит к ошибке 400 на любой модели.

Следующий запрос задаёт prefix_mismatch_behavior значение "drop_block". На первом ходе нет размышлений, которые нужно отправить обратно, поэтому input_transformations возвращается пустым:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

Отслеживайте рабочий трафик

Когда настройка prefix_mismatch_behavior не указана, запрос, не прошедший проверку префикса, может не получить ошибки на некоторых моделях. Тогда блоки размышлений, не прошедшие проверку префикса, доходят до модели. Чтобы найти эти блоки в рабочем трафике, отправляйте бета-заголовок thinking-binding-controls-2026-08-01, не указывайте настройку и записывайте в журнал массив input_transformations каждого ответа. Заголовок добавляет этот массив и не меняет того, что получает модель.

Каждый из этих блоков получает в этом массиве собственную запись thinking_mismatch_allowed. Одна запись выглядит так:

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Чтобы найти изменение, см. Найдите, что изменил ваш код.

Проверьте, какой случай вы получаете

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

1. Возьмите разговор, содержащий блок размышлений от одной из этих моделей. Измените или добавьте системную подсказку (system). Тогда блок не проходит проверку префикса, потому что системная подсказка изменилась после того, как Claude создал блок.
2. Отправьте его той же модели с бета-заголовком thinking-binding-controls-2026-08-01 и не указывайте prefix_mismatch_behavior.

Ответ будет одним из следующих:

• Ошибка 400 с текстом bound to a different conversation: запрос получил ошибку 400.
• Ответ 200, массив input_transformations которого содержит записи thinking_mismatch_allowed: запрос не получил ошибки. Каждая запись указывает блок размышлений, который не прошёл проверку префикса и дошёл до Claude.
• Ответ 200 с пустым массивом input_transformations: ни один блок не провалил проверку префикса, поэтому тест ничего не показывает. Убедитесь, что разговор содержит блок размышлений от этой модели.

Результат описывает только этот один запрос и ничего не гарантирует относительно последующих, поэтому пишите код так, чтобы обрабатывать оба случая.

Дальнейшие шаги