長時間動かすエージェントを書いていると、決まって同じ壁にぶつかります。タスクは半分しか終わっていないのに、context window が先に枯渇する。tool_result が積み上がって、Claude が肝心の指示を見失う。
私もここで何度も詰まりました。Memory Tool だけでは足りない、プロンプトキャッシュだけでも足りない。答えは2025年9月にベータ公開され、2026年に入って実務で使えるレベルになった Context Editing にありました。
この記事では、Claude API の clear_tool_uses_20250919 を中心に、長時間エージェントが context を使い切らずに走り続ける設計を、Python の最小コードと運用上の落とし穴つきで解説します。
結論:Context Editing は「捨てる場所」を決める設計
先に結論から書きます。Context Editing は単独で使う機能ではなく、プロンプトキャッシュ・Memory Tool・Tool Search と組み合わせて「どの層で context を削るか」を分担する設計です。
私の現在の構成は以下です。
- Tool Search で tool 定義をオンデマンド化(入口の削減)
- プロンプトキャッシュで system + tools を固定キャッシュ(再利用の最大化)
- Context Editing で古い tool_result を自動破棄(中間の削減)
- Memory Tool で捨てた情報のうち必要なものだけを永続化(出口の保全)
この4層を分担させると、50ターン超えのエージェントでも 1M context を使い切らずに走り切れます。逆に1つでも欠けると、どこかでトークンが破裂します。
なぜ Context Editing が必要になったか
2025年までの長時間エージェントは、context window が満杯になったら compaction で要約して仕切り直す、というのが定石でした。これは効くんですが、欠点が2つあります。
1つ目は、要約のたびに細かいニュアンスが消えること。2つ目は、要約の前後でキャッシュヒットが切れて、コストが跳ねること。
Anthropic の公式発表によれば、context editing は context window 内の古い tool 呼び出しと結果を、トークン上限に近づいたタイミングで自動的に削除します。会話の流れは保ったまま、不要になった内容だけを抜き取る、というイメージです。
実際に手元の Sonnet 4.5 系で計測したところ、ツール多用のエージェントでベースラインの context 使用量が体感で4割ほど軽くなりました。これは想像以上に効きました。
clear_tool_uses_20250919 の最小実装
まずは動くコードから。anthropic-beta: context-management-2025-06-27 ヘッダを付けて、context_management パラメータに strategy を渡すだけです。
from anthropic import Anthropic
client = Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=4096,
messages=conversation_history,
tools=my_tools,
betas=["context-management-2025-06-27"],
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
"trigger": {"type": "input_tokens", "value": 30000},
"keep": {"type": "tool_uses", "value": 3},
"clear_at_least": {"type": "input_tokens", "value": 5000},
"clear_tool_inputs": False,
}
]
},
)パラメータの意味を、私が実務で詰まった順に並べます。
trigger:どこで掃除を起動するか
入力トークンが指定値を超えたら掃除が走ります。1M context のモデルで 30000 は早すぎる気がしますが、早めに掃除した方がキャッシュヒットを保てるケースが多いです。
私はだいたい「想定平均の1.5倍」あたりに置いています。深く考えず 100K で固定すると、ツール頻度の高いエージェントで途中から急に削られて、Claude が困惑することがありました。
keep:直近をいくつ残すか
直近 N 個の tool 呼び出しは保持します。これを 0 や 1 にすると、Claude が「さっき見たファイル」を覚えていない状態で次の判断をしてしまいがちです。
私の体感では 3〜5 が安定領域です。タスクの種類によりますが、ファイル編集系は 5、検索系は 3 で運用しています。
clear_at_least:ここが一番重要
これが最初わかりにくかった。「少なくとも何トークン削るか」の最低保証です。
なぜ重要かというと、context editing は実行されるたびにプロンプトキャッシュを無効化するから。公式ドキュメントによれば、tool result clearing はキャッシュされた prefix を invalidate するため、毎回少しずつ削るとキャッシュライト料金だけが嵩む結果になります。
まとめて削れば、その後の再キャッシュで元が取れます。私はだいたい 5000〜10000 トークンの最低保証を入れています。
clear_tool_inputs:呼び出し側も消すか
デフォルトは False(tool_result のみ削除、tool_use の呼び出しパラメータは残す)。これを True にすると tool_use 側も削れますが、Claude が「自分が何を呼んだか」を忘れます。
私は基本 False のまま。会話の流れだけは保ちたいからです。
Memory Tool との二段構えで「捨てたけど忘れない」を作る
ここが2026年版の本命です。Context Editing だけだと、削った情報は本当に消えます。これだと「30ファイル読んで、その総括をしてから50ファイル目を編集する」みたいなタスクで詰みます。
そこで Memory Tool を併用します。Anthropic の公式ガイドにも、コーディングワークフローではコンテキストが膨らむにつれて完了した変更を memory ファイルに要約していく使い方が紹介されています。
response = client.beta.messages.create(
model="claude-sonnet-4-5",
max_tokens=4096,
messages=conversation_history,
tools=[
{"type": "memory_20250818", "name": "memory"},
# 他の自作ツール
],
betas=["context-management-2025-06-27"],
context_management={
"edits": [{"type": "clear_tool_uses_20250919"}]
},
)運用の鉄則は1つ。「掃除される前に Memory に避難しろ」を system prompt に明文化することです。
私の system prompt にはこんな一節を入れています。「重要な発見・読み終えたファイルの要約・次に必要そうな情報は、tool_result が古くなる前に memory に書き出すこと。memory は再起動後も残るが、tool_result は context editing で消える」。
これを入れるだけで、Claude は能動的に memory への退避を始めました。地味ですが、長時間エージェントの完走率が体感で3割上がった印象です。
プロンプトキャッシュと両立させる3つのコツ
ここが落とし穴の宝庫です。Context Editing は性質上、キャッシュを壊しに行きます。それでも両立させるには、3つのコツがあります。
1. trigger は高め、clear_at_least はまとめて
細かく頻繁に削ると、キャッシュ書き込み料金(ベース入力単価の +25%)が積み重なります。たまに大きく削る方が結果的に安いです。
2. system prompt と tools は完全固定
セッション中に system prompt や tool 定義の文字列が1byteでも変わると、prefix キャッシュは丸ごと無効化されます。動的に変えたい設定は、最初の user メッセージ側に寄せる癖をつけました。
3. extended thinking との併用は keep:‘all’ を意識する
clear_thinking_20251015 を併用する場合、デフォルトでは直近1ターンの thinking ブロックしか残らないため、その時点でキャッシュが切れがちです。長いセッションでキャッシュを最大化したいなら、公式ドキュメント通り keep: "all" を設定します。
ただし thinking ブロックを全部残すと context は膨らみます。キャッシュ効率を取るか、context 余裕を取るかの二択になるので、自分のワークロードで計測して決めるのが結論でした。
本番投入で踏んだ落とし穴3つ
落とし穴1:placeholder が増えすぎて混乱する
Context editing は削除した tool_result を placeholder テキストで置き換えます。これが100個も並ぶと、Claude が「何が起きたか」を取り違えることがありました。
対策は、trigger を早めに引いて削除回数自体を減らすこと。あと keep を 5 まで上げて、直近のコンテキストを厚めに残しました。
落とし穴2:model_context_window_exceeded が突然出る
Claude 4.5 以降は input + max_tokens が context を超えても、ひとまずリクエストを受理して、生成中に上限到達したら model_context_window_exceeded で停止する挙動になっています。
これが context editing と組み合わさると、「掃除はされたが、それでも足りなかった」というケースで突然落ちます。stop_reason のハンドリングを書いて、必要なら強制 compaction にフォールバックするコードを入れました。
落とし穴3:ZDR 環境での挙動を読み違える
組織が Zero Data Retention 契約をしている場合、API レスポンス後にデータは保持されません。これ自体は良いことですが、デバッグ時に「何を消したか」を後から追えないため、独自にローカルログを残す癖をつけた方が安全です。
まとめ:今日から試す3つのアクション
長文になりました。最後に、明日から動かせる3ステップに圧縮します。
- 今あるエージェントに beta ヘッダと最小設定を1行入れる:
clear_tool_uses_20250919だけならコード変更は10行以内。まず効果を見る - Memory Tool を併設し、system prompt に「重要情報は memory に退避」と明記:これだけで完走率が変わる
clear_at_leastを 5000〜10000 で設定:キャッシュコストが跳ねるのを防ぐ最大の防波堤
Context Editing は派手な新機能ではないですが、長時間エージェントを書く人にとっては地味に効くインフラです。私のように途中で落ちて泣いた人ほど、効果を実感できると思います。
まずは手元のサブエージェント1つに仕込んで、/stats で context 使用率の推移を見てみてください。数値で効いているのが見えると、設計の選択肢が一気に増えます。
参考リンク
- Anthropic - Context editing 公式ドキュメント — clear_tool_uses_20250919 と clear_thinking_20251015 の仕様
- Anthropic - Manage tool context — Tool Search / キャッシュ / Context Editing の使い分け
- Anthropic News - Managing context on the Claude Developer Platform — Context Editing と Memory Tool の発表記事
- Anthropic - Context windows — Claude 4.5 以降の model_context_window_exceeded 挙動