ウェブ検索ツール

引用元付きの最新のウェブコンテンツ、オプションの動的フィルタリング、ドメイン制御へのアクセスをClaudeに提供します。

ウェブ検索ツールは、Claudeにリアルタイムのウェブコンテンツへの直接アクセスを提供し、知識のカットオフを超えた最新情報で質問に回答できるようにします。レスポンスには、検索結果から得られたソースの引用が含まれます。

web_search_20260209以降のバージョンでは、Claudeは検索結果が「context window」（コンテキストウィンドウ）に到達する前にそれらをフィルタリングするコードを記述して実行でき（動的フィルタリング）、関連する情報のみを保持します。動的フィルタリングは、Claude 4.6以降のモデルおよびClaude Mythos Previewで利用できます。

ウェブ検索ツールには3つのバージョンがあります。

web_search_20250305：基本的なウェブ検索
web_search_20260209：動的フィルタリングを追加
web_search_20260318：エージェントワークフロー向けのレスポンスへの包含制御を追加

このページの例では、基本検索にはweb_search_20250305を、動的フィルタリングにはweb_search_20260318を使用しています。

ウェブ検索のZero Data Retention適格性および関連するallowed_callers設定については、サーバーツールを参照してください。

モデルのサポートについては、ツールリファレンスを参照してください。

ウェブ検索の仕組み

APIリクエストにウェブ検索ツールを追加すると、次のように動作します。

Claudeはプロンプトに基づいて検索するタイミングを判断します。
APIが検索を実行し、結果をClaudeに提供します。このプロセスは1つのリクエスト全体で複数回繰り返されることがあります。
ターンの最後に、Claudeは引用元付きの最終レスポンスを提供します。

Claudeが検索するタイミング

Claudeは、リクエストが最新の情報、変化する情報、またはトレーニングデータ外の情報に依存する場合に検索します。

最近の出来事、ニュース、発表
現在の価格、レート、スコア、統計
変化している可能性のある特定の組織、人物、製品に関する情報
検索や調査を明示的に求めるリクエスト

Claudeは、リクエストが安定した知識に基づく場合、検索せずに直接回答します。

確立された事実、数学、科学の基礎、コーディングの概念
クリエイティブライティングやブレインストーミング
会話内ですでに提供されたコンテンツの分析
会話のやり取りや挨拶

トリガーは「system prompt」（システムプロンプト）を通じて調整可能です。Claudeがより積極的に検索するよう促すことも、直接回答を優先するよう促すこともできます。厳密な制約が必要な場合は、max_usesを使用してリクエストごとの検索回数に上限を設けてください。

動的フィルタリング

基本的なウェブ検索では、すべての検索結果がClaudeのコンテキストウィンドウに読み込まれますが、そのコンテンツの多くはリクエストと無関係な場合があります。web_search_20260209以降では、Claudeは代わりに結果を最初にフィルタリングするコードを記述して実行するため、関連するコンテンツのみがコンテキストウィンドウに到達します。これにより、検索を多用するリクエストでのトークン使用量が削減されます。

動的フィルタリングはコード実行の内部からウェブ検索を実行します。web_search_20260209以降では、ツールのallowed_callersフィールドのデフォルトは["code_execution_20260120"]であり、動的フィルタリングが実行されると、APIはリクエストに必要なコード実行を自動的にプロビジョニングします。コード実行ツールを自分でtoolsに追加する必要はありません。この方法で行われるコード実行呼び出しには、標準のトークンコスト以外の追加料金は発生しません。

動的フィルタリングなしでウェブ検索を直接呼び出すには、allowed_callers: ["direct"]を設定します。プログラムによるツール呼び出しをサポートしていないモデルでは、この設定が必要です。設定しない場合、APIはこれを設定するよう指示する400エラーを返します。

以下の例ではweb_search_20260318を使用しています。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260318", "name": "web_search"}],
)
print(response)

ウェブ検索の使い方

Claude Consoleのこれらの組織レベルの設定は、Messages APIリクエストにのみ適用されます。Claude Managed Agentsセッションは、エージェントツールセットのツールごとのallowed_domainsおよびblocked_domainsリストのみを使用します。ウェブ検索とウェブフェッチのドメインを制限するを参照してください。

APIリクエストでウェブ検索ツールを指定します。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

ツール定義

ウェブ検索ツールは以下のパラメータをサポートしています。

JSON

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

すべてのウェブ検索ツールバージョンはallowed_callersを受け付けます。これは、Claudeがウェブ検索を直接呼び出すか、動的フィルタリングを通じてコード実行から呼び出すかを制御します。web_search_20260209以降では、デフォルトは["direct"]ではなく["code_execution_20260120"]です。設定方法についてはサーバーツールを参照してください。web_search_20260318以降はresponse_inclusionも受け付けます。

最大使用回数

max_usesパラメータは、実行される検索の回数を制限します。Claudeが許可された回数を超えて検索を試みた場合、web_search_tool_resultはmax_uses_exceededエラーコードを持つエラーになります。

単純な事実確認のクエリでは通常1〜3回の検索を使用します。比較や複数エンティティの調査では10回以上使用することがあります。値の選び方のガイダンスについては、サーバーツールを参照してください。

ドメインフィルタリング

allowed_domainsまたはblocked_domainsのいずれか一方を指定し、両方は指定しないでください。リクエストに両方が含まれている場合、APIは400エラーを返します。エントリはスキームなしの、オプションのパス付きのベアドメインです（例：example.comまたはexample.com/blog）。

ドメインフィルタリングの完全なルールについては、サーバーツールガイドのドメインフィルタリングを参照してください。

Claude Managed Agentsでは、これらのフィールドをエージェントツールセットのweb_searchエントリに設定します。ウェブ検索とウェブフェッチのドメインを制限するを参照してください。

ローカライゼーション

user_locationパラメータを使用すると、ユーザーの所在地に基づいて検索結果をローカライズできます。city、region、country、timezoneのうち少なくとも1つを指定してください。

type：所在地のタイプ（approximateである必要があります）
city：都市名
region：地域または州
country：2文字のISO 3166-1 alpha-2国コード。APIはサポートされていない国コードを400エラーで拒否します。
timezone：IANAタイムゾーンID。

Claude Managed Agentsでは、エージェントツールセットのweb_searchエントリは同じフィールドを持つuser_locationオブジェクトを受け付けます。APIは、エージェントの作成または更新時、あるいはこの設定を指定するセッションの作成または更新時に、サポートされていないcountryコードを400エラーで拒否します。ウェブ検索とウェブフェッチのドメインを制限するを参照してください。

レスポンスへの包含

response_inclusionパラメータは、同じターン内で完了したコード実行呼び出しによって結果が消費された場合に、検索結果ブロックがAPIレスポンスにどのように表示されるかを制御します。"response_inclusion": "excluded"を設定すると、それらのネストされたserver_tool_useと結果ブロックのペアがレスポンスから完全に削除され、生の検索コンテンツをクライアントにエコーバックする必要のないエージェントワークフローの出力トークンコストが削減されます。デフォルトは"full"です。直接呼び出しからの結果、または完了前に一時停止したコード実行呼び出しからの結果は、次のターンで送り返せるように常に完全な形で返されます。

JSON

{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

レスポンス

レスポンス構造の例を以下に示します。

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude's response with citations
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

この例は直接検索を示しています。検索が動的フィルタリングを通じて実行される場合、レスポンスにはコード実行ツールの結果ブロックも含まれ、ネストされた各server_tool_useとweb_search_tool_resultのペアには、それを呼び出したコード実行呼び出しを識別するcallerフィールドが付きます。

検索結果

検索結果には以下が含まれます。

url：ソースページのURL
title：ソースページのタイトル
page_age：サイトが最後に更新された時期
encrypted_content：マルチターン会話で送り返す必要がある暗号化されたコンテンツ

検索結果を含む会話を続けるには、各結果のencrypted_contentを含め、アシスタントのコンテンツブロックを受け取ったとおりに正確に送り返してください。APIは後続のターンでそのコンテンツを復号し、Claudeのコンテキスト内に検索結果を復元します。encrypted_contentが欠落しているか変更されている場合、リクエストは400バリデーションエラーで失敗します。

引用

ウェブ検索では引用は常に有効であり、各web_search_result_locationには以下が含まれます。

url：引用元のURL
title：引用元のタイトル
encrypted_index：マルチターン会話で送り返す必要がある参照
cited_text：引用されたコンテンツの最大150文字

ウェブ検索の引用フィールドcited_text、title、urlは、入力または出力トークン使用量にカウントされません。

エラー

ウェブ検索ツールがエラー（「rate limit」（レート制限）への到達など）に遭遇した場合でも、Claude APIは200（成功）レスポンスを返します。エラーはレスポンス本文内で以下の構造を使用して表現されます。

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

エラー時には、contentは結果ブロックのリストではなく単一のエラーオブジェクトになります。検索が成功したものの一致する結果がなかった場合は、エラーではなく空のcontentリストが返されます。

発生しうるエラーコードは以下のとおりです。

too_many_requests：レート制限を超過
invalid_tool_input：無効な検索クエリパラメータ
max_uses_exceeded：ウェブ検索ツールの最大使用回数を超過
query_too_long：クエリが最大長を超過
request_too_large：検索リクエストが大きすぎる（通常は長いドメインフィルタリストが原因）
unavailable：内部エラーが発生

`pause_turn`停止理由

APIは長時間実行される検索ターンを一時停止し、stop_reason: "pause_turn"を返すことがあります。続行するには、一時停止したアシスタントメッセージを変更せずに新しいリクエストで送り返してください。

Claudeが同じ並列ツール呼び出しグループ内でウェブ検索とクライアントツールの1つを呼び出した場合、APIは代わりにstop_reason: "tool_use"を返し、検索はまだ実行しません。続行するには、クライアントツールの結果を返してください。APIは次のリクエストで検索を実行します。1つのターンでサーバーツールとクライアントツールを混在させるを参照してください。

サーバーサイドループとpause_turnの処理については、サーバーツールガイドのサーバーサイドループとpause_turnを参照してください。

プロンプトキャッシング

ターンをまたいでツール定義をキャッシュするには、プロンプトキャッシングを使用したツール使用を参照してください。

ストリーミング

「streaming」（ストリーミング）を有効にすると、ストリームの一部として検索イベントを受け取ります。検索の実行中は一時停止が発生します。

Output

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Claude's decision to search

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude's response with citations (omitted in this example)

バッチリクエスト

Messages Batches APIにウェブ検索ツールを含めることができます。Messages Batches APIを通じたウェブ検索ツール呼び出しは、通常のMessages APIリクエストと同じ料金です。

共有キャパシティを保護するため、Batches APIは組織ごとにウェブ検索リクエストをスロットリングします。そのため、多数の検索を含む大規模なバッチは完了までに時間がかかる場合があります。組織のウェブ検索レート制限は、Claude Consoleのレート制限ページで確認できます。より高い制限をリクエストするには、そのページから営業担当にお問い合わせください。

使用量と料金

ウェブ検索の使用は、トークン使用量に加えて課金されます。

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

ウェブ検索はClaude APIで1,000回の検索あたり$10で利用でき、検索によって生成されたコンテンツには標準のトークンコストが加算されます。会話全体を通じて取得されたウェブ検索結果は、単一のターン内で実行される検索の反復においても、その後の会話ターンにおいても、入力トークンとしてカウントされます。

各ウェブ検索は、返される結果の数に関係なく1回の使用としてカウントされます。ウェブ検索中にエラーが発生した場合、そのウェブ検索は課金されません。

次のステップ

ウェブフェッチツール

特定のURLからコンテンツを取得して読み取り、ライブのウェブコンテンツでClaudeのコンテキストを拡張します。

サーバーツール

Anthropicが実行するツールの扱い方：server_tool_useブロック、pause_turnの継続、ドメインフィルタリング。

ツールリファレンス

Anthropic提供ツールの一覧と、オプションのツール定義プロパティのリファレンス。

ウェブ検索の仕組み

Claudeが検索するタイミング

動的フィルタリング

ウェブ検索の使い方

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンスへの包含

レスポンス

検索結果

引用

エラー

pause_turn停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

次のステップ

ウェブ検索の仕組み

Claudeが検索するタイミング

動的フィルタリング

ウェブ検索の使い方

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンスへの包含

レスポンス

検索結果

引用

エラー

`pause_turn`停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

次のステップ