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

ウェブ検索ツールでの体験を共有するために、フィードバックフォームからお気軽にお問い合わせください。

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

ウェブ検索は以下で利用可能です：

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (new) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
ウェブ検索の仕組み

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

  1. Claudeはプロンプトに基づいて検索するタイミングを決定します。
  2. APIが検索を実行し、Claudeに結果を提供します。このプロセスは単一のリクエスト中に複数回繰り返される場合があります。
  3. ターンの最後に、Claudeは引用されたソースと共に最終的な回答を提供します。

​
ウェブ検索の使用方法

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

APIリクエストでウェブ検索ツールを提供します：

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-20250514",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "How do I update a web app to TypeScript 5.5?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

​
ツール定義

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

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をカバーします）
  • サブパスがサポートされています（example.com/blog）
  • 同じリクエストでallowed_domainsまたはblocked_domainsのいずれかを使用できますが、両方は使用できません。

​
ローカライゼーション

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_search_result_locationには以下が含まれます：

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

ウェブ検索の引用フィールド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：ウェブ検索ツールの最大使用回数を超過
  • query_too_long：クエリが最大長を超過
  • unavailable：内部エラーが発生

​
pause_turn停止理由

レスポンスにはpause_turn停止理由が含まれる場合があり、これはAPIが長時間実行されるターンを一時停止したことを示します。後続のリクエストでレスポンスをそのまま提供してClaudeにターンを続行させるか、会話を中断したい場合はコンテンツを変更できます。

​
プロンプトキャッシュ

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

マルチターン会話では、最後のweb_search_tool_resultブロック上またはその後にcache_controlブレークポイントを設定して、キャッシュされたコンテンツを再利用します。

例えば、マルチターン会話でウェブ検索とプロンプトキャッシュを使用するには：

import anthropic

client = anthropic.Anthropic()

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

response1 = client.messages.create(
    model="claude-opus-4-20250514",
    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-20250514",
    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にウェブ検索ツールを含めることができます。Messages Batches APIを通じたウェブ検索ツール呼び出しは、通常の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 Anthropic 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.