ai-docs

Effort

Properties1
tagseffort, thinking, costs, api, agents

9 min read

一行要約

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 "high" produces exactly the same behavior as omitting the parameter entirely. effort を "high" に設定することは、パラメータを完全に省略した場合とまったく同じ挙動になる。

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（既定）高い能力。パラメータ未設定と同じ複雑な推論、難しいコーディング、agentic タスク
medium適度なトークン節約とのバランス速度・コスト・性能のバランスが要る agentic タスク
low最も効率的。能力は多少落ちる単純なタスク、subagent

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

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

モデル推奨
Opus 5high（既定）から始める。 要求の厳しいコーディング / agentic 作業で xhigh、正当化できるときだけ max。品質が保てる範囲で low / medium をトークンコストと応答時間の主要な制御手段として積極的に使う。旧モデルから設定を引き継いでいるなら、eval で effort sweep をやり直す
Opus 4.8 / 4.7コーディングと agentic は xhigh から始める。 他の知能重視のワークロードは high を最低線に。max は本当に frontier な問題にだけ
Sonnet 5既定は high。最難のコーディング / agentic に xhigh。medium は「Sonnet 4.6 の high 相当」のコスト削減段
Sonnet 4.6medium を推奨既定に。 既定は high なので、予期しないレイテンシを避けるため明示的に設定する
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 トークンから始めてそこから調整するのが妥当な既定である。

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

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

ツール使用との関係

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

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

output_config.effort is a request-level setting. Because effort shapes the rendered prompt, changing it between requests does not preserve cached prefixes from earlier turns. output_config.effort はリクエスト単位の設定である。effort はレンダリングされるプロンプトを形づくるため、リクエスト間でこれを変えると、以前のターンのキャッシュ済み prefix は保たれない。

Hold effort constant within cached conversations. Vary effort across workloads rather than within a conversation that relies on cache hits. キャッシュを効かせている会話の中では、effort を一定に保て。effort を振るのは、キャッシュヒットに依存する会話の中ではなく、ワークロードをまたいで行え。

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.

判断のフロー:

既定は high（= 未設定と同じ）
  ↓ コーディング / agentic で足りない
xhigh（max_tokens を 64k 以上に）
  ↓ eval で headroom が測れた場合のみ
max
  ↓ 品質が保てることを eval で確認した場合
medium / low を積極的に使う（コストとレイテンシの主要な制御手段）

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

未取得の派生リンク

グラフビュー

バックリンク