ai-docs

Thinking

Properties1
tagsthinking, effort, tools, prompt-caching, context, api

11 min read

一行要約

thinking は「thinking ブロックで考えるかどうか」、effort は「応答全体にどれだけ労力を割くか」。混同しやすいが別の軸で、adaptive を effort の値として渡してはいけない。

要点

Thinking has a cost: the tokens Claude spends reasoning are billed as output tokens, even when the thinking text isn’t returned to you, and they count toward max_tokens alongside the response text. thinking にはコストがある。Claude が推論に費やしたトークンは、その思考テキストが返されない場合でも出力トークンとして課金され、応答テキストと合わせて max_tokens を消費する。

設定（モデルによって既定が違う）

モデル既定
Opus 5 / Sonnet 5 / Fable 5 / Mythos 5 / Mythos Previewthinking はすでにオン。設定不要
Opus 4.8 / 4.7 / 4.6 / Sonnet 4.6thinking: {type: "adaptive"} を設定するまでオフ

display — thinking テキストを返すか

値挙動既定のモデル
"summarized"要約された thinking テキストを返すOpus 4.6 / Sonnet 4.6 以前
"omitted"thinking フィールドが空のブロックを返す。signature は暗号化された完全な thinking を保持するFable 5 / Mythos 5 / Opus 5 / Sonnet 5 / Opus 4.8 / Opus 4.7 / Mythos Preview

You’re still charged for the full thinking tokens. Omitting reduces latency, not cost. それでも thinking トークンの全量が課金される。省略が減らすのはレイテンシであって、コストではない。

omitted の主な利点はストリーミング時の time-to-first-text-token が速くなること — サーバが thinking トークンのストリーミングを完全に飛ばす。

summarized についての重要な注意:

  • 返ってくるのは要約であって、生の chain of thought ではない。 どの display 設定でも生の思考は返らない
  • 課金は元のリクエストが生成した完全な thinking トークンに対して行われる（要約のトークン数ではない）。課金される出力トークン数はレスポンスで見えるトークン数と一致しない
  • 要約は、リクエストで指定したモデルとは別のモデルが処理する。thinking したモデルは要約を見ない

thinking と effort の使い分け

目的使うもの
thinking 有効のワークロードでコスト / レイテンシを下げたいまず effort を下げる（応答全体が縮む）
thinking の頻度が低い / 浅いeffort を上げる
thinking を完全に切りたいthinking: {type: "disabled"}
支出に厳密な上限が要るmax_tokens。effort はソフトな指針で、max_tokens は厳密な上限

ツール使用時の2つの制約

1. tool choice の制約（manual モードのみ）

Tool use with manual extended thinking (thinking: {type: "enabled"}) only supports tool_choice: {"type": "auto"} or {"type": "none"}. Adaptive thinking, including on models where thinking is on by default, supports forced tool use. 手動の extended thinking（thinking: {type: "enabled"}）でのツール使用は、tool_choice: {"type": "auto"} か {"type": "none"} しかサポートしない。adaptive thinking は、thinking が既定で有効なモデルも含め、ツール使用の強制をサポートする。

2. thinking ブロックの保持（必須）

Pass every thinking block back to the API complete and unmodified, alongside the tool_use block it accompanied. すべての thinking ブロックを、それが伴っていた tool_use ブロックとともに、完全かつ未改変のまま API へ返せ。

ツール使用ループは1つの assistant ターン。複数のツール呼び出しと結果を含んでも、モデルから見れば1ターン。

扱い
必須ツール使用ターン内では thinking ブロックを返す
推奨ターンをまたいでも全部返す
許容ツール使用の外では過去ターンの thinking を省いてよい

You don’t need to prune old thinking yourself. Pass all thinking blocks back, and the API automatically filters them, keeps the blocks needed, and bills input tokens only for the blocks actually shown to Claude. **古い thinking を自分で刈り取る必要はない。**すべての thinking ブロックを返せば、API が自動的に選別して必要なブロックを保持し、実際に Claude へ見せたブロックのぶんだけ入力トークンを課金する。

改変された thinking ブロックは 400 エラーで拒否される。 例外は omitted ブロックの空の thinking フィールドに置いたテキスト（無視される）。

interleaved thinking

ツール呼び出しの間で考える。adaptive thinking では対応する全モデルで自動（beta header 不要）。Haiku 4.5 は非対応。

Consecutive tool calls do not require interleaved thinking. Interleaving changes where thinking blocks appear between tool calls, not whether tool calls can chain. 連続したツール呼び出しに interleaved thinking は必要ない。interleaving が変えるのは、ツール呼び出しの間のどこに thinking ブロックが現れるかであって、ツール呼び出しを連鎖できるかどうかではない。

モデル別の thinking ブロック保持

挙動モデル
過去ターンを全部保持Opus 4.5 以降の Opus、Sonnet 4.6 以降の Sonnet、Fable 5、Mythos 5、Mythos Preview
直近ターンのみ保持それ以前の Opus / Sonnet、Haiku 4.5 までの全 Haiku。古いブロックを返しても API が自動的に剥がす

保持の利点: ツール使用中のキャッシュヒットを可能にする（assistant ターンをまたいで増分的にキャッシュされる）、知能への悪影響はない。

トレードオフ: keep-all モデルでは長い会話が context を食う。

Switching models mid-conversation: strip thinking and redacted_thinking blocks from prior assistant turns. Other models silently ignore them rather than rejecting the request, but ignored blocks still add input tokens. 会話の途中でモデルを切り替える場合: それ以前の assistant ターンから thinking と redacted_thinking のブロックを取り除け。他のモデルはリクエストを拒否せず黙って無視するが、無視されたブロックも入力トークンとしては加算される。

prompt caching との相互作用

Configuration changes invalidate caching. The thinking configuration and the resolved effort level are rendered into the prompt itself. Switching between adaptive, enabled, and disabled, changing budget_tokens, and changing the effort value all invalidate cache breakpoints. 設定の変更はキャッシュを無効にする。thinking の設定と、解決後の effort レベルはプロンプトそのものにレンダリングされる。adaptive / enabled / disabled の切り替え、budget_tokens の変更、effort 値の変更は、いずれもキャッシュの breakpoint を無効にする。

設定を明示的に既定値にすることは、省略することと等価。

thinking ブロックはツール結果と一緒にキャッシュされる。 これは cache_control を付けなくても自動的に起きる。トレードオフ: レスポンスで二度と見ない thinking ブロックも、キャッシュから読まれるときに入力トークンとして計上される。

Thinking-heavy tasks often take longer than the default 5-minute cache lifetime. Consider the 1-hour cache duration. thinking の重いタスクは、既定の5分というキャッシュ寿命を超えることが多い。1時間のキャッシュ期間を検討せよ。

context window との関係

扱い
現ターンの thinking常に max_tokens に算入、出力トークンとして課金、そのターンの context を占める
過去ターンの thinking保持されるモデルでは context に残り、入力トークンとして課金。剥がされるモデルでは window も入力トークンも消費しない

実務的には:

  • keep-all モデルでは、thinking を通常の会話履歴と同じものとして context 予算を組む。 長い agentic セッションでは thinking が context に蓄積する
  • last-turn-only モデルでは、thinking はターンごとのコストだけ

そのまま使える具体例

thinking を有効にして可視化する（Opus 4.8 など、既定オフのモデル）:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "What is the greatest common divisor of 1071 and 462?"}],
)
 
for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

既定オンのモデル（Opus 5 / Sonnet 5 / Fable 5）で thinking を見たいとき（display の既定が omitted なので）:

thinking={"type": "adaptive", "display": "summarized"}

display: "omitted" のときのレスポンス:

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

ツール使用ループが1ターンであることの図:

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"]

last-turn-only モデルでは、tool result でない user メッセージが来た時点で過去の thinking が全部剥がされる:

実際に送る:
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]

原典で言及されている関連文書

未取得の派生リンク

グラフビュー

バックリンク