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に移行するためのコード変更を説明します。最初の2つのセクションを読んでから、現在のモデルに対応するセクションまで読み進めてください。移行チェックリストには、開始モデルごとにすべての変更点がまとめられています。

Claude Sonnet 5.5の価格はClaude Sonnet 5と同じですが、プロンプトキャッシングのキャッシュ読み取りは例外で、100万トークンあたり0.10 USDと、Claude Sonnet 5の半額です。料金を参照してください。「context window」（コンテキストウィンドウ）と出力の上限については、Claude Sonnet 5.5のモデルページを参照してください。機能とプロンプトについては、Claude Sonnet 5.5の新機能およびClaude Sonnet 5.5へのプロンプトを参照してください。

Claude Sonnet 5.5にリクエストを送信する

このリクエストは、記述どおりにClaude Sonnet 5.5で動作します。「effort」（エフォート）レベルを設定しており、400エラーを返す5つの設定は含まれていません：思考予算、サンプリングパラメータ、アシスタントのプレフィル、強制ツール選択、および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フィールドのないリクエストは、thinking: {"type": "adaptive"}と同様に、「adaptive thinking」（適応型思考）で実行されます。Claude Sonnet 4.6以前のモデルおよびClaude Haiku 4.5では、このリクエストは思考なしで実行されていました。事前の思考なしで実行し続けるには、事前の思考をオフにするを参照してください。

応答内の思考を処理する

思考なしで実行していたコードには、3つの項目すべてが必要です。Claude Sonnet 5からのコードには、おそらく最初の2つがすでに含まれています。

• コンテンツブロックをtypeで読み取る。 応答はthinkingブロックで始まる場合があるため、content[0].textを読み取るコードは動作しなくなります。
• thinkingブロックを変更せずにそのまま返す。 ツール使用ループでは、空のものも含めて返します。思考ブロックの保持を参照してください。
• max_tokensを見直す。 これは思考とテキストの両方をカバーし、思考トークンは出力トークンとして課金されます。コスト管理を参照してください。

思考テキストはデフォルトで省略されます。thinkingブロックは、空のthinkingフィールドとsignatureを伴って届きます。読み取り可能な要約を取得するには、display: "summarized"を設定します。これはClaude Sonnet 4.6以前のモデルおよびClaude Haiku 4.5でのデフォルトです。思考表示の制御を参照してください。

事前の思考をオフにする

Claude Sonnet 5.5で事前の思考をオフにするには、thinking: {"type": "between_tools"}を送信します。これは最も低い思考設定です。ツール呼び出し間の進捗更新は、引き続き要約テキスト付きのthinkingブロックとして返されます。ツールがない場合、応答にはテキストのみが含まれます。Claude Sonnet 5では代わりにthinking: {"type": "disabled"}で思考をオフにし、それ以前のモデルはデフォルトで思考なしで実行されます。Claude Sonnet 5.5では、disabledは400 invalid_request_errorを返します：

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

between_toolsは、Claude Sonnet 5.5を提供するすべてのプラットフォームで動作します。low、medium、highのエフォートで受け付けられます。xhighまたはmaxでは400エラーを返します。これらのレベルで実行するには、適応型思考を使用してください：thinkingフィールドを省略するか、thinking: {"type": "adaptive"}を送信します。between_toolsは他のフィールドを受け付けません：display、budget_tokens、またはblock_bindingを一緒に送信すると400エラーを返します。サーバーサイドフォールバックを使用する場合、Claude Sonnet 5にフォールバックしたbetween_toolsリクエストは、そちらでthinking: {"type": "disabled"}として実行されます。

between_toolsを使用する場合、エフォートを会話の途中で変更することはできません：有効なレベルと異なるメッセージごとのoutput_config.effortは400エラーを返します。ターンごとにエフォートを変えるには、適応型思考を使用してください。プロンプトのガイダンスについては、事前の思考なしでの実行を参照してください。

変更前（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のみ」で終了します。

すべての開始モデル

• モデルIDをclaude-sonnet-5-5に変更します。
• コンテンツブロックをtypeで読み取り、thinkingブロックは変更せずにそのまま返します。
• 事前の思考なしで実行し続けるには、high以下のエフォートで最も低い思考設定を送信します。
• 強制ツール使用をautoとstrictツールに置き換えます。
• 会話を追記のみに保ちます。
• コンピューター使用をfine-grained-tool-streaming-2025-05-14ベータヘッダーなしでツールセットに移行します。Amazon Bedrockでは、computer_20251124も動作します。
• アドバイザーツールをサポートされているアドバイザーと組み合わせ、暗号化されたアドバイスが返されることを想定してください。
• ツール呼び出し間のテキストはthinkingブロックから読み取ります。
• 拒否を処理し、フォールバックを設定します。
• エフォートの比較検証を再実行し、コストのベースラインを再設定します。

Claude Sonnet 4.6以前

• thinkingフィールドのないリクエストでの思考を想定し、max_tokensを見直します。
• 思考予算をエフォートレベルに置き換えます。
• temperature、top_p、top_kを削除します。
• 思考テキストを表示する場合は、display: "summarized"を設定します。
• トークンを再カウントし、画像トークンの予算を再設定します。

Claude Sonnet 4.5以前

• アシスタントのプレフィルを置き換えます。
• ツール呼び出しの入力は標準のJSONパーサーで解析します。
• 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からClaude Sonnet 5.5への移行

すべての開始モデルで、このセクションの変更が必要です。モデルIDを、日付サフィックスのないclaude-sonnet-5-5に置き換えます。他のプラットフォームでは、利用可能性に記載されているIDを使用してください。

強制ツール使用はサポートされていない

このページに記載されているそれ以前のすべてのモデルは、タイプanyまたはtoolのtool_choiceを受け付けます。Claude Sonnet 5.5は、トークンカウントエンドポイントを含め、両方を400エラーで拒否します：

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

tool_choice: {"type": "auto"}を送信し、入力がスキーマに一致するようにツールにstrict: trueを指定します。この場合、モデルはツールを呼び出さずに回答できるため、いつツールを使用するかをプロンプトで指示してください。Strictツール使用はJSON Schemaのサブセットをサポートし、すべてのオブジェクトにadditionalProperties: falseが必要です。JSON Schemaの制限を参照してください。

変更前（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,
    # strict tool use（厳格なツール使用）: すべての呼び出しがツールの 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.",
        }
    ],
)

この例では、リスト内のすべてのツールをstrictに指定しています。1つのリクエストに含められるstrictツールは最大20個で、MCP、コンピューター使用、ブラウザ使用のツールセットエントリはstrictを受け付けません。より長いツールリストでは、必要なツールのみを指定してください。

思考ブロックはモデルと会話に紐付けられる

Claude Sonnet 5.5は、Claude Sonnet 5、Claude Opus 4.8、Claude Haiku 4.5、およびそれ以前のモデルからの思考ブロックを読み取ります。また、Claude APIおよびClaude Models on Google Cloud (Google managed)では、Claude Haiku 5.5からの思考ブロックも読み取ります。Claude Opus 5、Claude Opus 5.5、またはClaude FableやClaude Mythosのいずれのモデルからのブロックも読み取りません。

APIは、モデルが読み取れないブロックを除外します。リクエストは200を返し、除外されたブロックは課金されません。モデルを切り替えて元に戻すを参照してください。

思考ブロックがプレフィックスチェックに合格するように、会話は追記のみで進めてください。指示やツールを変更するには、会話途中のシステムメッセージとツールの変更を参照してください。

プレフィックスチェックに失敗すると、400エラーになる場合もあれば、ならない場合もあります。両方のケースを特定して対処するには、思考ブロックのプレフィックスチェックを参照してください。

プレフィックスチェックは、Claude APIおよび一部のクラウドプラットフォームで実行されます。

Claude Sonnet 5.5の思考ブロックは、それを生成したアカウント、またはそのアカウントにリンクされたアカウントでのみ機能します。保持された思考を参照してください。

一部のコンピューター使用ツールバージョンはサポートされていません

Claude Sonnet 5.5は、computer_toolset_20260801ツールセットを通じてコンピューター使用をサポートします。Amazon Bedrockでは、Claude Sonnet 5.5はcomputer-use-2025-11-24ベータヘッダー付きのcomputer_20251124ツールも受け付けます。Claude Sonnet 5.5は、Claude APIでのcomputer_20251124など、受け付けないコンピューター使用ツールバージョンに対しては400エラーを返します。computer_20250124はどのプラットフォームでも受け付けません。

ツールセットを使用している統合は変更不要です。ツールセットに移行するには、computer_20251124またはcomputer_20250124をcomputer_toolset_20260801に置き換え、そのバージョンのベータヘッダーを削除します。リクエストとエージェントループの変更点については、computer_20251124からの移行を参照してください。

fine-grained-tool-streaming-2025-05-14ベータヘッダーを送信している場合は、ツールセットに移行する際に削除してください。ツールセットエントリと一緒に送信すると400エラーを返します。代わりに、必要な各ツールにeager_input_streaming: trueを設定してください。

アドバイザーツールで受け付けられるアドバイザーが少なくなる

アドバイザーツールを使用する場合、Claude Sonnet 5.5のエグゼキューターには次のいずれかのアドバイザーが必要です：Claude Opus 5、Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5、Claude Fable 5.1、Claude Fable 5.2、Claude Mythos 5、Claude Mythos 5.1、またはClaude Mythos 5.2。Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5、Claude Sonnet 4.6、およびClaude Haiku 5.5のアドバイザーは400エラーを返します。アドバイスはadvisor_redacted_resultブロックとして暗号化されて返されるため、そのテキストは応答内で読み取ることはできません。モデルの互換性を参照してください。

ツール呼び出し間のテキストは思考ブロックで返される

Claude Sonnet 5.5では、モデルがツール呼び出しの間に書く1〜2文より長いメモは、進捗更新の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"： リクエストが、競合するAIモデルの開発を支援する可能性があります。
• "reasoning_extraction"： リクエストが、モデルの内部推論を応答テキストで再現するよう求めています。
• "general_harms"： リクエストが、その他の利用ポリシー領域に該当します。無害な作業でもこのカテゴリがトリガーされる場合があります。

Claude APIおよびClaude Models on Google Cloud (Anthropic managed)でベータ版として提供されているサーバーサイドフォールバック（fallbacks: "default"）は、"cyber"および"frontier_llm"の拒否をClaude Sonnet 5で再試行します。"bio"、"reasoning_extraction"、または"general_harms"の拒否は再試行しません。拒否とフォールバックおよび拒否の課金方法を参照してください。

リアルタイムのサイバーセーフガードは、Claude Sonnet 4.6、Claude Sonnet 4.5、およびClaude Haiku 4.5からのコードにとっては新しいものです。正当なセキュリティ作業については、Cyber Verification Programに申請してください。

その他の変更

• 「prompt caching」（プロンプトキャッシング）： キャッシュ可能なプロンプトの最小サイズは512トークンで、Claude Sonnet 5、Claude Sonnet 4.6、Claude Sonnet 4.5の1,024から引き下げられました。プロンプトキャッシングを参照してください。
• 新機能： 会話途中のシステムメッセージ、会話途中のツール変更、メッセージごとのエフォートについては、Claude Sonnet 5.5の新機能を参照してください。between_toolsでは、エフォートを会話の途中で変更することはできません。

推奨される変更

エフォートの比較検証を再実行してください。Claude Sonnet 5.5には5つのエフォートレベルがあります：low、medium、high、xhigh、max。Claude APIでのデフォルトはhighです。レベルは再調整されているため、同じレベルでもClaude Sonnet 5と同じ量の思考が生成されるわけではありません。ワークロードがエージェント型またはレイテンシに敏感なものでない限り、highから始めてください。エージェント型のコーディングや複数ステップのツール使用では、仕様が明確なタスクにはmediumから始め、より難しいタスクや長いタスクにはhighに移行してください。チャットやその他のレイテンシに敏感な作業では、mediumまたはlowから始めてください。レベルはoutput_config.effortで設定します。Claude Sonnet 5.5の推奨エフォートレベルを参照してください。その後、モデル固有のプロンプト指示をClaude Sonnet 5.5へのプロンプトに照らして再評価してください。

Claude Sonnet 4.6以前のSonnetモデルからClaude Sonnet 5.5への移行

まず、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.

予算を削除し、エフォートレベルを設定してください。予算からエフォートレベルへの固定的な対応関係はないため、2つか3つのレベルで評価を実行してください。

変更前（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": "..."}],
)

サンプリングパラメータはエラーを返す。 temperature、top_p、top_kを削除してください。

思考テキストはデフォルトで省略される。 応答内の思考を処理するを参照してください。

その他の変更

• トークン数が約30%増加： Claude Sonnet 5.5はClaude Sonnet 5のトークナイザーを使用します。Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Haiku 4.5と比較すると、同じテキストでもコンテンツに応じて約30%多くのトークンが生成されます。トークンカウントで再カウントし、max_tokensとコストを見直してください。
• エフォート： Claude Sonnet 5.5はxhighをサポートしており、レベルが再調整されています。推奨される変更を参照してください。
• 画像： Claude Sonnet 5.5は高解像度の画像ティアを使用し、長辺最大2,576ピクセル、1画像あたり最大4,784ビジュアルトークンに対応します。Claude Sonnet 4.6、Claude Sonnet 4.5、Claude Haiku 4.5は、1,568ピクセルおよび1,568トークンが上限です。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は、Claude Sonnet 4.6およびClaude Sonnet 5と同様に、プレフィルされた最後のアシスタントターンを400エラーで拒否します。Claude Sonnet 4.5、Claude Haiku 4.5、およびそれ以前のモデルはこれを受け付けます。エラーは次のとおりです：

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

各プレフィルを、その用途に応じて置き換えてください：

• 出力形式： 構造化出力を使用するか、分類には列挙型フィールドを持つツールを使用します。
• 前置き： システムプロンプトで直接的な回答を求めます。
• 不要な拒否： 通常は、ユーザーメッセージ内の明確な指示で十分です。
• 続き： ユーザーメッセージに移動します。例：「前回の応答は中断され、[previous_response]で終わりました。中断したところから続けてください。」
• コンテキストのリマインダー： ユーザーターンに含めます。

ツール入力のエスケープ。 ツール呼び出しの引数におけるエスケープが異なる場合があります。inputは標準のJSONパーサーで解析してください。

コンピューター使用。 Claude Sonnet 5.5はcomputer_20250124を受け付けません。一部のコンピューター使用ツールバージョンはサポートされていませんを参照してください。

エフォート。 Claude Sonnet 4.5にはエフォートパラメータがありません。エフォートレベルを明示的に設定してください（推奨される変更を参照）。

コンテキストと出力。 Claude Sonnet 5.5は、より大きなコンテキストウィンドウを持ち、出力の上限も高くなっています。Claude Sonnet 5.5のモデルページを参照してください。コンテキストウィンドウ関連のベータヘッダーはすべて削除してください。

ベータヘッダー。 適応型思考は自動的にインターリーブするため、interleaved-thinking-2025-05-14を削除してください。fine-grained-tool-streaming-2025-05-14は、必要な各ツールのeager_input_streaming: trueに置き換えてください。このヘッダーは、コンピューター使用またはブラウザ使用のツールセットエントリと一緒に送信すると400エラーを返します。きめ細かなツールストリーミングを参照してください。

構造化出力。 output_formatパラメータは非推奨です。それでも使用する場合は、structured-outputs-2025-11-13ベータヘッダーを追加してください。これがない場合、APIは400エラーを返します。代わりにoutput_config.formatを使用してください。

Claude Sonnet 4以前からの移行

Claude Sonnet 4はClaude APIでは廃止済みですが、Claude Models on Google Cloud (Google managed)およびAmazon Bedrockでは利用可能です。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 Haiku 4.5からClaude Sonnet 5.5への移行

まず、Claude Sonnet 4のサブセクションを除き、Claude Sonnet 4.5以前からの移行までのすべてのセクション（同セクションを含む）を適用します。その後、以下の変更を行います：

• モデルID： claude-haiku-4-5-20251001、またはエイリアスclaude-haiku-4-5をclaude-sonnet-5-5に置き換えてください。
• コスト： トークンあたりの価格が高くなり、同じテキストでもより多くのトークンが生成されます。トークンを再カウントし、コストのベースラインを再設定してください。料金を参照してください。
• プロンプトキャッシング： キャッシュ可能なプロンプトの最小サイズは、4,096トークンからClaude Sonnet 5.5の最小値に引き下げられます。
• インターリーブ思考： 適応型思考は、ツール呼び出しの間に自動的に実行されます。
• ルーティング： Claude Sonnet 5.5はClaude Haiku 4.5の思考ブロックを読み取ります。上位モデルに移行する会話は推論を保持します。Claude Haiku 4.5に戻る会話では、Claude Sonnet 5.5のブロックが除外されます。