拡張思考を使用した構築

拡張思考により、Claudeは複雑なタスクに対して強化された推論能力を備え、最終的な回答を提供する前に段階的な思考プロセスへのさまざまなレベルの透明性を提供します。

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

拡張思考は以下のモデルでサポートされています：

• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (claude-3-7-sonnet-20250219) (非推奨)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

拡張思考の仕組み

拡張思考が有効になると、Claudeは内部推論を出力するthinkingコンテンツブロックを作成します。Claudeはこの推論からの洞察を組み込んでから、最終的な応答を作成します。

APIレスポンスにはthinkingコンテンツブロックが含まれ、その後にtextコンテンツブロックが続きます。

デフォルトのレスポンス形式の例を以下に示します：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

拡張思考のレスポンス形式の詳細については、Messages APIリファレンスを参照してください。

拡張思考の使用方法

Messages APIで拡張思考を使用する例を以下に示します：

拡張思考を有効にするには、thinkingオブジェクトを追加し、typeパラメータをenabledに設定し、budget_tokensを拡張思考の指定されたトークン予算に設定します。

budget_tokensパラメータは、Claudeが内部推論プロセスに使用できる最大トークン数を決定します。Claude 4モデルでは、この制限は完全な思考トークンに適用され、要約された出力には適用されません。より大きな予算は、複雑な問題に対してより徹底的な分析を可能にすることで応答品質を向上させることができますが、Claudeは割り当てられた予算全体を使用しない場合があります。特に32k以上の範囲では使用しない場合があります。

budget_tokensはmax_tokensより小さい値に設定する必要があります。ただし、ツールを使用したインターリーブ思考を使用する場合、トークン制限がコンテキストウィンドウ全体（200kトークン）になるため、この制限を超えることができます。

要約された思考

拡張思考が有効になると、Claude 4モデルのMessages APIはClaudeの完全な思考プロセスの要約を返します。要約された思考は、拡張思考の完全な知能上の利点を提供しながら、悪用を防ぎます。

要約された思考に関する重要な考慮事項を以下に示します：

• 要約トークンではなく、元のリクエストによって生成された完全な思考トークンに対して課金されます。
• 請求される出力トークン数は、レスポンスに表示されるトークン数と一致しません。
• 思考出力の最初の数行はより詳細で、プロンプトエンジニアリングの目的に特に役立つ詳細な推論を提供します。
• Anthropicが拡張思考機能を改善しようとしているため、要約動作は変更される可能性があります。
• 要約は、Claudeの思考プロセスの重要なアイデアを最小限の追加レイテンシで保持し、ストリーム可能なユーザーエクスペリエンスとClaude Sonnet 3.7からClaude 4モデルへの簡単な移行を可能にします。
• 要約は、リクエストで対象とするモデルとは異なるモデルによって処理されます。思考モデルは要約された出力を見ません。

ストリーミング思考

サーバー送信イベント（SSE）を使用して拡張思考レスポンスをストリーミングできます。

拡張思考でストリーミングが有効になると、thinking_deltaイベントを介して思考コンテンツを受け取ります。

Messages APIを介したストリーミングの詳細については、ストリーミングメッセージを参照してください。

思考を使用したストリーミングの処理方法を以下に示します：

ストリーミング出力の例：

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-5", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

ツール使用を伴う拡張思考

拡張思考はツール使用と一緒に使用でき、Claudeがツール選択と結果処理を通じて推論することができます。

ツール使用を伴う拡張思考を使用する場合、以下の制限に注意してください：

1. ツール選択の制限：思考を伴うツール使用はtool_choice: {"type": "auto"}（デフォルト）またはtool_choice: {"type": "none"}のみをサポートします。tool_choice: {"type": "any"}またはtool_choice: {"type": "tool", "name": "..."}を使用するとエラーが発生します。これらのオプションはツール使用を強制するため、拡張思考と互換性がありません。

2. 思考ブロックの保持：ツール使用中に、最後のアシスタントメッセージのthinkingブロックをAPIに戻す必要があります。推論の連続性を維持するために、完全な未修正ブロックをAPIに戻してください。

会話での思考モードの切り替え

アシスタントターンの途中（ツール使用ループ中を含む）で思考を切り替えることはできません。アシスタントターン全体は単一の思考モードで動作する必要があります：

• 思考が有効な場合、最終的なアシスタントターンは思考ブロックで始まる必要があります。
• 思考が無効な場合、最終的なアシスタントターンは思考ブロックを含まない必要があります

モデルの観点から、ツール使用ループはアシスタントターンの一部です。アシスタントターンは、Claudeが完全な応答を完了するまで完了しません。これには複数のツール呼び出しと結果が含まれる場合があります。

例えば、このシーケンスはすべて単一のアシスタントターンの一部です：

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

複数のAPIメッセージがありますが、ツール使用ループは概念的には1つの継続的なアシスタント応答の一部です。

一般的なエラーシナリオ

このエラーが発生する場合があります：

Expected `thinking` or `redacted_thinking`, but found `tool_use`.
When `thinking` is enabled, a final `assistant` message must start
with a thinking block (preceding the lastmost set of `tool_use` and
`tool_result` blocks).

これは通常、以下の場合に発生します：

1. ツール使用シーケンス中に思考が無効だった
2. 思考を再度有効にしたい
3. 最後のアシスタントメッセージに思考ブロックなしのツール使用ブロックが含まれている

実用的なガイダンス

✗ 無効：ツール使用直後に思考を切り替える

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
// Cannot enable thinking here - still in the same assistant turn

✓ 有効：最初にアシスタントターンを完了する

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"] 
User: "What about tomorrow?" (thinking disabled)
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

ベストプラクティス：ターン中に切り替えようとするのではなく、各ターンの開始時に思考戦略を計画してください。

思考ブロックの保持

ツール使用中に、thinkingブロックをAPIに戻す必要があり、完全な未修正ブロックをAPIに戻す必要があります。これはモデルの推論フローと会話の整合性を維持するために重要です。

Claudeがツールを呼び出すとき、それは外部情報を待つために応答の構築を一時停止しています。ツール結果が返されると、Claudeはその既存の応答の構築を続けます。これにより、ツール使用中に思考ブロックを保持する必要があります。理由は2つあります：

1. 推論の連続性：思考ブロックはツール要求につながったClaudeのステップバイステップの推論をキャプチャします。ツール結果を投稿するとき、元の思考を含めることで、Claudeは中断したところから推論を続けることができます。

2. コンテキストの維持：ツール結果はAPI構造ではユーザーメッセージとして表示されますが、継続的な推論フローの一部です。思考ブロックを保持することで、複数のAPI呼び出しにわたってこの概念的なフローを維持します。コンテキスト管理の詳細については、コンテキストウィンドウに関するガイドを参照してください。

重要：thinkingブロックを提供する場合、連続したthinkingブロックのシーケンス全体は、元のリクエスト中にモデルによって生成された出力と一致する必要があります。ブロックのシーケンスを再配置または変更することはできません。

インターリーブ思考

Claude 4モデルでのツール使用を伴う拡張思考は、インターリーブ思考をサポートしており、これによってClaudeはツール呼び出し間で思考し、ツール結果を受け取った後、より高度な推論を行うことができます。

インターリーブ思考により、Claudeは以下のことができます：

• ツール呼び出しの結果について推論し、次に何をするかを決定する
• 複数のツール呼び出しを推論ステップでチェーンする
• 中間結果に基づいてより微妙な決定を下す

インターリーブ思考を有効にするには、ベータヘッダー interleaved-thinking-2025-05-14 をAPIリクエストに追加してください。

インターリーブ思考に関する重要な考慮事項は以下の通りです：

• インターリーブ思考では、budget_tokens が max_tokens パラメータを超える可能性があります。これは1つのアシスタントターン内のすべての思考ブロック全体の予算を表しているためです。
• インターリーブ思考は Messages APIを介して使用されるツール に対してのみサポートされています。
• インターリーブ思考はClaude 4モデルのみでサポートされており、ベータヘッダー interleaved-thinking-2025-05-14 が必要です。
• Claude APIへの直接呼び出しでは、interleaved-thinking-2025-05-14 をリクエストに渡すことができ、どのモデルでも効果はありません。
• サードパーティプラットフォーム（例：Amazon Bedrock および Vertex AI）では、Claude Opus 4.5、Claude Opus 4.1、Opus 4、またはSonnet 4以外のモデルに interleaved-thinking-2025-05-14 を渡すと、リクエストは失敗します。

プロンプトキャッシングを伴う拡張思考

プロンプトキャッシング と思考にはいくつかの重要な考慮事項があります：

思考ブロックコンテキスト削除

• 前のターンからの思考ブロックはコンテキストから削除されます。これはキャッシュブレークポイントに影響を与える可能性があります
• ツール使用で会話を続ける場合、思考ブロックはキャッシュされ、キャッシュから読み取られるときに入力トークンとしてカウントされます
• これはトレードオフを生み出します：思考ブロックは視覚的にはコンテキストウィンドウスペースを消費しませんが、キャッシュされるときは入力トークン使用量にカウントされます
• 思考が無効になった場合、現在のツール使用ターンで思考コンテンツを渡すとリクエストは失敗します。他のコンテキストでは、APIに渡された思考コンテンツは単に無視されます

キャッシュ無効化パターン

• 思考パラメータの変更（有効/無効または予算配分）はメッセージキャッシュブレークポイントを無効化します
• インターリーブ思考 はキャッシュ無効化を増幅します。思考ブロックは複数の ツール呼び出し 間で発生する可能性があるためです
• システムプロンプトとツールは思考パラメータの変更またはブロック削除にもかかわらずキャッシュされたままです

思考ブロックキャッシング動作の理解

ツール使用を伴う拡張思考を使用する場合、思考ブロックはトークンカウントに影響を与える特定のキャッシング動作を示します：

動作方法：

1. キャッシングは、ツール結果を含む後続のリクエストを行う場合にのみ発生します
2. 後続のリクエストが行われると、前の会話履歴（思考ブロックを含む）がキャッシュされる可能性があります
3. これらのキャッシュされた思考ブロックは、キャッシュから読み取られるときの使用メトリクスで入力トークンとしてカウントされます
4. 非ツール結果ユーザーブロックが含まれる場合、すべての前の思考ブロックは無視され、コンテキストから削除されます

詳細な例フロー：

リクエスト1：

User: "What's the weather in Paris?"

応答1：

[thinking_block_1] + [tool_use block 1]

リクエスト2：

User: ["What's the weather in Paris?"], 
Assistant: [thinking_block_1] + [tool_use block 1], 
User: [tool_result_1, cache=True]

応答2：

[thinking_block_2] + [text block 2]

リクエスト2はリクエストコンテンツのキャッシュを書き込みます（応答ではなく）。キャッシュには、元のユーザーメッセージ、最初の思考ブロック、ツール使用ブロック、およびツール結果が含まれます。

リクエスト3：

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

Claude Opus 4.5以降の場合、すべての前の思考ブロックはデフォルトで保持されます。古いモデルの場合、非ツール結果ユーザーブロックが含まれたため、すべての前の思考ブロックは無視されます。このリクエストは以下と同じように処理されます：

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

重要なポイント：

• このキャッシング動作は自動的に発生します。明示的な cache_control マーカーがなくても発生します
• この動作は通常の思考またはインターリーブ思考を使用しているかどうかに関係なく一貫しています

拡張思考を伴う最大トークンとコンテキストウィンドウサイズ

古いClaudeモデル（Claude Sonnet 3.7より前）では、プロンプトトークンと max_tokens の合計がモデルのコンテキストウィンドウを超えた場合、システムは自動的に max_tokens を調整してコンテキスト制限内に収まるようにしていました。これは大きな max_tokens 値を設定でき、システムが必要に応じて自動的に削減することを意味していました。

Claude 3.7および4モデルでは、max_tokens（思考が有効な場合は思考予算を含む）は厳密な制限として適用されます。システムは、プロンプトトークン + max_tokens がコンテキストウィンドウサイズを超える場合、検証エラーを返すようになりました。

拡張思考を伴うコンテキストウィンドウ

思考が有効な場合のコンテキストウィンドウ使用量を計算する場合、注意すべき考慮事項があります：

• 前のターンからの思考ブロックは削除され、コンテキストウィンドウにカウントされません
• 現在のターンの思考はそのターンの max_tokens 制限にカウントされます

以下の図は、拡張思考が有効な場合の特殊なトークン管理を示しています：

有効なコンテキストウィンドウは以下のように計算されます：

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

特に思考を含むマルチターン会話を扱う場合、トークンカウントAPI を使用して、特定のユースケースの正確なトークンカウントを取得することをお勧めします。

拡張思考とツール使用を伴うコンテキストウィンドウ

ツール使用を伴う拡張思考を使用する場合、思考ブロックは明示的に保持され、ツール結果と共に返される必要があります。

ツール使用を伴う拡張思考の有効なコンテキストウィンドウ計算は以下のようになります：

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

以下の図は、ツール使用を伴う拡張思考のトークン管理を示しています：

拡張思考を伴うトークン管理

拡張思考Claude 3.7および4モデルのコンテキストウィンドウと max_tokens 動作を考慮すると、以下が必要になる場合があります：

• トークン使用量をより積極的に監視および管理する
• プロンプト長が変わるにつれて max_tokens 値を調整する
• トークンカウントエンドポイント をより頻繁に使用する可能性がある
• 前の思考ブロックがコンテキストウィンドウに蓄積しないことに注意する

この変更は、特に最大トークン制限が大幅に増加したため、より予測可能で透明性のある動作を提供するために行われました。

思考暗号化

完全な思考コンテンツは暗号化され、signature フィールドで返されます。このフィールドは、思考ブロックがClaudeによって生成されたことを確認するために、APIに渡される場合に使用されます。

思考暗号化に関する重要な考慮事項は以下の通りです：

• ストリーミング応答 時、署名は content_block_stop イベントの直前に content_block_delta イベント内の signature_delta を介して追加されます。
• signature 値はClaude 4モデルでは前のモデルよりも大幅に長くなります。
• signature フィールドは不透明なフィールドであり、解釈または解析されるべきではありません。検証目的のためにのみ存在します。
• signature 値はプラットフォーム間で互換性があります（Claude API、Amazon Bedrock、および Vertex AI）。1つのプラットフォームで生成された値は別のプラットフォームと互換性があります。

思考の編集

時々、Claudeの内部推論が当社のセーフティシステムによってフラグが立てられることがあります。これが発生した場合、thinkingブロックの一部またはすべてを暗号化し、redacted_thinkingブロックとして返します。redacted_thinkingブロックはAPIに渡されるときに復号化され、Claudeがコンテキストを失わずに応答を続けることができます。

拡張思考を使用する顧客向けアプリケーションを構築する場合：

• redacted_thinkingブロックには、人間が読める形式ではない暗号化されたコンテンツが含まれていることに注意してください
• 「Claudeの内部推論の一部は安全上の理由から自動的に暗号化されています。これは応答の品質に影響しません。」のような簡単な説明を提供することを検討してください
• 思考ブロックをユーザーに表示する場合、通常の思考ブロックを保持しながら、編集されたブロックをフィルタリングできます
• 拡張思考機能を使用すると、推論の一部が暗号化される可能性があることを透過的に伝えてください
• redacted_thinkingを適切に処理し、UIを破壊しないようにするための適切なエラーハンドリングを実装してください

以下は、通常の思考ブロックと編集された思考ブロックの両方を示す例です：

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

マルチターン会話でAPIにthinkingおよびredacted_thinkingブロックを渡す場合、最後のアシスタントターンの完全な未修正ブロックをAPIに含める必要があります。これはモデルの推論フローを維持するために重要です。すべての思考ブロックをAPIに渡すことをお勧めします。詳細については、上記の思考ブロックの保持セクションを参照してください。

モデルバージョン間での思考の違い

Messages APIは、Claude Sonnet 3.7とClaude 4モデル間で思考を異なる方法で処理し、主に編集と要約の動作が異なります。

以下の表で簡潔な比較を参照してください：

Claude Opus 4.5での思考ブロック保持

Claude Opus 4.5は新しいデフォルト動作を導入します：前のアシスタントターンからの思考ブロックはデフォルトでモデルコンテキストに保持されます。これは、前のターンから思考ブロックを削除する以前のモデルとは異なります。

思考ブロック保持の利点：

• キャッシュ最適化：ツール使用を使用する場合、保持された思考ブロックはツール結果とともに渡され、アシスタントターン全体でインクリメンタルにキャッシュされるため、キャッシュヒットが可能になり、マルチステップワークフローでトークンが節約されます
• インテリジェンスへの影響なし：思考ブロックの保持はモデルのパフォーマンスに悪影響を与えません

重要な考慮事項：

• コンテキスト使用量：思考ブロックがコンテキストに保持されるため、長い会話はより多くのコンテキストスペースを消費します
• 自動動作：これはClaude Opus 4.5のデフォルト動作です。コード変更またはベータヘッダーは必要ありません
• 後方互換性：この機能を活用するには、ツール使用の場合と同じように、完全な未修正思考ブロックをAPIに渡し続けてください

価格設定

基本料金、キャッシュ書き込み、キャッシュヒット、出力トークンを含む完全な価格情報については、価格ページを参照してください。

思考プロセスは以下に対して料金が発生します：

• 思考中に使用されるトークン（出力トークン）
• 後続のリクエストに含まれる最後のアシスタントターンからの思考ブロック（入力トークン）
• 標準テキスト出力トークン

要約された思考を使用する場合：

• 入力トークン：元のリクエスト内のトークン（前のターンからの思考トークンを除外）
• 出力トークン（請求対象）：Claudeが内部的に生成した元の思考トークン
• 出力トークン（表示）：応答に表示される要約された思考トークン
• 請求なし：要約を生成するために使用されるトークン

拡張思考のベストプラクティスと考慮事項

思考予算の操作

• **予算最適化：**最小予算は1,024トークンです。最小値から始めて、思考予算を段階的に増やして、ユースケースに最適な範囲を見つけることをお勧めします。トークン数が多いほど、より包括的な推論が可能になりますが、タスクに応じて収益が減少します。予算を増やすと応答品質が向上する可能性がありますが、レイテンシが増加するというトレードオフがあります。重要なタスクの場合、異なる設定をテストして最適なバランスを見つけてください。思考予算はターゲットであり、厳密な制限ではないことに注意してください。実際のトークン使用量はタスクに基づいて異なる場合があります。
• **開始点：**複雑なタスクの場合は大きな思考予算（16k以上のトークン）から始めて、必要に応じて調整してください。
• **大きな予算：**思考予算が32kを超える場合、ネットワークの問題を回避するためにバッチ処理を使用することをお勧めします。モデルを32kトークン以上で思考させるリクエストは、システムタイムアウトとオープン接続制限に対して実行される可能性のある長時間実行リクエストを引き起こします。
• **トークン使用量追跡：**思考トークン使用量を監視して、コストとパフォーマンスを最適化してください。

パフォーマンスに関する考慮事項

• **応答時間：**推論プロセスに必要な追加処理により、応答時間が長くなる可能性があることに備えてください。思考ブロックの生成により、全体的な応答時間が増加する可能性があることを考慮してください。
• ストリーミング要件：max_tokensが21,333より大きい場合、ストリーミングが必要です。ストリーミング時は、思考とテキストコンテンツブロックの両方が到着するときに処理する準備をしてください。

機能の互換性

• 思考はtemperatureまたはtop_kの変更、および強制ツール使用と互換性がありません。
• 思考が有効になっている場合、top_pを1から0.95の間の値に設定できます。
• 思考が有効になっている場合、応答を事前入力することはできません。
• 思考予算への変更は、メッセージを含むキャッシュされたプロンプトプレフィックスを無効にします。ただし、キャッシュされたシステムプロンプトとツール定義は、思考パラメータが変更されても機能し続けます。

使用ガイドライン

• **タスク選択：**数学、コーディング、分析など、ステップバイステップの推論から利益を得る特に複雑なタスクに拡張思考を使用してください。
• **コンテキスト処理：**前の思考ブロックを自分で削除する必要はありません。Claude APIは自動的に前のターンからの思考ブロックを無視し、コンテキスト使用量を計算するときに含まれません。
• **プロンプトエンジニアリング：**Claudeの思考機能を最大化したい場合は、拡張思考プロンプティングのヒントを確認してください。

次のステップ