拡張思考を使った構築

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

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

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

Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)

APIの動作はClaude 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-20250514",
    "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パラメータをenabledに設定し、budget_tokensを拡張思考のための特定のトークン予算に設定したthinkingオブジェクトを追加します。

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

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

要約された思考

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

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

元のリクエストによって生成された完全な思考トークンに対して課金され、要約トークンに対しては課金されません。
請求される出力トークン数は、レスポンスで表示されるトークン数と一致しません。
思考出力の最初の数行はより詳細で、特にプロンプトエンジニアリングの目的に役立つ詳細な推論を提供します。
Anthropicが拡張思考機能の改善を求めるにつれて、要約の動作は変更される可能性があります。
要約は、最小限の追加レイテンシでClaudeの思考プロセスの主要なアイデアを保持し、ストリーム可能なユーザーエクスペリエンスとClaude 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-20250514",
    "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-20250514", "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: anyのみをサポートします（specific、auto、またはその他の値はサポートされません）。
思考ブロックの保存：ツール使用中、最後のアシスタントメッセージのthinkingブロックをAPIに戻す必要があります。推論の連続性を維持するために、完全な未変更のブロックをAPIに戻してください。

例：ツール結果と共に思考ブロックを渡す

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

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-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[weather_tool],
    messages=[
        {"role": "user", "content": "What's the weather in Paris?"}
    ]
)

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

{
    "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-20250514",
    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はその既存の応答の構築を続けます。これにより、ツール使用中に思考ブロックを保存する必要があります。理由は次のとおりです：

推論の連続性：思考ブロックはツールリクエストにつながったClaudeのステップバイステップの推論をキャプチャします。ツール結果を投稿するとき、元の思考を含めることで、Claudeが中断した場所から推論を続けることができます。
コンテキストの維持：ツール結果はAPI構造ではユーザーメッセージとして表示されますが、それらは連続した推論フローの一部です。思考ブロックを保存することで、複数のAPI呼び出し間でこの概念的なフローが維持されます。コンテキスト管理の詳細については、コンテキストウィンドウに関するガイドをご覧ください。

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

インターリーブ思考

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

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

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

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

インターリーブ思考はMessages APIを介して使用されるツールでのみサポートされています。

インターリーブ思考では、budget_tokensはmax_tokensパラメータを超えることができます。これは、1つのアシスタントターン内のすべての思考ブロック間の合計予算を表すためです。

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

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-20250514",
    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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    # Enable interleaved thinking with beta header
    extra_headers={
        "anthropic-beta": "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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    extra_headers={
        "anthropic-beta": "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.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    tools=[calculator_tool, database_tool],
    extra_headers={
        "anthropic-beta": "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は最終的な応答を作成する前に両方の結果についてもう一度考えます
思考予算はターン内のすべての思考ブロック間で分配されます

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

プロンプトキャッシングと拡張思考

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

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

以前のターンからの思考ブロックはコンテキストから削除され、キャッシュのブレークポイントに影響を与える可能性があります
ツール使用で会話を続ける場合、思考ブロックはキャッシュされ、キャッシュから読み込まれるときに入力トークンとしてカウントされます
これによりトレードオフが生じます：思考ブロックは視覚的にコンテキストウィンドウのスペースを消費しませんが、キャッシュされると入力トークンの使用量にカウントされます
思考が無効になると、現在のツール使用ターンで思考コンテンツを渡すとリクエストは失敗します。他のコンテキストでは、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-20250514",
    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-20250514",
    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-20250514",
    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-20250514",
    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-20250514",
    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-20250514",
    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でキャッシュヒットがないことが示されており、思考パラメータが変更されるとメッセージベースのキャッシングが無効になることが証明されています。

拡張思考を使用した最大トークン数とコンテキストウィンドウサイズ

古い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フィールドで返されます。このフィールドは、APIに戻されたときに思考ブロックがClaudeによって生成されたことを検証するために使用されます。レスポンスをストリーミングする場合、署名はcontent_block_stopイベントの直前にcontent_block_deltaイベント内のsignature_deltaを介して追加されます。

署名フィールドは以前のモデルよりも大幅に長くなることに注意してください。これは不透明なフィールドであり、解釈または解析すべきではありません - 検証目的のみに存在します。

思考ブロックを戻す必要があるのは、ツールを使用した拡張思考を使用する場合のみです。それ以外の場合は、以前のターンからの思考ブロックを省略するか、それらを戻した場合はAPIが削除するようにすることができます。

思考ブロックを戻す場合は、一貫性を保ち、潜在的な問題を避けるために、受け取ったすべてをそのまま戻すことをお勧めします。

思考の編集

時々、Claudeの内部推論が安全システムによってフラグが立てられることがあります。これが発生すると、thinkingブロックの一部またはすべてを暗号化し、redacted_thinkingブロックとして返します。redacted_thinkingブロックはAPIに戻されるときに復号化され、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-3-7-sonnet-20250219",
    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	$15 / MTok	$18.75 / MTok	$1.50 / MTok	$75 / 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の間の値に設定できます。
思考が有効な場合、応答を事前に入力することはできません。
思考予算を変更すると、メッセージを含むキャッシュされたプロンプトプレフィックスが無効になります。ただし、キャッシュされたシステムプロンプトとツール定義は、思考パラメータが変更されても引き続き機能します。

使用ガイドライン

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

次のステップ

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

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

拡張思考プロンプトのヒント

拡張思考のプロンプトエンジニアリングのベストプラクティスを学びましょう。

プロンプトキャッシングメッセージのストリーミング

On this page

サポートされているモデル
拡張思考の仕組み
拡張思考の使用方法
要約された思考
思考のストリーミング
ツール使用と拡張思考
思考ブロックの保存
インターリーブ思考
プロンプトキャッシングと拡張思考
思考ブロックのキャッシング動作の理解
拡張思考を使用した最大トークン数とコンテキストウィンドウサイズ
拡張思考を使用したコンテキストウィンドウ
拡張思考とツール使用を使用したコンテキストウィンドウ
拡張思考を使用したトークンの管理
思考の暗号化
思考の編集
モデルバージョン間の思考の違い
価格
拡張思考のベストプラクティスと考慮事項
思考予算の活用
パフォーマンスの考慮事項
機能の互換性
使用ガイドライン
次のステップ

はじめの一歩

モデルと料金

機能を探索

Claudeについて学ぶ

法務センター

テストと評価

エージェントコンポーネント

拡張思考を使った構築

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

拡張思考の仕組み

拡張思考の使用方法

要約された思考

思考のストリーミング

ツール使用と拡張思考

思考ブロックの保存

インターリーブ思考

プロンプトキャッシングと拡張思考

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

拡張思考を使用した最大トークン数とコンテキストウィンドウサイズ

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

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

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

思考の暗号化

思考の編集

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

価格

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

思考予算の活用

パフォーマンスの考慮事項

機能の互換性

使用ガイドライン

次のステップ

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

拡張思考プロンプトのヒント

はじめの一歩

モデルと料金

機能を探索

Claudeについて学ぶ

法務センター

テストと評価

エージェントコンポーネント

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

​拡張思考の仕組み

​拡張思考の使用方法

​要約された思考

​思考のストリーミング

​ツール使用と拡張思考

​思考ブロックの保存

​インターリーブ思考

​プロンプトキャッシングと拡張思考

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

​拡張思考を使用した最大トークン数とコンテキストウィンドウサイズ

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

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

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

​思考の暗号化

​思考の編集

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

​価格

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

​思考予算の活用

​パフォーマンスの考慮事項

​機能の互換性

​使用ガイドライン

​次のステップ

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

拡張思考プロンプトのヒント

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

拡張思考の仕組み

拡張思考の使用方法

要約された思考

思考のストリーミング

ツール使用と拡張思考

思考ブロックの保存

インターリーブ思考

プロンプトキャッシングと拡張思考

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

拡張思考を使用した最大トークン数とコンテキストウィンドウサイズ

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

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

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

思考の暗号化

思考の編集

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

価格

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

思考予算の活用

パフォーマンスの考慮事項

機能の互換性

使用ガイドライン

次のステップ