ウェブ検索ツールは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に結果を提供します。このプロセスは1つのリクエスト内で複数回繰り返される場合があります。
  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リクエストと同じ価格で課金されます。

​
使用量と価格

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

"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 APIで1,000回の検索あたり$10で利用可能で、検索によって生成されたコンテンツの標準トークンコストが追加されます。会話全体で取得されたウェブ検索結果は、1回のターン中に実行された検索イテレーションと、後続の会話ターンの両方で入力トークンとしてカウントされます。

返される結果の数に関係なく、各ウェブ検索は1回の使用としてカウントされます。ウェブ検索中にエラーが発生した場合、そのウェブ検索は課金されません。