網頁搜尋工具

網頁搜尋工具讓 Claude 直接存取即時網頁內容，使其能夠以超越知識截止日期的最新資訊回答問題。回應包含從搜尋結果中提取的來源引用。

最新的網頁搜尋工具版本（web_search_20260209）支援動態篩選，適用於 Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6。Claude 可以編寫並執行程式碼來篩選搜尋結果，在它們進入上下文視窗之前進行篩選，只保留相關資訊並捨棄其餘部分。這導致更準確的回應，同時減少代幣消耗。先前的工具版本（web_search_20250305）仍然可用，但不支援動態篩選。

對於 Claude Mythos Preview，網頁搜尋在 Claude API、Microsoft Foundry 和 Google Vertex AI 上受支援。Mythos Preview 在 Amazon Bedrock 上不提供網頁搜尋。

如需零資料保留資格和 allowed_callers 解決方案，請參閱伺服器工具。

如需模型支援，請參閱工具參考。

網頁搜尋的運作方式

當您在 API 請求中新增網頁搜尋工具時：

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

動態篩選

網頁搜尋是一項代幣密集的任務。使用基本網頁搜尋時，Claude 需要將搜尋結果拉入上下文、從多個網站擷取完整 HTML，並在推理所有內容後才能得出答案。通常，大部分內容都是無關的，這可能會降低回應品質。

使用 web_search_20260209 工具版本，Claude 可以編寫並執行程式碼來後處理查詢結果。Claude 不是推理完整 HTML 檔案，而是在將搜尋結果載入上下文之前動態篩選它們，只保留相關內容並捨棄其餘部分。

動態篩選特別適用於：

搜尋技術文件
文獻回顧和引用驗證
技術研究
回應基礎和驗證

動態篩選需要啟用程式碼執行工具。改進的網頁搜尋工具在 Claude API 和 Microsoft Azure 上可用。在 Google Vertex AI 上，基本網頁搜尋工具（不支援動態篩選）可用。

若要啟用動態篩選，請使用 web_search_20260209 工具版本：

如何使用網頁搜尋

您組織的管理員必須在 Claude Console 中啟用網頁搜尋。

在您的 API 請求中提供網頁搜尋工具：

工具定義

網頁搜尋工具支援以下參數：

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 錯誤代碼的錯誤。

網域篩選

如需使用 allowed_domains 和 blocked_domains 進行網域篩選，請參閱伺服器工具。

本地化

user_location 參數允許您根據使用者的位置本地化搜尋結果。

type：位置類型（必須是 approximate）
city：城市名稱
region：地區或州
country：國家
timezone：IANA 時區 ID。

回應

以下是一個回應結構範例：

Output

{
  "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 不計入輸入或輸出代幣使用量。

在直接向終端使用者顯示 API 輸出時，必須包含對原始來源的引用。如果您在向終端使用者顯示之前對 API 輸出進行修改，包括重新處理和/或將其與您自己的材料結合，請根據與您的法律團隊的諮詢適當顯示引用。

錯誤

當網頁搜尋工具遇到錯誤（例如達到速率限制）時，Claude API 仍會傳回 200（成功）回應。錯誤在回應正文中使用以下結構表示：

Output

{
  "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 停止原因後繼續，請參閱伺服器工具。

提示快取

如需在各回合間快取工具定義，請參閱工具使用與提示快取。

串流

啟用串流後，您將在串流中接收搜尋事件。搜尋執行時會有暫停：

Output

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 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.

後續步驟

伺服器工具

Anthropic 執行工具的共享機制。

工具參考

所有 Anthropic 提供的工具目錄。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.",
        }
    ],
    tools=[{"type": "web_search_20260209", "name": "web_search"}],
)
print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

網頁搜尋的運作方式

動態篩選

如何使用網頁搜尋

工具定義

最大使用次數

網域篩選

本地化

回應

搜尋結果

引用

錯誤

pause_turn 停止原因

提示快取

串流

批次請求

使用和定價

後續步驟

`pause_turn` 停止原因