Claude Haiku 5.5 移行ガイド：旧リクエストのエラー要因と既存コードの改修方法

Anthropic は Claude Haiku 5.5 をリリースしました。この軽量モデルは、呼び出し頻度が高く、コストと応答速度に敏感なアプリケーションを主に対象としており、フラッグシップモデルと連携するサブ Agent として具体的なタスクを担うこともできます。

主な機能特徴および今回のリリースに伴う関連アップデートは以下のとおりです。

• 高頻度タスクがさらに低コストに：平均運用コストが Haiku 4.5 と比較して約 75% 削減され、要約、コンテキスト圧縮、データベースクエリ、分類などの反復作業向けに最適化されています。
• より高速な応答：標準速度において最速の Claude モデルであり、リアルタイムカスタマーサポートなど即座の応答が求められるシナリオに適しています。（Fast Mode を有効にした Opus のほうが高速です。）
• フラッグシップモデルと連携したコーディングサブタスク：Sonnet 5.5 や Opus 5.5 と組み合わせるサブ Agent として、スコープが明確な作業を引き継ぐことができます。
• 推論への投入量（effort）の調整に初対応：Haiku シリーズに effort 設定が導入され、タスクごとに思考への投入度合いを調整して、費用とパフォーマンスのバランスを取ることが可能になりました。
• 複数の能力向上：公式ベンチマークにおいて、コンピュータ操作、ナレッジワーク、コーディングの各スコアがいずれも Haiku 4.5 を上回っています。
• Sonnet のキャッシュ読み込み値下げ：単価が半減。Anthropic の試算によると、大半の Sonnet 5.5 Agent タスクにおいて総コストが約 20% 削減されます。
• SDK での操作サポート拡充：Python および TypeScript SDK において、コンピュータ操作およびブラウザ操作の Beta サポートが追加されました。
• 有料プランユーザーへの API クレジット付与：リリースに伴い、Anthropic は Max および Team ユーザーに対して、Claude Platform 上の任意のモデルで使用可能な月次 API クレジットを順次展開します。

すでに Haiku 4.5 を導入しているアプリケーションが Claude Haiku 5.5 へアップグレードする際は、リクエストパラメータ、レスポンス解析、およびマルチターン会話を同時に見直す必要があります。従来の思考設定、サンプリングパラメータ、またはアシスタントメッセージの事前入力（prefilling）は HTTP 400 エラーを返す可能性があり、位置指定で回答を取得していた既存コードでは本文が読み取れなくなるおそれもあります。

この公式移行ガイドは Messages API （Claude に会話を送信しレスポンスを受け取るインターフェース）を対象としています。Claude Managed Agents を利用しているアプリケーションは、ドキュメント上モデル名の更新のみが求められます。既存の API 連携については以下の項目に沿って点検してください。Haiku 3.5 または Haiku 3 のユーザーは、記事末尾の世代間追加項目も完了させる必要があります。

モデルの能力と価格の変更については、まずHaiku 5.5 リリース解説をご覧ください。本稿では既存コードのアップグレード手順に焦点を当てて説明します。

アップグレードの近道：コマンドラインツールによる自動診断

手動でコードを書き換える前に、公式の Claude Code 開発環境を利用している場合は、組み込みの移行スキルを活用してコードの検査と修正を直接補助させることができます。

/claude-api migrate this project to claude-haiku-5-5

この自動化ツールはコードベースをスキャンし、モデル ID を置換したうえで、非互換パラメータの修正、アシスタントメッセージ事前入力の置き換え、effort の調整を必要に応じて実施します。実際にファイルを変更する前に、修正対象の範囲（ワークスペース全体、サブディレクトリ、または指定ファイルリストに対応）の確認が求められます。また、Amazon Bedrock や AWS 版 Claude クライアントを認識し、各プラットフォームに応じたモデル ID 形式へ自動調整します。

移行スキルは effort の調整も行い、人間による手動検証が必要なチェックリストを出力します。自動修正後も、リクエスト、レスポンス解析、セッション処理が以下のルールを満たしているか確認してください。

リクエストの修正点：モデル ID、思考設定、および旧パラメータ

このレイヤーの変更は、Messages API へ送信する HTTP リクエストの Request Body に直接影響します。以下の条件に該当する従来の記法は、Haiku 5.5 において HTTP 400 エラーを返します。

1. モデル ID の置換：日付サフィックスのない固定識別子へ統一

Haiku 5.5 では日付サフィックスのない固定モデル ID が採用され、個別の latest エイリアス（alias）は提供されなくなりました。各クラウドプラットフォームにおける対応関係は以下のとおりです。

2. effort による思考投入量の調整

• 従来の挙動：Haiku 4.5 では、拡張思考の有効化に通常 thinking: {"type": "enabled", "budget_tokens": 8000} を使用していました。Haiku 5.5 でこの記法をそのまま使用すると、API は直ちに HTTP 400 エラーを返します。
• メカニズムの変更：Haiku 5.5 では明示的な数値トークンバジェットが廃止され、アダプティブ思考（Adaptive Thinking）に移行しました。思考の強度を制御するレバーは output_config.effort フィールドに移っています。
• デフォルト有効化の仕組み：アダプティブ思考はデフォルトで有効になっています。リクエスト本文に thinking パラメータをまったく記述しなくても、モデルが返すレスポンスには思考ブロックが含まれる可能性があります。時間とトークンを節約するために思考を抑えたい場合は、effort を低く設定（例："low"）します。投入量を低くすると、モデルの思考量が減り、単純なリクエストでは思考をスキップすることもあります。
• 思考要約の表示：従来の 4.5 では要約テキスト付きの思考内容が返されていましたが、5.5 ではデフォルトで返される思考ブロック内の thinking テキストフィールドは空であり、signature 署名フィールドのみが保持されます。フロントエンドで思考プロセスの要約を表示する必要がある場合は、リクエスト内で明示的に thinking: {"type": "adaptive", "display": "summarized"} を宣言する必要があります。
• ツール強制呼び出し時の挙動：リクエストでツールの強制呼び出しが設定されている場合（例：tool_choice: {"type": "any"} または具体的なツール名の指定）、Haiku 5.5 は思考ブロックを生成せず、直接ツール呼び出し命令を出力します。モデルに「考えてから呼び出す」動作を強制させたい場合は、ツール呼び出しを auto モード tool_choice: {"type": "auto"} に設定し、プロンプト内でツールを呼び出すタイミングを明示する必要があります。

3. 旧サンプリングパラメータの削除

• 従来の挙動：従来のコードでは慣例的に temperature: 0.7、top_p: 0.9、またはカスタムの top_k を設定していました。Haiku 5.5 では、これらはすべて HTTP 400 バリデーションエラーを引き起こします。
• 新仕様のルール：リクエストから temperature、top_p、top_k を完全に削除し、出力スタイルや発散度はプロンプト側の指示で制御します。
• 厳格なバリデーション規則：
  • リクエストに temperature を含める場合、その数値は厳格に 1 でなければなりません。
  • リクエストに top_p を含める場合、その数値はデフォルト値である 0.99 のみ許容されます（注：top_p: 1 を渡しても 400 エラーになります）。
  • リクエストに top_k が含まれている場合、値に関わらず直ちに 400 エラーとなります。
  • 同一リクエスト内に temperature と top_p の両方が含まれている場合、たとえ上記で許可された値であっても HTTP 400 エラーとなります。

4. アシスタントメッセージ事前入力の置き換え

• 従来の挙動：旧バージョンでは、JSON 形式のみを出力させたり挨拶の前置きを省く目的で、messages 配列の末尾に閉じられていないアシスタントメッセージを挿入する手法（例：{"role": "assistant", "content": "{"} や {"role": "assistant", "content": "Sure, here is the answer:"}）が使われていました。Haiku 5.5 では、末尾の assistant メッセージによる続きの生成は、思考を無効化していても HTTP 400 エラーを返します。リクエストの messages リストは必ず user メッセージで終わるように変更してください。
• 用途別の改修アプローチ：

旧方式：末尾の Assistant メッセージで出力を誘導
[User: "..."] -> [Assistant: "誘導用テキスト..."] -> 400 エラーが発生！

新方式：用途に応じてシステムプロンプト、構造化インターフェース、ユーザーターンへ移す
├─ 厳格な形式指定（JSON など） ────> 構造化出力（Structured Outputs）または Enum 制約付きのツール定義を使用
├─ 不要な導入文（Preambles）を除く ─> System Prompt に明示的な指示を置く（例：「前置きや挨拶を省き、直接回答してください」）
├─ 中断箇所からの続行（Continuations） ──> User メッセージに移す（「前回の回答は [...] で中断しました。その直後から続けてください」）
└─ コンテキストの強調リマインダー ──────────────> 現在の User メッセージの末尾に直接追加

プラットフォーム制限に関する注意：Amazon Bedrock では現在、ネイティブの構造化出力（Structured Outputs）がサポートされていません。Bedrock 上で出力フォーマットを厳密に制限する必要がある場合は、パラメータスキーマを持つツール（Tool）を定義し、そのツールの呼び出しへとモデルを誘導して構造化データを返却させる構成を推奨します。

トークンとセッションの処理：使用量の再計算と思考ブロックコンテキストの保持

この層の変更は単発のシンプルな呼び出しでは顕在化しない場合がありますが、マルチターン対話システム、チャット履歴保存サービス、課金システム、長文処理の安定性に影響します。

1. カウントの再計測：同一入力でトークン数が約 30% 増加

• メカニズムの変更：Haiku 5.5 では、Claude 4.7 以降のモデルと同じ更新されたトークナイザーが採用されています。まったく同一のテキストであっても、Haiku 5.5 でトークン化すると、Haiku 4.5 と比べてトークン数が約 30% 増加します（具体的な増加率は内容により異なります）。
• 本番環境で生じる問題：
  1. 出力の切り捨て：固定トークン数に収まる文字数が減少します。Haiku 4.5 向けに調整された max_tokens の上限をそのまま流用すると、同等の長さの出力が途中で切れてしまう可能性があります。
  2. 思考による上限枯渇：思考トークンも max_tokens の枠を消費します。旧コードで小さめの max_tokens を設定していると、アダプティブ思考フェーズで枠を使い果たし、最終的なレスポンスに実際の本文回答が一切含まれず思考ブロックのみとなり、停止理由が stop_reason: "max_tokens" で返されることがあります。
  3. 課金および見積もりの乖離：ローカルのトークンカウンターに依存して予算を見積もったり呼び出し単価を計算しているモジュールは、再測定が必要です。トークンカウント API を呼び出す際は、旧版 4.5 の試算データを流用せず、明示的に model: "claude-haiku-5-5" を渡してください。

2. 思考ブロック返却時、直前の会話内容を変更しない

• 点検が必要なコード：過去の会話をトリミングしたり、system や tools を変更したうえで、過去の思考ブロックを含むメッセージを再送する実装が存在する場合があります。Haiku 4.5 では以下のプレフィックス検証は実施されていませんでした。
• 新仕様の厳格な検証：Haiku 5.5 の思考ブロックは、その直前の内容が改変されていない場合にのみ有効です。思考ブロックを返送する際に直前の system、tools、または先行する messages を変更した場合、リクエストは 400 エラーを返します。ドキュメントに記載された互換条件によると、2026 年 8 月 31 日 00:00 UTC より前に作成されたアカウントでは、リクエストで thinking.block_binding.prefix_mismatch_behavior が設定されている場合にのみ、この種のエラーが発生します。
• 改修の原則：思考ブロックを含むセッションの維持は、追記専用モード（Append-Only）を採用する必要があります。思考ブロックを保持する場合、それ以前のシステムプロンプト、ツール、メッセージを変更してはなりません。

3. セッション再生時は思考ブロックを生成したアカウントを使用

マルチテナント SaaS アーキテクチャや大規模な社内共通ゲートウェイでは、ユーザーの過去セッションを共通データベースに保存し、異なるテナントやロードバランサーの振り分けによって、別のアカウント経由で過去のコンテキストを流し込んで再生する構成が見られます。

• リクエストは成功するが思考ブロックが破棄される：Haiku 5.5 で生成された思考ブロックは、それを生成したアカウントまたは関連付けられたアカウントでのみ有効です。関連のない別アカウント B でアカウント A の思考ブロックを再生した場合、API は 400 エラーをスローせず、思考ブロックをサイレントに破棄（drop）します。
• 影響：リクエスト自体は成功しますが、モデルは破棄された思考内容を参照できません。複数アカウントでストレージと再生を行う場合は、各セッションを最初に生成したアカウントへルーティングする必要があります。関連アカウントの適用ルールについては公式ドキュメントを参照してください。

コンピュータ操作の移行：リクエスト宣言と実行ループの双方を変更

チャットだけでなく、Agent のツールチェーン呼び出し、コード実行、自動化操作を扱っている場合は、ツール層のプロトコルバージョンも合わせて見直す必要があります。

1. コンピュータ操作ツールセットへの切り替え

• 対象プラットフォーム：Claude API への直接接続および Google Cloud プラットフォーム。
• 旧プロトコルの廃止：従来のツール名 computer_20250124 および対応する Beta ヘッダー computer-use-2025-01-24 は 5.5 で完全に廃止され、リクエストを送信すると 400 エラーが返されます。
• 新バージョン Toolset への移行手順：
  1. リクエストヘッダーから computer-use-2025-01-24 を削除します。
  2. tools リスト内で単一の tool ではなく、ツールセットとして宣言します：{"type": "computer_toolset_20260801"}。
  3. ディスパッチロジックの再構築：マウスやキーボードの動作判定を input.action のみに依存することはできなくなり、各 tool_use ブロックの name および toolset_name の双方をチェックする必要があります。
  4. 全ブロックの処理と返却：同一ターン内に該当ツールセットの呼び出しブロックが複数存在する場合、現行ターンで全ブロックを処理し、実行結果（tool_result）を返送する際に明示的に toolset_name を付与する必要があります。
  5. 画面ズーム（Zoom）デフォルト有効化への対応：新しいツールセットではズーム機能がデフォルトで有効になっています。実行環境でズーム機能が未実装の場合は、設定で明示的に無効化する必要があります："configs": {"zoom": {"enabled": false}}。
  6. ストリーミングヘッダーの競合排除：古いリクエストに fine-grained-tool-streaming-2025-05-14 ヘッダーが含まれている場合は削除する必要があります。新しい toolset と共存できず、インターフェースが 400 エラーを返します。
• ウェブ操作機能の新規追加：Claude API および Google Cloud において、Haiku 5.5 ではウェブ操作に特化した browser_toolset_20260801 が新たに追加されました。これは 4.5 にはなかった新機能です。

2. Priority Tier キャパシティの再設計

過去に Claude Haiku 4.5 で Priority Tier（優先保証枠） のコンピュートコミットメントを購入していたチームは、Claude Haiku 5.5 では現在 Priority Tier がサポートされていない点に十分ご注意ください。5.5 へのアップグレード時は、別途キャパシティの設計を行う必要があります。

レスポンス受信後の処理：ブロックの type から本文を取得し、停止理由を識別

Haiku 5.5 へのアップグレード後は、レスポンス受領後のクライアント側解析コードも確認する必要があります。

1. content ブロックの type に基づいて本文を取得

多くの旧コードでは、簡便さのために以下のように記述されていました。

# 旧記法：最初のブロックが回答本文だと仮定
reply_text = response.content[0].text

Haiku 5.5 ではアダプティブ思考がデフォルトで有効になっているため、返却される response.content 配列において、先頭が type: "thinking" の思考ブロックとなり、実際の回答内容は後続の type: "text" ブロックに格納される場合があります。インデックス 0 から固定でテキストを取得し続けると、そのブロックに text フィールドが存在せずエラーになるか、後続の本文を見落とすことになります。

改修後の解析ロジック：content 配列をループ処理し、type に応じて厳格に条件分岐を行います。type == "text" の場合はユーザー向け本文として連結し、type == "thinking" の場合はツール結果と一緒に返送する際に元のブロックを改変せずそのまま保持します。

2. refusal 停止理由の処理

Haiku 5.5 のセーフティ分類器はリクエストを拒否（refusal）することがあり、モデル側でのサーバーサイドフォールバックは用意されていません。クライアント側でこの停止理由を識別する必要があります。

{ "stop_reason": "refusal" }

コード内に "refusal" の判定処理を追加する必要があります。旧コードが "end_turn"、"max_tokens"、"tool_use" のみを前提としている場合、拒否が発生した際に業務フローが停止するか、未処理の例外としてクラッシュするおそれがあります。

Haiku 3.5 または Haiku 3 からのアップグレード時の追加チェック項目

業務コードが依然として Claude Haiku 3.5 や Haiku 3 のまま稼働している場合、ドキュメントに記載されたステータスとして、Haiku 3.5 は Claude API および Amazon Bedrock で提供終了（retired）、Haiku 3 は Claude API で提供終了となっています。提供終了したモデルの呼び出しは失敗します。Google Cloud では Haiku 3.5 を非推奨（deprecated）としており、既存顧客にのみ提供されています。この場合、前述のすべての改修に加えて、以下の変更を行う必要があります。

1. モデル ID と旧ツール：
   • claude-3-5-haiku-20241022、claude-3-5-haiku-latest、または claude-3-haiku-20240307 を claude-haiku-5-5 に変更します。Google Cloud の旧 ID claude-3-5-haiku@20241022 も同様に変更し、Bedrock では前述の表に記載されたプラットフォームプレフィックス付き ID を使用します。
   • 初期の純粋な Python 実行ツール code_execution_20250522 は code_execution_20250825 以降のバージョンへアップグレードする必要があります。
   • テキスト編集ツールは text_editor_20250728（内部ツール名 str_replace_based_edit_tool に対応）へ切り替える必要があります。このバージョンでは undo_edit（編集の取り消し）コマンドが削除されている点に注意してください。
2. コンテキスト上限超過の検出：refusal のハンドリングに加え、停止理由として model_context_window_exceeded を追加処理します。
3. ツール引数の末尾改行への許容：4.5 以降のモデルでは、ツール呼び出しの文字列引数の末尾に改行文字 \n が保持されます。バックエンド側でツール引数の完全一致比較を行っている場合は、末尾の改行を許容するように変更してください。
4. プロンプトの再構成：Claude 4 以降のモデルは、より簡潔で直接的なコミュニケーションスタイルを持つため、より具体的で指示内容が明確なシステムインストラクションが求められます。

リクエスト例の比較とレスポンス解析の確認

以下のサンプルは、公式ドキュメントの仕様に基づいて整理した移行ロジックの概念図です（SDK 実機実行の出力結果ではなく、パラメータ構造の変化を示すためのものです）。

1. 公式リクエストの新旧比較

budget_tokens で思考バジェットを固定していた旧リクエスト：

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

移行後、モデル ID を claude-haiku-5-5 に変更し、思考モードを adaptive に設定、output_config.effort で投入量を制御します：

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

ここではドキュメントの例示にある max_tokens を使用していますが、実際の実装ではタスクに応じてトークン数を再計算し、途中で切り捨てが発生していないか点検する必要があります。思考要約が必要な場合は、さらに display: "summarized" を追加します。

2. Python クライアントのレスポンス処理サンプル

# 公式移行ルールに基づくレスポンス解析の例（学習用）
from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-haiku-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[
        {"role": "user", "content": "この計画の実現可能性を評価し、三つの提案を示してください。"}
    ]
)

# 1. エラー処理：安全上の拒否を検出
if response.stop_reason == "refusal":
    print("セーフティ分類器がリクエストを拒否したため、回答は生成されませんでした。")
elif response.stop_reason == "max_tokens":
    print("警告：Token の上限に達し、出力が途中で切り捨てられました（思考で多く消費したか、設定上限が低すぎる可能性があります）。")

# 2. 現在の回答本文のみ抽出。ツールループで思考を返送する場合は元のブロックを保持
thinking_process = []
final_answers = []

for block in response.content:
    if block.type == "thinking":
        # デフォルトでは block.thinking は空文字列で、signature のみ保持される
        # display: "summarized" を有効にすると要約テキストが含まれる
        if hasattr(block, "thinking") and block.thinking:
            thinking_process.append(block.thinking)
    elif block.type == "text":
        final_answers.append(block.text)

print("最終回答：")
print("\n".join(final_answers))

本番移行チェックリスト

リクエスト、レスポンス、セッション、ツールの 4 つのグループに分けて確認します。利用していない機能の項目はスキップ可能です。本番環境へ反映する前に、実タスクを用いて修正後の結果を検証してください。

リクエスト設定

• モデル ID：利用プラットフォームに応じてモデル名を変更し、環境変数やゲートウェイルーティングを確認。
• サンプリングパラメータ：temperature、top_p、top_k を削除。
• 思考投入量：budget_tokens の送信を停止。アダプティブ思考を利用し、effort で投入量を調整。
• メッセージ末尾：末尾のアシスタント事前入力を廃止。厳格な形式指定には構造化出力やツールを使用し、続きの指示やリマインダーはユーザーメッセージに配置。

レスポンスとトークン上限

• 本文取得：type == "text" に基づいてコンテンツを取得し、content[0] の固定読み取りを廃止。
• 停止理由：refusal の処理を追加。max_tokens 到達時に切り捨てを認識できることを確認。
• 出力枠：トークン数を再計算し、タスクに応じて max_tokens の調整や effort の引き下げを行い、本文生成前に枠が枯渇しないか確認。
• 思考要約：要約の表示が必要な場合は、明示的に display: "summarized" を設定。

マルチターン会話

• 先行コンテキストの保持：思考ブロックを返送する際、それ以前のシステムプロンプト、ツール、過去メッセージを変更しない。既存アカウントの互換条件は前述を参照。
• アカウントの関連付け維持：思考ブロックを生成したアカウントまたは関連付けられたアカウントにセッションを渡し、関連のない別アカウントへのルーティングを防止。

ツール実行

• コンピュータ操作：新しいツールセットへ移行し、旧 Beta リクエストヘッダーを削除したうえで、ズーム対応を確認。
• 実行ループ：同一ターン内の全ツールブロックを処理し、名前でディスパッチを行い、結果返送時にツールセット識別子を維持。

Haiku 3.5 または Haiku 3 のユーザーは前述の世代間追加項目も完了してください。既存の Priority Tier コミットメントをお持ちのチームは、別途キャパシティの調整を行ってください。