ウェブ検索ツール

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

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

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

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

• Claude Opus 4.1 (claude-opus-4-1-20250805)
• 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リクエストでウェブ検索ツールを提供します：

Shell

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-1-20250805",
        "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

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のいずれかを使用できますが、両方は使用できません。

リクエストレベルのドメイン制限は、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_search_result_locationには以下が含まれます：

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

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

エンドユーザーにウェブ結果またはウェブ結果に含まれる情報を表示する場合、インライン引用はユーザーインターフェースで明確に見えるようにし、クリック可能にする必要があります。

エラー

ウェブ検索ツールがエラー（レート制限に達するなど）に遭遇した場合でも、Anthropic 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：最大ウェブ検索ツール使用数を超過
• 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-1-20250805",
    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-1-20250805",
    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.