• メッセージ
  • マネージドエージェント
  • 管理

Search...
⌘K
はじめに
Claude入門クイックスタート
Claudeで構築する
機能の概要Messages APIの使用停止理由とフォールバック拒否とフォールバックフォールバッククレジット
モデルの機能
拡張思考適応型思考エフォートタスクバジェット(ベータ版)高速モード(リサーチプレビュー)構造化出力引用メッセージのストリーミングバッチ処理検索結果拒否のストリーミング多言語サポート埋め込み
ツール
概要ツール使用の仕組みチュートリアル:ツール使用エージェントの構築ツールの定義ツール呼び出しの処理並列ツール使用ツールランナー(SDK)厳密なツール使用プロンプトキャッシングを使ったツール使用サーバーツールトラブルシューティングウェブ検索ツールウェブ取得ツールコード実行ツールアドバイザーツールメモリツールBashツールコンピュータ使用ツールテキストエディタツール
ツールインフラストラクチャ
ツールリファレンスツールコンテキストの管理ツールの組み合わせツール検索プログラムによるツール呼び出しきめ細かいツールストリーミング
コンテキスト管理
コンテキストウィンドウコンパクションコンテキスト編集プロンプトキャッシング会話途中のシステムメッセージオーケストレーションモードの構築キャッシュ診断(ベータ版)トークンカウント
ファイルの操作
Files APIPDFサポート画像とビジョン
スキル
概要クイックスタートベストプラクティスエンタープライズ向けスキルAPIでのスキル
MCP
リモートMCPサーバーMCPコネクタ
クラウドプラットフォーム上のClaude
Amazon BedrockAmazon Bedrock(レガシー)AWS上のClaude PlatformMicrosoft FoundryVertex AI

Log in
拡張思考
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
メッセージ/モデルの機能

拡張思考を使った構築



この機能はZero Data Retention(ZDR)の対象です。組織がZDR契約を締結している場合、この機能を通じて送信されたデータは、APIレスポンスが返された後に保存されることはありません。

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



claude-fable-5およびclaude-mythos-5では、拡張思考は常に有効であり、無効にすることはできません。手動の拡張思考(thinking: {type: "enabled", budget_tokens: N})はサポートされていません。代わりに適応型思考を使用してください。適応型思考は常にオンであり、thinking: {type: "disabled"}はエラーを返します。



Claude Opus 4.8およびClaude Opus 4.7では、thinking: {type: "adaptive"}を設定して適応型思考を有効にし、effortパラメータを使用して思考の深さを制御してください。両モデルでは、手動の拡張思考(thinking: {type: "enabled", budget_tokens: N})はサポートされておらず、400エラーを返します。適応型思考では、モデルが各リクエストに基づいていつ、どの程度思考するかを決定するため、必要な場合にのみ思考がトリガーされます。Claude Opus 4.6およびClaude Sonnet 4.6でも適応型思考が推奨されます。これらのモデルでは手動設定は引き続き機能しますが、非推奨であり、将来のモデルリリースで削除される予定です。

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

手動の拡張思考(thinking: {type: "enabled", budget_tokens: N})は、Claude Fable 5、Claude Mythos 5、Claude Opus 4.8、およびClaude Opus 4.7を除くすべての現行Claudeモデルでサポートされています。これらのモデルでは受け付けられず、400エラーを返します。いくつかのモデルにはモード固有の動作があります。

  • Claude Fable 5(claude-fable-5)およびClaude Mythos 5(claude-mythos-5): 手動の拡張思考はサポートされておらず、400エラーを返します。適応型思考は常にオンです。思考の深さを制御するにはeffortパラメータを使用してください。
  • Claude Opus 4.8(claude-opus-4-8): 手動の拡張思考はサポートされておらず、400エラーを返します。代わりに適応型思考(thinking: {type: "adaptive"})とeffortパラメータを使用してください。モデルは各リクエストに基づいて、拡張思考を使用するかどうか、およびどの程度使用するかを決定します。
  • Claude Opus 4.7(claude-opus-4-7): 手動の拡張思考はサポートされなくなりました。代わりに適応型思考(thinking: {type: "adaptive"})とeffortパラメータを使用してください。
  • Claude Mythos Preview: 適応型思考がデフォルトです。thinking: {type: "enabled", budget_tokens: N}も受け付けられます。thinking: {type: "disabled"}はサポートされておらず、displayは思考コンテンツを返すのではなく、デフォルトで"omitted"になります。要約を受け取るにはdisplay: "summarized"を渡してください。
  • Claude Opus 4.6(claude-opus-4-6): 適応型思考が推奨されます。手動モード(type: "enabled")は非推奨ですが、引き続き機能します。
  • Claude Sonnet 4.6(claude-sonnet-4-6): 適応型思考が推奨されます。インターリーブモードを使用した手動モード(type: "enabled")は非推奨ですが、引き続き機能します。


思考の動作はClaudeモデルのバージョンによって異なります。詳細については、モデルバージョン間の思考の違いを参照してください。

拡張思考の仕組み

拡張思考がオンになると、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オブジェクトを追加します。Claude Opus 4.6およびClaude Sonnet 4.6では、代わりにtype: "adaptive"を使用してください。詳細については適応型思考を参照してください。これらのモデルではbudget_tokensを指定したtype: "enabled"は引き続き機能しますが、非推奨であり、将来のリリースで削除される予定です。

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



budget_tokensはClaude Opus 4.6およびClaude Sonnet 4.6では非推奨であり、将来のモデルリリースで削除される予定です。代わりに適応型思考とeffortパラメータを使用して思考の深さを制御してください。



Claude Mythos Preview、Claude Opus 4.8、Claude Opus 4.7、およびClaude Opus 4.6は最大128kの出力トークンをサポートしています。Claude Sonnet 4.6およびClaude Haiku 4.5は最大64kをサポートしています。レガシーモデルの制限については、モデルの概要を参照してください。Message Batches APIでは、output-300k-2026-03-24 ベータヘッダーにより、Claude Opus 4.8、Opus 4.7、Opus 4.6、およびSonnet 4.6の出力制限が300kに引き上げられます。

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

要約された思考

拡張思考を有効にすると、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の思考プロセスの主要なアイデアを保持し、ストリーミング可能なユーザー体験を実現します。
  • 要約は、リクエストで指定したモデルとは異なるモデルによって処理されます。思考モデルは要約された出力を参照しません。


まれに、Claude 4モデルの完全な思考出力へのアクセスが必要な場合は、Anthropicの営業担当にお問い合わせください。

思考表示の制御

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の値に関係なく思考ブロックは生成されません。


signatureフィールドは、displayが"summarized"でも"omitted"でも同一です。会話のターン間でdisplayの値を切り替えることはサポートされています。



Claude Mythos Previewでは、displayはデフォルトで"omitted"になります。このセクションの例では、すべてのモデルに適用されるようにdisplayを明示的に渡していますが、Mythos Previewでは未設定のままにしても同じ動作になります。Mythos Previewで要約された思考を受け取るには、display: "summarized"を明示的に設定してください。

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

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ブロックが含まれます。

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

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

思考のストリーミング

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

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

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

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

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

Try in Console
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.")

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

Output
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イベントなしでブロックが閉じます。テキストストリーミングはその直後に開始されます。

Output
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に含める必要があります。これは、モデルの推論フローと会話の整合性を維持するために重要です。



以前のassistantロールターンからthinkingブロックを省略することはできますが、マルチターン会話では常にすべての思考ブロックをAPIに渡してください。APIは以下を行います。

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

どのブロックが保持されるかはモデルによって異なります。クラスごとのデフォルトについては、モデル別の思考ブロック保持を参照してください。デフォルトをオーバーライドするには、clear_thinking_20251015コンテキスト編集戦略を使用してください。



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

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

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

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

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

インターリーブ思考

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

インターリーブ思考により、Claudeは以下を行うことができます。

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

モデルサポート:

  • Claude Opus 4.8:適応型思考(Claude Opus 4.8でサポートされている唯一の思考モード)を使用する場合、インターリーブ思考は自動的に有効になります。ベータヘッダーは不要です。
  • Claude Mythos Preview:インターリーブ思考は自動的に行われます。ツール間のすべての推論ステップはプレーンテキストではなく思考ブロックに移動し、思考ブロックはデフォルトでターン間で保持されます。ベータヘッダーは不要であり、サポートもされていません。
  • Claude Opus 4.7:適応型思考(Opus 4.7でサポートされている唯一の思考モード)を使用する場合、インターリーブ思考は自動的に有効になります。ベータヘッダーは不要です。
  • Claude Opus 4.6:適応型思考を使用する場合、インターリーブ思考は自動的に有効になります。ベータヘッダーは不要です。interleaved-thinking-2025-05-14ベータヘッダーはOpus 4.6では非推奨であり、含まれていても安全に無視されます。
  • Claude Sonnet 4.6:適応型思考(推奨)を使用する場合、インターリーブ思考は自動的に有効になります。手動の拡張思考(thinking: {type: "enabled"})とinterleaved-thinking-2025-05-14ベータヘッダーの組み合わせは引き続き機能しますが、非推奨です。
  • その他のClaude 4モデル(Opus 4.5、Opus 4.1(非推奨)、Opus 4(非推奨)、Sonnet 4.5、Sonnet 4(非推奨)):インターリーブ思考を有効にするには、APIリクエストにベータヘッダーinterleaved-thinking-2025-05-14を追加してください。

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

  • インターリーブ思考では、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(非推奨)、Sonnet 4.5、またはSonnet 4(非推奨)以外のモデルにinterleaved-thinking-2025-05-14を渡すと、リクエストは失敗します。

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

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



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

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

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

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

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

以前の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によって生成されたものであることを検証するために使用されます。



思考ブロックを送り返すことが厳密に必要なのは、拡張思考でツールを使用する場合のみです。それ以外の場合は、以前のターンの思考ブロックを省略できます。思考ブロックを渡し戻した場合、APIがそれらを保持するか削除するかはモデルによって異なります。Opus 4.5以降およびSonnet 4.6以降はデフォルトでコンテキストに保持しますが、それより前のOpus/SonnetモデルおよびすべてのHaikuモデルは削除します。この動作を設定するには、コンテキスト編集を参照してください。

思考ブロックを送り返す場合は、一貫性を保ち、潜在的な問題を回避するために、受け取ったとおりにすべてを渡し戻してください。

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

  • レスポンスをストリーミングする場合、署名は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に渡す必要があります。



ツール使用でレスポンスをラウンドトリップする際にコードがコンテンツブロックをタイプでフィルタリングする場合(たとえば、block.type == "thinking")、redacted_thinkingブロックも含めてください。block.type == "thinking"のみでフィルタリングすると、redacted_thinkingブロックが暗黙的に削除され、上記のマルチターンプロトコルが壊れます。



redacted_thinkingブロックは、思考の一部が安全性のために編集された場合にAPIによって返される、別個のコンテンツブロックタイプです。これは、空のthinkingフィールドを持つ通常のthinkingブロックを返すdisplay: "omitted"オプションとは別のものです。

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

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

機能Claude 4モデル(Opus 4.5より前)Claude Opus 4.5Claude Sonnet 4.6Claude Opus 4.6(適応型思考)Claude Opus 4.7(適応型思考)Claude Opus 4.8(適応型思考)Claude Mythos Preview(適応型思考)
思考出力要約された思考を返す要約された思考を返す要約された思考を返す要約された思考を返すデフォルトで省略。要約された思考を受け取るにはdisplay: "summarized"を設定デフォルトで省略。要約された思考を受け取るにはdisplay: "summarized"を設定デフォルトで省略。要約された思考を受け取るにはdisplay: "summarized"を設定。生の思考トークンは返されません。
インターリーブ思考interleaved-thinking-2025-05-14ベータヘッダーでサポートinterleaved-thinking-2025-05-14ベータヘッダーでサポート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に渡し続けてください


以前のモデル(Claude Sonnet 4.5、Opus 4.1(非推奨)など)では、以前のターンの思考ブロックは引き続きコンテキストから削除されます。プロンプトキャッシングと拡張思考セクションで説明されている既存の動作がこれらのモデルに適用されます。

料金

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

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

  • 思考中に使用されたトークン(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の思考能力を最大限に活用したい場合は、拡張思考のプロンプトのヒントを確認してください。

次のステップ

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

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

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

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

Was this page helpful?

  • サポートされているモデル
  • 拡張思考の仕組み
  • 拡張思考の使用方法
  • 要約された思考
  • 思考表示の制御
  • 思考のストリーミング
  • ツール使用と拡張思考
  • 会話中の思考モードの切り替え
  • 思考ブロックの保持
  • インターリーブ思考
  • プロンプトキャッシングと拡張思考
  • 思考ブロックのキャッシング動作の理解
  • 拡張思考での最大トークンとコンテキストウィンドウサイズ
  • 拡張思考でのコンテキストウィンドウ
  • 拡張思考とツール使用でのコンテキストウィンドウ
  • 拡張思考でのトークン管理
  • 思考の暗号化
  • 編集済み思考ブロック
  • モデルバージョン間の思考の違い
  • モデル別の思考ブロック保持
  • 料金
  • 拡張思考のベストプラクティスと考慮事項
  • 思考予算の扱い方
  • パフォーマンスに関する考慮事項
  • 機能の互換性
  • 使用ガイドライン
  • 次のステップ