Миграция на Claude Sonnet 5.5

В этом руководстве перечислены изменения кода для перехода на Claude Sonnet 5.5 с Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5, Claude Sonnet 4, Claude 3.7 Sonnet или Claude Haiku 4.5. Прочитайте первые два раздела, а затем читайте дальше до раздела о вашей текущей модели. В контрольном списке миграции перечислены все изменения для каждой исходной модели.

Цены Claude Sonnet 5.5 такие же, как у Claude Sonnet 5. См. цены Claude. Сведения о его «context window» (контекстном окне) и ограничениях на вывод см. на странице модели Claude Sonnet 5.5. О функциях и «prompting» (составлении подсказок) см. Что нового в Claude Sonnet 5.5 и Составление подсказок для Claude Sonnet 5.5.

Отправка запроса к Claude Sonnet 5.5

Этот запрос работает на Claude Sonnet 5.5 в том виде, в каком он написан. Он задаёт уровень «effort» (усилий), а вкладки «software development kit» (набора средств разработки), или SDK, читают ответ по типу блока. В нём опущены пять настроек, которые возвращают ошибку 400: «thinking budgets» (бюджеты размышлений), «sampling parameters» (параметры сэмплирования), «assistant prefill» (предзаполнение ответа ассистента), принудительный выбор инструмента и thinking: {"type": "disabled"}.

client = anthropic.Anthropic()

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

print(f"Stop reason: {response.stop_reason}")
for block in response.content:
    if block.type == "text":
        print(block.text)

Размышления включены по умолчанию

На Claude Sonnet 5.5 запрос без поля thinking выполняется с «adaptive thinking» (адаптивными размышлениями), как и запрос с thinking: {"type": "adaptive"}. На Claude Sonnet 4.6 и более ранних моделях, а также на Claude Haiku 4.5 такой запрос выполнялся без размышлений. Чтобы и дальше работать без «up-front thinking» (предварительных размышлений), см. Отключение предварительных размышлений.

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

Коду, который работал без размышлений, нужны все три пункта. В коде для Claude Sonnet 5, скорее всего, уже есть первые два.

• Читайте блоки содержимого по type. Ответ может начинаться с блоков thinking, поэтому код, который читает content[0].text, перестаёт работать.
• Передавайте блоки thinking обратно без изменений в циклах «tool use» (использования инструментов), включая пустые блоки. См. Сохранение блоков размышлений.
• Пересмотрите max_tokens. Это значение охватывает размышления и текст, а токены размышлений оплачиваются как выходные токены. См. Контроль затрат.

Текст размышлений по умолчанию опускается. Блоки thinking приходят с пустым полем thinking и полем signature. Чтобы получать читаемые сводки, задайте display: "summarized" — это значение по умолчанию на Claude Sonnet 4.6 и более ранних моделях, а также на Claude Haiku 4.5. См. Управление отображением размышлений.

Отключение предварительных размышлений

Чтобы отключить предварительные размышления на Claude Sonnet 5.5, отправьте thinking: {"type": "between_tools"}. Это самая низкая настройка размышлений. Её «progress updates» (обновления о ходе работы) между вызовами инструментов по-прежнему возвращаются как блоки thinking с текстом сводки. Без инструментов ответ содержит только текст. Claude Sonnet 5 вместо этого отключает размышления с помощью thinking: {"type": "disabled"}, а более ранние модели по умолчанию работают без размышлений. На Claude Sonnet 5.5 значение disabled возвращает ошибку 400 invalid_request_error:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

between_tools работает на всех платформах, где доступен Claude Sonnet 5.5, без «beta header» (бета-заголовка). Это значение принимается при уровнях усилий low, medium и high. При xhigh или max оно возвращает ошибку 400. Чтобы работать на этих уровнях, используйте адаптивные размышления: опустите поле thinking или отправьте thinking: {"type": "adaptive"}. between_tools не принимает других полей: display, budget_tokens или block_binding, отправленные вместе с ним, возвращают ошибку 400. При «server-side fallback» (резервном переключении на стороне сервера) запрос с between_tools, который переключается на Claude Sonnet 5, выполняется там с thinking: {"type": "disabled"}.

С between_tools уровень усилий нельзя менять посреди разговора: output_config.effort для отдельного сообщения, отличающийся от действующего уровня, возвращает ошибку 400. Чтобы менять уровень усилий от хода к ходу, используйте адаптивные размышления. Рекомендации по составлению подсказок см. в разделе Работа без предварительных размышлений.

В версиях SDK, где between_tools не определено, примеры на Python и TypeScript не проходят проверку типов. Обновите SDK или передайте значение как необработанный JSON, как это делают примеры на C#, Go и Java.

До (Claude Sonnet 5):

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

После (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

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

Проходите группы сверху вниз и остановитесь после той, в которой названа ваша модель. Для Claude Haiku 4.5 примените все группы, кроме «Claude Sonnet 4 или более ранние», и закончите группой «Только Claude Haiku 4.5».

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

• Измените идентификатор модели на claude-sonnet-5-5.
• Читайте блоки содержимого по type и передавайте блоки thinking обратно без изменений.
• Чтобы и дальше работать без предварительных размышлений, отправляйте самую низкую настройку размышлений при уровне усилий high или ниже.
• Замените принудительное использование инструментов на auto и строгие инструменты, а на Amazon Bedrock — только на auto.
• Ведите разговоры только с добавлением.
• В Claude API и Google Cloud переведите использование компьютера на набор инструментов без бета-заголовка fine-grained-tool-streaming-2025-05-14.
• Используйте инструмент-советник с поддерживаемым советником и учитывайте, что советы приходят в зашифрованном виде.
• Читайте текст между вызовами инструментов из блоков thinking.
• Обрабатывайте отказы и настройте резервное переключение.
• Повторите подбор уровня усилий и заново определите базовый уровень затрат.

Claude Sonnet 4.6 или более ранние

• Учитывайте, что размышления выполняются в запросах без поля thinking, и пересмотрите max_tokens.
• Замените бюджеты размышлений уровнем усилий.
• Удалите значения temperature, top_p и top_k, отличные от значений по умолчанию.
• Если вы показываете текст размышлений, задайте display: "summarized".
• Пересчитайте токены и пересмотрите бюджет токенов для изображений.

Claude Sonnet 4.5 или более ранние

• Замените предзаполнения ответа ассистента.
• Разбирайте входные данные вызовов инструментов стандартным JSON-парсером.
• В Amazon Bedrock перенесите использование компьютера с computer_20250124 на computer_20251124.
• Явно задайте output_config.effort.
• Удалите любой бета-заголовок контекстного окна.
• Удалите interleaved-thinking-2025-05-14 и замените fine-grained-tool-streaming-2025-05-14 на eager_input_streaming.
• Перенесите output_format в output_config.format.

Claude Sonnet 4 или более ранние

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

Только Claude Haiku 4.5

• Замените claude-haiku-4-5-20251001 или его псевдоним.
• Заново определите базовый уровень затрат с учётом более высокой цены за токен.
• Пересмотрите подсказки, которые были слишком короткими для кэширования на Claude Haiku 4.5.

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

Изменения из этого раздела нужны для любой исходной модели. Замените ID модели на claude-sonnet-5-5 — у него нет суффикса с датой. На других платформах используйте ID, указанный в разделе Доступность.

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

Все более ранние модели на этой странице принимают tool_choice типа any или tool. Claude Sonnet 5.5 отклоняет оба варианта с ошибкой 400, в том числе на эндпоинте «token counting» (подсчёта токенов):

tool_choice: type "tool" and "any" are not supported for this model.

Отправляйте tool_choice: {"type": "auto"} и помечайте инструмент как strict: true, чтобы его входные данные соответствовали схеме. В этом случае модель может ответить, не вызывая инструмент, поэтому укажите в подсказке, когда его использовать. Строгое использование инструментов поддерживает подмножество JSON Schema и требует additionalProperties: false для каждого объекта. См. Ограничения JSON Schema. На Amazon Bedrock структурированные выходные данные, включающие строгое использование инструментов, недоступны для Claude Sonnet 5.5. Там отправляйте auto без strict, указывайте в подсказке, когда вызывать инструмент, и проверяйте входные данные инструмента в своём коде.

До (Claude Sonnet 5):

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

После (Claude Sonnet 5.5):

client.messages.create(
    model="claude-sonnet-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.",
        }
    ],
)

В примере все инструменты в списке помечены как строгие. Запрос может содержать не более 20 строгих инструментов, а записи наборов инструментов «Model Context Protocol», или MCP, использования компьютера и использования браузера не принимают strict. В более длинном списке инструментов помечайте только те инструменты, которым это нужно.

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

Claude Sonnet 5.5 читает блоки размышлений от Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 и более ранних моделей. Он не читает блоки от Claude Opus 5, Claude Opus 5.5 или любой модели Claude Fable или Claude Mythos. API отбрасывает блоки, которые модель не может прочитать. Запрос при этом всё равно возвращает 200, а отброшенные блоки не оплачиваются. См. Смена модели посреди разговора.

Кроме того, каждый блок размышлений Claude Sonnet 5.5 подписывается с учётом предшествующей ему части разговора. Для аккаунтов, созданных 31 августа 2026 года в 00:00 UTC или позже, API по умолчанию проверяет это, в Claude API, Amazon Bedrock и Google Cloud. Для таких аккаунтов запрос, который повторно передаёт блок после изменения более ранней истории, возвращает ошибку 400. Ведите разговоры в режиме только добавления, а инструкции или инструменты меняйте с помощью системных сообщений посреди разговора. Блоки размышлений, созданные Claude Sonnet 5.5, работают только в аккаунте, в котором они были созданы, или в связанном с ним аккаунте. См. Сохранённые размышления.

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

В Claude API и Google Cloud Claude Sonnet 5.5 поддерживает использование компьютера только через набор инструментов computer_toolset_20260801. Там computer_20251124 возвращает ошибку 400. Claude Sonnet 5.5 не принимает computer_20250124 ни на одной платформе. Найдите версию, которую вы отправляете сейчас:

Если вы отправляете бета-заголовок fine-grained-tool-streaming-2025-05-14, удалите его при переходе на набор инструментов. Вместе с записью набора инструментов он возвращает ошибку 400. Вместо этого задайте eager_input_streaming: true для каждого инструмента, которому это нужно.

Код, который уже отправляет набор инструментов, изменять не нужно. В разделе Миграция с computer_20251124 перечислены изменения запроса и агентного цикла. Сведения о других платформах см. в разделе Совместимость.

Инструмент-советник принимает меньше советников

При использовании «advisor tool» (инструмента-советника) исполнителю Claude Sonnet 5.5 нужен один из следующих советников: Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5, Claude Fable 5.1, Claude Mythos 5 или Claude Mythos 5.1. Советники Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 и Claude Sonnet 4.6 возвращают ошибку 400. Совет возвращается в зашифрованном виде как блок advisor_redacted_result, поэтому его текст в ответе прочитать нельзя. См. Совместимость моделей.

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

На Claude Sonnet 5.5 заметки длиннее одного-двух предложений, которые модель пишет между вызовами инструментов, возвращаются как блоки thinking с обновлениями о ходе работы, пустые при значении display по умолчанию. Более короткие замечания остаются блоками text. На Claude Sonnet 5 и более ранних моделях весь текст между вызовами инструментов возвращается в блоках text. Ни один запрос не завершается ошибкой, но интерфейс, который показывает эти заметки, перестаёт их отображать.

При адаптивных размышлениях задайте для display значение "updates" (бета-версия, заголовок thinking-display-updates-2026-08-18), чтобы получать только обновления, или "summarized", чтобы получать их вперемешку с рассуждениями. Отображайте каждый непустой блок thinking перед следующим за ним блоком tool_use. С between_tools текст возвращается без display. См. Обновления о ходе работы для пользователя.

Классификаторы безопасности и резервное переключение

Claude Sonnet 5.5 отказывает в большем числе категорий, чем Claude Sonnet 5. Отказ возвращает stop_reason: "refusal", а его stop_details может указывать одну из следующих категорий:

• "cyber": Запрос может способствовать причинению киберугроз, например разработке вредоносного ПО или эксплойтов.
• "bio": Запрос может способствовать причинению биологического вреда, например через опасные лабораторные методы.
• "frontier_llm": Запрос может помочь в разработке конкурирующих моделей «artificial intelligence» (искусственного интеллекта), или AI.
• "reasoning_extraction": Запрос просит модель воспроизвести свои внутренние рассуждения в тексте ответа.
• "general_harms": Запрос относится к другой области политики использования. Эту категорию может вызвать и безобидная работа.

Резервное переключение на стороне сервера (fallbacks: "default", бета-версия, только Claude API) повторяет на Claude Sonnet 5 запросы, отклонённые по категориям "cyber" и "frontier_llm". Запросы, отклонённые по категориям "bio", "reasoning_extraction" или "general_harms", оно не повторяет. См. Отказы и резервное переключение и Как оплачиваются отказы.

Защитные механизмы от киберугроз в реальном времени — новинка для кода, переносимого с Claude Sonnet 4.6, Claude Sonnet 4.5 и Claude Haiku 4.5. Для легитимной работы в области безопасности подайте заявку в Cyber Verification Program.

Другие изменения

• «Prompt caching» (кэширование подсказок): Минимальный размер кэшируемой подсказки — 512 токенов вместо 1024 на Claude Sonnet 5, Claude Sonnet 4.6 и Claude Sonnet 4.5. См. Кэширование подсказок.
• Новые функции: О системных сообщениях посреди разговора, изменении инструментов посреди разговора и уровне усилий для отдельных сообщений см. Что нового в Claude Sonnet 5.5. С between_tools уровень усилий нельзя менять посреди разговора.

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

Повторите перебор уровней усилий. У Claude Sonnet 5.5 пять уровней усилий: low, medium, high, xhigh и max. По умолчанию в Claude API используется high. Уровни откалиброваны заново, поэтому один и тот же уровень не даёт того же объёма размышлений, что на Claude Sonnet 5. Начинайте с high, если только ваша нагрузка не является агентной или чувствительной к «latency» (задержке). Для агентного программирования и многошагового использования инструментов начинайте с medium для чётко поставленных задач и переходите на high для более сложных или длительных. Для чата и другой работы, чувствительной к задержке, начинайте с medium или low. Задайте уровень в output_config.effort. См. Рекомендуемые уровни усилий для Claude Sonnet 5.5. Затем пересмотрите специфичные для модели инструкции в подсказках с учётом руководства Составление подсказок для Claude Sonnet 5.5.

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

Сначала примените все предыдущие разделы, заменив claude-sonnet-4-6. Затем внесите следующие изменения. Для Claude Sonnet 4.5 или более ранних моделей продолжите с последующих подразделов.

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

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

Бюджеты размышлений возвращают ошибку. Claude Sonnet 4.6 принимает thinking: {"type": "enabled", "budget_tokens": N} как устаревшую настройку. Claude Sonnet 4.5 и Claude Haiku 4.5 используют её для всех размышлений. Claude Sonnet 5.5 возвращает ошибку 400:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Удалите бюджет и задайте уровень усилий. Фиксированного соответствия между бюджетом и уровнем усилий нет, поэтому проведите оценку на двух-трёх уровнях.

До (Claude Sonnet 4.6):

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

После (Claude Sonnet 5.5):

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

Параметры сэмплирования возвращают ошибку. Claude Sonnet 4.6 и более ранние модели, а также Claude Haiku 4.5 принимают temperature, top_p и top_k. На Claude Sonnet 5.5 значение, отличное от значения по умолчанию, возвращает ошибку 400. Удалите эти параметры.

Текст размышлений по умолчанию опускается. См. Обработка размышлений в ответах.

Другие изменения

• Примерно на 30% больше токенов: Claude Sonnet 5.5 использует токенизатор Claude Sonnet 5. По сравнению с Claude Sonnet 4.6, Claude Sonnet 4.5 и Claude Haiku 4.5 один и тот же текст даёт примерно на 30% больше токенов в зависимости от содержимого. Пересчитайте токены с помощью подсчёта токенов и пересмотрите max_tokens и затраты.
• Уровень усилий: Уровень xhigh — новый, а уровни откалиброваны заново. См. Рекомендуемые изменения.
• Изображения: Claude Sonnet 5.5 использует уровень изображений высокого разрешения — до 2576 пикселей по длинной стороне и до 4784 визуальных токенов на изображение. Claude Sonnet 4.6, Claude Sonnet 4.5 и Claude Haiku 4.5 ограничены 1568 пикселями и 1568 токенами. Изображение 2000×1500 на Claude Sonnet 5.5 стоит примерно в 2,5 раза больше токенов. См. Разрешение и стоимость в токенах.

Миграция с Claude Sonnet 4.5 или более ранних моделей

Для Claude Sonnet 4.5, Claude Sonnet 4 или Claude 3.7 Sonnet сначала примените все предыдущие разделы, а затем следующие изменения.

Предзаполнение возвращает ошибку. Claude Sonnet 5.5 отклоняет предзаполненный последний ход ассистента с ошибкой 400, как и Claude Sonnet 4.6 и Claude Sonnet 5. Claude Sonnet 4.5, Claude Haiku 4.5 и более старые модели его принимают. Текст ошибки:

This model does not support assistant message prefill. The conversation must end with a user message.

Замените каждое предзаполнение в зависимости от его назначения:

• Формат вывода: используйте структурированные выходные данные или инструменты с полями enum для классификации.
• Вступления: попросите в «system prompt» (системной подсказке) давать прямой ответ.
• Нежелательные отказы: обычно достаточно чётких инструкций в сообщении пользователя.
• Продолжения: перенесите их в сообщение пользователя, например: «Ваш предыдущий ответ был прерван и закончился на [previous_response]. Продолжите с того места, где остановились.»
• Напоминания о контексте: поместите их в ход пользователя.

Экранирование входных данных инструментов. Экранирование в аргументах вызовов инструментов может отличаться. Разбирайте input стандартным JSON-парсером.

Использование компьютера. Claude Sonnet 5.5 не принимает computer_20250124. См. таблицу использования компьютера.

Уровень усилий. У Claude Sonnet 4.5 нет параметра effort. Задайте уровень усилий явно, как описано в разделе Рекомендуемые изменения.

Контекст и вывод. У Claude Sonnet 5.5 более крупное контекстное окно, не требующее бета-заголовка, и более высокий лимит вывода. См. страницу модели. Удалите любой бета-заголовок контекстного окна.

Бета-заголовки. Удалите interleaved-thinking-2025-05-14, поскольку адаптивные размышления автоматически чередуются с вызовами инструментов. Замените fine-grained-tool-streaming-2025-05-14 на eager_input_streaming: true для каждого инструмента, которому это нужно. Этот заголовок возвращает ошибку 400 вместе с записью набора инструментов для использования компьютера или браузера. См. «Fine-grained tool streaming» (детализированная потоковая передача инструментов).

Структурированные выходные данные. Параметр output_format устарел и будет удалён в будущем. Чтобы всё же использовать его, добавьте бета-заголовок structured-outputs-2025-11-13. Без него API возвращает ошибку 400. Вместо этого используйте output_config.format.

Миграция с Claude Sonnet 4 или более ранних моделей

Claude Sonnet 4 выведен из эксплуатации в Claude API, но по-прежнему доступен в Amazon Bedrock и Google Cloud. Claude 3.7 Sonnet выведен из эксплуатации. При переходе с любой из этих моделей сначала примените все предыдущие разделы, а затем следующие изменения:

• Версии инструментов: Используйте text_editor_20250728 с именем инструмента str_replace_based_edit_tool и без команды undo_edit. Используйте code_execution_20260521. См. инструмент текстового редактора и инструмент выполнения кода.
• Причины остановки: Обрабатывайте refusal. Модели Claude 4.5 и более поздние также останавливаются с model_context_window_exceeded при достижении предела контекстного окна. См. Обработка причин остановки.
• Завершающие символы новой строки: Модели Claude 4.5 и более поздние сохраняют их в строковых параметрах вызовов инструментов.
• Устаревшие бета-заголовки: Удалите token-efficient-tools-2025-02-19 и output-128k-2025-02-19.
• Подсказки: Пересмотрите их с учётом рекомендаций по составлению подсказок.

Миграция на Claude Sonnet 5.5 с Claude Haiku 4.5

Сначала примените все разделы вплоть до раздела Миграция с Claude Sonnet 4.5 или более ранних моделей включительно, пропустив подраздел о Claude Sonnet 4. Затем внесите следующие изменения:

• ID модели: Замените claude-haiku-4-5-20251001 или псевдоним claude-haiku-4-5 на claude-sonnet-5-5.
• Затраты: Цена за токен выше, а один и тот же текст даёт больше токенов. Пересчитайте токены и заново определите базовый уровень затрат. См. цены Claude.
• Кэширование подсказок: Минимальный размер кэшируемой подсказки снижается с 4096 токенов до минимума Claude Sonnet 5.5.
• Чередующиеся размышления: Адаптивные размышления автоматически выполняются между вызовами инструментов, без бета-заголовка.
• Маршрутизация: Claude Sonnet 5.5 читает блоки размышлений Claude Haiku 4.5. Разговор, переходящий на более мощную модель, сохраняет свои рассуждения. Разговор, возвращающийся обратно на Claude Haiku 4.5, теряет блоки Claude Sonnet 5.5.