網頁搜尋工具讓 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 (新版) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
網頁搜尋的運作方式

當您將網頁搜尋工具加入您的 API 請求時：

  1. Claude 根據提示決定何時進行搜尋。
  2. API 執行搜尋並向 Claude 提供結果。此過程可能在單一請求中重複多次。
  3. 在其回合結束時，Claude 提供包含引用來源的最終回應。

​
如何使用網頁搜尋

您組織的管理員必須在控制台中啟用網頁搜尋。

在您的 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 協定（使用 example.com 而非 https://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 繼續其回合，或者如果您希望中斷對話，可以修改內容。

​
提示快取

網頁搜尋與提示快取配合使用。要啟用提示快取，請在您的請求中添加至少一個 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
})

# 第二個在搜尋結果後帶有快取中斷點的請求
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"
        }
    }]
)
# 第二個回應將受益於快取的搜尋結果
# 同時仍能在需要時執行新的搜尋
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 的回應與引用（在此範例中省略）

​
批次請求

您可以在訊息批次 API中包含網頁搜尋工具。透過訊息批次 API 的網頁搜尋工具呼叫與一般訊息 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.