拡張思考

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



対応モデル

拡張思考は、現在のすべてのClaudeモデルで利用可能です。有効化の方法はモデルによって異なります。

適応型思考では、モデルが各リクエストでいつ、どの程度思考するかを決定します。Claude Mythos Preview、Claude Fable 5、Claude Mythos 5では、thinking: {type: "disabled"}はサポートされていません。モデルごとの動作の違い（思考出力、インターリーブ思考、ブロックの保持）については、モデルバージョン間の思考の違いを参照してください。



拡張思考の仕組み

拡張思考が有効になっている場合、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で拡張思考を使用する例を以下に示します。

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:
    if block.type == "thinking":
        print(f"\nThinking summary: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

拡張思考を有効にするには、typeをenabledに設定し、budget_tokens値を指定したthinkingオブジェクトを追加します。手動拡張思考が非推奨または非対応のモデル（対応モデルを参照）では、適応型思考で説明されているように、代わりにtype: "adaptive"を使用してください。

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

budget_tokensはmax_tokensより小さい値に設定する必要があります。ただし、ツールとのインターリーブ思考を使用する場合は、トークン制限がコンテキストウィンドウ全体になるため、この制限を超えることができます。budget_tokensはmax_tokensより小さくなければならないため、拡張思考はmax_tokens: 0（キャッシュの事前ウォーミング）と組み合わせることはできません。



思考表示の制御

thinking設定のdisplayフィールドは、APIレスポンスで思考コンテンツがどのように返されるかを制御します。次の2つの値を受け付けます。

• "summarized"：思考ブロックには要約された思考テキストが含まれます。詳細については要約された思考を参照してください。これはClaude Opus 4.6、Claude Sonnet 4.6、およびそれ以前のClaude 4モデルでのデフォルトです。
• "omitted"：思考ブロックは空のthinkingフィールドとともに返されます。signatureフィールドには、マルチターンの継続性のために暗号化された完全な思考が引き続き含まれます（思考の暗号化を参照）。これはClaude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7、およびClaude Mythos Previewでのデフォルトです。

display: "omitted"の設定は、アプリケーションが思考コンテンツをユーザーに表示しない場合に便利です。主な利点は、ストリーミング時の最初のテキストトークンまでの時間が短縮されることです。サーバーは思考トークンのストリーミングを完全にスキップし、署名のみを配信するため、最終的なテキストレスポンスのストリーミングがより早く開始されます。

省略された思考に関する重要な考慮事項は次のとおりです。

• 完全な思考トークンに対して引き続き課金されます。省略によって削減されるのはレイテンシであり、コストではありません。
• マルチターンの会話で思考ブロックを返す場合は、変更せずにそのまま渡してください。サーバーはsignatureを復号してプロンプト構築のために元の思考を再構成します（思考ブロックの保持を参照）。ラウンドトリップされた省略ブロックのthinkingフィールドに配置したテキストはすべて無視されます。
• displayはthinking.type: "disabled"と組み合わせて使用することはできません（表示するものがないため）。
• thinking.type: "adaptive"を使用していて、モデルが単純なリクエストに対して思考をスキップした場合、displayの値に関係なく思考ブロックは生成されません。

思考内容をエンドユーザーに表示しない自動化パイプラインでは、思考トークンをネットワーク経由で受信するオーバーヘッドを省略できます。レイテンシに敏感なアプリケーションでは、最終応答が開始される前に思考テキストのストリーミングを待つことなく、同じ推論品質を得られます。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000,
        "display": "omitted",
    },
    messages=[
        {"role": "user", "content": "What is 27 * 453?"},
    ],
)

for block in response.content:
    if block.type == "thinking":
        if block.thinking:
            print(f"Thinking: {block.thinking}")
        else:
            print("Thinking: [omitted]")
    elif block.type == "text":
        print(f"Response: {block.text}")

display: "omitted"が設定されている場合、レスポンスにはthinkingフィールドが空のthinkingブロックが含まれます。

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

display: "omitted"でストリーミングする場合、thinking_deltaイベントは発行されません。イベントシーケンスについては、思考のストリーミングを参照してください。



要約された思考

拡張思考を有効にすると、Claude 4モデルのMessages APIはClaudeの完全な思考プロセスの要約を返します。要約された思考は、拡張思考の知能面での利点を完全に提供しながら、悪用を防止します。これは、思考設定のdisplayフィールドが未設定または"summarized"に設定されている場合のClaude 4モデルのデフォルト動作です。Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、Claude Opus 4.7、およびClaude Mythos Previewでは、displayのデフォルトは"omitted"となるため、要約された思考を受け取るにはdisplay: "summarized"を明示的に設定する必要があります。

要約された思考に関する重要な考慮事項は以下のとおりです。

• 要約トークンではなく、元のリクエストによって生成された完全な思考トークンに対して課金されます。
• 請求される出力トークン数は、レスポンスに表示されるトークン数と一致しません。
• Claude 4モデルでは、思考出力の最初の数行はより詳細であり、プロンプトエンジニアリングの目的に特に役立つ詳細な推論を提供します。Claude Mythos Previewは最初のトークンから要約するため、その思考ブロックにはこの詳細な前置きは表示されません。
• Anthropicは拡張思考機能の改善を目指しているため、要約の動作は変更される可能性があります。
• 要約は、最小限の追加レイテンシでClaudeの思考プロセスの主要なアイデアを保持し、ストリーミング可能なユーザー体験を実現します。
• 要約は、リクエストで指定したモデルとは異なるモデルによって処理されます。思考モデルは要約された出力を参照しません。



思考のストリーミング

server-sent events (SSE)を使用して、拡張思考のレスポンスをストリーミングできます。

拡張思考でストリーミングが有効になっている場合、thinking_deltaイベントを介して思考内容を受信します。

display: "omitted"が設定されている場合、thinking_deltaイベントは発行されません。思考表示の制御を参照してください。

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

思考を使用したストリーミングの処理方法は以下のとおりです。

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
) as stream:
    thinking_started = False
    response_started = False

    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
            # 新しいブロックごとにフラグをリセット
            thinking_started = False
            response_started = False
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                if not thinking_started:
                    print("Thinking: ", end="", flush=True)
                    thinking_started = True
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                if not response_started:
                    print("Response: ", end="", flush=True)
                    response_started = True
                print(event.delta.text, end="", flush=True)
        elif event.type == "content_block_stop":
            print("\nBlock complete.")

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

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

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// 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": "The greatest common divisor of 1071 and 462 is **21**."}}

// 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"}

display: "omitted"が設定されている場合、思考ブロックが開き、単一のsignature_deltaが到着し、thinking_deltaイベントなしでブロックが閉じます。テキストストリーミングはその直後に開始されます。

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

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

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":""}}



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

拡張思考はツール使用と併用でき、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つの連続したアシスタント応答の一部です。



思考の段階的な無効化

ターン途中で思考の競合が発生した場合（ツール使用ループ中に思考のオン/オフを切り替えるなど）、APIはそのリクエストの思考を自動的に無効にします。モデルの品質を維持し、分布内に留まるために、APIは以下を行う場合があります。

• 無効なターン構造を作成する場合、会話から思考ブロックを削除する
• 会話履歴が思考の有効化と互換性がない場合、現在のリクエストの思考を無効にする

つまり、ターン途中で思考を切り替えようとしてもエラーは発生しませんが、そのリクエストでは思考が暗黙的に無効になります。思考がアクティブだったかどうかを確認するには、レスポンス内のthinkingブロックの有無を確認してください。



実践的なガイダンス

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

例：ターン完了後に思考を切り替える

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

思考を切り替える前にアシスタントターンを完了することで、新しいリクエストで思考が実際に有効になることを保証できます。



思考ブロックの保持

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

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

1. 推論の連続性：思考ブロックは、ツールリクエストにつながったClaudeの段階的な推論を記録します。ツール結果を投稿する際に元の思考を含めることで、Claudeは中断したところから推論を続けることができます。

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

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



インターリーブ思考

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

インターリーブ思考により、Claudeは以下が可能になります。

• 次に何をするかを決定する前に、ツール呼び出しの結果について推論する
• 間に推論ステップを挟んで複数のツール呼び出しを連鎖させる
• 中間結果に基づいてより微妙な判断を行う

インターリーブ思考を有効にする方法はモデルによって異なります。

ここでの「以前のClaude 4モデル」とは、Claude Sonnet 4.5、Claude Opus 4.1（非推奨）、Claude Opus 4（Vertex AIを除き廃止）、Claude Sonnet 4（BedrockおよびVertex AIを除き廃止）を指します。

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

• インターリーブ思考では、budget_tokensは1つのアシスタントターン内のすべての思考ブロックにわたる合計予算を表すため、max_tokensパラメータを超えることができます。
• インターリーブ思考は、Messages APIを介して使用されるツールでのみサポートされています。
• Claude APIおよびAWS上のClaude Platformは、エラーを返すことなく、任意のモデルへのリクエストでinterleaved-thinking-2025-05-14を受け入れます。インターリーブ思考をサポートしていないモデルでは、ヘッダーは無視されます。Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6では、非推奨であり安全に無視されます。Claude Mythos Previewでは、不要であり安全に無視されます。
• パートナー運営のプラットフォーム（たとえば、Amazon BedrockやVertex AI）では、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5、Claude Opus 4.1（非推奨）、Opus 4（Vertex AIを除き廃止）、Sonnet 4.5、Sonnet 4（BedrockおよびVertex AIを除き廃止）以外のモデルにinterleaved-thinking-2025-05-14を渡すと、リクエストは失敗します。



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

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

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

• 以前のOpus/SonnetモデルおよびすべてのHaikuモデルでは、以前のターンの思考ブロックがコンテキストから削除され、キャッシュブレークポイントに影響する可能性があります。Opus 4.5以降およびSonnet 4.6以降では、デフォルトで保持されます。
• ツール使用で会話を続ける場合、思考ブロックはキャッシュされ、キャッシュから読み取られるときに入力トークンとしてカウントされます
• これによりトレードオフが生じます。思考ブロックは視覚的にはコンテキストウィンドウのスペースを消費しませんが、キャッシュされると入力トークン使用量にカウントされます
• 思考が無効になり、現在のツール使用ターンで思考内容を渡した場合、思考内容は削除され、そのリクエストでは思考は無効のままになります

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

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



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

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

仕組み：

1. キャッシングは、ツール結果を含む後続のリクエストを行った場合にのみ発生します
2. 後続のリクエストが行われると、以前の会話履歴（思考ブロックを含む）をキャッシュできます
3. これらのキャッシュされた思考ブロックは、キャッシュから読み取られるときに使用量メトリクスで入力トークンとしてカウントされます
4. ツール結果以外のユーザーブロックが含まれている場合：Opus 4.5以降およびSonnet 4.6以降では、以前の思考ブロックが保持されます。以前のOpus/SonnetモデルおよびすべてのHaikuモデルでは、以前のすべての思考ブロックが無視され、コンテキストから削除されます

詳細な例のフロー：

リクエスト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]

Opus 4.5以降およびSonnet 4.6以降では、以前のすべての思考ブロックがデフォルトで保持されます。以前のOpus/SonnetモデルおよびすべてのHaikuモデルでは、ツール結果以外のユーザーブロックが含まれているため、以前のすべての思考ブロックが無視され、コンテキストから削除されます。このリクエストは以下と同じように処理されます。

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 4.5モデル以降では、入力トークンとmax_tokensの合計がコンテキストウィンドウサイズを超える場合でも、APIはリクエストを受け入れます。その後、生成がコンテキストウィンドウの制限に達すると、stop_reason: "model_context_window_exceeded"で停止します。以前のモデルでは、APIは代わりに検証エラーを返します。停止理由の処理を参照してください。



拡張思考でのコンテキストウィンドウ

思考を有効にしてコンテキストウィンドウの使用量を計算する場合、注意すべき考慮事項がいくつかあります。

• Opus 4.5以降およびSonnet 4.6以降では、以前のターンの思考ブロックが保持され、コンテキストウィンドウにカウントされます。以前のOpus/SonnetモデルおよびすべてのHaikuモデルでは、削除されカウントされません
• 現在のターンの思考は、そのターンの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)

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



拡張思考でのトークン管理

拡張思考でのコンテキストウィンドウとmax_tokensの動作を考慮すると、以下が必要になる場合があります。

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



思考の暗号化

思考の完全な内容は暗号化され、signatureフィールドで返されます。このフィールドは、思考ブロックがAPIに渡し戻された際に、それらがClaudeによって生成されたものであることを検証するために使用されます。

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

• レスポンスをストリーミングする場合、署名はcontent_block_stopイベントの直前に、content_block_deltaイベント内のsignature_deltaを通じて追加されます。
• Claude 4モデルのsignature値は、以前のモデルよりも大幅に長くなっています。
• signatureフィールドは不透明なフィールドであり、解釈や解析を行うべきではありません。
• signature値はプラットフォーム間（Claude API、Amazon Bedrock、Vertex AI）で互換性があります。あるプラットフォームで生成された値は、別のプラットフォームでも互換性があります。



編集済み思考ブロック

通常のthinkingブロックに加えて、APIはredacted_thinkingブロックを返す場合があります。redacted_thinkingブロックには、dataフィールドに暗号化された思考内容が含まれ、読み取り可能な要約はありません。

{
  "type": "redacted_thinking",
  "data": "..."
}

dataフィールドは不透明で暗号化されています。通常の思考ブロックのsignatureフィールドと同様に、ツールを使用したマルチターン会話を続ける場合は、redacted_thinkingブロックを変更せずにAPIに返す必要があります。



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

Messages APIは、Claudeモデルのバージョンによって思考の処理が異なります。以下の表は簡潔な比較を示しています。

¹ 要約された思考を受け取るにはdisplay: "summarized"を設定してください。Claude Fable 5、Claude Mythos 5、Claude Mythos Previewでは、生の思考トークンは返されません。
² 適応型思考を使用した場合。これらのモデルではinterleaved-thinking-2025-05-14ベータヘッダーは不要であり、含まれていても安全に無視されます。
³ Mythos思考形式をサポートしていないモデルで会話を続ける場合、ブロックは削除されます。



モデル別の思考ブロック保持

以前のアシスタントターンの思考ブロックがデフォルトでコンテキストに保持されるかどうかは、モデルクラスによって異なります。Opus：Claude Opus 4.5以降のOpusモデルは、以前のすべての思考ブロックを保持します。Claude Opus 4.1（非推奨）以前のOpusモデルは、最後のアシスタントターンの思考のみを保持します。Sonnet：Claude Sonnet 4.6以降のSonnetモデルはすべて保持します。Claude Sonnet 4.5以前のSonnetモデルは最後のターンのみを保持します。Haiku：Claude Haiku 4.5までのすべてのHaikuモデルは最後のターンのみを保持します。Claude Mythos Previewも、以前のすべての思考ブロックを保持します。

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

• キャッシュの最適化：ツール使用時、保持された思考ブロックはツール結果とともに返され、アシスタントターン全体で段階的にキャッシュされるため、キャッシュヒットが可能になり、マルチステップワークフローでトークンを節約できます
• 知能への影響なし：思考ブロックを保持しても、モデルのパフォーマンスに悪影響はありません

重要な考慮事項：

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



料金

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

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

• 思考中に使用されたトークン（output tokens）
• コンテキストに保持される以前のアシスタントターンの思考ブロック：以前のOpus/SonnetモデルおよびすべてのHaikuモデルでは最後のターンのみ、Opus 4.5+およびSonnet 4.6+ではデフォルトですべてのターン（input tokens）
• 標準的なテキスト出力トークン

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

• 入力トークン： 元のリクエスト内のトークン（以前のターンの思考トークンは除く）
• 出力トークン（課金対象）： Claudeが内部的に生成した元の思考トークン
• 出力トークン（表示）： レスポンスに表示される要約された思考トークン
• 課金なし： 要約の生成に使用されたトークン

display: "omitted"を使用する場合：

• 入力トークン： 元のリクエスト内のトークン（要約の場合と同じ）
• 出力トークン（課金対象）： Claudeが内部的に生成した元の思考トークン（要約の場合と同じ）
• 出力トークン（表示）： 思考トークンはゼロ（thinkingフィールドは空）

内部推論に費やされた課金対象の出力トークン数を確認するには、レスポンスのusage.output_tokens_details.thinking_tokensを読み取ってください。この値は、モデルが生成した生の推論（本文で返される要約テキストではありません）を反映しており、常にoutput_tokens以下になります。出力のうち推論以外の部分を概算するには、output_tokensからこの値を引いてください。

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

output_tokensは、課金に使用される包括的で正式な合計値のままです。output_tokens_detailsは、可観測性のための読み取り専用の内訳です。



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



思考バジェットの活用

• バジェットの最適化： 最小バジェットは1,024トークンです。最小値から始めて、思考バジェットを段階的に増やし、ユースケースに最適な範囲を見つけてください。トークン数が多いほど、より包括的な推論が可能になりますが、タスクによっては収穫逓減が生じます。バジェットを増やすと、レイテンシの増加というトレードオフはあるものの、応答品質が向上する可能性があります。重要なタスクでは、さまざまな設定をテストして最適なバランスを見つけてください。なお、思考バジェットは厳密な制限ではなく目標値です。実際のトークン使用量はタスクによって異なる場合があります。
• 開始点： 複雑なタスクでは、より大きな思考バジェット（16,000トークン以上）から始めて、ニーズに応じて調整してください。
• 大きなバジェット： 32,000を超える思考バジェットの場合は、ネットワークの問題を回避するためにバッチ処理を使用してください。モデルに32,000トークンを超える思考を行わせるリクエストは、実行時間の長いリクエストとなり、システムのタイムアウトやオープン接続の制限に達する可能性があります。
• トークン使用量の追跡： コストとパフォーマンスを最適化するために、思考トークンの使用量を監視してください。レスポンスのusage.output_tokens_details.thinking_tokensフィールドは、課金対象の出力トークンのうち内部推論に使用されたトークン数を報告します。ストリーミング時には、この内訳は最後のmessage_deltaイベントにのみ表示されます。



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

• 応答時間： 追加の処理により、応答時間が長くなることを想定してください。思考ブロックの生成により、全体の応答時間が増加します。
• ストリーミング要件： SDKでは、長時間実行されるリクエストでのHTTPタイムアウトを回避するため、max_tokensが21,333を超える場合にストリーミングが必要です。これはクライアント側の検証であり、APIの制限ではありません。イベントを段階的に処理する必要がない場合は、.stream()と.get_final_message()（Python）または.finalMessage()（TypeScript）を使用して、個々のイベントを処理せずに完全なMessageオブジェクトを取得してください。詳細については、メッセージのストリーミングを参照してください。ストリーミング時には、思考コンテンツブロックとテキストコンテンツブロックの両方が到着した際に処理できるよう準備してください。
• レイテンシのための思考の省略： アプリケーションで思考コンテンツを表示しない場合は、思考設定でdisplay: "omitted"を設定して、最初のテキストトークンまでの時間を短縮してください。思考表示の制御を参照してください。



機能の互換性

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



使用ガイドライン

• タスクの選択： 数学、コーディング、分析など、段階的な推論が有益な特に複雑なタスクには拡張思考を使用してください。
• コンテキストの処理： 以前の思考ブロックを自分で削除する必要はありません。Opus 4.5以降およびSonnet 4.6以降では、Claude APIはデフォルトで前のターンの思考ブロックを保持します。それ以前のOpus/SonnetモデルおよびすべてのHaikuモデルでは、自動的に無視され、コンテキスト使用量の計算には含まれません。
• プロンプトエンジニアリング： Claudeの思考能力を最大限に活用したい場合は、拡張思考のプロンプトのヒントを確認してください。



次のステップ