Claude Platform Docs
Messages思考

拡張思考

拡張思考をサポートするClaudeモデルで、固定のbudget_tokens予算を使用した手動の拡張思考を設定し、アダプティブ思考へ移行する方法について説明します。

手動モードの「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 は引き続き総出力のハードな上限です。

effortをサポートする唯一の拡張思考専用モデルであるClaude Opus 4.5では、effortがレスポンス全体を形作り、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モデル（Claude Opus 4.1、Claude Opus 4、Claude Sonnet 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つの考慮事項があります。

プラットフォームによるベータヘッダーの扱いは異なります。Claude APIとClaude Platform on AWSは、どのモデルでも interleaved-thinking-2025-05-14 を受け入れ、サポートされていない場合は無視します。受け入れられることは効果があることと同じではありません。type: "enabled" を拒否するモデル（4.7以降）や手動モードのインターリーブを持たないモデル（Claude Opus 4.6）では、ヘッダーは手動モードでは効果がありません。そこではアダプティブ思考が自動的にインターリーブします。

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

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

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

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

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

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

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

Output
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 が果たすキャッシュ上の役割をeffortレベルが果たすアダプティブモードでの同じ実験の実行可能なバージョンについては、ステアリングページのプロンプトキャッシングを参照してください。

共通の仕組み

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

アダプティブ思考への移行

お使いのモデルが拡張思考のみをサポートしている場合（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 Opus 4.7、Claude Opus 4.8、Claude Opus 5、Claude Sonnet 5、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、またはClaude Mythos 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"
  }
}

effort: "high" はAPIのデフォルトと一致します。ここでは深さの制御が現在どこにあるかを示すためだけに記載しており、省略しても同じ動作になります。

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

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

完全なガイダンスについては、アダプティブ思考、effort、およびモデル移行ガイドを参照してください。

次のステップ

思考

思考の仕組み（ブロック、表示、ストリーミング、ツール使用）について学びます。

思考のステアリング

各リクエストでいつ、どれだけ思考するかをClaudeに決定させます。

ツールおよびマルチターンワークフローでの思考

思考ブロックを保持し、ツール呼び出しやターンをまたいで思考を管理します。

Was this page helpful?