検索結果を二度運ばない — response_inclusion で消費済みブロックを応答から外す設計

excluded を有効にする最小構成

実装は、ツール定義に一行足すだけです。dynamic filtering は code execution の有効化が前提なので、両方を渡します。検索・取得と併用する場合、code execution の課金は無料になる点も運用上ありがたいところです。

import anthropic
 
client = anthropic.Anthropic()
 
resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": (
            "主要クラウドのAI推論料金の最新値を調べ、"
            "1Mトークンあたりの相対比だけを表にして返してください。"
            "取得したページの生本文は返さなくて構いません。"
        ),
    }],
    tools=[
        {"type": "code_execution_20250825", "name": "code_execution"},
        {
            "type": "web_search_20260318",
            "name": "web_search",
            "max_uses": 8,
            "response_inclusion": "excluded",
        },
    ],
)
 
print(resp.usage)

このリクエストでは、モデルが検索を反復し、code execution の中で結果を絞り込み、最後に相対比の表だけを返します。excluded を付けているので、絞り込みに消費された検索原文は応答から落ち、output_tokens には最終的な表とそこに至る思考だけが乗ります。

削減が効いているかは、応答 content の中身を数えると一目で分かります。次のヘルパーは、echo された生の結果ブロック数と usage を並べて表示します。

def summarize(resp) -> None:
    echoed = sum(
        1 for b in resp.content
        if b.type == "web_search_tool_result"
    )
    sts = resp.usage.server_tool_use
    print(f"output_tokens        = {resp.usage.output_tokens}")
    print(f"web_search_requests  = {sts.web_search_requests if sts else 0}")
    print(f"echoed_result_blocks = {echoed}")

full で走らせたときと excluded で走らせたときを同じプロンプトで比べると、web_search_requests は同じまま echoed_result_blocks が 0 に落ち、それに連動して output_tokens が下がります。検索回数は変わらないのに出力だけが軽くなる、というこの形が見えれば、設定が正しく効いている証拠です。

安全に外せる場合・full を保つべき場合

excluded は万能スイッチではありません。応答の使い道によっては full を保たねばならない場面があります。私が運用で線引きしている基準を表にまとめます。

判断の軸は単純です。「その生ブロックを、このターンの応答を受け取った後にもう一度使うか」。使うなら full、使わないなら excluded。私の自動投稿パイプラインの調査エージェントは、最終的に構造化した所見だけを次の工程へ渡すので、ほとんどの検索を excluded に倒しています。一方、読者に出典リンクを見せる用途のエージェントだけは full のまま残しています。

clear_tool_uses・クライアント側圧縮との使い分け

ツール返り値でコンテキストが膨らむ問題には、response_inclusion の他にも手があります。混同して同じ場所に二重で対策を打たないよう、効く場所が違うことを押さえておきます。

この三つは競合しません。response_inclusion は今このターンの出力を軽くする。context editing の clear_tool_uses は、ターンをまたいで溜まった過去の tool 履歴を入力から削る。自前ツールのクライアント側圧縮 は、サーバーツールではない自分で書いたツールの返り値を返す瞬間に絞り込む。

私の運用では、サーバーツール（検索・取得）には response_inclusion、自前の MCP ツールにはクライアント側圧縮、そして長く回り続けるループ全体には context editing、という三層で住み分けています。どれか一つで全部を賄おうとすると、必ずどこかに取りこぼしが残ります。

出力トークンの削減を push 前に usage で確かめる

最後に、設定を本番へ入れる前の確認手順です。体感ではなく数字で裏を取ります。私自身は、次の順で確かめています。

1. 同じプロンプト・同じ max_uses で full と excluded を一度ずつ走らせ、output_tokens の差分を記録します。
2. excluded 側で最終応答の中身（要約・表・判定）が劣化していないことを確認します。
3. 引用をユーザーに見せる経路だけは full のまま据え置くと決めます。

検索の量が多いタスクほど差は大きく出ます。私の調査エージェントの一例では、web_search_requests が 6 回前後のタスクで、excluded にしたときの output_tokens がおおむね 3〜4 割落ちました。検索回数が少ない単発タスクでは差は小さく、ループが深く検索が多いほど効く、という素直な傾向です。

def compare(make_request) -> None:
    """make_request(inclusion) は response を返す関数"""
    for mode in ("full", "excluded"):
        r = make_request(mode)
        echoed = sum(1 for b in r.content if b.type == "web_search_tool_result")
        print(f"[{mode:8}] out={r.usage.output_tokens:>6}  echoed_blocks={echoed}")

出力が軽くなっても結論がぶれていては本末転倒なので、トークン差分そのものよりも、応答の質が保たれているかを最終的な判断基準にしています。

個人開発の自動運用での落としどころ

response_inclusion は、課金体系を眺めていて「検索は入力でも出力でも金を取られる」と気づいたときに、初めて価値が腑に落ちるたぐいの機能です。dynamic filtering で入力を絞っただけで満足していると、出力側に残った原文の二度運びを見落とします。

一人で複数サイトのパイプラインを回していると、こうした地味な漏れが毎日少しずつ積み上がります。私は調査・絞り込みが主目的で原文を下流に渡さないエージェントを既定で excluded にし、読者向けに出典を見せる経路だけを full で残す、という運用に落ち着きました。

まず手元の一番検索の多いエージェントで、full と excluded を一度ずつ走らせ、output_tokens の差を見てみてください。差が出るなら、それは毎回の実行で静かに払っていたコストです。お読みいただきありがとうございました。