Claude API の思考機能は、2世代にわたって設計思想が大きく変わっています。単なる機能追加ではなく、「コスト制御の主体がユーザーからモデルへと移っていく」という方向性の転換が起きています。

第1世代：budget_tokens によるユーザー主導の制御

初期の拡張思考は、開発者が思考トークン数の上限を明示的に指定する方式でした。

thinking={"type": "enabled", "budget_tokens": 10000}

この設計は直感的ですが、いくつかの課題がありました。「このタスクには何トークン必要か」を事前に見積もることは難しく、固定予算では簡単なリクエストにもトークンを消費してしまいます。また、思考以外のトークン（テキスト出力・ツール呼び出し）は別途制御が必要でした。

第2世代：effort による Claude 主導の適応

現在の推奨方式では、開発者は「方向性」だけを示し、具体的なトークン配分は Claude が決めます。

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "..."}],
)

effort は high（デフォルト）を基準に、low から max までのレベルで指定します。Claude はそのレベルをガイドとして、思考量・テキストの詳細さ・ツール呼び出し回数を総合的に調整します。

なぜこの設計になったのか

公式ドキュメントでは二峰性タスク（簡単なものと難しいものが混在するワークロード）への対応が理由として挙げられています。たとえば「今日の天気は？」と「この数学の証明を検証して」が混在するエージェントに固定予算を設定すると、前者では予算が無駄になり、後者では不足します。

adaptive thinking では、簡単なリクエストには思考をスキップし（medium や low effort の場合）、難しいリクエストには深く思考する動作が自動で実現されます。開発者は「effort の方向性」だけを決め、タスクごとの配分判断はモデルが行います。

この設計の実用的なメリットとして、「API の利用者がトークノミクスを細かく管理しなくてよい」という点も重要です。エージェントのパイプラインで effort: "high" と書くだけで、単純なステップも複雑なステップも適切な深さで処理されます。

インターリーブ思考が自動化

もう一つの変化はインターリーブ思考（ツール呼び出しの間でも思考できる機能）の扱いです。extended thinking でインターリーブを使うには interleaved-thinking-2025-05-14 というベータヘッダーが必要でしたが、adaptive thinking では自動で有効になります。

ツール呼び出しの結果を受け取って、次のアクションを決める前に改めて推論できるため、エージェントワークフローの品質が向上します。特にマルチステップのデータ収集や複数ツールを組み合わせた処理で、前ターンの結果を踏まえて戦略を調整できる点が有効です。

次世代（Fable 5 / Mythos 5）の方向性

Fable 5 / Mythos 5 では思考が常にオンになり、thinking パラメータで有効・無効を切り替えることができなくなります。「思考するかどうか」ではなく「どれくらい思考するか（effort）」だけを制御する設計への移行です。これは「すべてのリクエストで思考を活用する」という方向性を示しています。

移行のポイント

Opus 4.8 / 4.7 では budget_tokens を指定した type: "enabled" が 400 エラーになります。これらのモデルを使う場合は、adaptive thinking + effort への移行が必須です。Opus 4.6 / Sonnet 4.6 では両方が動作しますが、budget_tokens は非推奨です。

まとめ

  • 第1世代：budget_tokens でトークン上限をユーザーが指定。思考専用
  • 第2世代：effort でレベルを示し、Claude がトークン配分を決定。思考・テキスト・ツール全体に影響
  • 二峰性タスクや長いエージェントループでは adaptive thinking が効率的
  • インターリーブ思考が adaptive では自動で有効になる点がエージェント開発で重要
  • Fable 5 / Mythos 5 では思考が常にオン。「有効化するかどうか」の概念自体がなくなる