Руководство по миграции на Claude Opus 5.5

На этой странице перечислены изменения кода для перехода на Claude Opus 5.5 с Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 и более ранних моделей Opus или Claude Sonnet 5. Всем читателям нужны разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5 и Обработка размышлений в каждом ответе. Затем перейдите к разделу для вашей текущей модели: в его первом предложении названы другие разделы, которые к вам относятся. В контрольном списке миграции перечислены все изменения для каждой исходной модели.

Claude Opus 5.5 стоит дешевле, чем Claude Opus 5 ($4 / $20 USD за миллион входных / выходных токенов по сравнению с $5 / $25; см. цены Claude). Сведения о поддержке функций см. в разделе Что нового в Claude Opus 5.5. Различия в поведении и шаблоны подсказок для конкретной модели описаны в разделе Составление подсказок для Claude Opus 5.5.

Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5

С какой бы модели вы ни переходили, запрос к claude-opus-5-5 должен соответствовать следующим требованиям. Если в пункте сказано, что параметр отклоняется, API возвращает ошибку 400.

• Идентификатор модели: Используйте claude-opus-5-5 — фиксированный идентификатор модели без суффикса даты. В Amazon Bedrock, Claude Platform on AWS, Google Cloud и Microsoft Foundry используйте идентификатор модели соответствующей платформы; см. Доступность.
• Размышления: Не отправляйте поле thinking или отправьте thinking: {"type": "adaptive"}, что равнозначно: «adaptive thinking» (адаптивные размышления) всегда включены. thinking: {"type": "disabled"} и ручные бюджеты размышлений (thinking: {"type": "enabled", "budget_tokens": N}) отклоняются. См. пример «до и после» для размышлений.
• Effort: Управляйте глубиной размышлений с помощью параметра effort — единственного параметра запроса, который ею управляет. Поддерживаются все пять уровней (low, medium, high, xhigh, max), по умолчанию используется medium. См. Рекомендуемые уровни effort для Claude Opus 5.5.
• Выбор инструмента: Используйте tool_choice {"type": "auto"} (по умолчанию) или {"type": "none"}. Принудительный вызов инструмента с помощью {"type": "any"} или {"type": "tool", "name": "..."} отклоняется. См. пример «до и после» для выбора инструмента.
• Параметры сэмплирования: Не указывайте temperature, top_p и top_k или оставьте их значения по умолчанию: любое другое значение отклоняется. Используйте подсказки, чтобы направлять поведение модели.
• Предзаполнение: Не завершайте messages предзаполненным ходом ассистента: такой запрос отклоняется. Вместо этого используйте структурированные выходные данные или инструкции в системной подсказке. В Amazon Bedrock структурированные выходные данные недоступны для Claude Opus 5.5, поэтому там используйте инструкции в системной подсказке.
• «Computer use» (использование компьютера): В Claude API и Google Cloud объявляйте использование компьютера как набор инструментов computer_toolset_20260801; более ранний инструмент computer_20251124 там отклоняется. См. критическое изменение для использования компьютера.
• Контекстное окно: Бета-заголовок для контекстного окна не нужен. Контекстное окно на 1M токенов используется по умолчанию, а заголовок, отправляемый для старых моделей, ни на что не влияет.

Следующий запрос соответствует всем пунктам списка: effort задан, а поле thinking отсутствует. Вкладки SDK, которые выводят текст, выбирают его по типу блока, поскольку блоки thinking идут первыми.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

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

Обработка размышлений в каждом ответе

Размышления выполняются при каждом запросе к Claude Opus 5.5, поэтому каждый ответ может начинаться с блоков thinking, а max_tokens охватывает размышления вместе с текстом. Если ваш код уже работает с включёнными размышлениями, пункты 1–3, скорее всего, уже выполнены: проверьте пункты 4 и 5. Если он работал без размышлений на любой более ранней модели, каждый пункт требует изменений.

1. max_tokens охватывает размышления и текст: В Claude Opus 4.8 и более ранних моделях Opus запросы без поля thinking выполняются без размышлений. Claude Opus 5 и Claude Sonnet 5 принимают thinking: {"type": "disabled"}. В Claude Opus 5.5 каждый запрос выполняется с адаптивными размышлениями. max_tokens остаётся жёстким ограничением на общий вывод — размышления плюс текст ответа, поэтому пересмотрите это значение для рабочих нагрузок, которые выполнялись без размышлений. Токены размышлений оплачиваются как выходные токены, даже если текст размышлений вам не возвращается, поэтому такая рабочая нагрузка может генерировать больше выходных токенов на запрос. См. Контроль затрат. Чтобы тратить меньше токенов на размышления, понизьте уровень effort. Если вы работаете с effort xhigh или max, задайте большое значение max_tokens, чтобы у модели было пространство для размышлений и действий; начните с 64k токенов и настраивайте дальше. Если ваши подсказки были настроены для работы без размышлений, см. Подсказки, написанные для отключённых размышлений.

2. Ответы начинаются с блоков размышлений: Ответ может начинаться с одного или нескольких блоков thinking перед первым блоком text. Код, который читает ответ по позиции, например content[0].text или обработчик потока, считающий первое событие content_block_start текстом, ломается на таких ответах. Вместо этого выбирайте блоки содержимого по их полю type: читайте text из блоков, у которых type равен "text", и ветвите логику по типу блока при обработке событий потока.

3. Возвращайте блоки размышлений без изменений в циклах использования инструментов: Если вы запускаете цикл «tool use» (использование инструментов), при возврате результатов инструментов передавайте блоки thinking из каждого ответа ассистента обратно в API полностью и без изменений, включая блоки с пустым полем thinking. Отправляйте сообщение ассистента обратно в том виде, в каком оно было получено, вместо того чтобы фильтровать его блоки содержимого по типу или пересобирать его: API отклоняет отредактированные, переупорядоченные или частично удалённые блоки размышлений с ошибкой 400. См. Сохранение блоков размышлений.

4. Текст размышлений по умолчанию опускается: thinking.display по умолчанию имеет значение "omitted", поэтому блоки thinking приходят с пустым полем thinking вместе со своей signature. Рассматривайте поле thinking только как текст для отображения. Чтобы вместо этого получать читаемые сводки, установите для thinking.display значение "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

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

5. Текст между вызовами инструментов приходит в блоках размышлений: Короткие заметки, которые модель пишет между вызовами инструментов, возвращаются как блоки thinking, которые пусты при режиме отображения по умолчанию. См. Текст между вызовами инструментов возвращается в блоках размышлений.

Контрольный список миграции по исходной модели

Проходите группы сверху вниз и остановитесь после той, в которой названа ваша текущая модель: к вам относятся все пункты до этого места. Если вы используете Claude Opus 5, первая группа — это весь список. Если вы используете Claude Sonnet 5, примените первую и последнюю группы.

Любая исходная модель

• Обновите идентификатор модели на claude-opus-5-5.
• Удалите thinking: {"type": "disabled"} и thinking: {"type": "enabled", ...}; вместо этого выберите уровень effort.
• Задайте effort явно: по умолчанию используется medium, тогда как у Claude Opus 5 — high.
• Замените типы tool_choice any и tool на auto в сочетании со строгим использованием инструментов или структурированными выходными данными либо только на auto в Amazon Bedrock.
• Если вы используете инструмент использования компьютера в Claude API или Google Cloud, объявите computer_toolset_20260801 (без бета-заголовка) вместо computer_20251124 и обновите цикл агента для набора инструментов. В Amazon Bedrock оставьте computer_20251124; для других платформ см. раздел Совместимость инструмента использования компьютера.
• Если маршрутизатор или резервный механизм может перевести разговор с Claude Opus 5.5 на другую модель, учитывайте, что эта модель будет работать без блоков размышлений Claude Opus 5.5 (исключение — Claude Fable 5.1 и Claude Mythos 5.1 в Claude API, которые их сохраняют). Сам Claude Opus 5.5 читает размышления от Claude Opus 5, от более ранних моделей Opus, Sonnet и Haiku, а в Claude API и Google Cloud — от Claude Sonnet 5.5 и Claude Haiku 5.5, но не от моделей Claude Fable или Claude Mythos.
• Читайте блоки содержимого по type и передавайте блоки thinking обратно без изменений в циклах использования инструментов.
• Если ваш интерфейс отображает текст между вызовами инструментов, задайте display: "updates" (бета) или "summarized" и отображайте непустые блоки thinking.
• Если ваш код редактирует предыдущие ходы, подсказку system или tools посреди разговора, следуйте разделу Сохранённые размышления.
• Обрабатывайте stop_reason: "refusal" и настройте резервный механизм.
• Заново определите базовые показатели стоимости и задержки на выбранном уровне effort.
• Если ваш код отключал размышления, пересмотрите max_tokens, который охватывает размышления вместе с текстом ответа; при effort xhigh или max начните с 64k. См. Обработка размышлений в каждом ответе.

Claude Opus 4.8 или более ранние модели

• Проверьте рабочие нагрузки, которые выполнялись без поля thinking: в Claude Opus 5.5 они выполняются с размышлениями, и размышления нельзя отключить. Пересмотрите max_tokens, который остаётся жёстким ограничением на общий вывод (размышления плюс текст ответа), и понизьте effort там, где вам нужно меньше размышлений. Токены размышлений оплачиваются как выходные токены, поэтому эти рабочие нагрузки могут генерировать больше выходных токенов на запрос.
• Убедитесь, что любой код, разбирающий поле thinking, рассматривает его только как текст для отображения. Установите display: "summarized", чтобы получать читаемые сводки.
• Проверьте подсказки, длина которых близка к минимуму для кэширования: подсказки длиной 512 токенов и более могут создавать записи кэша.
• Если у вашей организации есть обязательство по Priority Tier, планируйте мощности отдельно: Priority Tier не поддерживается в Claude Opus 5.5.
• Если вы работаете с effort xhigh или max, для начала увеличьте max_tokens как минимум до 64k.
• Для агентных рабочих нагрузок рассмотрите бюджеты задач (бета) и изменение инструментов посреди разговора (бета).

Claude Opus 4.7 или более ранние модели

• Заново подберите уровень effort на собственных оценках вместо того, чтобы переносить настройку, подобранную для более ранней модели.
• Удалите любой бета-заголовок для контекстного окна.
• Если вы пересобираете историю разговора для обновления инструкций, рассмотрите переход на системное сообщение посреди разговора, чтобы сохранить попадания в кэш подсказок.
• Убедитесь, что ваша обработка причин остановки читает stop_details при отказах.
• Если вам нужен быстрый режим, который Claude Opus 4.7 отклоняет, установите speed: "fast" в своих запросах к Claude API. Claude Opus 5.5 не требует бета-заголовка.

Claude Opus 4.6 или более ранние модели

• Удалите temperature, top_p и top_k из тел запросов.
• Замените thinking: {"type": "enabled", "budget_tokens": N} на thinking: {"type": "adaptive"} вместе с параметром effort или полностью удалите поле thinking; адаптивные размышления всегда включены.
• Если ваш интерфейс отображает содержимое размышлений, явно включите суммаризацию размышлений.
• Заново измерьте сквозную стоимость и задержку с учётом обновлённой токенизации.
• Перенастройте max_tokens с учётом обновлённой токенизации, включая триггеры сжатия.
• Повторно протестируйте любые клиентские оценки количества токенов.
• Если ваше приложение отправляет изображения, пересчитайте бюджет с учётом поддержки изображений высокого разрешения (примерно до 3 раз больше токенов изображения на одно изображение в полном разрешении). Уменьшайте разрешение перед отправкой, если дополнительная детализация вам не нужна.
• Если вы используете координаты указания или ограничивающих рамок, возвращаемые моделью, удалите любое преобразование с масштабным коэффициентом; в Claude Opus 4.7 и более поздних моделях координаты соответствуют фактическим пикселям изображения 1:1.
• Ознакомьтесь с изменениями поведения, появившимися в Claude Opus 4.7.
• Если ваш продукт выполняет легитимную работу в области безопасности, подайте заявку в Cyber Verification Program, чтобы получить доступ к менее строгим ограничениям на киберконтент.

Claude Opus 4.5 или более ранние модели

• Удалите любые предзаполнения сообщений ассистента; Claude Opus 4.6 уже отклоняет их.
• Убедитесь, что для разбора JSON вызовов инструментов используется стандартный парсер JSON.
• Перейдите с client.beta.messages.create() на client.messages.create(): адаптивным размышлениям и effort не нужно бета-пространство имён.
• Удалите бета-заголовок effort-2025-11-24 (параметр effort его не требует).
• Удалите бета-заголовок fine-grained-tool-streaming-2025-05-14.
• Удалите бета-заголовок interleaved-thinking-2025-05-14 (адаптивные размышления автоматически включают чередующиеся размышления).
• Перенесите output_format в output_config.format (если применимо).

Claude 4.1 или более ранние модели

• Обновите версии инструментов (text_editor_20250728, code_execution_20260521).
• Обрабатывайте причину остановки refusal.
• Обрабатывайте причину остановки model_context_window_exceeded.
• Проверьте обработку строковых параметров инструментов на наличие завершающих символов новой строки.
• Удалите устаревшие заголовки бета-версий (token-efficient-tools-2025-02-19, output-128k-2025-02-19).
• Проверьте и обновите подсказки в соответствии с лучшими практиками составления подсказок.

Только Claude Sonnet 5

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

Миграция на Claude Opus 5.5 с Claude Opus 5

Сначала проработайте разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5 и Обработка размышлений в каждом ответе. Изменения из этого раздела нужны для любой исходной модели. Это параметры запроса, которые Claude Opus 5.5 отклоняет, и связанные с ним изменения в ответах. Контрольный список для этого раздела — первая группа контрольного списка миграции.

Обновите название модели

model = "claude-opus-5"  # Before
model = "claude-opus-5-5"  # After

claude-opus-5-5 — фиксированный идентификатор модели без суффикса даты, построенный по той же схеме, что и claude-opus-5. В Amazon Bedrock, Claude Platform on AWS, Google Cloud и Microsoft Foundry используйте идентификатор модели соответствующей платформы; см. Доступность.

Критические изменения

Каждое изменение объясняется в разделе Что нового в Claude Opus 5.5; здесь для каждого из них приведено изменение кода.

Размышления нельзя отключить

thinking: {"type": "disabled"} и thinking: {"type": "enabled", "budget_tokens": N} возвращают ошибку 400 ("thinking.type.disabled" is not supported for this model. или "thinking.type.enabled" is not supported for this model.). Удалите поле thinking и выберите уровень effort; там, где вы отключали размышления для экономии токенов, используйте более низкий уровень. После этого ответы будут начинаться с блоков thinking, поэтому выбирайте блоки содержимого по type и передавайте блоки thinking обратно без изменений вместе с результатами инструментов. См. Размышления нельзя отключить.

До. Claude Opus 5 принимает этот запрос, а Claude Opus 5.5 отклоняет его с ошибкой 400:

client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "..."}],
)

После:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    output_config={"effort": "low"},  # thinking is always on; effort is the control
    messages=[{"role": "user", "content": "..."}],
)

Принудительное использование инструментов не поддерживается

Типы tool_choice any и tool возвращают ошибку 400 (tool_choice: type "tool" and "any" are not supported for this model.), в том числе на эндпоинте подсчёта токенов. Используйте auto со строгим использованием инструментов или структурированными выходными данными и укажите в подсказке, когда применяется инструмент. Строгое использование инструментов принимает подмножество JSON Schema, поэтому проверьте input_schema каждого инструмента, прежде чем добавлять strict: true. Каждый объект в схеме должен задавать additionalProperties: false; см. Ограничения JSON Schema. В Amazon Bedrock структурированные выходные данные, включающие строгое использование инструментов, недоступны для Claude Opus 5.5. Там отправляйте auto без strict, указывайте в подсказке, когда применяется инструмент, и проверяйте входные данные инструмента в своём коде. См. Принудительное использование инструментов не поддерживается.

До. Claude Opus 5 принимает этот запрос, а Claude Opus 5.5 отклоняет его с ошибкой 400:

client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

После:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    # строгое использование инструментов: каждый вызов соответствует input_schema инструмента
    tools=[{**tool, "strict": True} for tool in tools],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": "What's the weather in Paris? Use the get_weather tool.",
        }
    ],
)

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

В Claude API блоки размышлений Claude Opus 5.5 читают Claude Fable 5.1 и Claude Mythos 5.1; никакая другая модель этого не делает. Маршрутизатор или резервный механизм, который переводит разговор с Claude Opus 5.5 на любую другую модель, выполняет эти ходы без них. В обратном направлении Claude Opus 5.5 читает блоки размышлений от Claude Opus 5, от более ранних моделей Opus, Sonnet и Haiku, а в Claude API и Google Cloud — от Claude Sonnet 5.5 и Claude Haiku 5.5, но не от моделей Claude Fable или Claude Mythos. Ведите разговор только с добавлением (без правок подсказки system, tools или предыдущих сообщений посреди разговора), чтобы блоки оставались действительными; Claude Code, claude.ai, Claude Managed Agents и Claude Agent SDK уже так делают. Проверка применяется так же, как для Claude Fable 5.1, на всех платформах: для аккаунтов, созданных 31 августа 2026 года в 00:00 UTC или позже, повторная отправка блока размышлений после такой правки по умолчанию возвращает ошибку 400. Для интеграций, работающих только с добавлением, изменения кода не требуются. См. Блоки размышлений привязаны к модели и разговору и Сохранённые размышления.

Инструмент использования компьютера computer_20251124 не поддерживается в Claude API и Google Cloud

В Claude API и Google Cloud запись tools с типом computer_20251124 возвращает ошибку 400 ('claude-opus-5-5' does not support tool types: computer_20251124., за которым следуют типы инструментов, принимаемые моделью). Вместо этого объявите набор инструментов computer_toolset_20260801: уберите бета-заголовок и отправьте запись без name и размеров дисплея. В цикле агента обрабатывайте блоки tool_use для инструментов из набора (действие задаётся полем name блока, а не input.action), по несколько за ход, и возвращайте toolset_name в каждом результате. Изменение запроса показано ниже; изменения цикла агента перечислены в разделе Миграция с computer_20251124. В Amazon Bedrock более ранний инструмент computer_20251124 продолжает работать в Claude Opus 5.5 так же, как в Claude Opus 5, поэтому там изменения не нужны; для других платформ см. раздел Совместимость инструмента использования компьютера. См. Инструмент использования компьютера computer_20251124 не поддерживается в Claude API и Google Cloud.

До. Claude Opus 5 принимает этот запрос, а в Claude API и Google Cloud Claude Opus 5.5 отклоняет его с ошибкой 400:

client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    betas=["computer-use-2025-11-24"],
    tools=[
        {
            "type": "computer_20251124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        }
    ],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

После:

client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    # без бета-заголовка; запись набора инструментов не принимает имя или размер экрана
    tools=[{"type": "computer_toolset_20260801"}],
    messages=[{"role": "user", "content": "Open the display settings."}],
)

Текст между вызовами инструментов возвращается в блоках размышлений

В Claude Opus 5 текст, который модель пишет между вызовами инструментов, возвращается в блоках text. В Claude Opus 5.5, как и в Claude Fable 5.1, эти пояснения возвращаются в блоках thinking с обновлениями о ходе работы. Перед каждым вызовом инструмента приходит не более одного такого блока. По умолчанию thinking.display имеет значение "omitted", и поле thinking в этих блоках пустое.

Запросы не завершаются ошибкой. Но если приложение через «streaming» (потоковую передачу) показывает этот текст пользователям как обновления о ходе работы, между вызовами инструментов оно замолкает. Чтобы вернуть обновления, считывайте их из блоков thinking и задайте значение display, при котором их текст возвращается:

• "updates" (бета, заголовок thinking-display-updates-2026-08-18) возвращает обновления о ходе работы, а рассуждения остаются скрытыми;
• "summarized" возвращает и обновления, и рассуждения вперемешку.

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

Классификаторы безопасности и резервный механизм

Claude Opus 5.5 может возвращать stop_reason: "refusal" с категорией stop_details. Его классификаторы охватывают более широкий набор категорий, чем у Claude Opus 5, поэтому ожидайте значения stop_details.category, такие как "bio", в дополнение к "cyber" и "reasoning_extraction"; см. таблицу категорий отказов. Обрабатывайте отказы и настройте серверную резервную обработку или собственные повторные попытки (серверная резервная обработка не повторяет запросы, отклонённые с "reasoning_extraction"; такой отказ возвращается вам); см. Отказы и резервная обработка и Отказы защитных механизмов.

Рекомендуемые изменения

1. Заново подберите уровень effort. Effort — единственный способ управления размышлениями в Claude Opus 5.5, и по умолчанию он равен medium, тогда как у Claude Opus 5 — high, поэтому запрос без effort теперь выполняется на уровне medium. Понижайте уровень там, где качество сохраняется, и повышайте его для самых требовательных задач. См. Уровень усилий (effort).
2. Пересмотрите инструкции в подсказках, рассчитанные на конкретную модель. Инструкции, настроенные под поведение Claude Opus 5, могут больше не понадобиться; см. Составление подсказок для Claude Opus 5.5. Если вы работали с отключёнными размышлениями, см. также Подсказки, написанные для отключённых размышлений.
3. Протестируйте в среде разработки, прежде чем переключать производственный трафик.

Миграция на Claude Opus 5.5 с Claude Opus 4.8

Сначала проработайте разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5, Обработка размышлений в каждом ответе и Миграция на Claude Opus 5.5 с Claude Opus 5. В качестве заменяемого идентификатора модели используйте claude-opus-4-8. Последний из этих разделов применим к коду на Claude Opus 4.8 в неизменном виде, потому что Claude Opus 4.8, как и Claude Opus 5:

• Принимает thinking: {"type": "disabled"}, принудительный выбор инструмента и инструмент computer_20251124.
• Возвращает текст между вызовами инструментов в блоках text.
• По умолчанию использует effort high.

В этом разделе описано то, что изменилось между Claude Opus 4.8 и Claude Opus 5. Контрольный список см. в первых двух группах контрольного списка миграции.

Что изменилось

1. Размышления выполняются в запросах, где они не были указаны: В Claude Opus 4.8 размышления выключены, если вы их не запросите. В Claude Opus 5.5 запрос без поля thinking выполняется с размышлениями, поэтому для такого кода каждый пункт из раздела Обработка размышлений в каждом ответе требует изменений. Если ваш код никогда не отправлял поле thinking, то в сравнении «до» и «после» для размышлений удалять нечего.

2. Более низкий минимум для кэширования подсказок: Минимальная длина кэшируемой подсказки в Claude Opus 5.5 составляет 512 токенов вместо 1024 токенов в Claude Opus 4.8. Подсказки, которые были слишком короткими для кэширования в Claude Opus 4.8, могут создавать записи кэша без каких-либо изменений кода. Минимумы для каждой модели см. в разделе Кэширование подсказок.

3. Priority Tier не поддерживается: Priority Tier не поддерживается в Claude Opus 5.5, тогда как в Claude Opus 4.8 он сохраняется. Если у вашей организации есть обязательство по Priority Tier, планируйте мощности отдельно.

Рекомендуемые изменения

Эти изменения не обязательны, но улучшат ваш опыт работы:

1. Рассмотрите бюджеты задач (бета): Для агентных рабочих нагрузок бюджеты задач сообщают модели, сколько токенов у неё есть на полный агентный цикл. Для них требуется бета-заголовок task-budgets-2026-03-13.

2. Рассмотрите изменения инструментов посреди разговора (бета): Изменения инструментов посреди разговора позволяют добавлять или удалять инструменты между ходами разговора, не аннулируя попадания в кэш подсказок для более ранних ходов. Изменение самого массива tools аннулирует кэшированный префикс. В Claude API отправляйте бета-заголовок inline-tools-2026-09-15. Более старый заголовок mid-conversation-tool-changes-2026-07-01 по-прежнему работает для изменений, которые указывают инструмент по ссылке, в Claude API, Amazon Bedrock и Google Cloud.

Миграция на Claude Opus 5.5 с Claude Opus 4.7

Сначала проработайте разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5, Обработка размышлений в каждом ответе, Миграция на Claude Opus 5.5 с Claude Opus 5 и Миграция на Claude Opus 5.5 с Claude Opus 4.8. В качестве заменяемого идентификатора модели используйте claude-opus-4-7. Эти разделы применимы к коду на Claude Opus 4.7 в неизменном виде. Как и Claude Opus 4.8, эта модель принимает thinking: {"type": "disabled"}, принудительный выбор инструмента и инструмент computer_20251124. По умолчанию она использует effort high и работает без размышлений, если вы их не запросите.

В этом разделе описано то, что изменилось после Claude Opus 4.7. Если ваш код работает на Claude Opus 4.6 или более ранней модели, после этого раздела перейдите к разделу Миграция на Claude Opus 5.5 с Claude Opus 4.6 и более ранних моделей Opus. В нём описаны критические изменения, вступившие в силу в Claude Opus 4.7. Контрольный список см. в первых трёх группах контрольного списка миграции.

Что изменилось

Ни один из этих пунктов не добавляет критических изменений к перечисленным в предыдущих разделах; их стоит проверить после замены идентификатора модели.

1. Уровни effort перекалиброваны: Распределение токенов для каждого уровня effort в Claude Opus 5.5 изменилось по сравнению с Claude Opus 4.7. По умолчанию используется medium, тогда как у Claude Opus 4.7 — high. Заново подберите уровень effort на собственных оценках вместо того, чтобы переносить настройку, подобранную для Claude Opus 4.7. См. Уровень усилий (effort).

2. Контекстное окно на 1M используется по умолчанию: Claude Opus 5.5 по умолчанию предоставляет полное контекстное окно на 1M токенов без бета-заголовка. Если ваш клиент передаёт бета-заголовок для контекстного окна ради совместимости со старыми моделями, удалите его.

3. Системные сообщения посреди разговора: В Claude API, Amazon Bedrock и Google Cloud Claude Opus 5.5 принимает сообщения role: "system" сразу после хода пользователя в массиве messages (с учётом правил размещения). Для инструкций, которые действуют с самого начала, используйте поле верхнего уровня system. Claude Opus 4.7 отклоняет role: "system" в messages с ошибкой 400. Если вы поддерживаете участки кода, которые пересобирают всю историю сообщений для обновления инструкций, вы можете упростить их и сохранить попадания в кэш подсказок на предыдущих ходах.

4. Подробности об отказе в причине остановки: Когда модель отклоняет запрос, Claude Opus 5.5 вместе с причиной остановки refusal возвращает объект stop_details, в котором указана категория отказа. Claude Opus 4.7 возвращает тот же объект, поэтому это важно, только если ваша обработка причин остановки его ещё не читает. Бета-заголовок не требуется, и отключить это поведение нельзя. Если ваша обработка причин остановки его ещё не читает, см. Обработка причин остановки. Claude Opus 5.5 отказывает в большем числе категорий; см. Классификаторы безопасности и резервный механизм.

5. Быстрый режим: Claude Opus 5.5 поддерживает быстрый режим в Claude API. Быстрый режим недоступен в Claude Opus 4.7, где запросы с speed: "fast" возвращают ошибку. Установите speed: "fast" в своих запросах. Claude Opus 5.5 не требует бета-заголовка.

6. Набор инструментов использования компьютера и инструмент использования браузера: В Claude API и Google Cloud Claude Opus 5.5 поддерживает использование компьютера в виде набора инструментов computer_toolset_20260801, а также инструмент «browser use» (использование браузера) для задач внутри веб-страниц. Claude Opus 4.7 не поддерживает ни то, ни другое. На этих платформах Claude Opus 5.5 не принимает более ранний инструмент computer_20251124; см. критическое изменение для использования компьютера.

Миграция на Claude Opus 5.5 с Claude Opus 4.6 и более ранних моделей Opus

Сначала проработайте все предыдущие разделы в порядке их следования на странице. Это разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5, Обработка размышлений в каждом ответе, а также разделы для Claude Opus 5, Claude Opus 4.8 и Claude Opus 4.7. Эти разделы применимы к коду на Claude Opus 4.6 в неизменном виде. Как и Claude Opus 4.7, эта модель принимает thinking: {"type": "disabled"}, принудительный выбор инструмента и инструмент computer_20251124. По умолчанию она использует effort high и работает без размышлений, если вы их не запросите. Claude Opus 4.5 и более ранние модели Opus также принимают thinking: {"type": "disabled"} и принудительный выбор инструмента и работают без размышлений, если вы их не запросите, поэтому эти разделы применимы и к ним.

В этом разделе описано то, что изменилось в Claude Opus 4.7; в качестве заменяемого идентификатора модели используется claude-opus-4-6. В двух его подразделах описано то, что изменилось до этого, — для читателей, использующих Claude Opus 4.5 или более ранние модели и Claude 4.1 или более ранние модели. Контрольный список см. в контрольном списке миграции вплоть до группы, в которой названа ваша модель.

Критические изменения

1. Расширенные размышления удалены: thinking: {"type": "enabled", "budget_tokens": N} больше не поддерживается в Claude Opus 4.7 и более поздних моделях и возвращает ошибку 400. Перейдите на «adaptive thinking» (адаптивные размышления) (thinking: {"type": "adaptive"}) и используйте параметр effort для управления глубиной размышлений. В Claude Opus 5.5 адаптивные размышления всегда включены: thinking: {"type": "adaptive"} допустимо и эквивалентно полному отсутствию поля thinking.

   До (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client.messages.create(
       model="claude-opus-4-6",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[{"role": "user", "content": "..."}],
   )

   После (Claude Opus 5.5), где отличаются строки с ID модели, thinking и output_config:

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   Python

   

   client.messages.create(
       model="claude-opus-5-5",
       max_tokens=16000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
       messages=[{"role": "user", "content": "..."}],
   )

   Адаптивными размышлениями можно управлять с помощью подсказок и параметра effort, который заменяет бюджет размышлений в качестве способа контролировать, насколько много рассуждает модель. Проведите перебор уровней effort на собственных оценках, а не пересчитывайте значение budget_tokens. Таблица уровней effort описывает, когда использовать каждый уровень, а раздел Рекомендуемые уровни effort для Claude Opus 5.5 посвящён этой модели.

2. Параметры сэмплирования удалены: Установка temperature, top_p или top_k в любое значение, отличное от значения по умолчанию, в Claude Opus 4.7 и более поздних моделях, включая Claude Opus 5.5, возвращает ошибку 400. Python SDK (v1.0 и новее) не определяет эти параметры, и их передача вызывает TypeError. Самый безопасный путь миграции — полностью исключить эти параметры из тела запросов. Рекомендуемый способ управлять поведением модели в Claude Opus 5.5 — подсказки. Если вы использовали temperature = 0 для детерминированности, учтите, что это никогда не гарантировало идентичных результатов и на предыдущих моделях.

3. Содержимое размышлений по умолчанию опускается: Блоки размышлений по-прежнему появляются в потоке ответа в Claude Opus 4.7 и более поздних моделях, но их поле thinking пусто, если вы явно не включите его. Это незаметное изменение по сравнению с Claude Opus 4.6, где по умолчанию возвращался текст сводки размышлений. Чтобы восстановить его, см. пункт 4 раздела Обработка размышлений в каждом ответе.

4. Обновлённый подсчёт токенов: В Claude Opus 4.7 появился новый токенизатор, который используют и более поздние модели Opus, включая Claude Opus 5.5. Он способствует повышению производительности на широком спектре задач и может использовать примерно в 1–1,35 раза больше токенов при обработке текста по сравнению с моделями до Claude Opus 4.7 (до ~35% больше, в зависимости от содержимого).

   /v1/messages/count_tokens возвращает для Claude Opus 5.5 другое количество токенов, чем для Claude Opus 4.6. Эффективность использования токенов может различаться в зависимости от характера нагрузки.

   Обновите параметры max_tokens, чтобы обеспечить дополнительный запас, включая триггеры сжатия, и повторно протестируйте любой код, который оценивает количество токенов на стороне клиента или предполагает фиксированное соотношение токенов и символов. Для проверки используйте эндпоинт подсчёта токенов. Контролировать затраты помогают изменения в подсказках, task_budget и effort; эти механизмы могут снижать интеллектуальные возможности модели.

5. Удаление предзаполнения (уже действует в Claude Opus 4.6): Предзаполнение сообщений ассистента возвращает ошибку 400 в Claude Opus 4.6 и более поздних моделях Opus, включая Claude Opus 5.5, поэтому это изменение касается вас, только если вы переходите с Claude Opus 4.5 или более ранней версии. Вместо этого используйте структурированные выходные данные или инструкции в системной подсказке. В Amazon Bedrock структурированные выходные данные недоступны для Claude Opus 5.5, поэтому там используйте инструкции в системной подсказке.

Изменения в поведении

Claude Opus 4.7 привнёс поведенческие отличия от Claude Opus 4.6, которые не являются критическими изменениями API. Следующие три затрагивают код или вспомогательную обвязку (scaffolding):

1. Встроенные обновления о ходе работы в агентных трассировках: Claude Opus 4.7 предоставляет пользователю более регулярные и качественные обновления на протяжении длинных агентных трассировок. Если вы добавили обвязку для принудительных промежуточных сообщений о статусе («После каждых 3 вызовов инструментов подводи итог прогресса»), попробуйте её удалить. В Claude Opus 5.5 эти обновления приходят в блоках thinking, которые пусты при значении thinking.display по умолчанию. Чтобы получать их, см. Текст между вызовами инструментов возвращается в блоках размышлений. Чтобы настроить их длину и содержание, см. Обновления о ходе работы для пользователя.

2. Защитные механизмы кибербезопасности в реальном времени: Эти механизмы, впервые добавленные в Claude Opus 4.7, могут приводить к отказам на запросы, связанные с запрещёнными или высокорисковыми темами. Для легитимной работы в области безопасности, такой как тестирование на проникновение, исследование уязвимостей или red-teaming, подайте заявку в Cyber Verification Program, чтобы запросить ослабление ограничений. Способ подачи заявки зависит от того, как вы получаете доступ к Claude.

3. Поддержка изображений высокого разрешения: Claude Opus 4.7 — первая модель Claude с поддержкой изображений высокого разрешения. Максимальное разрешение изображения составляет 2576 пикселей по длинной стороне вместо 1568 пикселей в предыдущих моделях. Это даёт выигрыш на рабочих нагрузках, активно использующих зрение, и особенно ценно для использования компьютера, понимания скриншотов и анализа документов.

   Поддержка высокого разрешения включается автоматически и не требует бета-заголовка или включения на стороне клиента. Следует учесть две вещи:

   • Изображения в полном разрешении могут использовать примерно до 3 раз больше токенов изображения, чем в предыдущих моделях (до 4784 токенов на изображение по сравнению с прежним пределом примерно в 1600 токенов на изображение). Пересмотрите бюджет max_tokens и ожидания по стоимости для рабочих нагрузок с большим количеством изображений или уменьшайте разрешение перед отправкой, если дополнительная точность вам не нужна.
   • Координаты указания и ограничивающих рамок, возвращаемые моделью, в Claude Opus 4.7 соответствуют реальным пикселям изображения 1:1, поэтому преобразование с коэффициентом масштабирования не требуется.

   Подробности см. в разделе Поддержка изображений высокого разрешения в Claude Opus 4.7.

Об отличиях на стороне подсказок см. Составление подсказок для Claude Opus 5.5 и Лучшие практики составления подсказок.

Миграция с Claude Opus 4.5 или более ранних версий

Если вы переходите с Claude Opus 4.5, Claude Opus 4.1 или более ранней модели напрямую на Claude Opus 5.5, читайте эту страницу с самого начала: сначала проработайте все предыдущие разделы в порядке их следования на странице. Затем проработайте критические изменения при миграции с Claude Opus 4.6, приведённые ранее в этом разделе. После этого примените следующие накопительные изменения, вступившие в силу между Claude Opus 4.5 и Claude Opus 4.7. Если вы используете Claude Opus 4.1 или более раннюю версию, после этого подраздела перейдите к разделу Миграция с Claude 4.1 или более ранних версий.

Критические изменения

1. Удаление предзаполнения описано в критических изменениях при миграции с Claude Opus 4.6.

2. Экранирование параметров инструментов: Claude Opus 4.6 и более поздние модели могут создавать немного иное экранирование строк JSON в аргументах вызовов инструментов (например, иначе обрабатывать экранирование Unicode или прямой косой черты). Если вы разбираете input вызова инструмента как необработанную строку, а не с помощью парсера JSON, проверьте логику разбора. Стандартные парсеры JSON (такие как json.loads() или JSON.parse()) обрабатывают эти различия автоматически.

Рекомендуемые изменения

Первый пункт обязателен для Claude Opus 5.5; остальные рекомендуются.

1. Переход на адаптивные размышления (обязательно): thinking: {"type": "enabled", "budget_tokens": N} возвращает ошибку 400 в Claude Opus 4.7 и более поздних моделях. Пример «до» и «после» приведён в пункте 1 критических изменений при миграции с Claude Opus 4.6. Миграция также означает переход с client.beta.messages.create() на client.messages.create(): адаптивные размышления и effort не требуют бета-пространства имён SDK или каких-либо бета-заголовков.

2. Удалите бета-заголовок effort: Параметр effort не требует бета-заголовка. Удалите бета-заголовок effort-2025-11-24 из своих запросов.

3. Удалите бета-заголовок детализированной потоковой передачи инструментов: «Fine-grained tool streaming» (детализированная потоковая передача инструментов) не требует бета-заголовка. Удалите бета-заголовок fine-grained-tool-streaming-2025-05-14 из своих запросов.

4. Удалите бета-заголовок чередующихся размышлений: При адаптивных размышлениях «interleaved thinking» (чередующиеся размышления) включаются автоматически на каждой модели, поддерживающей адаптивные размышления. Удалите бета-заголовок interleaved-thinking-2025-05-14 из своих запросов.

5. Переход на output_config.format: Если вы используете структурированные выходные данные, замените output_format={...} на output_config={"format": {...}}. Параметр output_format устарел и будет удалён в будущем. Чтобы всё же использовать его, добавьте бета-заголовок structured-outputs-2025-11-13. Без него API возвращает ошибку 400. Python SDK (v1.0 и новее) не принимает output_format={...} в client.beta.messages.create() или count_tokens(). Аргумент output_format=Model вспомогательных методов parse() и stream() не изменился.

Миграция с Claude 4.1 или более ранних версий

Если вы переходите с Claude Opus 4.1 или более ранних моделей напрямую на Claude Opus 5.5, сначала примените всё из раздела Миграция с Claude Opus 4.5 или более ранних версий. Этот подраздел начинается со всех предыдущих разделов, так что фактически вы читаете эту страницу с самого начала. Затем примените дополнительные изменения из этого подраздела.

Дополнительные критические изменения

1. Удалите параметры сэмплирования: Описано в разделе Параметры сэмплирования удалены.

2. Обновите версии инструментов

   Обновитесь до текущих версий инструментов. Удалите любой код, использующий команду undo_edit.

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # До
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # После
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

   • Текстовый редактор: Используйте text_editor_20250728 и str_replace_based_edit_tool. Подробности см. в документации инструмента текстового редактора.
   • Выполнение кода: Обновитесь до code_execution_20260521. Инструкции по миграции см. в документации инструмента выполнения кода.
   • Использование компьютера: В Claude API и Google Cloud Claude Opus 5.5 принимает использование компьютера только в виде набора инструментов computer_toolset_20260801: более ранние инструменты computer_20250124 и computer_20251124 там отклоняются. См. критическое изменение для использования компьютера.

3. Обработайте причину остановки refusal

   Обновите приложение, чтобы обрабатывать причины остановки refusal:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # Корректно обработайте отказ
       pass

4. Обработайте причину остановки model_context_window_exceeded

   Модели Claude 4.5 и более поздние возвращают причину остановки model_context_window_exceeded, когда генерация останавливается из-за достижения предела контекстного окна, а не запрошенного предела max_tokens. Обновите приложение для обработки этой новой причины остановки:

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # Корректно обрабатываем достижение лимита контекстного окна
       pass

5. Проверьте обработку параметров инструментов (завершающие символы новой строки)

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

6. Обновите подсказки с учётом изменений в поведении

   Модели Claude 4 и более поздние отличаются более лаконичным, прямым стилем общения и требуют явных указаний. Рекомендации по оптимизации см. в лучших практиках составления подсказок.

Дополнительные рекомендуемые изменения

• Удалите устаревшие бета-заголовки: Удалите token-efficient-tools-2025-02-19 и output-128k-2025-02-19. Все модели Claude 4 и более поздние имеют встроенное экономное по токенам использование инструментов, и эти заголовки ни на что не влияют.

Миграция на Claude Opus 5.5 с Claude Sonnet 5

Проработайте разделы Каким требованиям должен соответствовать каждый запрос к Claude Opus 5.5, Обработка размышлений в каждом ответе и Миграция на Claude Opus 5.5 с Claude Opus 5. В качестве заменяемого идентификатора модели используйте claude-sonnet-5. Последний из этих разделов применим к коду на Claude Sonnet 5 без изменений, поскольку Claude Sonnet 5, как и Claude Opus 5:

• Работает с включёнными по умолчанию размышлениями и принимает thinking: {"type": "disabled"}, причём в его случае — при любом уровне effort.
• Принимает принудительный выбор инструмента и инструмент computer_20251124.
• Возвращает текст между вызовами инструментов в виде блоков text.
• По умолчанию использует уровень effort high.

Ручные расширенные размышления, параметры сэмплирования со значениями не по умолчанию и предзаполнение ассистента возвращают ошибку 400 на обеих моделях, так что здесь ничего не меняется. Ни одно из обязательных изменений в разделах для Claude Opus 4.8, Claude Opus 4.7 и Claude Opus 4.6 к вам не относится.

Что изменилось

1. Системные сообщения посреди разговора: В Claude API, Amazon Bedrock и Google Cloud Claude Opus 5.5 принимает сообщения role: "system" сразу после хода пользователя в массиве messages (с учётом правил размещения). Эта функция недоступна в Claude Sonnet 5. Если вы поддерживаете участки кода, которые пересобирают всю историю сообщений для обновления инструкций, вы можете упростить их и сохранить попадания в кэш подсказок на более ранних ходах.

2. Снижен минимум для кэширования подсказок: Минимальная длина кэшируемой подсказки в Claude Opus 5.5 составляет 512 токенов вместо 1024 токенов в Claude Sonnet 5. Подсказки, которые были слишком короткими для кэширования в Claude Sonnet 5, теперь могут создавать записи кэша без каких-либо изменений кода. Минимальные значения для каждой модели см. в разделе Кэширование подсказок.