拡張思考

手動モードの「extended thinking」（拡張思考）では、Claudeがどれだけ思考するかを直接制御できます。各リクエストで thinking: {type: "enabled", budget_tokens: N} を使用して思考トークン予算を設定すると、Claudeは最終的な回答を開始する前にその予算に対して思考します。手動モードは、ワークロードが予測可能なレイテンシや思考コストの正確な制御を必要とする場合に引き続き有用です。このページでは、予算の設定と調整方法、手動モードがインターリーブ思考および「prompt caching」（プロンプトキャッシング）とどのように相互作用するか、そして適応型思考への移行方法について説明します。

思考ブロックとレスポンスの形状、display パラメータ、ストリーミング、ツール使用を伴う思考、暗号化など、思考そのものの仕組みについては、思考の概要を参照してください。

サポートされているモデル

拡張思考が唯一のモードであるモデルを含め、各モデルにおける拡張思考の利用可否は、モデルごとの設定表に記載されています。

拡張思考の使用方法

以下は、Messages APIで拡張思考を使用する例です。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# レスポンスには要約された思考ブロックとテキストブロックが含まれます
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

手動の拡張思考を有効にするには、type を enabled に設定し、budget_tokens の値を指定した thinking オブジェクトを追加します。

budget_tokensパラメータは、Claudeが内部の推論プロセスに使用できるトークン数の目標を設定します。予算を大きくすると、複雑な問題に対してより徹底的な分析が可能になり、応答の品質が向上する場合があります。

予算のルールと調整

budget_tokens は以下の制約を満たす必要があります。

• 最小1,024トークン。 APIはこれより小さい値を拒否します。
• max_tokens未満。 思考トークンはそのターンのmax_tokensの上限にカウントされるため、予算は最終的な応答のための余地を残す必要があります。唯一の例外は手動モードでのインターリーブ思考で、この場合、予算は1つのアシスタントターン内のすべての思考ブロックにまたがるため、budget_tokensはmax_tokensを超えることができます。
• キャッシュの事前ウォーミングは不可。 budget_tokens は max_tokens 未満でなければならないため、拡張思考を max_tokens: 0（キャッシュの事前ウォーミング）と組み合わせることはできません。

予算は厳密な上限ではなく目標です。実際のトークン使用量はタスクによって異なり、Claudeは予算を使い切るずっと前に推論を停止する場合があります。max_tokensは引き続き総出力に対する厳密な上限です。

エフォートをサポートする唯一の拡張思考専用モデルであるClaude Opus 4.5では、エフォートは応答全体を形作るのに対し、budget_tokensは思考の深さを設定します。両方を設定してください。

予算を調整するには、以下のようにします。

• 出発点をタスクに合わせます。単純なタスクでは、最小値の1,024トークン付近から始め、段階的に増やしてユースケースに最適な範囲を見つけます。複雑なタスクでは、16,000トークン以上の大きな予算から始め、レイテンシと品質のニーズに合わせて調整します。予算を大きくするとより包括的な推論が可能になりますが、その効果はタスクに応じて逓減し、レイテンシの増加という代償を伴います。重要なタスクでは、さまざまな設定をテストして適切なバランスを見つけてください。
• 32kを超える思考予算では、ネットワークの問題を避けるためにバッチ処理を使用してください。モデルに32kトークンを超えて思考させると、長時間実行されるリクエストが発生し、システムのタイムアウトやオープン接続数の制限に達する可能性があります。

予算が実際にどれだけのコストになるかを追跡するには、レスポンスの usage.output_tokens_details.thinking_tokens フィールドを監視してください。このフィールドは、課金された出力トークンのうち内部推論に使われた数を報告します。ストリーミング時には、この内訳は最後の message_delta イベントにのみ表示されます。

手動予算から移行する準備ができたら、適応型思考への移行を参照してください。

手動モードでのインターリーブ思考

「interleaved thinking」（インターリーブ思考）を使用すると、Claudeは1つのアシスタントターン内でツール呼び出しの間に思考し、次に何をするかを決定する前に各ツール結果について推論できます。概念、ターン構造、および適応型思考モデルでの動作については、思考の概要のインターリーブ思考を参照してください。このセクションでは、手動の type: "enabled" 思考を使用する場合に有効にする方法について説明します。

Claude Opus 4.5、Claude Sonnet 4.5（非推奨）、およびそれ以前のClaude 4モデルでは、APIリクエストに interleaved-thinking-2025-05-14 ベータヘッダーを追加してください。

4.6世代は手動モードで分かれます。

• Claude Sonnet 4.6：手動の type: "enabled" とベータヘッダーの組み合わせは引き続き機能しますが、非推奨です。ヘッダーなしで自動的にインターリーブする適応型思考を推奨します。
• Claude Opus 4.6：手動モードにはインターリーブ思考がまったくありません。アダプティブモードのみがインターリーブするため、このモデルでツール呼び出し間の推論が必要な場合は thinking: {type: "adaptive"} に切り替えてください。

Claude Haiku 4.5はインターリーブ思考をサポートしていません。Claude APIでは、ベータヘッダーは受け入れられますが無視されます。

手動モードでのインターリーブ思考に関するさらに2つの考慮事項があります。

• ここでは budget_tokens が max_tokens を超えることができます。この例外については予算のルールで説明しています。
• インターリーブ思考は、Messages APIを通じて使用されるツールでのみサポートされています。

ベータヘッダーの扱いはプラットフォームによって異なります。Claude API、Claude Platform on AWS、およびClaude Models on Google Cloud (Anthropic managed)は、任意のモデルでinterleaved-thinking-2025-05-14を受け付け、サポートされていない場合は無視します。受け付けられることと効果があることは同じではありません。type: "enabled"を拒否するモデル（4.7以降）や、手動モードのインターリーブをサポートしていないモデル（Claude Opus 4.6）では、このヘッダーは手動モードに対して何の効果も持ちません。これらのモデルでは、適応型思考が自動的にインターリーブを行います。

パートナーが運営するプラットフォームであるClaude Models on Google Cloud (Google managed)およびAmazon Bedrockも同様に、どのモデルでもエラーを返すことなくこのヘッダーを受け入れ、interleaved thinking（インターリーブ思考）をサポートしていないモデルではこれを無視します。

手動モードでのターン構造

単一ターンのツール使用ループ、ターン途中の競合処理、ターン間での思考の切り替えなど、一般的なターン構造のルールは、ツール使用を伴う思考に記載されています。

手動モードでは要件が1つ追加されます。思考が有効なリクエストの最後のアシスタントターンは、思考ブロックで始まる必要があります（適応型思考ではこの要件はありません）。また、ターン間で思考の設定を変更すると、プロンプトキャッシングが無効になります。次のセクションを参照してください。

手動モードでのプロンプトキャッシング

手動モードでは、思考とプロンプトキャッシングで説明されているモードに依存しないキャッシング動作に加えて、1つのルールが追加されます。リクエスト間で budget_tokens を変更すると、思考モードを切り替えた場合と同様にキャッシュブレークポイントが無効になります。これは予算の値がプロンプトにレンダリングされるためです。メッセージレベルのブレークポイントは予算変更後に常にミスします。ツールおよびシステムプロンプトのブレークポイントもミスするかどうかは、モデルが設定をどこにレンダリングするかによって異なります。

実際には、予算を選んだら、キャッシュされた会話の存続期間中はそれを安定して保持してください。Claude Sonnet 4.6でメッセージレベルのキャッシングを使用してマルチターンの会話を実行し、3番目のリクエストで予算を4,000トークンから8,000トークンに変更すると、無効化が直接確認できます。

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

3番目のリクエストは、リクエスト間で予算が変更されたため、キャッシュを再作成します（cache_creation_input_tokens=1370、cache_read_input_tokens=0）。ここで budget_tokens が果たすキャッシュ上の役割をエフォートレベルが果たすアダプティブモードでの同じ実験の実行可能なバージョンについては、ステアリングページのプロンプトキャッシングを参照してください。

共通の仕組み

思考の動作のほとんどはモードに依存せず、思考ページに一度だけ記載されています。そこに記載されている内容はすべて手動モードにも適用されます。

• 思考の表示の制御
• 思考のストリーミング
• ツール使用を伴う思考（思考ブロックの保持を含む）
• 思考とプロンプトキャッシング
• 思考とコンテキストウィンドウ
• 思考の暗号化
• 料金（思考のステアリングページ内）

適応型思考への移行

お使いのモデルが拡張思考のみをサポートしている場合（Claude Sonnet 4.5（非推奨）、Claude Opus 4.5、Claude Haiku 4.5、およびそれ以前のClaude 4モデル）、現時点で対応は必要ありません。これらのモデルでは適応型思考は利用できず、type: "adaptive" は400エラーを返します。適応型思考をサポートするモデルに移行するまでは budget_tokens を使い続け、移行時に以下の対応関係を適用してください。

以下の場合は type: "enabled" から移行する必要があります。

• budget_tokens が非推奨となっているClaude Opus 4.6またはClaude Sonnet 4.6を使用している場合。
• type: "enabled" が400エラーを返すClaude 4.7以降のモデル（Claude Opus 5.5、Claude Sonnet 5、Claude Sonnet 5.5、Claude Fable 5.1、Claude Haiku 5.5など）を使用している場合。

マッピングは小規模です。budget_tokens を削除し、thinking: {type: "adaptive"} を設定し、トークン予算の代わりに output_config: {effort: ...} で推論の深さを制御します。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

これは次のようになります。

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

Claude Sonnet 4.6では effort: "high" がデフォルトであるため、ここで省略しても動作は同じです。これは、アダプティブモードで深さの制御がどこにあるかを示すためだけに記載しています。Claude Opus 5.5とClaude Haiku 5.5のデフォルトは "medium" で、エフォートをサポートするその他のモデルのデフォルトは "high" です（エフォートレベルを参照）。

構文の変更だけでなく、動作の違いも想定してください。固定予算の場合、Claudeはすべてのリクエストで思考します。適応型思考の場合、Claudeは各リクエストで思考するかどうか、またどれだけ思考するかを判断し、低いエフォート設定では簡単な入力に対して思考を完全にスキップする場合があります。移行後はinterleaved-thinking-2025-05-14ベータヘッダーを削除することもできます。適応型思考は自動的にインターリーブし、Claude APIはこれらのモデルでヘッダーを無視します。思考ブロックの保持も変わります。Claude Opus 4.5および4.6以上の番号のモデルは、以前のターンの思考ブロックをコンテキストに保持して入力として課金しますが、Claude Sonnet 4.5（非推奨）、Claude Haiku 4.5、およびそれ以前のモデルはそれらを除去します。モデルごとの思考ブロックの保持を参照してください。

モードの切り替えは思考設定の変更であるため、手動モードでのプロンプトキャッシングで説明されているように、切り替え後の最初のリクエストはキャッシュブレークポイントを無効にします。

完全なガイダンスについては、適応型思考、エフォート、およびモデル移行ガイドを参照してください。

次のステップ

利用可能状況

拡張思考は一部のモデルで利用可能または非推奨です。

APIサポート