拡張思考を使用した構築

拡張思考により、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)

API の動作は Claude Sonnet 3.7 と Claude 4 モデル間で異なりますが、API の形状は完全に同じです。詳細については、モデルバージョン間の思考の違いを参照してください。

拡張思考の仕組み

拡張思考が有効になると、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 モデルへの簡単な移行を実現します。
要約は、リクエストでターゲットにしたモデルとは異なるモデルによって処理されます。思考モデルは要約された出力を見ません。

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 がツール選択と結果処理を通じて推論することができます。ツール使用を伴う拡張思考を使用する場合、以下の制限に注意してください：

ツール選択の制限: 思考を伴うツール使用は tool_choice: {"type": "auto"} (デフォルト) または tool_choice: {"type": "none"} のみをサポートします。tool_choice: {"type": "any"} または tool_choice: {"type": "tool", "name": "..."} を使用するとエラーが発生します。これらのオプションはツール使用を強制するため、拡張思考と互換性がありません。
思考ブロックの保持: ツール使用中に、最後のアシスタントメッセージの 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).

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

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

実践的なガイダンス

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

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)

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

思考モードの切り替えは、メッセージ履歴のプロンプトキャッシングも無効にします。詳細については、プロンプトキャッシングを伴う拡張思考セクションを参照してください。

例: ツール結果を伴う思考ブロックの渡し方

ツール結果を提供する際に思考ブロックを保持する方法を示す実践的な例を次に示します：

weather_tool = {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }
}

# First request - Claude responds with thinking and tool request
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"}
    ]
)

API レスポンスには思考、テキスト、および tool_use ブロックが含まれます：

{
    "content": [
        {
            "type": "thinking",
            "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "I can help you get the current weather information for Paris. Let me check that for you"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

それでは会話を続けてツールを使用しましょう

# Extract thinking block and tool use block
thinking_block = next((block for block in response.content
                      if block.type == 'thinking'), None)
tool_use_block = next((block for block in response.content
                      if block.type == 'tool_use'), None)

# Call your actual weather API, here is where your actual API call would go
# let's pretend this is what we get back
weather_data = {"temperature": 88}

# Second request - Include thinking block and tool result
# No new thinking blocks will be generated in the response
continuation = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"},
        # notice that the thinking_block is passed in as well as the tool_use_block
        # if this is not passed in, an error is raised
        {"role": "assistant", "content": [thinking_block, tool_use_block]},
        {"role": "user", "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use_block.id,
            "content": f"Current temperature: {weather_data['temperature']}°F"
        }]}
    ]
)

API レスポンスは現在テキストのみを含みます

{
    "content": [
        {
            "type": "text",
            "text": "Currently in Paris, the temperature is 88°F (31°C)"
        }
    ]
}

思考ブロックの保持

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

以前の assistant ロールターンから thinking ブロックを省略できますが、マルチターン会話の場合は常にすべての思考ブロックを API に返すことをお勧めします。API は以下を行います：

提供された思考ブロックを自動的にフィルタリングする
モデルの推論を保持するために必要な関連する思考ブロックを使用する
Claude に表示されるブロックの入力トークンのみに対して課金する

会話中に思考モードを切り替える場合、アシスタントターン全体（ツール使用ループを含む）は単一の思考モードで動作する必要があることに注意してください。詳細については、会話での思考モードの切り替えを参照してください。

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

推論の連続性: 思考ブロックは、ツール要求につながった段階的な推論をキャプチャします。ツール結果を投稿するとき、元の思考を含めることで、Claude は中断したところから推論を続けることができます。
コンテキストの維持: ツール結果は 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 を渡すと、リクエストが失敗します。

インターリーブ思考なしのツール使用

import anthropic

client = anthropic.Anthropic()

# Define tools
calculator_tool = {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Query product database",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "SQL query to execute"
            }
        },
        "required": ["query"]
    }
}

# First request - Claude thinks once before all tool calls
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    messages=[{
        "role": "user",
        "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
    }]
)

# Response includes thinking followed by tool uses
# Note: Claude thinks once at the beginning, then makes all tool decisions
print("First response:")
for block in response.content:
    if block.type == "thinking":
        print(f"Thinking (summarized): {block.thinking}")
    elif block.type == "tool_use":
        print(f"Tool use: {block.name} with input {block.input}")
    elif block.type == "text":
        print(f"Text: {block.text}")

# You would execute the tools and return results...
# After getting both tool results back, Claude directly responds without additional thinking

この例では、インターリーブ思考なし：

Claude は最初にタスクを理解するために一度考えます
すべてのツール使用決定を事前に行います
ツール結果が返されると、Claude は追加の思考なしで直ちに応答を提供します

インターリーブ思考を伴うツール使用

import anthropic

client = anthropic.Anthropic()

# Same tool definitions as before
calculator_tool = {
    "name": "calculator",
    "description": "Perform mathematical calculations",
    "input_schema": {
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "Mathematical expression to evaluate"
            }
        },
        "required": ["expression"]
    }
}

database_tool = {
    "name": "database_query",
    "description": "Query product database",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "SQL query to execute"
            }
        },
        "required": ["query"]
    }
}

# First request with interleaved thinking enabled
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[{
        "role": "user",
        "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
    }]
)

print("Initial response:")
thinking_blocks = []
tool_use_blocks = []

for block in response.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Thinking: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Tool use: {block.name} with input {block.input}")
    elif block.type == "text":
        print(f"Text: {block.text}")

# First tool result (calculator)
calculator_result = "7500"  # 150 * 50

# Continue with first tool result
response2 = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        }
    ]
)

print("\nAfter calculator result:")
# With interleaved thinking, Claude can think about the calculator result
# before deciding to query the database
for block in response2.content:
    if block.type == "thinking":
        thinking_blocks.append(block)
        print(f"Interleaved thinking: {block.thinking}")
    elif block.type == "tool_use":
        tool_use_blocks.append(block)
        print(f"Tool use: {block.name} with input {block.input}")

# Second tool result (database)
database_result = "5200"  # Example average monthly revenue

# Continue with second tool result
response3 = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    betas=["interleaved-thinking-2025-05-14"],
    messages=[
        {
            "role": "user",
            "content": "What's the total revenue if we sold 150 units of product A at $50 each, and how does this compare to our average monthly revenue from the database?"
        },
        {
            "role": "assistant",
            "content": [thinking_blocks[0], tool_use_blocks[0]]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[0].id,
                "content": calculator_result
            }]
        },
        {
            "role": "assistant",
            "content": thinking_blocks[1:] + tool_use_blocks[1:]
        },
        {
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use_blocks[1].id,
                "content": database_result
            }]
        }
    ]
)

print("\nAfter database result:")
# With interleaved thinking, Claude can think about both results
# before formulating the final response
for block in response3.content:
    if block.type == "thinking":
        print(f"Final thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Final response: {block.text}")

この例では、インターリーブ思考を使用：

Claude は最初にタスクについて考えます
計算機の結果を受け取った後、Claude はその結果が何を意味するかについて再度考えることができます
Claude は最初の結果に基づいてデータベースをクエリする方法を決定します
データベース結果を受け取った後、Claude は最終応答を作成する前に両方の結果について再度考えます
思考予算はターン内のすべての思考ブロック全体に分散されます

このパターンにより、各ツールの出力が次の決定に情報を提供するより洗練された推論チェーンが可能になります。

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

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

拡張思考タスクは通常、5 分以上かかります。1 時間のキャッシュ期間を使用して、長い思考セッションとマルチステップワークフロー全体でキャッシュヒットを維持することを検討してください。

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

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

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

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

思考ブロックはキャッシングおよびコンテキスト計算から削除されますが、特にインターリーブ思考を使用する場合、ツール使用で会話を続ける場合は保持する必要があります。

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

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

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

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

システムプロンプトキャッシング（思考の変更時に保持）

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remove script and style elements
    for script in soup(["script", "style"]):
        script.decompose()

    # Get text
    text = soup.get_text()

    # Break into lines and remove leading and trailing space on each
    lines = (line.strip() for line in text.splitlines())
    # Break multi-headlines into a line each
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Drop blank lines
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:5000]

SYSTEM_PROMPT=[
    {
        "type": "text",
        "text": "You are an AI assistant that is tasked with literary analysis. Analyze the following text carefully.",
    },
    {
        "type": "text",
        "text": LARGE_TEXT,
        "cache_control": {"type": "ephemeral"}
    }
]

MESSAGES = [
    {
        "role": "user",
        "content": "Analyze the tone of this passage."
    }
]

# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the characters in this passage."
})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    system=SYSTEM_PROMPT,
    messages=MESSAGES
)

print(f"Second response usage: {response2.usage}")

# Third request - different thinking parameters (cache miss for messages)
print("\nThird request - different thinking parameters (cache miss for messages)")
response3 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Changed thinking budget
    },
    system=SYSTEM_PROMPT,  # System prompt remains cached
    messages=MESSAGES  # Messages cache is invalidated
)

print(f"Third response usage: {response3.usage}")

メッセージキャッシング（思考の変更時に無効化）

from anthropic import Anthropic
import requests
from bs4 import BeautifulSoup

client = Anthropic()

def fetch_article_content(url):
    response = requests.get(url)
    soup = BeautifulSoup(response.content, 'html.parser')

    # Remove script and style elements
    for script in soup(["script", "style"]):
        script.decompose()

    # Get text
    text = soup.get_text()

    # Break into lines and remove leading and trailing space on each
    lines = (line.strip() for line in text.splitlines())
    # Break multi-headlines into a line each
    chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
    # Drop blank lines
    text = '\n'.join(chunk for chunk in chunks if chunk)

    return text

# Fetch the content of the article
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Use just enough text for caching (first few chapters)
LARGE_TEXT = book_content[:5000]

# No system prompt - caching in messages instead
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {
                "type": "text",
                "text": "Analyze the tone of this passage."
            }
        ]
    }
]

# First request - establish cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    },
    messages=MESSAGES
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response1.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the characters in this passage."
})
# Second request - same thinking parameters (cache hit expected)
print("\nSecond request - same thinking parameters (cache hit expected)")
response2 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 4000  # Same thinking budget
    },
    messages=MESSAGES
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({
    "role": "assistant",
    "content": response2.content
})
MESSAGES.append({
    "role": "user",
    "content": "Analyze the setting in this passage."
})

# Third request - different thinking budget (cache miss expected)
print("\nThird request - different thinking budget (cache miss expected)")
response3 = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=20000,
    thinking={
        "type": "enabled",
        "budget_tokens": 8000  # Different thinking budget breaks cache
    },
    messages=MESSAGES
)

print(f"Third response usage: {response3.usage}")

スクリプトの出力を次に示します（数値は若干異なる場合があります）

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 }

この例は、メッセージ配列にキャッシングが設定されている場合、思考パラメータを変更する（budget_tokens を 4000 から 8000 に増加）とキャッシュが無効化されることを示しています。3 番目のリクエストは cache_creation_input_tokens=1370 と cache_read_input_tokens=0 でキャッシュヒットがないことを示し、思考パラメータが変更されるとメッセージベースのキャッシングが無効化されることを証明しています。

拡張思考を使用した 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 に返される場合に使用されます。

思考ブロックを返す必要があるのは、ツールを使用した拡張思考を使用する場合のみです。それ以外の場合は、以前のターンから思考ブロックを省略するか、API に渡す場合は 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..."
    }
  ]
}

レスポンスで編集された思考ブロックを見ることは予想される動作です。モデルは、安全ガードレールを維持しながら、この編集された推論を使用して応答に情報を提供できます。アプリケーションで編集された思考処理をテストする必要がある場合は、プロンプトとしてこの特別なテスト文字列を使用できます：ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

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

例: 編集された思考ブロックの操作

この例は、Claude の内部推論に安全システムによってフラグが立てられたコンテンツが含まれている場合に表示される可能性がある redacted_thinking ブロックを処理する方法を示しています：

import anthropic

client = anthropic.Anthropic()

# Using a special prompt that triggers redacted thinking (for demonstration purposes only)
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{
        "role": "user",
        "content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB"
    }]
)

# Identify redacted thinking blocks
has_redacted_thinking = any(
    block.type == "redacted_thinking" for block in response.content
)

if has_redacted_thinking:
    print("Response contains redacted thinking blocks")
    # These blocks are still usable in subsequent requests

    # Extract all blocks (both redacted and non-redacted)
    all_thinking_blocks = [
        block for block in response.content
        if block.type in ["thinking", "redacted_thinking"]
    ]

    # When passing to subsequent requests, include all blocks without modification
    # This preserves the integrity of Claude's reasoning

    print(f"Found {len(all_thinking_blocks)} thinking blocks total")
    print(f"These blocks are still billable as output tokens")

コンソールで試す

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

Messages API は Claude Sonnet 3.7 と Claude 4 モデル間で思考を異なる方法で処理します。主に編集と要約動作の違いがあります。以下の表で簡潔な比較を参照してください：

機能	Claude Sonnet 3.7	Claude 4 モデル
思考出力	完全な思考出力を返す	要約された思考を返す
インターリーブ思考	サポートされていない	`interleaved-thinking-2025-05-14` ベータヘッダーでサポート

価格

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

モデル	基本入力トークン	キャッシュ書き込み	キャッシュヒット	出力トークン
Claude Opus 4.1	$15 / MTok	$18.75 / MTok	$1.50 / MTok	$75 / MTok
Claude Opus 4	$15 / MTok	$18.75 / MTok	$1.50 / MTok	$75 / MTok
Claude Sonnet 4.5	$3 / MTok	$3.75 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 4	$3 / MTok	$3.75 / MTok	$0.30 / MTok	$15 / MTok
Claude Sonnet 3.7	$3 / MTok	$3.75 / MTok	$0.30 / MTok	$15 / MTok

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

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

拡張思考が有効な場合、この機能をサポートするために特殊なシステムプロンプトが自動的に含まれます。

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

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

請求される出力トークン数は、レスポンスに表示される可視トークン数と一致しません。要約ではなく、完全な思考プロセスに対して課金されます。

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

思考予算の使用

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

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

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

機能の互換性

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

使用ガイドライン

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

次のステップ

拡張思考クックブックを試す

クックブックで思考の実践的な例を探索してください。

拡張思考プロンプティングのヒント

拡張思考のプロンプトエンジニアリングのベストプラクティスを学んでください。

はじめの一歩

モデルと価格

Claudeで構築

機能

ツール

エージェントスキル

Agent SDK

API内のMCP

Claude on 3rd-party platforms

プロンプトエンジニアリング

テストと評価

ガードレールを強化

管理とモニタリング

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

​拡張思考の仕組み

​拡張思考の使用方法

​要約された思考

​ストリーミング思考

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

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

​一般的なエラーシナリオ

​実践的なガイダンス

​思考ブロックの保持

​インターリーブ思考

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

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

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

​拡張思考を使用したコンテキストウィンドウ

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

​拡張思考を使用したトークンの管理

​思考暗号化

​思考の編集

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

​価格

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

​思考予算の使用

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

​機能の互換性

​使用ガイドライン

​次のステップ

拡張思考クックブックを試す

拡張思考プロンプティングのヒント

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

拡張思考の仕組み

拡張思考の使用方法

要約された思考

ストリーミング思考

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

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

一般的なエラーシナリオ

実践的なガイダンス

思考ブロックの保持

インターリーブ思考

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

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

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

拡張思考を使用したコンテキストウィンドウ

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

拡張思考を使用したトークンの管理

思考暗号化

思考の編集

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

価格

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

思考予算の使用

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

機能の互換性

使用ガイドライン

次のステップ