Переезд с Opus 5 на Opus 5.5: четыре ломающих изменения и чек-лист проверки кода

Что меняется в двух словах

Opus 5.5 сохраняет почти всю поверхность API Opus 5: тот же контекст, тот же токенизатор, те же бюджеты задач, сжатие контекста, системные сообщения посреди диалога, пакетный режим и Files API. Перемерять токены не нужно.

Но есть четыре ломающих изменения, одно изменение формы ответа, которое не роняет запросы, и смена уровня усилия по умолчанию. Три из четырёх ломающих изменений — те же механизмы, что появились в Fable 5.1: если вы уже переезжали на неё, большая часть работы сделана.

1. Мышление нельзя отключить

На Opus 5 значение thinking с типом disabled принималось на усилии high и ниже. На Opus 5.5 оно возвращает 400 на любом уровне усилия. Фиксированный бюджет рассуждения тоже возвращает 400, как и раньше.

Как чинить: уберите параметр thinking совсем или передайте тип adaptive. Если маршрут выключал мышление ради скорости первого токена, поставьте усилие low и замерьте качество; если оно просело — medium. Увеличьте max_tokens: рассуждение считается в этот лимит, даже если его текст не возвращается. Для длинных агентных ходов хорошо работает 64 тысячи.

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

И ещё одно: читайте ответ по типу блока, а не по позиции. Ответ может начинаться с одного или нескольких блоков thinking, по умолчанию с пустым текстом. Код вида content[0].text на Opus 5.5 сломается.

• Убрать thinking disabled и budget_tokens.
• Для скорости — effort low, затем замер качества.
• Поднять max_tokens с учётом рассуждения.
• Удалить из промптов запреты на рассуждение.
• Искать текст по type === "text", а не по content[0].

2. Уровень усилия по умолчанию стал ниже

Это не ломающее изменение в смысле ошибок, но самое незаметное. У Opus 5 по умолчанию усилие high, у Opus 5.5 — medium. Код, который никогда не задавал output_config.effort, после смены идентификатора начнёт рассуждать меньше, и сравнение качества «до и после» окажется некорректным.

Как чинить: пропишите усилие явно на каждом маршруте. Для сравнения с Opus 5 начните с high, а дальше спускайтесь по ступеням и смотрите, где качество ещё держится. Для агентной разработки разумный старт — high или xhigh, для простых маршрутов — low.

3. Принудительный вызов инструмента запрещён

tool_choice со значениями any и tool возвращает 400 — в Messages API, в пакетном режиме и при подсчёте токенов. Значения auto и none работают по-прежнему, disable_parallel_tool_use вместе с auto тоже работает, но означает «не более одного вызова».

Как чинить по назначению. Если нужно направить модель к инструменту — ставьте auto, пишите в промпте, какой инструмент использовать, включайте strict: true в описании инструмента, чтобы аргументы строго соответствовали схеме. auto не гарантирует вызов, поэтому проверяйте, что блок tool_use в ответе есть, и повторяйте запрос, если его нет.

Если принудительный вызов был нужен только для того, чтобы получить JSON, замените его структурированным выводом через output_config.format — это надёжнее и проще.

• any и tool заменить на auto + инструкцию в промпте.
• strict: true для строгой схемы аргументов.
• Проверять наличие tool_use и повторять при отсутствии.
• Для извлечения JSON — структурированный вывод.

4. Блоки мышления привязаны к модели и к диалогу

Привязка к модели. Opus 5.5 читает блоки мышления от Opus 5 и более ранних моделей Opus, Sonnet и Haiku — диалог, переехавший на Opus 5.5, сохраняет рассуждение. Но на Claude API блоки Opus 5.5 читают только Fable 5.1 и Mythos 5.1. При переключении на Opus 5 или Opus 4.8 — через роутер, ретрай на другой модели или запасную модель при отказе — рассуждение прошлых ходов молча отбрасывается. Запрос проходит, отброшенные блоки не тарифицируются. Сами блоки не вырезайте: передавайте историю как есть.

Привязка к диалогу. Системный промпт, набор инструментов и все предыдущие сообщения должны оставаться байт-в-байт такими же, как в момент создания блока. Для аккаунтов, созданных 31 августа 2026 года и позже, нарушение этого правила возвращает 400; старые аккаунты могут включить проверку сами.

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

Хорошая новость: эти же правки повышают долю попаданий в кеш, так что они окупаются даже для аккаунтов, на которые проверка не распространяется.

• Блоки Opus 5.5 читают только Fable 5.1 и Mythos 5.1.
• История только дописывается — никаких правок задним числом.
• Инструменты объявляются полным набором в начале сессии.
• Сжатие — серверное или полной заменой истории.

5. Управление компьютером — только через computer toolset

Opus 5 принимал и новый набор computer_toolset_20260801, и старый инструмент computer_20251124 с бета-заголовком. Opus 5.5 принимает только набор. Запрос со старым инструментом возвращает 400 с перечнем допустимых типов.

Это больше, чем замена одной строки в tools. У набора нет имени и размеров экрана в описании. Действие — это имя блока tool_use (screenshot, left_click, zoom и так далее), а не поле input.action. За один ход может прийти несколько вызовов. На каждый нужно вернуть отдельный tool_result с полем toolset_name: "computer", а изображение — только для screenshot и zoom.

Opus 5 принимает обе формы, поэтому переделку удобно сделать и проверить на нём, а уже потом менять идентификатор модели.

6. Заметки между вызовами инструментов уехали в блоки мышления

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

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

Чек-лист перед сменой идентификатора

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

• Поиск по thinking: disabled и budget_tokens — убрать, заменить на effort.
• Явно прописать output_config.effort на каждом маршруте.
• Поднять max_tokens с учётом рассуждения.
• Поиск по tool_choice any и tool — заменить на auto + strict + проверку вызова.
• Разбирать ответ по типу блока, а не по индексу.
• Проверить, что история, системный промпт и набор инструментов не редактируются задним числом.
• Перевести computer use на computer_toolset_20260801.
• Настроить отображение заметок о прогрессе в интерфейсе агента.
• Проверить обработку причины остановки refusal — классификаторов стало больше.
• Прогнать свои задачи на Opus 5 и Opus 5.5 и сравнить стоимость за выполненную задачу.

Переезд через наш шлюз

Со стороны шлюза менять ничего не нужно: запросы проксируются в формате Anthropic API без изменений, поэтому все описанные параметры — effort, строгие инструменты, режимы отображения мышления, бета-заголовки — передаются как есть. Достаточно поменять идентификатор на claude-opus-5-5. Расход по новой модели считается по её собственному тарифу и виден в кабинете отдельно, так что Opus 5 и Opus 5.5 удобно гонять параллельно на время перехода.