モデル更新の失敗には、HTTP 400 で止まるものと、成功しているのに画面が静かになるものがあります。Claude Sonnet 5.5 はリクエストの互換性だけでなく、応答ブロックの形も変わります。Messages API の移行はモデル ID の置き換えだけでは終わりません。
本稿は API 統合の保守担当者向けです。Claude Managed Agents は、公式案内ではモデル名以外の変更は不要です。製品のモデル選択画面を使う利用者が、自分で API パラメータを変更する必要はありません。以下は文書に基づく説明であり、本番環境で実行した結果ではありません。
出発点のモデルで確認項目を分ける
Sonnet 5 からなら、思考を無効にする設定、強制ツール呼び出し、履歴再送、computer use、advisor の組み合わせを先に確認します。Sonnet 4.6 以前なら、手動の思考予算、サンプリング設定、トークン数も対象です。4.5 以前なら assistant prefill と旧 beta header も見直します。
Sonnet 5 と tokenizer は同じです。一方、4.6、4.5、Haiku 4.5 との比較では、同じ文章が内容によって約 30% 多いトークンになると公式は説明しています。異なる移行経路を一つの増加率で扱わないことが大切です。変更前のモデル、プラットフォーム、SDK、ツール定義、thinking 設定、応答の原本を保存しましょう。
まず拒否される設定を取り除く
ID は claude-sonnet-5-5。Adaptive thinking が既定で有効、Claude API の effort は High が既定です。thinking: {"type":"disabled"} は使えません。前置きの思考をなくすには between_tools を使い、effort は Low、Medium、High のいずれかにします。
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4096,
thinking={"type": "between_tools"},
output_config={"effort": "high"},
messages=[{"role": "user", "content": "Summarize the supplied release notes."}],
)
between_tools に display、budget_tokens、block_binding を追加すると 400 になります。Xhigh、Max、会話途中の effort 変更も使えません。必要なら adaptive thinking と該当機能の beta 条件を確認します。ツールなしの推論課題では前置きの思考を行わないため、万能な高速化設定ではありません。
tool_choice の any と tool も拒否されます。auto に変更し、どの場面でツールを使うかを指示します。対応する環境では strict tool schema を使えますが、strict が保証するのは呼び出し時の引数形式であり、呼び出しそのものではありません。Amazon Bedrock の Sonnet 5.5 では strict tool use 非対応のため、アプリ側で検証します。
古いモデルからなら enabled の思考予算、非既定の temperature/top_p/top_k、assistant prefill も置き換えます。思考予算を effort に変換する固定式はありません。複数の設定で評価してください。
画面の沈黙は表示処理の問題かもしれない
ツール間の長い進捗説明は thinking blocks に入り、短い説明は text に残ることがあります。Adaptive の既定 display は omitted なので、ブロックがあっても表示用の thinking は空です。Text だけ表示する実装では、Agent が動いていても停止して見えます。
通信、ツール実行、画面表示を分けて調べます。無条件の再試行は副作用を重複させるだけかもしれません。Adaptive では display の updates により進捗を返せますが、thinking-display-updates-2026-08-18 header が必要です。summarized は進捗と思考要約を混ぜて返します。between_tools は要約付きで返すので display を追加しません。
最終回答は content[0].text と決めつけず、種類ごとに読みます。ツールループには空 thinking と署名を含む assistant blocks をそのまま戻します。表示する要約と、再送するプロトコルデータは区別しましょう。
履歴とプラットフォーム差を確認する
Sonnet 5.5 の thinking blocks は、生成モデルとそれ以前の会話に結び付きます。2026 年 8 月 31 日 00:00 UTC 以降に作られたアカウントでは、前方履歴の一致チェックが既定で有効です。過去のメッセージ、system、ツールを編集してから同じブロックを戻すと 400 になることがあります。
履歴は追記型にし、指示更新は公式の会話途中更新機能を確認します。別モデルが読めないブロックは捨てられても応答は成功する場合があるため、200 は推論履歴の完全保存を意味しません。
Claude API と Google Cloud の computer use は computer_toolset_20260801 が必要です。Amazon Bedrock は computer_20251124 を受け付けます。Advisor も対応する組み合わせと暗号化結果への対応が必要です。一つの API 例を全プラットフォームに流用しないでください。
移行を一段ずつ診断する：要求、ツール、履歴を同時に変えない
以下は公式の API 仕様から構成した例であり、本番障害の記録ではありません。旧 Sonnet 5 の連携で thinking を無効化し、検索ツールの呼び出しを強制し、text ブロックだけを表示していたとします。さらに各ターンの後で履歴を要約へ置き換えています。モデル ID だけを変更すると、三つの異なる問題が現れ得ます。
最初に要求の拒否を解消します。 thinking.type=disabled と tool_choice.type=any が同時にある場合、一方だけを直しても有効な要求にはなりません。元のエラー応答を保存し、隔離した環境で対応する thinking 設定へ変更した後、ツール選択を auto にします。200 を得るためにツールと履歴をすべて削除すると、別の要求を試しただけで、元の業務フローを検証したことにはなりません。
次にツールを独立して検証します。 Auto は呼び出し保証ではありません。実際に検索が必要な入力を用意し、テスト用ツールから識別できる値を返します。ツール名、引数、結果が最終回答に反映されたかを確認します。最新在庫が必要なのに検索せず数値を答えた場合、応答が成功しても不合格です。必須の業務前提はアプリケーション側で検査・制御し、strict の引数検証で代替しません。
最後に進捗表示と履歴を修正します。 要求が通ったのに画面が静かな場合、まず raw content とストリーミングイベントを調べます。表示可能な更新を UI へ送り、次のターンへは完全なプロトコルブロックを戻します。空ブロックを削った text だけの配列に、この二つの役割を兼ねさせてはいけません。長い会話の圧縮も別途検証します。旧連携による任意の履歴書き換えが、そのまま対応済みの圧縮方式になるわけではありません。
要求が有効、ツールが完了、履歴を継続できる、という三段階の合格条件は別です。実際の応答形式は現在の SDK と文書で確認してください。この例は本番へそのまま貼る完全なアダプターではありません。
障害を区別できる証拠をログに残す
ログから、モデルと thinking/effort、失敗した要求やツール、終了理由、出現したブロック種別、副作用の実行有無を確認できるようにします。署名、顧客データ、認証情報を含む raw block はアクセスを制限し、公開ログへ流しません。
| 観測 | 最初に見る証拠 | それだけでは分からないこと |
|---|---|---|
| HTTP 400 | 完全なエラー、旧 thinking/tool_choice、基盤差 | モデルの業務能力が低下したか |
| 200 だが進捗が見えない | ブロック、display、表示・ストリーム処理 | ツールが実行されなかったか |
| ツール成功だが回答に反映なし | tool_result の対応と完全な次ターン要求 | 結果が正しく利用されたか |
| 履歴編集後に失敗 | 署名、前置履歴の変更、アカウント・モデル差 | 再試行で直るか |
| 作業途中で回答終了 | stop_reason、max_tokens、結果と作業状態 | 文章を受け取れば完了か |
目的はログの量ではなく、誤った復旧を避けることです。書き込みが成功した後で画面接続が切れた場合、ターン全体を再実行すると二重書き込みになり得ます。アプリケーション自身のトランザクション状態を確認して再試行を判断します。モデル移行が業務の重複防止やロールバックを提供するわけではありません。
本番切り替えを三つの回帰試験で判断する
最初は通信形式：文章応答、実際のツールループ、進捗表示、拒否、max_tokens 終了を確認します。次は履歴：追記、モデル変更、対応する圧縮、保存会話の再生。最後に業務：同じ入力と合格条件で成果物を作り、品質、時間、消費、手直しを記録します。
読み取り専用ツールと試験データから始めます。再試行による二重書き込みを防ぎ、戻せることを確認してから副作用のある処理へ広げます。Effort の調整は互換性試験の代わりではありません。
FAQ
ID だけ変えれば十分ですか？
Messages API では必ずしも十分ではありません。Managed Agents には別の移行範囲があります。
Strict は強制呼び出しの代替ですか？
引数を制約するもので、呼び出さない分岐もアプリ側で扱う必要があります。
空の thinking は削除できますか？
画面で隠すことと、ツールループで原本を保持することは別です。再送ブロックは変更しません。
400 が出なければ完了ですか？
進捗、履歴、副作用、成果物の合格も確認してから判断します。