ウェブ検索ツール

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

使用方法は製品によって異なります

Messages API

リクエストのtoolsにweb_searchツールを追加します。max_uses、ドメインリスト、user_locationなどの設定はそのツールに指定します。

Managed Agents

エージェントのツールセットでデフォルトで有効です。max_uses、citations、cache_controlは使用できません。

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

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

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

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

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

Web検索の「Zero Data Retention」（ゼロデータ保持）の適格性と関連するallowed_callersの設定については、サーバーツールを参照してください。

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

リクエストを送信する前にモデルがWeb検索を受け付けるかどうかを確認するには、Models APIからそのモデルのcapabilities.server_tools.web_search.supportedの値を読み取ります。このフィールドについてはModels APIの使用で説明しています。

Web検索の仕組み

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

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

Claudeが検索するタイミング

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

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

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

確立された事実、数学、科学の基礎、またはコーディングの概念
創作や「brainstorming」（ブレインストーミング）
会話内ですでに提供されたコンテンツの分析
会話上のやり取りや挨拶

検索のトリガーはシステムプロンプトで調整できます。Claudeがより積極的に検索するよう促すことも、直接回答することを優先させることもできます。制限を強制するには、max_usesを使用して1ターンあたりの検索回数に上限を設けてください。

動的フィルタリング

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

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

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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)

Web検索の使い方

Claude Managed Agentsのセッションで組織のWeb検索設定がどのように適用されるかについては、Web検索とWebフェッチのドメインを制限するを参照してください。

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

client = anthropic.Anthropic()

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

ツール定義

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

JSON

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

  // Optional: Limit the number of searches
  "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"
  }
}

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

最大使用回数

max_usesパラメータは、1つのターン内の検索回数を制限します。単一の事実に関するクエリでは通常1〜3回の検索が使用されますが、比較調査や複数エンティティの調査では10回以上使用されることがあります。

失敗した検索も上限にカウントされます。ClaudeがWeb検索を直接、許可された回数を超えて呼び出すと、web_search_tool_resultはmax_uses_exceededエラーコードを伴うエラーになります。Claudeがコード実行からWeb検索を許可された回数を超えて呼び出すと、コード実行の実行はエラーで終了します。

1つのターンは複数のリクエストにまたがることがあります。リクエストがpause_turnの後に再開する場合、または最後のメッセージにtool_resultブロックのみが含まれる場合、そのリクエストはターンを継続します。そのターン内の以前のリクエストで行われた検索は上限にカウントされます。ただし、Claudeが動的フィルタリングを通じてコード実行から実行した検索は除きます。

ドメインフィルタリング

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

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

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

ローカライゼーション

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を受け付けます。Webツールの設定を参照してください。

レスポンスへの包含

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

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検索では引用が常に有効になっており、各web_search_result_locationには以下が含まれます。

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

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

エラー

Web検索ツールでエラー（レート制限に達した場合など）が発生しても、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：Web検索ツールの最大使用回数を超過しました
query_too_long：クエリが最大長を超えています
request_too_large：検索リクエストが大きすぎます（通常はドメインフィルターのリストが長いことが原因です）
unavailable：内部エラーが発生しました

`pause_turn`停止理由

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

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

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

プロンプトキャッシング

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

ストリーミング

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

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 runs

// 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)

バッチリクエスト

Web検索ツールはMessage Batches APIに含めることができます。Message Batches APIを通じたWeb検索ツールの呼び出しは、通常のMessages APIリクエストでの呼び出しと同じ価格設定です。

共有キャパシティを保護するため、Batches APIは組織ごとにWeb検索リクエストをスロットリングします。そのため、多数の検索を含む大規模なバッチは完了までに時間がかかる場合があります。組織のWeb検索のレート制限は、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回の使用としてカウントされます。エラーで失敗したウェブ検索は課金されません。

次のステップ

Webフェッチツール

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

サーバーツール

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

ツールリファレンス

Anthropicが提供するツールのディレクトリと、オプションのツール定義プロパティのリファレンス。

利用可能状況

ウェブ検索ツールはすべてのモデルで利用可能であり、ゼロデータ保持とHIPAAレディネスの対象です。

APIサポート

Messages API

使用方法

リクエストのtoolsにweb_searchツールを追加します。max_uses、ドメインリスト、user_locationなどの設定はそのツールに指定します。

ステータス利用可能

クラウドプラットフォーム

Claude API
Claude Platform on AWS
Claude Models on Google CloudAnthropic managed
Microsoft FoundryHosted on Anthropic

ステータス利用可能

クラウドプラットフォーム

Claude Models on Google CloudGoogle managed
Microsoft FoundryHosted on Azure

動的フィルタリングなしの基本的なウェブ検索ツール（web_search_20250305）のみです。

Managed Agents

使用方法

エージェントのツールセットの一部で、ツールセットを追加するとデフォルトで有効になります。ドメインリストとuser_locationはツールセットのweb_searchエントリに指定します。max_uses、citations、cache_controlは使用できません。

ステータス利用可能

クラウドプラットフォーム

Claude API
Claude Platform on AWS

データの取り扱い

データの取り扱いの概要

対象エンドポイント

/v1/messages web_searchツールを使用する場合

ゼロデータ保持対象

対象モデルを除く

リアルタイムのウェブ検索結果がAPIレスポンスで返されます。ウェブ検索の動的フィルタリングは、ZDRまたはHIPAAの適格対象ではありません。

HIPAA対象

ウェブ検索の動的フィルタリングは、ZDRまたはHIPAAの適格対象ではありません。

Web検索の仕組み

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

動的フィルタリング

Web検索の使い方

ツール定義

最大使用回数

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

ローカライゼーション

レスポンスへの包含

レスポンス

検索結果

引用

エラー

pause_turn停止理由

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

ストリーミング

バッチリクエスト

使用量と料金

次のステップ

利用可能状況

APIサポート

データの取り扱い

Web検索の仕組み

Claudeが検索するタイミング

動的フィルタリング

Web検索の使い方

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンスへの包含

レスポンス

検索結果

引用

エラー

`pause_turn`停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

次のステップ

利用可能状況

APIサポート

データの取り扱い