Миграция Claude Opus 5.5 API: что менять? Проверка 2026

Симптом: после замены идентификатора модели ответы приходят, но Agent теряет контекст, повторяет инструменты или зависает на длинной задаче.

Самое быстрое решение: миграция Claude Opus 5.5 API не сводится к замене model. Сначала зафиксируйте старый baseline, затем в двух контурах проверьте thinking, полный возврат thinking block, инструменты, очистку контекста при переключении и восстановление после прерывания. Низкорисковые запросы можно пилотировать сразу; производственный Agent с инструментами не переводите полностью без одинаковой регрессионной проверки.

Эта статья для разработчиков Claude API, которым нужно проверить совместимость существующих запросов Messages API; для платформенных инженеров, отвечающих за thinking block, инструменты и состояние отката; а также для технических руководителей AI-команд, которым нужно провести ограниченный запуск в окне релиза и не потерять прежнюю модель как резервный маршрут.

Дата проверки: последнее обновление — 23 сентября 2026 года. Дата релиза и доступность Claude Opus 5.5 сверены с официальным объявлением Anthropic от 22 сентября 2026 года. Поведение конкретного SDK, клиента и обвязки нельзя считать подтверждённым без отдельного теста.

Сначала разделите релиз, платформу и ваш интеграционный код

Claude Opus 5.5 официально представлен 22 сентября 2026 года и доступен через Claude Platform; это не означает, что одинаковая миграция автоматически применима к Claude Code, стороннему клиенту, внутреннему шлюзу или собственной системе оркестрации. В каждом из этих путей могут различаться точка выбора модели, поддерживаемые параметры, сериализация истории и обработка ошибок. Поэтому в журнале миграции укажите не только название модели, но и путь запроса: напрямую через API, через прокси, через SDK или через внутренний Agent Host.

Официальное описание также связывает новую модель с preserved thinking. Для API-аккаунтов, созданных 31 августа 2026 года или позже, этот механизм имеет отдельное значение; дату и правило нужно сверять по первоисточнику, а не переносить из поста сообщества. В документации о thinking и его сохранении проверяйте именно актуальные требования к истории и содержимому блоков.

Нельзя превращать формулировку о том, что большинство задач демонстрирует результат, близкий к Claude Fable 5.1, в обещание полной эквивалентности. «Похожая производительность» не отвечает на вопросы о вашем tool executor, правах, тайм-ауте, рабочем каталоге, CI или длительности восстановления. Модельный ответ и исполнение задачи — разные объекты приёмки.

До первого запроса заморозьте старый baseline

Миграция Claude Opus 5.5 API начинается не с нового запроса, а с копии работающего старого маршрута. Зафиксируйте:

• идентификатор прежней модели и все параметры Messages API;
• включён ли thinking, каким способом задавался бюджет и какие ограничения действовали;
• описания tools, обязательность выбора инструмента и порядок передачи tool_use и tool_result;
• способ объединения системной инструкции, истории, результатов инструментов и промежуточных сообщений;
• правила тайм-аута, повтора, ручной остановки и переключения на резервную модель;
• структуру логов, по которой можно восстановить запрос без утечки секретов.

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

Минимальный набор контрольных заданий должен включать обычный вопрос, изменение кода, вызов инструмента, длинный контекст и намеренный откат. Это не рейтинг моделей: вы проверяете сохранение контракта. Если старый запуск уже не воспроизводится, сначала исправьте baseline, иначе проблема в облачном Mac, CI, правах или рабочем каталоге будет ошибочно приписана API-миграции.

Для внешнего действия отдельно запишите ожидаемый результат и фактический побочный эффект. Agent, который сформировал корректный JSON, ещё не доказал, что исполнитель применил его безопасно. Точно так же успешный HTTP-ответ не доказывает, что изменился файл, прошла сборка или сохранилась бизнес-транзакция.

Первый контур: сравните контракт запроса и ответа

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

Проверяйте контракт в следующем порядке.

1. Идентификатор модели. Убедитесь, что шлюз не заменяет значение своим alias и не отправляет старую модель после локального кэширования конфигурации.
2. Thinking. Сопоставьте включённый и выключенный режимы, а также параметр effort, если он предусмотрен вашим актуальным API-контрактом. Старый параметр бюджета нельзя считать совместимым только потому, что запрос не завершился HTTP-ошибкой.
3. Структура ответа. Клиент должен разбирать не только text, но и thinking, redacted_thinking, вызовы инструментов и промежуточные события, если они используются вашим способом передачи.
4. Tools. Сверьте имя, описание, JSON-схему аргументов, обязательные поля, режим принудительного выбора и фактический ответ исполнителя.
5. Предварительно заполненный ответ. Если старый клиент начинал ответ за модель или подставлял часть сообщения, прогоните этот путь отдельно: такая техника может быть связана с прежней последовательностью сообщений.
6. Ошибки. Различайте отказ параметров, отказ инструмента, сетевой повтор, тайм-аут и ошибку бизнес-операции. Ориентиром служит официальная страница ошибок API, но итоговый код нужно подтвердить на вашей версии клиента.

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

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

После первого вызова сохраните не только текст, но и состояние

Основная ловушка Claude Opus 5.5 — считать естественный язык полной историей задачи. Для AI Agent это неверно. Разделите минимум четыре слоя:

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

Если вы храните только краткое резюме, после остановки Agent может знать, «что хотел сделать», но не знать, какой инструмент уже выполнился, какой файл изменён и можно ли повторять действие. Резюме полезно как индекс для оператора, но не как единственная точка восстановления.

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

Тестируйте три независимых сценария:

1. обычный вызов без инструмента;
2. успешный вызов инструмента с последующим ответом;
3. ошибка инструмента или прерывание между вызовом и сохранением результата.

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

Важное ограничение: при переходе между моделями не переносите историю механически. Официальные правила preserved thinking требуют учитывать, какие thinking block принадлежат прежней модели; несовместимые блоки нужно очищать перед новым запросом. Это граница контракта, а не косметическая настройка интерфейса.

Переключение модели требует отдельного маршрута очистки

Модельный fallback — это не строка if error then another_model. Сначала определите причину переключения. Сетевой повтор может сохранить тот же контекст; отказ параметров требует исправления запроса; ошибка инструмента может требовать ручной остановки; смена модели может потребовать удаления thinking block, которые новая модель не должна получать.

Перед откатом сохраните:

• исходный запрос и версию контракта;
• последнюю принятую последовательность сообщений;
• незавершённое бизнес-состояние;
• список уже выполненных инструментов;
• рабочую область и незакоммиченные изменения;
• причину переключения и решение оператора.

Затем соберите контекст для целевой модели заново. Передавайте только те блоки, которые разрешены её текущей схемой, а состояние операции представляйте структурированными полями. Не пытайтесь «починить» несовместимый thinking block простой обрезкой строки: вы можете скрыть причину ошибки и получить дублирование действия.

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

Если ошибка возникает после успешного tool use, повторять весь запрос опасно. Сначала определите, был ли инструмент исполнен. Идемпотентная операция может быть повторена по ключу; неидемпотентное внешнее действие должно перейти оператору. Это особенно важно для платежей, публикаций, изменения прав, удаления файлов и операций с production-ресурсами.

Длинная задача: от тайм-аута до доказательства результата

В последнем контуре воспроизведите не идеальный ответ, а рабочий сбой. Запустите представительскую длинную задачу и искусственно проверьте:

• превышение тайм-аута API;
• отказ инструмента;
• разрыв между ответом модели и сохранением результата;
• переключение на резервную модель;
• повтор после частичного выполнения;
• ручную передачу задачи оператору;
• финальную независимую проверку результата.

Обычный сетевой retry нельзя смешивать с отказом безопасности или неверным параметром. В первом случае возможно повторное соединение; во втором повтор не исправляет контракт. В логах должны быть разные причины, иначе статистика создаст ложное ощущение стабильности.

Для Xcode, macOS-приложений, настольных инструментов и CI нужен отдельный реальный Mac. Успешный API-вызов не подтверждает доступ к ключевой цепочке, симулятору, рабочему каталогу, подписанию, GUI-сессии или установленной версии SDK. Перед передачей такой задачи на арендуемый Mac зафиксируйте ожидаемый артефакт, команду сборки, права и критерий завершения. На стороне MacPull можно сверить руководство по приёмке полной нагрузки Mac mini, но оно не заменяет проверку вашего Agent Host.

Практическая последовательность запуска выглядит так:

1. Скопируйте старый конфиг и зафиксируйте его версию.
2. Подготовьте обезличенные контрольные задания.
3. Подключите Claude Opus 5.5 в изолированном маршруте без внешней записи.
4. Сравните запросы, все блоки ответа и фактические вызовы tools.
5. Введите искусственное прерывание и восстановите задачу из раздельного состояния.
6. Проверьте откат после ошибки, очистив несовместимые блоки.
7. Выполните реальную сборку или другое конечное действие в независимой среде.
8. Подпишите решение: миграция, два контура или временная остановка.

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

Первая неделя: низкий риск вперёд, исполнение под защитой

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

Сравнивайте не одну удачную реплику, а весь жизненный цикл:

• завершилась ли задача с доказанным результатом;
• сколько раз оператор исправлял вывод;
• сколько было повторов инструментов;
• сохранился ли контекст после прерывания;
• сколько раз потребовался ручной перехват;
• сколько времени ожидалась внешняя среда;
• какие ошибки пришлись на API, а какие — на исполнитель, CI или Mac.

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

Для наблюдения за API-частью и инструментальными блоками полезно сверяться с обзором tool use в официальной документации. А если после API-проверки задача переходит к удалённой macOS-среде, заранее определите, что именно считается доставленным результатом; для этого пригодится материал о проверке macOS-сборки в удалённой среде.

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

Какие параметры нужно менять в первую очередь?

Начните с модели, thinking, effort, tools и обработчика ответа. Затем проверьте старые параметры бюджета, обязательный выбор инструмента и предварительно заполненный ответ. Ошибка «запрос принят» не доказывает совместимость: клиент мог отбросить thinking block или преобразовать вызов инструмента в текст.

Можно ли сразу заменить старую модель?

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

Как передавать thinking block?

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

Почему после миграции ломается tool use?

Причина может быть в имени или JSON-схеме инструмента, порядке tool_use и tool_result, принудительном выборе, старом адаптере либо в самом исполнителе. Поэтому воспроизводите не только API-запрос, но и реальное действие с отказом, тайм-аутом, повтором и записью результата.

Как оставить резервный маршрут для Agent?

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

Текущий API-маршрут обычно быстрее для уже работающей команды, но он может скрывать старые параметры, не сохранять полные блоки ответа и не иметь проверенного восстановления. Облачный запуск без отдельной macOS-приёмки добавляет ещё одну слабую границу: API завершился, а сборка, подпись или GUI-действие так и не доказаны. Если для регрессии нужна временная изолированная Mac-среда, аренда MacPull удобнее именно как контролируемый этап проверки, а не как обещание автоматически улучшить модель или снизить расходы. Сначала сохраните baseline, затем оформите критерии отката; ознакомиться с доступными вариантами можно в разделе аренды MacPull.

Частые вопросы