ai-docs

Effort

Properties1
tagseffort, thinking, costs, api, agents

原典: Effort ／ 日本語版

一行要約

effort は thinking の有無に関わらず、応答内のすべてのトークン（テキスト・ツール呼び出し・thinking）に効く単一のダイヤル。thinking を有効にする必要がなく、低くするとツール呼び出しの回数自体が減るのが budget_tokens との決定的な違い。

要点

The effort parameter affects all tokens in the response: text responses and explanations, tool calls and function arguments, and thinking (when active).

effort パラメータは応答内のすべてのトークンに影響する。テキストの応答と説明、ツール呼び出しと関数の引数、そして（有効なときは）thinking である。

利点は2つ。① thinking を有効にする必要がない ② ツール呼び出しを含む全トークン支出に効く。

Setting effort to the model’s default ("medium" on Claude Opus 5.5, "high" on other models) produces exactly the same behavior as omitting the effort parameter entirely.

effort をそのモデルの既定値（Claude Opus 5.5 では "medium"、他のモデルでは "high"）に設定することは、effort パラメータを完全に省略した場合とまったく同じ挙動になる。

「省略 = high」は Opus 5.5 では成り立たない（以前の取得ではまだ "high" と書かれていた）。Opus 5 から Opus 5.5 に替えただけで、effort を書いていないリクエストは1段低く走る。

Effort is a behavioral signal, not a strict token budget. At lower effort levels, Claude will still think on sufficiently difficult problems, but it will think less.

effort は振る舞いのシグナルであって、厳密なトークン予算ではない。低い effort でも、Claude は十分に難しい問題については考える。ただし考える量は減る。

5段階

レベル内容典型的な用途
maxtoken 支出に制約なしの最大能力最も深い推論が要るタスク
xhigh長時間作業向けの拡張能力30分を超える長時間の agentic / coding タスク、トークン予算が数百万規模
high課題が必要とするだけトークンを使う。Opus 5.5 以外の全モデルで既定複雑な推論、難しいコーディング、agentic タスク
medium適度なトークン節約とのバランス。Opus 5.5 の既定速度・コスト・性能のバランスが要る agentic タスク
low最も効率的。能力は多少落ちる単純なタスク、subagent

xhigh は新しいレベルなので、max に対応していても xhigh に対応していないモデルがある。

モデル別の推奨（この文書の実質的な中身）

モデル推奨
Opus 5.55段階すべてに対応し、既定は medium（Opus 5 以前の Opus は high なので、effort を省いたリクエストは Opus 5 のときより1段低く走る）。adaptive thinking が常にオンで切れないので、effort が推論量とコストの主要な制御手段。旧モデルの設定を持ち越さず自分の eval で effort sweep を回す。高いレベルでは max_tokens を大きく。thinking: {"type": "disabled"} はどの effort でも 400。会話の途中で effort を変えられる（下記）
Opus 5high（既定）から始める。 要求の厳しいコーディング / agentic 作業で xhigh、正当化できるときだけ max。品質が保てる範囲で low / medium をトークンコストと応答時間の主要な制御手段として積極的に使う。旧モデルから設定を引き継いでいるなら、eval で effort sweep をやり直す
Opus 4.8 / 4.7コーディングと agentic は xhigh から始める。 他の知能重視のワークロードは high を最低線に。max は本当に frontier な問題にだけ
Sonnet 5.55段階すべてに対応し、Claude API での既定は high（Claude Code の既定は medium —— model-config）。レベルは較正し直されているので、Sonnet 5 の設定を持ち越さず eval で effort sweep をやり直す。 agentic でも遅延に敏感でもなければ high から。agentic なコーディングと多段のツール使用は、仕様が明確なタスクなら medium、難しい・長いタスクなら high。チャットなど遅延に敏感な作業は medium か low。xhigh / max は eval で品質が上がるところだけ。max_tokens には thinking と返答の余地を取る（agentic コーディングならモデル上限の 128,000 にしてストリーミング）。事前の thinking を切るのは "disabled" ではなく thinking: {"type": "between_tools"}（low / medium / high でだけ動く。xhigh / max では adaptive を使う）
Sonnet 5既定は high。最難のコーディング / agentic に xhigh。medium は「Sonnet 4.6 の high 相当」のコスト削減段
Sonnet 4.6medium を推奨既定に。 既定は high なので、予期しないレイテンシを避けるため明示的に設定する
Fable 5.1 / Mythos 5.15段階すべてに対応。high（既定）から。能力が要る agentic / coding は xhigh か max、eval で品質が保てると分かってから routine / レイテンシ重視を medium / low に落とす。会話の途中で effort を変えられる（下記）
Fable 5 / Mythos 5effort が知能・レイテンシ・コストのトレードオフの主要な制御手段。 high（既定）から。低い設定でも旧モデルの xhigh を上回ることが多い

Opus 4.7 以降の重要な性質:

Claude Opus 4.7 also respects effort levels more strictly than Claude Opus 4.6. At lower effort levels, the model scopes its work to what was asked rather than doing more than requested. If you observe shallow reasoning on complex problems, raise effort rather than prompting around it.

Claude Opus 4.7 は Claude Opus 4.6 より effort レベルを厳密に尊重する。低い effort では、モデルは求められた以上のことをせず、依頼された範囲に作業を限定する。複雑な問題で推論が浅いと感じたら、プロンプトで回避しようとせず、effort を上げよ。

レイテンシのために低く保つ必要があるなら、This task involves multistep reasoning. Think carefully before responding. のような的を絞った指示を足す。

When running at xhigh or max effort, set a large max_tokens so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default.

xhigh や max の effort で走らせるときは、max_tokens を大きく取れ。subagent やツール呼び出しをまたいで考え、動くための余地が要る。64k トークンから始めてそこから調整するのが妥当な既定である。

max_tokens は thinking と応答テキストを合わせた総出力の hard limit である（high 以上では大きく取る）。

Opus 5 の制約: xhigh / max では thinking を無効にできない（thinking: {"type": "disabled"} を送ると 400）。

Opus 5 の注意: effort は thinking の量を制御するのであって、可視の応答長は制御しない。 短くしたいなら prompt で指定する。

ツール使用との関係

低い effort高い effort
複数の操作を少ないツール呼び出しにまとめるツール呼び出しが増える
呼び出し回数が減る行動前に計画を説明する
前置きなしに行動へ進む変更の詳細な要約を出す
完了後の確認メッセージが簡潔コードコメントが充実する

prompt caching との相互作用（見落としやすい）

The top-level output_config.effort applies to the whole request. To run a later part of a conversation at a different level, set the new value on the next request. Because top-level effort shapes the rendered prompt, changing it between requests doesn’t preserve cached prefixes from earlier turns.

top-level の output_config.effort はリクエスト全体に効く。会話の後半を別のレベルで走らせるには、次のリクエストで新しい値を設定する。top-level の effort はレンダリングされるプロンプトを形づくるため、リクエスト間でこれを変えると、以前のターンのキャッシュ済み prefix は保たれない。

Hold top-level effort constant within cached conversations: Changing the top-level effort value between requests invalidates prompt caching, so vary it across workloads rather than within a conversation that relies on cache hits. On models that support it, use a per-message effort change instead, which preserves the cache.

キャッシュを効かせている会話の中では、top-level の effort を一定に保て。リクエスト間で top-level の値を変えると prompt caching が無効になるので、effort を振るのはキャッシュヒットに依存する会話の中ではなくワークロードをまたいで行う。対応しているモデルでは、代わりに per-message の effort 変更を使え。そちらはキャッシュを保つ。

この「一定に保て」は top-level の話で、逃げ道がある。下記の per-message effort なら会話の途中で変えてもキャッシュが残る。

会話の途中で effort を変える

変え方は2つあり、キャッシュが残るかどうかが違う。

On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, and Claude Sonnet 5.5, use a per-message effort change, which keeps the prompt cache. On other models, set a new top-level value on the next request, which starts the cache over.

Claude Fable 5.1・Claude Mythos 5.1・Claude Opus 5.5・Claude Opus 5・Claude Sonnet 5.5 では per-message の effort 変更を使う。これは prompt cache を保つ。それ以外のモデルでは次のリクエストで新しい top-level の値を設定する。こちらはキャッシュをやり直すことになる。

per-message 側は beta。ヘッダ mid-conversation-output-config-2026-07-01 が要る。Sonnet 5.5 で between_tools を使っているときは、会話の途中で effort を変えられない（その時点のレベルと違う per-message の output_config.effort は 400）。ターンごとに変えたいなら adaptive thinking にする。

Add a role: "system" message with empty content and the new level in output_config.effort. The new level takes effect from the next user turn and holds until a later message changes it. Everything before that message is unchanged, so the cached prefix still matches.

content が空の role: "system" メッセージを足し、新しいレベルを output_config.effort に入れる。新しいレベルは次の user ターンから効き、後のメッセージが変えるまで持続する。そのメッセージより前は何も変わらないので、キャッシュ済みの prefix は依然として一致する。

対応していないモデル（Fable 5 を含む）は 400 を返す —— output_config.effort requires a model that supports per-turn effort; this model does not。

effort だけの system メッセージは本文を持たないので、mid-conversation system メッセージの配置制限は適用されない。messages のどこに置いてもよい。

top-level を変える方式が劣るのはキャッシュだけではない。

A top-level change restarts the cache and also steers the model less reliably: its earlier replies were written at the previous level, and it tends to stay consistent with them.

top-level の変更はキャッシュをやり直すだけでなく、モデルの誘導としても信頼性が落ちる。以前の返答は前のレベルで書かれており、モデルはそれと一貫していようとする傾向がある。

adaptive を effort の値として渡してはいけない — adaptive は thinking のモードであって effort のレベルではない。

そのまま使える具体例

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Analyze the trade-offs between microservices and monolithic architectures"}
    ],
    output_config={"effort": "medium"},
)
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "..."}],
    "output_config": {"effort": "medium"}
  }'

xhigh / max を使うときの max_tokens:

output_config={"effort": "xhigh"},
max_tokens=64000,   # 64k から始めて調整する

低い effort で推論の浅さが問題になったときの当て木:

This task involves multistep reasoning. Think carefully before responding.

判断のフロー:

  1. 既定は high（= 未設定と同じ）。Opus 5.5 だけは既定が medium なので、high が要るなら明示する
  2. コーディング / agentic で足りないなら xhigh（max_tokens を 64k 以上に）
  3. eval で headroom が測れた場合のみ max
  4. 品質が保てることを eval で確認できたら、medium / low を積極的に使う（コストとレイテンシの主要な制御手段）

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

バックリンク