ウェブ検索ツール

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

web_search_20260209以降のバージョンでは、Claudeは検索結果がコンテキストウィンドウに到達する前にフィルタリングするコードを記述して実行でき（動的フィルタリング）、関連する情報のみを保持します。動的フィルタリングは、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リクエストにウェブ検索ツールを追加すると、次のように動作します。

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



Claudeが検索するタイミング

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

• 最近の出来事、ニュース、発表
• 現在の価格、レート、スコア、統計
• 変更されている可能性のある特定の組織、人物、製品に関する情報
• 検索や調査の明示的な依頼

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

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

検索のトリガーはシステムプロンプトで制御できます。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)



ウェブ検索の使い方

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)



ツール定義

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

{
  "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）。

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



ローカライゼーション

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

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



レスポンス包含

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

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



レスポンス

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

{
  "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は、入力トークンや出力トークンの使用量にはカウントされません。



エラー

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

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

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



プロンプトキャッシング

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



ストリーミング

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

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のLimitsページで確認できます。より高い制限をリクエストするには、そのページから営業にお問い合わせください。



使用量と価格

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

{
  "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回の使用としてカウントされます。ウェブ検索中にエラーが発生した場合、そのウェブ検索は課金されません。



次のステップ