ツール

Web検索ツール

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

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

Web検索ツールの使用体験を共有するために、フィードバックフォームからご連絡ください。

サポートされているモデル

Web検索は以下で利用可能です：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (非推奨) (claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5 (非推奨) (claude-3-5-haiku-latest)

Web検索の仕組み

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

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

Web検索の使い方

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

APIリクエストにWeb検索ツールを含めてください：

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "What is the weather in NYC?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

ツール定義

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

JSON

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

  // オプション：リクエストあたりの検索回数を制限
  "max_uses": 5,

  // オプション：これらのドメインからの結果のみを含める
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // オプション：これらのドメインからの結果を含めない
  "blocked_domains": ["untrustedsource.com"],

  // オプション：検索結果をローカライズ
  "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エラーコードのエラーになります。

ドメインフィルタリング

ドメインフィルターを使用する場合：

ドメインにはHTTP/HTTPSスキームを含めないでください（https://example.comではなくexample.comを使用）
サブドメインは自動的に含まれます（example.comはdocs.example.comをカバーします）
特定のサブドメインを指定すると、そのサブドメインのみに結果が制限されます（docs.example.comはそのサブドメインからの結果のみを返し、example.comやapi.example.comからは返しません）
サブパスがサポートされており、パス以降のすべてにマッチします（example.com/blogはexample.com/blog/post-1にマッチします）
allowed_domainsまたはblocked_domainsのいずれかを使用できますが、同じリクエストで両方を使用することはできません。

ワイルドカードサポート：

ドメインエントリごとに1つのワイルドカード（*）のみが許可され、ドメイン部分の後（パス内）に配置する必要があります
有効：example.com/*、example.com/*/articles
無効：*.example.com、ex*.com、example.com/*/news/*

無効なドメイン形式はinvalid_tool_inputツールエラーを返します。

リクエストレベルのドメイン制限は、Consoleで設定された組織レベルのドメイン制限と互換性がある必要があります。リクエストレベルのドメインはドメインをさらに制限することのみ可能で、組織レベルのリストを上書きしたり拡張したりすることはできません。リクエストに組織設定と競合するドメインが含まれている場合、APIはバリデーションエラーを返します。

ローカライゼーション

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

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

レスポンス

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

{
  "role": "assistant",
  "content": [
    // 1. Claudeの検索判断
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. 使用された検索クエリ
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. 検索結果
    {
      "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の回答
    {
      "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（成功）レスポンスを返します。エラーはレスポンスボディ内で以下の構造を使用して表現されます：

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_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停止理由が含まれる場合があります。これはAPIが長時間実行されているターンを一時停止したことを示します。Claudeにターンを続行させるために、後続のリクエストでレスポンスをそのまま返すか、会話を中断したい場合はコンテンツを変更できます。

プロンプトキャッシング

Web検索はプロンプトキャッシングと連携します。プロンプトキャッシングを有効にするには、リクエストに少なくとも1つのcache_controlブレークポイントを追加してください。システムはツール実行時に最後のweb_search_tool_resultブロックまでを自動的にキャッシュします。

マルチターン会話の場合、キャッシュされたコンテンツを再利用するために、最後のweb_search_tool_resultブロック以降にcache_controlブレークポイントを設定してください。

例えば、マルチターン会話でWeb検索とプロンプトキャッシングを使用する場合：

import anthropic

client = anthropic.Anthropic()

# Web検索とキャッシュブレークポイントを含む最初のリクエスト
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Claudeの回答を会話に追加
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 検索結果の後にキャッシュブレークポイントを含む2番目のリクエスト
messages.append({
    "role": "user",
    "content": "Should I expect rain later this week?",
    "cache_control": {"type": "ephemeral"}  # この時点までキャッシュ
})

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# 2番目のレスポンスはキャッシュされた検索結果の恩恵を受けつつ、
# 必要に応じて新しい検索を実行できます
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

ストリーミング

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

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の検索判断

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

// 検索クエリのストリーミング
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// 検索実行中の一時停止

// 検索結果のストリーミング
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の回答（この例では省略）

バッチリクエスト

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

使用量と料金

Web search usage is charged in addition to token usage:

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

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

Was this page helpful?

ツール

Web検索ツール

Web検索ツールの使用体験を共有するために、フィードバックフォームからご連絡ください。

サポートされているモデル

Web検索は以下で利用可能です：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7 (非推奨) (claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5 (非推奨) (claude-3-5-haiku-latest)

Web検索の仕組み

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

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

Web検索の使い方

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

APIリクエストにWeb検索ツールを含めてください：

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "What is the weather in NYC?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

ツール定義

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

JSON

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

  // オプション：リクエストあたりの検索回数を制限
  "max_uses": 5,

  // オプション：これらのドメインからの結果のみを含める
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // オプション：これらのドメインからの結果を含めない
  "blocked_domains": ["untrustedsource.com"],

  // オプション：検索結果をローカライズ
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

最大使用回数

ドメインフィルタリング

ドメインフィルターを使用する場合：

ドメインにはHTTP/HTTPSスキームを含めないでください（https://example.comではなくexample.comを使用）
サブドメインは自動的に含まれます（example.comはdocs.example.comをカバーします）
特定のサブドメインを指定すると、そのサブドメインのみに結果が制限されます（docs.example.comはそのサブドメインからの結果のみを返し、example.comやapi.example.comからは返しません）
サブパスがサポートされており、パス以降のすべてにマッチします（example.com/blogはexample.com/blog/post-1にマッチします）
allowed_domainsまたはblocked_domainsのいずれかを使用できますが、同じリクエストで両方を使用することはできません。

ワイルドカードサポート：

ドメインエントリごとに1つのワイルドカード（*）のみが許可され、ドメイン部分の後（パス内）に配置する必要があります
有効：example.com/*、example.com/*/articles
無効：*.example.com、ex*.com、example.com/*/news/*

無効なドメイン形式はinvalid_tool_inputツールエラーを返します。

ローカライゼーション

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

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

レスポンス

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

{
  "role": "assistant",
  "content": [
    // 1. Claudeの検索判断
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. 使用された検索クエリ
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. 検索結果
    {
      "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の回答
    {
      "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は入力トークンまたは出力トークンの使用量にカウントされません。

エラー

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_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`停止理由

プロンプトキャッシング

例えば、マルチターン会話でWeb検索とプロンプトキャッシングを使用する場合：

import anthropic

client = anthropic.Anthropic()

# Web検索とキャッシュブレークポイントを含む最初のリクエスト
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# Claudeの回答を会話に追加
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 検索結果の後にキャッシュブレークポイントを含む2番目のリクエスト
messages.append({
    "role": "user",
    "content": "Should I expect rain later this week?",
    "cache_control": {"type": "ephemeral"}  # この時点までキャッシュ
})

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# 2番目のレスポンスはキャッシュされた検索結果の恩恵を受けつつ、
# 必要に応じて新しい検索を実行できます
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

ストリーミング

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

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の検索判断

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

// 検索クエリのストリーミング
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// 検索実行中の一時停止

// 検索結果のストリーミング
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の回答（この例では省略）

バッチリクエスト

使用量と料金

Web search usage is charged in addition to token usage:

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

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

Was this page helpful?

サポートされているモデル

Web検索の仕組み

Web検索の使い方

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンス

検索結果

引用

エラー

pause_turn停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

サポートされているモデル

Web検索の仕組み

Web検索の使い方

ツール定義

最大使用回数

ドメインフィルタリング

ローカライゼーション

レスポンス

検索結果

引用

エラー

pause_turn停止理由

プロンプトキャッシング

ストリーミング

バッチリクエスト

使用量と料金

`pause_turn`停止理由

`pause_turn`停止理由