ホーム / チュートリアル / effort パラメータで思考の深さとコストを調整する

effort パラメータで思考の深さとコストを調整する

Claude API エンジニアリング 7分で読めます

Claude API の effort は、モデルがどれだけ深く考え、どれだけトークンを使うかを5段階で指定するパラメータです。ベータヘッダは不要で、現行モデルでは正式機能（GA）として使えます。品質とコストとレイテンシのバランスを1つの値で動かせるため、実運用でもっとも費用対効果の大きい調整点になります。本記事は公式の仕様を日本語で整理した非公式の解説です。

effort とは何か

effort は「このリクエストにどれだけ手間を掛けてよいか」をモデルに伝える指定です。指定できる値は low / medium / high / xhigh / max の5段階で、省略時の既定値は high です。つまり何も指定しなければ high で動いています。

effort が動かすのは思考の深さだけではありません。全体のトークン消費に効き、結果として振る舞いそのものが変わります。低い値ではツール呼び出しの回数が減って1回にまとまり、前置きが短くなり、確認の応答も簡潔になります。高い値では逆に、答える前の調査や検証に時間を掛けるようになります。

注意したいのは、これが「出力の長さを決めるつまみ」ではないという点です。とくに Claude Opus 5 では、effort を下げても利用者に見える応答の長さは確実には短くなりません。応答を短くしたいのであれば、effort ではなくプロンプトで指示するのが正しい方法です。

5段階のレベルと使い分け

公式に示されている目安は次のとおりです。

ただし、この表をそのまま固定値として運用するのは勧められません。effort は自分の評価セットで振ってみて決める軸です。関係は単調ではなく、エージェント的な作業では最初に高い effort を使うほうがターン数が減って総コストが下がることがあり、逆にタスクによっては medium でも同等の結果がより短時間で得られます。

Claude Opus 5 では特にこの傾向が強く、コーディングやエージェント用途は xhigh、それ以外の知性が要る作業は high から始め、そこから下げていく手順が案内されています。low と medium が想定以上に強いため、前のモデルから引き継いだ effort の既定値はたいてい最適ではありません。

低い側では effort が厳密に守られる点も押さえておく必要があります。low や medium では要求された範囲に作業を限定するので、そこそこ複雑なタスクを low で回すと考察が浅くなる危険があります。浅い推論が見えたら、プロンプトで補うより high や xhigh へ上げるほうが確実です。

基本的な使い方

effort は output_config の中に入れます。トップレベルのパラメータではありません。ここを間違えるのがもっとも多いつまずきです。

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},   # low | medium | high | xhigh | max
    messages=[{"role": "user", "content": "..."}],
)

TypeScript でも同じ構造です。

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

ベータヘッダは要りません。かつて必要だった effort-2025-11-24 は現行モデルでは正式機能になっているため、残っていれば外してよく、外したあとは client.beta.messages.create から通常の client.messages.create に戻せます。

モデル別の対応状況

使える段階はモデルによって違います。xhigh は Claude Opus 4.7 で追加された値なので、それより前のモデルにはありません。

手元のモデルが何に対応しているかは、Models API で実際に問い合わせるのが確実です。上記の表は更新のたびに古くなりますが、API の応答は現在の値を返します。

m = client.models.retrieve("claude-opus-5")
m.capabilities["effort"]["max"]["supported"]   # True / False

世代をまたいで比べるときは、レベル名をそのまま突き合わせないほうがよいという点も重要です。目安として、Claude Sonnet 5 の medium は Claude Sonnet 4.6 の high に、Claude Sonnet 5 の high は Claude Sonnet 4.6 の max に近い知性だとされています。ベンチマークを取るなら、名前ではなく観測された思考の長さで揃えてください。

thinking との関係

effort は思考（thinking）と組み合わせて使います。現行モデルでは thinking: {"type": "adaptive"} を指定し、深さの調整を effort に任せるのが基本形です。かつての budget_tokens（思考トークンの固定予算）は Claude Opus 5 / Fable 5 / Opus 4.8 / Opus 4.7 / Sonnet 5 では削除済みで、送ると 400 エラーになります。effort は budget_tokens の後継ではなく、出力全体のレベル指定なので、1対1で対応する値はありません。

Claude Opus 5 には、両者の組み合わせに関する制約が1つあります。思考を切る指定（thinking: {"type": "disabled"}）が使えるのは effort が high 以下のときだけで、xhigh または max と併用すると 400 エラーになります。しかも検証はリクエストごとに独立して行われるため、同じ会話の途中で effort を xhigh へ上げた回だけが弾かれることがあります。呼び出し箇所を一通り確認しておくのが安全です。

この制約に当たったら、思考を有効に戻すか、effort を high 以下へ下げるかのどちらかです。Claude Opus 5 は低い effort でも十分に強いので、レイテンシ重視で以前 xhigh と思考オフを組み合わせていた経路は、medium と思考オンに置き換えたほうがたいてい良い結果になります。

なお、思考が働く頻度そのものが多すぎると感じる場合（システムプロンプトが大きいと起こりやすい）は、effort ではなくプロンプトで抑えられます。「思考はレイテンシを増やすので、多段の推論が要る問題など、回答品質が明確に上がるときだけ使うこと。迷ったら直接答えること」といった指示が効きます。

max_tokens との組み合わせ

max_tokens は思考と応答テキストを合わせた出力全体の上限です。effort を上げると思考にトークンを使うため、max_tokens が窮屈だと応答が途中で切れます。症状としては stop_reason が max_tokens になり、ほとんど思考だけで終わった応答が返ります。

目安として、xhigh や max を使うなら max_tokens は 64000 以上から始めます。ツール呼び出しやサブエージェントをまたいで考え、動く余地を持たせるためです。そこから実測して詰めていきます。

そのくらいの max_tokens を指定する場合はストリーミングが前提になります。非ストリーミングだと SDK の HTTP タイムアウトに掛かるためで、目安として 16000 を超えるならストリーミングに寄せてください。

with client.messages.stream(
    model="claude-opus-5",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
) as stream:
    response = stream.get_final_message()

ループ全体の消費に上限を掛けたいのであれば、effort とは別に task_budget という仕組みがあります。effort が1回あたりの深さを決めるのに対し、task_budget は累積の予算をモデルに知らせるものです。使い分けはタスクバジェットの解説にまとめています。

よくある間違い

実際に踏みやすい点を挙げます。

最後に、実務での進め方をまとめます。まずコーディングやエージェント用途なら xhigh、それ以外の知性が要る作業は high から始めます。次に自分の評価セットで medium と low まで振り、品質が保てる範囲で下げます。max は極端に難しくレイテンシを気にしない場合に取っておく、という順番です。

関連チュートリアル / 次に読む

Claudeの拡張思考（Extended Thinking）を使う Claude API のタスクバジェット 使い方 コストを効果的に管理する 適切なClaudeモデルの選び方：Haiku、Sonnet、Opus Claudeモデルの移行ガイド
← チュートリアル一覧へ戻る カテゴリで探す