Claudeサーバーツール設計——Web Search・Code Executionの組み込み方

本番エージェントに「最新のWeb情報を調べさせたい」「ユーザーデータをその場で集計させたい」と思ったとき、よくある実装はカスタムツールをクライアント側に組み込む設計です。しかしAnthropicが提供するサーバーツールを使えば、クライアント側の実行ループなしにこれらの機能をエージェントに追加できます。

本稿ではエージェントガバナンスの設計基盤として重要な、Web Search・Code Executionの2系統を中心に、実装パターンと設計上の判断基準を解説します。

Claudeのサーバーツールとは何か——クライアントツールとの違い

Claudeサーバーツールは Anthropicインフラ上で実行されるツール群で、Web Search（$10/1,000件）・Code Execution（Pythonサンドボックス）などをクライアント実装なしに利用できます。

通常のFunction calling（クライアントツール）では、Claudeがツール呼び出しを要求するとstop_reason: "tool_use"で応答が停止し、クライアント側でツールを実行してから結果を返すターン制のループが必要です。

サーバーツールはこの構造が根本的に異なります。ツールがAnthropicのサーバー側で実行されるため、クライアントは実行ループを実装しなくて済みます。APIレスポンスにはtype: "server_tool_use"ブロックが含まれ、ツールの実行と結果の組み込みがサーバー内で完結します。

``json { "type": "server_tool_use", "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE", "name": "web_search", "input": { "query": "2026年Q2 日本のEC市場規模" } }``

現在提供されている主なサーバーツールの一覧です。

ツール	用途	課金
Web Search	リアルタイムWeb検索	$10/1,000件
Web Fetch	特定URL取得	トークン課金のみ
Code Execution	Python・Bashサンドボックス	通常価格（Web Searchと併用時は無料）
Files API	ファイル永続化	ストレージ課金
MCP Connectors	Anthropicホスト型MCPサーバー	個別設定

クライアントツールとの使い分け基準はシンプルです。Web上の最新情報やコード実行が必要ならサーバーツール、社内データベースや自社APIへのアクセスが必要ならクライアントツールという切り分けが基本になります。

Web Searchツールはどう設計するか——リアルタイム検索の実装パターン

Web Searchツールは1リクエストあたり$10/1,000件で提供され、max_usesとdomain filteringでAPIから検索回数と対象ドメインを制御できます。

Web Searchツールを有効化するにはtools配列にツール定義を追加するだけです。2026年現在、バージョンが3つ存在します。

web_search_20250305: 基本的なWeb検索
web_search_20260209: dynamic filtering追加（Code Executionが検索結果を前処理）
web_search_20260318: response_inclusionパラメータ追加（中間ブロックを非表示にしてレスポンスを軽量化）

``python response = client.messages.create( model="claude-opus-4-8", max_tokens=4096, messages=[{"role": "user", "content": "主要競合他社の最新ニュースを調べて要約して"}], tools=[{ "type": "web_search_20260318", "name": "web_search", "max_uses": 5, # 1リクエストあたりの検索上限 "allowed_domains": ["reuters.com", "nikkei.com"], # 信頼ドメイン限定 "user_location": { "type": "approximate", "country": "JP", "timezone": "Asia/Tokyo" }, "response_inclusion": "excluded" # 中間ブロックを非表示 }] )``

設計上の判断ポイントが3つあります。

① max_usesのチューニング: 単純な事実確認は1〜3件、比較分析や多エンティティ調査は10件以上に達します。レイテンシ重視のユースケースにはmax_uses: 3で上限を設け、リサーチエージェントには15〜20または無制限が現実的です。上限を超えるとレスポンス内にmax_uses_exceededエラーが埋め込まれますが、APIは200を返します。

② domain filteringの使い方: allowed_domainsとblocked_domainsは排他的で同時指定はエラーになります。コンプライアンス上特定ドメインへのアクセスを禁じる場合はblocked_domainsを使用し、信頼できる情報源のみに絞りたい場合はallowed_domainsを使用します。

③ マルチターン会話の必須処理: 検索結果ブロックに含まれるencrypted_contentフィールドは後続ターンでアシスタントメッセージにそのまま含めて送り返す必要があります。省略または変更すると400バリデーションエラーが発生します。

Web SearchはAmazon Bedrockでは現在利用できません。Bedrock依存の基盤を持つ場合はLLMゲートウェイ設計でルーティングを切り分けるか、Claude APIへの並行接続を検討してください。

Code Executionツールをどう使うか——Pythonサンドボックスの設計

Code ExecutionツールはサンドボックスでPythonとBashを実行でき、web_search_20260209以降と組み合わせると追加課金なしで利用できます。

Code Executionツールも3バージョンが提供されています。

code_execution_20250825: PythonとBash実行の基本版
code_execution_20260120: REPLセッション永続化とサンドボックス内からのプログラマティックなツール呼び出しを追加
code_execution_20260521: 各Pythonセルのwall-clock上限（90秒）をClaudeに認識させ、長時間処理の予算管理を可能に

``python response = client.messages.create( model="claude-sonnet-5", max_tokens=8192, messages=[{"role": "user", "content": "添付の売上CSVを分析して月次トレンドをグラフ化して"}], tools=[ {"type": "code_execution_20260521", "name": "code_execution"} ] )``

価格の最重要ポイント: web_search_20260209以降またはweb_fetch_20260209以降のツールを同一リクエストに含める場合、Code Executionは追加料金なしです。Web Searchを使うエージェントにCode Executionを追加してもコストが増えません。

制限事項:

Amazon BedrockとGoogle Cloudでは利用不可
各Pythonセルのwall-clock上限は90秒（code_execution_20260521でClaudeが認識できる）
ZDR（Zero Data Retention）対象外

実用ケースとして特に効果が高いのは、大量データの集計・変換・可視化です。データファイルをAPIリクエストに含め、Claudeが自律的にPandasやMatplotlibで処理する設計は、人手による定型作業の自動化に直結します。

Web Search × Code Executionの組み合わせで何が変わるか

web_search_20260209以降とCode Executionを同時に使うと、検索結果をコードで事前フィルタリングしてからコンテキストに渡すdynamic filteringが自動適用されます。

web_search_20260209以降のWeb SearchとCode Executionを組み合わせると、dynamic filteringが自動的に動作します。

通常のWeb Searchでは全検索結果がそのままClaudeのコンテキストウィンドウに入ります。dynamic filteringでは、ClaudeがCode Executionサンドボックス内でフィルタリングコードを生成・実行し、関連性の高いコンテンツだけをコンテキストに渡します。検索ヘビーなリクエストではトークン消費が大幅に削減されます。

``python # dynamic filteringが自動適用される組み合わせ response = client.messages.create( model="claude-opus-4-8", max_tokens=8192, tools=[ { "type": "web_search_20260318", "name": "web_search", # allowed_callersのデフォルト: ["code_execution_20260120"] # Direct検索のみにするなら: "allowed_callers": ["direct"] "response_inclusion": "excluded" # 中間の検索ブロックを非表示 }, {"type": "code_execution_20260521", "name": "code_execution"} ], messages=[{"role": "user", "content": "日本のSaaS市場の2026年Q2トレンドをリサーチして分析レポートを作成して"}] )``

dynamic filteringを無効化してClaudeが直接検索する設計にする場合は"allowed_callers": ["direct"]を明示します。programmatic tool callingを未サポートのモデルでは、この設定が必須です（未設定だと400エラーになります）。

バッチ処理との組み合わせも有効です。Message Batches APIはWeb SearchとCode Executionをバッチ内でサポートしており、大量の調査・分析タスクをトークンコスト50%割引で処理できます（Web Searchの$10/1,000件課金はバッチ内でも同額）。またpause_turnストップリーズンが返った場合は、そのアシスタントメッセージを変更なく次のリクエストに含めて継続します。

規模別の留意点（SMB / エンタープライズ）

SMBの場合: まずWeb Searchをmax_uses: 3〜5で試し、usage.server_tool_use.web_search_requestsの実測値でコストを確認してください。検索コストが大きくなる場合はallowed_domainsで信頼できる情報源に絞るか、RAG vs ツール使用の設計を参考に社内ナレッジベースと外部検索を使い分けます。初期設計の支援はKuuのエージェント運用管理サービスにご相談ください。

エンタープライズの場合: Web SearchはAmazon Bedrockで利用できないため、既存のBedrock基盤がある場合はLLMゲートウェイでClaude APIへのルーティングを分離する設計を検討してください。blocked_domainsでコンプライアンス上アクセス不可のドメインを除外し、user_locationでリージョン別検索結果を最適化します。複数チームへの統制的な展開はKuuのRDEサービスの支援範囲です。

参考

まとめ

ClaudeのサーバーツールはAnthropicインフラで実行されるため、クライアント側の実行ループなしにWeb Search・Code Executionをエージェントに統合できます。

設計の核心は3点です。①Web Searchはmax_usesとdomain filteringでコストと信頼性を制御する、②Code ExecutionはWeb Search（web_search_20260209以降）と同一リクエストに含めると追加料金なしで利用できる、③両ツールを組み合わせるとdynamic filteringが自動適用されトークン効率が大幅に向上する。

クライアントツールとサーバーツールを適切に組み合わせるエージェント設計の支援についてはKuuのエージェント運用管理サービスにお問い合わせください。