エージェントをある程度の規模で運用した最初の月に、1,400ドルを費やしてしまいました。そのほとんどは無駄でした。難しい問題を懸命に考えるモデルへの費用ではなく——それは有意義な出費です——問題だったのは、キャッシュなしで毎回同じ40Kトークンのシステムプロンプトを送信し、すべてを最大Effortで実行し、ファイルのgrepにOpusを使っていたことです。純粋な漏れです。
目標は、エージェントを愚かにすることでコストを下げることではありません。小さいモデルに切り替えてコスト管理と呼ぶことは誰でもできます。目標は無駄を省き、重要なところに知性を保つことです。お金が実際にどこへ行くのか、そしてそれぞれの漏れをどう塞ぐかをお伝えします。
プロンプトキャッシングは最大のレバー
大きくて安定したシステムプロンプトとツールセットを持つエージェントを実行していて、cache_read_input_tokens がゼロであれば、お金を燃やしています。キャッシングはプレフィックスマッチです——APIはブレークポイントまでレンダリングされたプロンプトをキャッシュし、読み取りコストはフル入力価格の約10分の1です。
落とし穴：プレフィックスのどこかでバイトが変わると、それ以降のすべてが無効になります。典型的な犯人はシステムプロンプト内のタイムスタンプです。
system = f"You are an agent. Current time: {datetime.now()}" # cache dead on arrival
この datetime.now() によって、すべてのリクエストがユニークなプレフィックスになります。何もキャッシュされません。タイムスタンプ、リクエストID、実際の質問などの揮発性の要素は、最後のキャッシュブレークポイントの後ろに移動させましょう。システムプロンプトとツールリストは固定してバイト単位で同一に保ちます。
動作確認の方法：繰り返しリクエスト全体で usage.cache_read_input_tokens を確認します。大きな数字であればキャッシュできています。ゼロであれば、2つのレンダリングされたプロンプトを比較して変化しているバイトを見つけます。常に何か馬鹿げたもの——ソートされていないJSONダンプ、UUID、日付——が原因です。長いエージェントセッションでは、$4のランと$0.40のランの違いになり、出力品質には何も影響しません。タダのお金です。
ルートごとにEffortを調整し、すべてを最大にしない
effort パラメーターはモデルがどれだけ深く考えるかを制御します。直感的には、エージェントができるだけ賢くなるよう max にしたくなります。間違った直感です。現在のOpusモデルでは、ほとんどの作業にとって high がスイートスポットで、max は多くの場合、考えすぎのために余分なトークンを燃やすだけで収益は逓減します。
さらに重要なのは、エージェントループのすべてのステップが同じ思考力を必要としないということです。分類ステップ、「どのファイルを見るべきか」という決定、yes/noゲートなどは low または medium でも問題なく動きます。high と xhigh は実際の難しい推論と長期計画のために取っておきましょう。
# cheap gate
client.messages.create(model="claude-opus-4-8", output_config={"effort": "low"}, ...)
# the real work
client.messages.create(model="claude-opus-4-8", output_config={"effort": "high"}, ...)
自分のevalセットでEffortスイープを実行——medium、high、xhigh——したところ、ほとんどのルートで high が xhigh と同等の品質を達成し、トークン消費は明らかに少なかったことがわかりました。測定するまで自分の数字はわかりません。恐れから最大をデフォルトにしないでください。
安い作業にはサブエージェント
これはコスト面でもキャッシング面でも効果的なトリックです。安い部分タスク——ディレクトリの探索、ファイルの要約、grepなど——が必要な場合、高価なメインループでインラインに実行しないでください。より安いモデルでサブエージェントを起動しましょう。
キャッシング上のメリットもある理由：会話の途中でモデルを切り替えるとキャッシュが無効になります。キャッシュはモデルスコープだからです。grepのためにメインループをOpusからHaikuに下げて戻すと、プレフィックスキャッシュを2回破壊したことになります。サブエージェントはメインループを1つのモデルと1つのキャッシュに保ちながら、安い作業はHaikuで別に処理します。Claude Code はまさにこれを行っています——ExploreサブエージェントはHaikuで動作するのはまさにこのためです。
長いランのためのコンテキスト編集とコンパクション
長いエージェントセッションでは、古いツール結果と古い思考ブロックが蓄積されます。毎ターン、それらすべてをフル入力価格で再送信します。2つのツールでこれを解決できます。
コンテキスト編集は、モデルが見る前にトランスクリプトから古いツール結果を削除します。コンパクションは、ウィンドウに近づいたときに履歴をサーバー側で要約します。両者は異なります——編集は刈り込み、コンパクションは凝縮——長いエージェントはしばしば両方を使います。節約は複利で効きます：毎ターン200Kトークンのデッドなツール出力を再送信するはずだった40ターンのセッションが、代わりにコンパクトな要約を送信します。
コンパクションで誰もが引っかかるgotcha：毎ターン抽出したテキストだけでなく、完全な response.content を追加してください。コンパクションの状態はそれらのコンテンツブロックに格納されています。テキストだけに絞り込むと、それが静かに失われ、なぜかコストがまた上がり始めます。
正しい数字を見る
最後に。コストをデバッグするとき、input_tokens だけを見ないでください。実際の合計は input_tokens + cache_creation_input_tokens + cache_read_input_tokens です。長時間実行中のエージェントが input_tokens が4Kしかないことでパニックになり、何かが壊れていると思う人を見たことがあります——いいえ、残りはキャッシュから提供されています。その4Kがキャッシュされていない残りです。3つすべてを合計しなければ、ゲージを誤読しています。
これらはどれもエージェントを愚かにしません。キャッシングは無料です。Effortチューニングは重要なところに思考力を保ちます。サブエージェントは安い作業を安いモデルに任せます。愚かな行動は賢く聞こえるものです：どこでも弱いモデルに切り替えて、数ドルを節約するために品質がクレーターするのを見ること。まず無駄を削減しましょう。無駄は膨大であり、あなたが忘れたタイムスタンプの中に隠れています。