budget_tokens と effort はどちらも Claude の応答の「重さ」を調整するパラメータですが、影響範囲と使い方が根本的に異なります。
budget_tokens とは
budget_tokens は extended thinking 専用のパラメータで、思考に使えるトークンの上限数を直接指定します。
# extended thinking（古いモデル向け）
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=16000,
thinking={"type": "enabled", "budget_tokens": 10000},
messages=[{"role": "user", "content": "..."}],
)
影響するのは思考トークンのみです。テキスト出力の長さやツール呼び出し回数には影響しません。Opus 4.6 / Sonnet 4.6 では非推奨扱いとなっており、Opus 4.8 / 4.7 では 400 エラーになります。
budget_tokens を使うモデルでは最小値の制約があります。Opus 4.6 / Sonnet 4.6 では最低 1,024 トークン、Opus 4.5 以前では最低 4,096 トークン必要です。
effort とは
effort は output_config に指定するパラメータで、応答内のすべてのトークンに影響します。
# adaptive thinking + effort（最新モデル向け）
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=32000,
thinking={"type": "adaptive"},
output_config={"effort": "medium"},
messages=[{"role": "user", "content": "この設計の問題点を分析してください。..."}],
)
影響範囲はテキスト応答・ツール呼び出しとその引数・拡張思考（有効な場合）すべてです。Sonnet 4.6 では medium がデフォルトとして推奨されます。
最大の違い：effort は思考を有効にしなくても使える
effort は thinking パラメータなしで単独で使用できます。たとえばシンプルな分類タスクに effort: "low" を指定すれば、思考なしで応答が短く・速くなります。
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
messages=[{"role": "user", "content": "この文章を要約してください。..."}],
output_config={"effort": "low"},
)
effort が低いと起きること
直感的でないポイントとして、effort: "low" にすると次のような変化が起きます。
- ツール呼び出し回数が減る・複数操作をまとめる
- 前置き説明が短くなる（または省略される）
- コードコメントが減る
「低コストで高速」ではありますが、複雑なタスクでは品質が落ちることがあります。サブエージェントや大量処理に向いています。
effort レベル早見表
| レベル | 説明 | 主な用途 |
|---|---|---|
low |
高速・低コスト・能力低下あり | サブエージェント・大量処理 |
medium |
バランス型 | エージェント的タスク全般（Sonnet 4.6 推奨デフォルト） |
high |
デフォルト。省略時と同等 | 複雑な推論・コーディング |
xhigh |
長時間エージェント向け | 30分超のエージェントタスク・Opus 4.8 / 4.7 |
max |
制約なしの最大能力 | フロンティア問題 |
xhigh は「数百万単位のトークン予算を使い、30分以上継続するエージェント的タスク」を想定しています。Fable 5 / Mythos 5 でも利用可能です。xhigh および max を使用する場合は max_tokens を 64,000 以上に設定することが推奨されます。
まとめ
budget_tokens：思考トークンの上限を数値指定。思考にのみ影響。新しいモデルでは非推奨または非対応effort：思考・テキスト・ツール呼び出しすべてに影響するレベル指定effortは思考を有効にしなくても使える点が大きな違い- Opus 4.8 では
budget_tokensは 400 エラーになるため、effort+ adaptive thinking への移行が必須 xhighは長時間エージェントタスク専用で、max_tokens: 64000以上を推奨