effort パラメータを工程ごとに振り分けて Claude の出力コストと待ち時間を整える

Before / After：一律 high をやめて工程別に振り分ける

まず、私が以前書いていた呼び出しです。どの工程でも同じヘルパーを通していました。

import anthropic
 
client = anthropic.Anthropic()  # ANTHROPIC_API_KEY を環境変数で読む
 
def call_claude(prompt: str) -> str:
    # すべての工程がこれを通る = すべて既定の high
    resp = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=4096,
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.content[0].text

このコードの問題は、コードを読んだだけでは見えません。請求とレイテンシを見て初めて分かります。カテゴリ判定のような軽い処理まで、毎回じっくり考える設定で動いていました。

次が、工程ごとに effort を渡せるように直したものです。変更は引数を1つ足すだけで、モデルは据え置きです。

import anthropic
from typing import Literal
 
client = anthropic.Anthropic()
 
Effort = Literal["low", "medium", "high", "xhigh", "max"]
 
def call_claude(prompt: str, effort: Effort = "high", max_tokens: int = 4096) -> str:
    resp = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=max_tokens,
        messages=[{"role": "user", "content": prompt}],
        output_config={"effort": effort},  # ここが効率制御の本体
    )
    return resp.content[0].text
 
# 工程ごとに意図を込めて呼ぶ
category = call_claude(classify_prompt, effort="low", max_tokens=256)
draft    = call_claude(draft_prompt,    effort="medium")
review   = call_claude(review_prompt,   effort="high")

output_config={"effort": ...} がパラメータの正式な渡し方です。ベータヘッダーは不要で、対応モデルならそのまま使えます。effort="high" は未指定と同義なので、既存コードの挙動を変えずに「下げたい工程だけ下げる」という安全な移行ができます。

工程をどう分類して effort を割り当てるか

振り分けの設計は、工程を「品質が効く度合い」で並べることから始めます。私のパイプラインでは、おおむね次の対応に落ち着きました。

判断の軸はシンプルで、「ここで品質を1段落としたら、後工程の手戻りや読者の不利益がどれだけ出るか」です。分類を間違えてもやり直しは安いので low に倒します。逆に、公開前の整合チェックでの見落としは記事そのものの信頼を損なうので、ここはコストより品質を優先して high に置きます。Opus 4.7 以降は低い effort のとき「頼まれた範囲に作業を絞る」傾向が強まっているため、複雑な工程を安易に下げると浅い結果になります。下げるなら計測してから、が原則です。

Opus 4.8 では adaptive thinking と組み合わせる

Opus 4.8 を使う場合、思考の制御方法が以前と変わっている点に注意が必要です。Opus 4.8 は adaptive thinking（モデルが必要に応じて思考量を自分で決める方式）を採用していて、手動の budget_tokens 指定は受け付けません。

# ❌ Opus 4.8 では 400 エラーになる
resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    thinking={"type": "enabled", "budget_tokens": 4000},  # 非対応
    messages=[{"role": "user", "content": prompt}],
)
 
# ✅ adaptive thinking を有効にし、深さは effort で寄せる
resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": prompt}],
)

thinking={"type": "adaptive"} を付けて初めて思考が有効になり、付けなければ思考なしで走ります。そのうえで high・xhigh・max ではほぼ常に深く考え、低いレベルでは簡単な問題で思考を省く、という調整になります。budget_tokens の感覚で書き続けると 400 で弾かれて気づく、というのが移行時にありがちな躓きです。

ツールを使うエージェントでの効き方

effort はツール呼び出しの「回数」と「饒舌さ」の両方を動かします。これはエージェントのコストに直結するので、振り分けの効果が最も体感しやすい場面です。

低い effort では、複数の操作を1回の呼び出しにまとめ、前置きなしで動き、終了報告も短くなります。高い effort では、計画を説明し、ツールを細かく呼び、変更点を丁寧に要約します。たとえば「ログを読んで原因を1つ特定する」程度の定型的なエージェント処理なら medium で十分なことが多く、xhigh にすると探索が増えてコストだけ膨らむことがあります。逆に、未知のコードベースを横断して調べるような探索的な作業は xhigh が向きます。xhigh や max で走らせるときは、思考とツール呼び出しが伸びる分、max_tokens を大きめ（まず 64k あたり）に取っておくと途中で頭打ちになりません。

入力に応じてレベルを選ぶ動的ルーター

工程が固定なら定数で割り当てれば済みますが、同じ工程でも入力の難しさが揺れる場合は、軽い前段で effort を選ぶと無駄が減ります。私は次のような薄いルーターを挟んでいます。

from dataclasses import dataclass
 
@dataclass
class Task:
    kind: str          # "classify" | "draft" | "review" | "redesign"
    input_len: int     # 入力文字数の目安
    high_stakes: bool  # 失敗が後工程に響くか
 
def pick_effort(task: Task) -> str:
    # 1) 工程の性質で土台を決める
    base = {
        "classify": "low",
        "draft": "medium",
        "review": "high",
        "redesign": "xhigh",
    }.get(task.kind, "high")
 
    # 2) 失敗コストが高い工程は1段引き上げる
    if task.high_stakes and base in ("low", "medium"):
        base = "medium" if base == "low" else "high"
 
    # 3) 入力が極端に短いなら、重い工程でも1段下げて様子を見る
    if task.input_len < 400 and base in ("high", "xhigh"):
        base = "high" if base == "xhigh" else "medium"
 
    return base
 
# 使用例
effort = pick_effort(Task(kind="review", input_len=120, high_stakes=False))
result = call_claude(review_prompt, effort=effort)

ポイントは、ルーター自体に Claude を使わないことです。ここで判定にもう1回 API を呼ぶと、節約したかったコストを判定で食い潰します。文字数や工程名のような安いシグナルで土台を決め、必要なら1段だけ動かす。この「安く決めて、確信があるときだけ動かす」割り切りが、運用で効きます。

下げる前に計測する

effort を下げる判断は、印象ではなく自分のデータでやってください。本番運用に入れる前に、同じプロンプト群を effort 違いで流して比べる、という手順を踏むことをお勧めします。

1. 対象の工程を1つだけ選び、high と1段下のレベルで同じ入力を流します。
2. 出力トークン・所要時間・品質（自分の合否基準での通過率）を並べて記録します。
3. 品質が基準を割らなければ採用し、割るなら1段戻す——この判断を工程ごとに残します。

この手順を踏まずにいきなり全工程を下げるのは、品質が静かに落ちる落とし穴です。特に注意点として、整合チェックのような見落としが致命的になる工程では、コスト削減を急がず high に据え置くことを推奨します。逆に、軽い工程で品質が保てたなら、迷わず下げて構いません。下げて問題が出たときに1段戻せる記録さえあれば、回避は簡単だからです。

私の小さなパイプラインでの体感を正直に書くと、分類・タグ抽出のような軽い工程を high から low に落としたとき、その工程の出力トークンは目に見えて減り、待ち時間も短くなりました。一方で、整合チェックを medium に落としたときは見落としがわずかに増えたため、そこは high に戻しました。数字は私の題材・プロンプト・記事の傾向に強く依存するので、ここで「何割減った」と一般化して書くことはしません。大切なのは、工程ごとに「下げてよかったか」を自分の基準で確かめる手順を持つことです。

最初の一歩はとても小さくできます。いちばん高頻度で、いちばん軽い工程を1つ選び、そこだけ output_config={"effort": "low"} を足してみてください。モデルもプロンプトも変えずに、その工程のコストと待ち時間が動くのを確かめる——そこから、自分のパイプラインに合った段階配分が見えてきます。

同じように自動運用のコストと向き合っている方の参考になれば幸いです。