メッセージツール

Web検索ツール

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

最新のWeb検索ツールバージョン（web_search_20260318）は、Claude Fable 5、Claude Opus 4.8、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6で動的フィルタリングをサポートしています。Claudeはコードを記述・実行して、検索結果がコンテキストウィンドウに到達する前にフィルタリングし、関連情報のみを保持して残りを破棄できます。これにより、トークン消費を削減しながら、より正確なレスポンスが得られます。web_search_20260318では、エージェントワークフロー向けのレスポンス包含制御も追加されています。以前のバージョン（動的フィルタリングのみのweb_search_20260209、基本検索のweb_search_20250305）も引き続き利用可能です。

Claude Mythos Previewでは、Web検索はClaude API、Microsoft Foundry、Vertex AIでサポートされています。Mythos Previewでは、Amazon BedrockおよびClaude Platform on AWSでWeb検索は利用できません。

Zero Data Retentionの適格性とallowed_callersによる回避策については、サーバーツールを参照してください。

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

Web検索の仕組み

APIリクエストにWeb検索ツールを追加すると：

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

Claudeが検索するタイミング

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

最近のイベント、ニュース、発表
現在の価格、レート、スコア、統計
変更された可能性のある特定の組織、人物、製品に関する情報
検索または調査を明示的に求めるリクエスト

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

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

検索のトリガーはシステムプロンプトで調整可能です。Claudeがより積極的に検索するように促したり、直接回答することを優先させたりできます。厳密な制約を設けるには、max_usesを使用して各リクエストの検索回数に上限を設定します。

動的フィルタリング

Web検索はトークンを大量に消費するタスクです。基本的なWeb検索では、Claudeは検索結果をコンテキストに取り込み、複数のウェブサイトから完全なHTMLを取得し、それらすべてを推論してから回答に到達する必要があります。多くの場合、このコンテンツの大部分は無関係であり、レスポンスの品質を低下させる可能性があります。

web_search_20260209以降では、Claudeはコードを記述・実行してクエリ結果を後処理できます。完全なHTMLファイルを推論する代わりに、Claudeは検索結果をコンテキストに読み込む前に動的にフィルタリングし、関連するものだけを保持して残りを破棄します。

動的フィルタリングは、特に以下の用途で効果的です：

技術ドキュメントの検索
文献レビューと引用の検証
技術調査
レスポンスの根拠付けと検証

動的フィルタリングには、コード実行ツールを有効にする必要があります。Web検索ツール（動的フィルタリングの有無にかかわらず）は、Claude API、Claude Platform on AWS、Microsoft Foundryで利用可能です。Vertex AIでは、基本的なWeb検索ツール（動的フィルタリングなし）のみが利用可能です。Amazon BedrockではWeb検索は利用できません。

動的フィルタリングを有効にするには、web_search_20260209以降のバージョンを使用します。以下の例ではweb_search_20260209を使用しています：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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_20260209", "name": "web_search"}],
)
print(response)

Web検索の使用方法

組織の管理者がClaude ConsoleでWeb検索を有効にする必要があります。

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

client = anthropic.Anthropic()

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

ツール定義

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

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
  "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"
  }
}

最大使用回数

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

単純な事実確認のクエリは通常1〜3回の検索を使用します。比較調査や複数エンティティの調査では10回以上使用することがあります。レイテンシが重要な検索では、max_uses: 3でコストを抑えつつ、途中で打ち切られることはほとんどありません。リサーチエージェントの場合は、max_usesを15〜20に設定するか、完全に省略します。

ドメインフィルタリング

allowed_domainsとblocked_domainsによるドメインフィルタリングについては、サーバーツールを参照してください。

ローカライゼーション

user_locationパラメータを使用すると、ユーザーの位置情報に基づいて検索結果をローカライズできます。

type：位置情報のタイプ（approximateである必要があります）
city：都市名
region：地域または州
country：国
timezone：IANAタイムゾーンID

レスポンス包含

web_search_20260318以降が必要です。

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

{
  "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"
}

検索結果

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

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

引用

Web検索では引用が常に有効になっており、各web_search_result_locationには以下が含まれます：

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

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

APIの出力をエンドユーザーに直接表示する場合、元のソースへの引用を含める必要があります。APIの出力に変更を加える場合（エンドユーザーに表示する前に再処理したり、独自の素材と組み合わせたりする場合を含む）は、法務チームとの相談に基づいて適切に引用を表示してください。

エラー

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"
  }
}

以下は発生する可能性のあるエラーコードです：

too_many_requests：レート制限を超過しました
invalid_input：無効な検索クエリパラメータ
max_uses_exceeded：Web検索ツールの最大使用回数を超過しました
query_too_long：クエリが最大長を超えています
unavailable：内部エラーが発生しました

`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 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にWeb検索ツールを含めることができます。Messages Batches APIを通じたWeb検索ツールの呼び出しは、通常のMessages APIリクエストと同じ料金で課金されます。

共有キャパシティを保護するため、Batches APIは組織ごとにWeb検索リクエストをスロットリングします。そのため、多数の検索を含む大規模なバッチは完了までに時間がかかる場合があります。組織のWeb検索レート制限は、Claude ConsoleのLimitsページで確認できます。より高い制限をリクエストするには、そのページから営業担当にお問い合わせください。典型的なバッチWeb検索ワークロードには、最新のウェブデータによるレコードの拡充、大量のエンティティリストの調査、ライブソースに対するコンテンツコーパスの根拠付けや確認などがあります。

使用量と料金

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

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

次のステップ

サーバーツール

Anthropicが実行するツールの共通メカニズム。

ツールリファレンス

Anthropicが提供するすべてのツールのディレクトリ。

Was this page helpful?

メッセージツール

Web検索ツール

Zero Data Retentionの適格性とallowed_callersによる回避策については、サーバーツールを参照してください。

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

Web検索の仕組み

APIリクエストにWeb検索ツールを追加すると：

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

Claudeが検索するタイミング

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

最近のイベント、ニュース、発表
現在の価格、レート、スコア、統計
変更された可能性のある特定の組織、人物、製品に関する情報
検索または調査を明示的に求めるリクエスト

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

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

動的フィルタリング

動的フィルタリングは、特に以下の用途で効果的です：

技術ドキュメントの検索
文献レビューと引用の検証
技術調査
レスポンスの根拠付けと検証

動的フィルタリングを有効にするには、web_search_20260209以降のバージョンを使用します。以下の例ではweb_search_20260209を使用しています：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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_20260209", "name": "web_search"}],
)
print(response)

Web検索の使用方法

組織の管理者がClaude ConsoleでWeb検索を有効にする必要があります。

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

client = anthropic.Anthropic()

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

ツール定義

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

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
  "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_domainsとblocked_domainsによるドメインフィルタリングについては、サーバーツールを参照してください。

ローカライゼーション

user_locationパラメータを使用すると、ユーザーの位置情報に基づいて検索結果をローカライズできます。

type：位置情報のタイプ（approximateである必要があります）
city：都市名
region：地域または州
country：国
timezone：IANAタイムゾーンID

レスポンス包含

web_search_20260318以降が必要です。

{
  "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"
}

検索結果

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

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

引用

Web検索では引用が常に有効になっており、各web_search_result_locationには以下が含まれます：

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

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

エラー

Output

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

以下は発生する可能性のあるエラーコードです：

too_many_requests：レート制限を超過しました
invalid_input：無効な検索クエリパラメータ
max_uses_exceeded：Web検索ツールの最大使用回数を超過しました
query_too_long：クエリが最大長を超えています
unavailable：内部エラーが発生しました

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

バッチリクエスト

使用量と料金

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

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

次のステップ

サーバーツール

Anthropicが実行するツールの共通メカニズム。

ツールリファレンス

Anthropicが提供するすべてのツールのディレクトリ。

Was this page helpful?

Web検索の仕組み

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

動的フィルタリング

Web検索の使用方法

ツール定義

最大使用回数

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

ローカライゼーション

レスポンス包含

レスポンス

検索結果

引用

エラー

pause_turn停止理由

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

ストリーミング

バッチリクエスト

使用量と料金

次のステップ

Web検索の仕組み

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

動的フィルタリング

Web検索の使用方法

ツール定義

最大使用回数

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

ローカライゼーション

レスポンス包含

レスポンス

検索結果

引用

エラー

pause_turn停止理由

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

ストリーミング

バッチリクエスト

使用量と料金

次のステップ

Web検索の仕組み

Claudeが検索するタイミング

動的フィルタリング

Web検索の使用方法

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンス包含

レスポンス

検索結果

引用

エラー

`pause_turn`停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

次のステップ

Web検索の仕組み

Claudeが検索するタイミング

動的フィルタリング

Web検索の使用方法

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンス包含

レスポンス

検索結果

引用

エラー

`pause_turn`停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

次のステップ