拡張思考を使用した構築

拡張思考により、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.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 で拡張思考を使用する例を次に示します：

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "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?"
        }
    ]
}'

拡張思考を有効にするには、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 経由のストリーミングに関する詳細なドキュメントについては、ストリーミングメッセージを参照してください。

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-sonnet-4-5",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}'

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

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 は中断したところから推論を続けることができます。

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

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

インターリーブ思考

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

インターリーブ思考により、Claude は以下を実行できます：

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

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

インターリーブ思考に関する重要な考慮事項を次に示します：

• インターリーブ思考では、budget_tokens は max_tokens パラメータを超える可能性があります。これは 1 つのアシスタントターン内のすべての思考ブロック全体の総予算を表すためです。
• インターリーブ思考は Messages API 経由で使用されるツールに対してのみサポートされています。
• インターリーブ思考は Claude 4 モデルに対してのみサポートされており、ベータヘッダー interleaved-thinking-2025-05-14 が必要です。
• Claude API への直接呼び出しにより、interleaved-thinking-2025-05-14 をリクエストの任意のモデルに渡すことができ、効果はありません。
• 3 番目のプラットフォーム（例：Amazon Bedrock および Vertex AI）では、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]

非ツール結果ユーザーブロックが含まれているため、すべての以前の思考ブロックは無視されます。このリクエストは以下と同じように処理されます：

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 マーカーがなくても自動的に発生します
• この動作は、通常の思考またはインターリーブ思考を使用しているかどうかに関係なく一貫しています

拡張思考を使用した max_tokens とコンテキストウィンドウサイズ

古い 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 がコンテキストを失わずに応答を続けることができます。

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

• 編集された思考ブロックには、人間が読めない暗号化されたコンテンツが含まれていることに注意してください
• 「Claude の内部推論の一部は安全上の理由から自動的に暗号化されています。これは応答の品質に影響しません」のような簡単な説明を提供することを検討してください
• 思考ブロックをユーザーに表示する場合、通常の思考ブロックを保持しながら編集されたブロックをフィルタリングできます
• 拡張思考機能を使用すると、推論が暗号化される場合があることを透過的にしてください
• 編集された思考を 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..."
    }
  ]
}

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

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

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

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

価格

拡張思考は標準的なトークン価格スキームを使用します：

思考プロセスは以下に対して課金されます：

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

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

• 入力トークン: 元のリクエストのトークン（前のターンからの思考トークンを除外）
• 出力トークン（課金）: Claude が内部的に生成した元の思考トークン
• 出力トークン（表示）: レスポンスに表示される要約された思考トークン
• 課金なし: 要約を生成するために使用されるトークン

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

思考予算の使用

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

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

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

機能の互換性

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

使用ガイドライン

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

次のステップ