🔧 Claude Sonnet 5 移行で壊れるAPI前提と運用破断点の棚卸し

本記事の角度は「モデル差（性能比較）」ではなく「エージェント運用の破断点棚卸し」です。既存ハーネスを Claude Sonnet 4.6 から Claude Sonnet 5 へ移行する実装エンジニア・SRE・LLMOps を読者に想定します。モデル更新は品質比較より先に、max_tokens・コスト見積り・リトライ条件・パラメータ禁止（400）・拒否応答（refusal）の扱いを回帰確認する、という観点で整理します。出典は Anthropic 公式ドキュメント（2026-07-01 取得）です。

概要

Claude Sonnet 5 は、Claude Sonnet 4.6 の drop-in 後継モデルです。「speed と intelligence の最良バランス」というポジションを継承しつつ、Sonnet 系列で最もエージェント的に動作します。API モデル ID を claude-sonnet-5 に変更するだけで移行できますが、3 つの behavior change と新トークナイザの影響を既存ハーネスで先に把握します。

これら以外（ツール定義・レスポンス形状・assistant prefill 非対応）は Sonnet 4.6 から変わりません。移行の本質は「静かに前提を壊す変更を、回帰確認で先に洗い出す」ことにあります。

新トークナイザ自体は Claude Opus 4.7 で先行導入したもので、Sonnet 5 固有ではありません。Sonnet 4.6（旧トークナイザ）から Sonnet 5（新トークナイザ）への移行で、同一テキストあたり約 30% 増が顕在化します。

特徴

• エージェント・コーディング性能が Sonnet 4.6 から大幅に向上します。Sonnet の速度と価格のまま、より高い agentic 性能を提供します。
• 価格は Sonnet 4.6 と同額です。標準 $3/$15 per MTok（input/output）で、2026-08-31 まで導入価格 $2/$10 per MTok を適用します。per-token 単価は不変ですが、新トークナイザで同一テキストのトークン数が増えるため、等価リクエストのコストは 4.6 と変わりえます。
• コンテキストウィンドウは 1M トークン（最大かつデフォルト、小さい variant なし）、最大出力は 128K トークンです。最大出力は Sonnet 4.6 と同じ 128K です。ただし新トークナイザにより、同じ 1M 窓に入るテキスト量は 4.6 より少なくなります。
• ZDR（ゼロデータ保持）に対応します。ZDR 契約を持つ組織で利用できます（30 日保持を必須とする Fable 5 と対照的です）。
• Priority Tier は非提供です。Sonnet 4.6 で利用できた Priority Tier を Sonnet 5 では提供しません。Priority Tier に依存したルーティングは standard tier へ見直します。
• Sonnet 系初のリアルタイム・サイバーセキュリティ safeguards を搭載します。禁止・高リスクなサイバーセキュリティ題材のリクエストを拒否します。拒否は HTTP 200 + stop_reason: "refusal" で返るため、エラーとの区別が必要です。
• adaptive thinking が既定 ON です。タスク複雑度に応じて思考深さを自動調整します。output_config: {effort: ...} で thinking 深さを制御でき、既定は high です。
• AWS（Claude in Amazon Bedrock / Claude Platform on AWS）・Google Cloud Vertex AI・Microsoft Foundry（preview）で利用できます。ただし Bedrock の legacy InvokeModel / Converse API は非対応です。

モデル比較

ユースケース別推奨

構造

Claude Sonnet 5 は単体製品ではなく API モデルです。本節では C4 model の 3 段階を「Claude Sonnet 5 を Messages API 経由で呼ぶエージェントハーネス」の論理構造として読み替えます。各段階で、移行における破断点（3 つの behavior change とトークナイザ変化）が構造上のどこで顕在化するかを位置づけます。

システムコンテキスト図

コンテナ図

コンポーネント図

リクエスト構築

送信

レスポンス処理

データ

Messages API リクエスト/レスポンスと、移行チェックリストを構成する破断点エンティティをモデル化します。

概念モデル

情報モデル

ThinkingConfig

Sonnet 5 における thinking の挙動は次のとおりです。

• type: "enabled" かつ budget_tokens 指定 → 400 エラー
• thinking 省略 / type: "adaptive" → adaptive thinking が ON
• type: "disabled" → 明示的に thinking を無効化

OutputConfig（effort とモデルの対応）

effort は output_config の中で指定します（top-level ではありません）。format は構造化出力のスキーマ定義（{type: "json_schema", schema: {...}}）です。

SamplingParams（Sonnet 5 制約）

temperature / top_p / top_k は Request のトップレベル任意パラメータです（sampling という入れ子オブジェクトは存在しません。本情報モデルでは説明上 SamplingParams としてグルーピングしています）。

ContentBlock の type 一覧

StopReason と StopDetails

stop_details（refusal 時のみ）は type（"refusal" 固定）・category（"cyber" / "bio" / "reasoning_extraction" / "frontier_llm" / null 等。値は将来拡張されうるため、特定値を列挙する前提で実装しない）・explanation（null の場合あり）を持ちます。stop_reason が refusal 以外のとき stop_details は null なので、参照前にガードします。

Usage と新トークナイザの影響

thinking 消費分は公式定義の read-only フィールド usage.output_tokens_details.thinking_tokens で確認できます。observability 用の内訳で、output_tokens 以下の値です。output_tokens から引くと応答テキスト分を概算でき、output_tokens が請求の権威値です。SDK バージョンによりアクセサが異なる場合があるため、本記事のコード例は getattr で防御的に参照します。

破断点エンティティ（BreakingPoint）

構築方法

モデル ID の変更

モデル ID は claude-sonnet-4-6 から claude-sonnet-5 に変更します。日付サフィックスの付かない dateless 形式が正式名称です（メジャー版は minor セグメントを省きます）。

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY を環境変数から読む

# 変更前: model = "claude-sonnet-4-6"
# 変更後:
model = "claude-sonnet-5"

response = client.messages.create(
    model=model,
    max_tokens=4096,
    thinking={"type": "disabled"},  # 既定 ON の adaptive を切り content[0] を text に固定
    messages=[{"role": "user", "content": "こんにちは"}],
)
print(response.content[0].text)

• SDK は anthropic Python パッケージを使います。output_config 等の新フィールドは比較的新しいリリースで追加したため、最新版を使います。
• API キーは環境変数 ANTHROPIC_API_KEY か anthropic.Anthropic(api_key="...") で渡します。
• Bedrock のモデル ID は anthropic.claude-sonnet-5（anthropic. プレフィックス付き）です。legacy InvokeModel / Converse API は非対応です。
• Vertex AI のモデル ID はプレフィックス無しの素の claude-sonnet-5 です。

移行前のトークン再計測

Sonnet 5 は新トークナイザを採用しており、同一テキストで約 30% 多くカウントします。旧モデルで計測した値を流用せず、移行先モデルで再計測します。

import anthropic

client = anthropic.Anthropic()

prompt_messages = [{"role": "user", "content": "移行前に計測したいプロンプト"}]
system_text = "あなたは役に立つアシスタントです。"

count_46 = client.messages.count_tokens(
    model="claude-sonnet-4-6", system=system_text, messages=prompt_messages,
)
count_5 = client.messages.count_tokens(
    model="claude-sonnet-5", system=system_text, messages=prompt_messages,
)
print(f"Sonnet 4.6: {count_46.input_tokens} トークン")
print(f"Sonnet 5  : {count_5.input_tokens} トークン")
print(f"増加率    : {count_5.input_tokens / count_46.input_tokens:.2f}x")

• tiktoken 等の汎用トークナイザは Claude 用ではないため使いません。公式の count_tokens エンドポイント（POST /v1/messages/count_tokens、返却は input_tokens 整数）が Claude 公式の事前見積りを返します。tiktoken より正確ですが、実送信時の値と小差が出る場合があります。
• token counting には RPM の上限があります。

利用方法

破断点パラメータ一覧

Sonnet 4.6 では動作したが Sonnet 5 で動作が変わるパラメータです。

構造化出力は本節のコード例の形（output_config.format）を使います。Python SDK には client.messages.parse() の便宜引数 output_format もありますが、Messages API の正式フィールドは output_config.format です。これは Sonnet 5 固有の変更ではありません。

adaptive thinking への移行

# Before: manual extended thinking（Sonnet 5 では 400）
# thinking={"type": "enabled", "budget_tokens": 10000}

# After: adaptive thinking + effort
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # low / medium / high(既定) / xhigh / max
    messages=[{"role": "user", "content": "複雑な問題を解いてください"}],
)
for block in response.content:
    if block.type == "thinking":
        print(f"思考: {block.thinking}")
    elif block.type == "text":
        print(f"回答: {block.text}")

thinking を完全に切る場合は {type: "disabled"} を明示します。thinking を表示したい場合は display: "summarized" を明示します。

# 最小レイテンシ（thinking 無効）
client.messages.create(
    model="claude-sonnet-5", max_tokens=4096,
    thinking={"type": "disabled"},
    messages=[{"role": "user", "content": "今日の天気は？"}],
)
# thinking を要約表示
client.messages.create(
    model="claude-sonnet-5", max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "証明してください"}],
)

sampling params 除去

# Before（Sonnet 5 では 400）
# temperature=0.7, top_p=0.9, top_k=40

# After: パラメータを除去し、system prompt で挙動を誘導する
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    system="創造的で多様な表現を使い、ユニークな視点で文章を書いてください。",
    messages=[{"role": "user", "content": "創作文を書いてください"}],
)

デフォルト値（または省略）は受理されます。非デフォルト値のみ拒否されます。

max_tokens の見直し

adaptive thinking では thinking トークンと応答テキストが max_tokens の合計上限を共有します。4.6 で thinking なし運用だった場合は thinking 分のトークンを追加で確保します。

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,   # thinking + 応答テキストの合計上限
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "..."}],
)
if response.stop_reason == "max_tokens":
    print("max_tokens に到達。上限引き上げを検討。")

• Sonnet 5 の最大出力は 128K トークン（Sonnet 4.6 と同じ）です。大きな max_tokens ではストリーミングを使い HTTP タイムアウトを避けます。

refusal を踏まえた安全な応答取得

Sonnet 5 はサイバーセキュリティ safeguards を搭載し、禁止・高リスクな要求を HTTP 200 + stop_reason: "refusal" で返します。例外キャッチでは検知できないため、stop_reason を先に確認してから content を読みます。

response = client.messages.create(
    model="claude-sonnet-5", max_tokens=4096,
    messages=[{"role": "user", "content": "..."}],
)
if response.stop_reason == "refusal":
    print("リクエストが拒否されました。内容を見直してください。")
elif response.stop_reason == "max_tokens":
    print("出力が max_tokens に達しました。上限を引き上げてください。")
else:
    text_blocks = [b for b in response.content if b.type == "text"]
    if text_blocks:
        print(text_blocks[0].text)

prefill の置換（structured outputs / output_config.format）

# Before: assistant prefill（Sonnet 4.6 でも 400、Sonnet 5 でも同様）
# messages=[..., {"role": "assistant", "content": "{"}]

# After 案1: system prompt で JSON 出力を指示
client.messages.create(
    model="claude-sonnet-5", max_tokens=4096,
    system="必ず有効な JSON のみを返してください。余分なテキストは不要です。",
    messages=[{"role": "user", "content": "ユーザー情報を JSON で返してください"}],
)

# After 案2: output_config.format で JSON スキーマを指定（structured outputs）
response = client.messages.create(
    model="claude-sonnet-5", max_tokens=4096,
    thinking={"type": "disabled"},  # content[0] を JSON text に固定（adaptive は既定 ON）
    messages=[{"role": "user", "content": "ユーザー情報を返してください"}],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
                "additionalProperties": False,
            },
        }
    },
)
import json
print(json.loads(response.content[0].text))

移行チェックリスト（実装者向け）

• モデル ID を claude-sonnet-4-6 から claude-sonnet-5 に変更
• budget_tokens 指定を thinking: {type: "adaptive"} + output_config: {effort: "..."} へ移行
• temperature / top_p / top_k の非デフォルト値指定を除去
• max_tokens を adaptive thinking 込みの合計量に見直し
• count_tokens を model="claude-sonnet-5" で再実行してコスト見積りを更新
• stop_reason チェックを先行させる安全パターンへ書き換え
• assistant prefill があれば structured outputs / output_config.format へ置換

運用

コスト再見積り

per-token 単価は Sonnet 4.6 と同じ（$3/$15 per MTok）ですが、新トークナイザにより同一テキストで約 30% 多くトークンを消費するため、等価リクエストの実コストは 4.6 より高くなります。

• 導入価格は 2026-08-31 まで $2/$10 per MTok です。
• 標準価格への切替は 2026-09-01 以降で $3/$15 です。この切替で月次コストが上昇するため、導入期間中に実トークン使用量を計測しておきます。

usage = response.usage
log = {
    "input_tokens": usage.input_tokens,
    "output_tokens": usage.output_tokens,
    "cache_read_input_tokens": getattr(usage, "cache_read_input_tokens", 0),
    "cache_creation_input_tokens": getattr(usage, "cache_creation_input_tokens", 0),
}

• cache_read_input_tokens が多いほど実コストは下がります。プロンプトキャッシュ命中率を監視して予測精度を上げます。
• 新規にトークンを計測する際は count_tokens に model: "claude-sonnet-5" を指定します。4.6 の計測値を流用すると約 30% 過小評価になります。

max_tokens 切り詰めの監視

adaptive thinking が既定 ON のため、max_tokens は「thinking トークン + 応答テキスト」の合計に対する hard limit として機能します。4.6 で thinking 無し運用だったワークロードは max_tokens が実質的に不足します。stop_reason == "max_tokens" をログで検知し、上限引き上げか effort 引き下げで対処します。

if response.stop_reason == "max_tokens":
    logger.warning("max_tokens exceeded", extra={
        "request_id": response._request_id,
        "output_tokens": response.usage.output_tokens,
    })

リトライ条件の回帰

SDK の自動リトライ対象（サーバー起因）とリトライ不可（クライアント起因）を分けて管理します。Anthropic SDK は接続エラー・408・409・429・5xx を指数バックオフで自動リトライします（既定 max_retries=2）。

Sonnet 5 で新たに 400 を返すのは 2 パターン（manual extended thinking / sampling params 非既定値）です。assistant prefill は 4.6 から継続して 400 です。いずれも自動リトライが効かないため、ハーネス起動前に CI でチェックします。

refusal 監視

拒否は HTTP 200 で返るためエラーログに現れません。stop_reason を先に評価しないと空の content をそのまま処理します。

if response.stop_reason == "refusal":
    details = getattr(response, "stop_details", None)
    category = getattr(details, "category", None) if details else None
    logger.warning("refusal", extra={"category": category, "request_id": response._request_id})
    raise RefusalError(f"Request refused: category={category}")

サイバーセキュリティ関連プロンプト（ペネトレーションテスト自動化・脆弱性スキャン等）では false positive が起こりえます。意図的なセキュリティ用途では system prompt に目的・文脈を明示して誤拒否を減らします。

ベストプラクティス

移行回帰テスト設計

Sonnet 4.6 から Sonnet 5 の移行で CI に組み込む 5 観点です。

段階移行（カナリアリリース）

全リクエストを一度に切り替えず、一定割合を並行計測します。

import random

def get_model(canary_fraction: float = 0.10) -> str:
    if random.random() < canary_fraction:
        return "claude-sonnet-5"
    return "claude-sonnet-4-6"

カナリア期間中の比較指標は、トークン数（新トークナイザの影響量を実測）・コスト（導入価格 $2/$10 と標準 $3/$15 の切替を織り込む）・品質（正解率・タスク完了率）・停止理由（stop_reason の分布）です。

観測設計

request_id・model・stop_reason・usage 各フィールド・latency_ms をログ化します。request_id はサポート問い合わせ時に即提示できます。cache_read_input_tokens が増加傾向なら prompt caching が有効に機能しています。

effort と max_tokens のチューニング

手順は次のとおりです。まず high（既定）で stop_reason == "max_tokens" の発生有無を確認します。頻発するなら上限引き上げか effort 引き下げを行います。品質不足なら xhigh に引き上げ max_tokens を確保します。low で多段推論の品質が落ちる場合は system prompt に「複数ステップの推論が必要です。応答前によく考えてください。」と追記します。

トラブルシューティング

まとめ

Claude Sonnet 5 はモデル ID を変えるだけで移行できますが、adaptive thinking 既定 ON・manual extended thinking と非既定 sampling params の 400・新トークナイザ約 30% 増という「静かに前提を壊す」変更を含みます。品質比較より先に、max_tokens・コスト見積り・リトライ条件・パラメータ禁止・refusal の 5 観点を回帰確認することが、エージェント運用での安全な移行につながります。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント（モデル / 移行）
  • What's new in Claude Sonnet 5 - Claude Platform Docs
  • Models overview - Claude Platform Docs
  • Migration guide - Claude Platform Docs
  • Introducing Claude Sonnet 5 - Anthropic
  • Pricing - Claude Platform Docs
• 公式ドキュメント（API / 機能）
  • Messages API - Claude Platform Docs
  • Adaptive thinking - Claude Platform Docs
  • Extended thinking - Claude Platform Docs
  • Effort parameter - Claude Platform Docs
  • Token counting - Claude Platform Docs
  • Structured outputs - Claude Platform Docs
  • Errors - Claude Platform Docs
  • Service tiers - Claude Platform Docs