網頁搜尋工具

讓 Claude 能夠存取附有引用來源的最新網頁內容，並可選用動態篩選與網域控制。

「Web search tool」（網頁搜尋工具）讓 Claude 能夠直接存取即時網頁內容，使其能以超出知識截止日期的最新資訊回答問題。回應中會包含取自搜尋結果之來源的「citations」（引用）。

使用 web_search_20260209 及更新版本時，Claude 可以撰寫並執行程式碼，在搜尋結果進入「context window」（上下文視窗）之前先行篩選（dynamic filtering，動態篩選），僅保留相關資訊。動態篩選適用於 Claude 4.6 及更新的模型，以及 Claude Mythos Preview。

網頁搜尋工具共有三個版本可供使用：

web_search_20250305：基本網頁搜尋
web_search_20260209：新增動態篩選
web_search_20260318：新增適用於代理式工作流程的回應包含控制

本頁的範例使用 web_search_20250305 進行基本搜尋，並使用 web_search_20260318 進行動態篩選。

關於網頁搜尋的零資料保留（Zero Data Retention）資格以及相關的 allowed_callers 設定，請參閱伺服器工具。

關於模型支援情況，請參閱工具參考。

網頁搜尋的運作方式

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

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

Claude 何時進行搜尋

當請求仰賴的資訊是最新的、持續變動的，或超出其訓練資料範圍時，Claude 會進行搜尋：

近期事件、新聞或公告
目前的價格、費率、比分或統計數據
關於特定組織、人物或產品且可能已有變動的資訊
明確要求搜尋或查詢某事物

當請求仰賴的是穩定的知識時，Claude 會直接回答而不進行搜尋：

既定事實、數學、科學基礎或程式設計概念
創意寫作或腦力激盪
分析對話中已提供的內容
對話性的回合與問候

觸發行為可透過您的「system prompt」（系統提示）加以引導：您可以鼓勵 Claude 更積極地搜尋，或偏好直接回答。若需要硬性限制，請使用 max_uses 來限制每個請求的搜尋次數上限。

動態篩選

使用基本網頁搜尋時，每一筆搜尋結果都會載入 Claude 的上下文視窗，而其中許多內容可能與請求無關。使用 web_search_20260209 或更新版本時，Claude 會改為先撰寫並執行程式碼來篩選結果，因此只有相關內容會進入上下文視窗。這能減少大量搜尋型請求的 token 用量。

動態篩選是從程式碼執行內部執行網頁搜尋：在 web_search_20260209 及更新版本上，工具的 allowed_callers 欄位預設為 ["code_execution_20260120"]，而當動態篩選執行時，API 會自動為該請求佈建所需的程式碼執行環境。您不需要自行將程式碼執行工具加入 tools。以此方式進行的程式碼執行呼叫，除標準 token 費用外不會產生額外費用。

若要直接呼叫網頁搜尋而不使用動態篩選，請設定 allowed_callers: ["direct"]。不支援程式化工具呼叫的模型必須使用此設定。若未設定，API 會回傳 400 錯誤並提示您進行設定。

以下範例使用 web_search_20260318：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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_20260318", "name": "web_search"}],
)
print(response)

如何使用網頁搜尋

Claude Console 中的這些組織層級設定僅適用於 Messages API 請求。Claude Managed Agents 工作階段僅使用代理工具集上各工具的 allowed_domains 和 blocked_domains 清單；請參閱限制網頁搜尋與網頁擷取的網域。

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

工具定義

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

JSON

{
  "type": "web_search_20250305",
  "name": "web_search",

  // Optional: Limit the number of searches per request
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

所有網頁搜尋工具版本皆接受 allowed_callers，此參數控制 Claude 是直接呼叫網頁搜尋，還是透過動態篩選從程式碼執行中呼叫。在 web_search_20260209 及更新版本上，其預設值為 ["code_execution_20260120"] 而非 ["direct"]。關於如何設定，請參閱伺服器工具。web_search_20260318 及更新版本也接受 response_inclusion。

最大使用次數

max_uses 參數限制執行的搜尋次數。若 Claude 嘗試的搜尋次數超過允許值，web_search_tool_result 會是帶有 max_uses_exceeded 錯誤代碼的錯誤。

簡單的事實查詢通常使用 1–3 次搜尋；比較性或多實體研究可能使用 10 次或更多。關於如何選擇數值的指引，請參閱伺服器工具。

網域篩選

請提供 allowed_domains 或 blocked_domains 其中之一，不可同時提供。若請求同時包含兩者，API 會回傳 400 錯誤。項目為不含協定的純網域，可選擇性附加路徑，例如 example.com 或 example.com/blog。

關於完整的網域篩選規則，請參閱伺服器工具指南中的網域篩選。

在 Claude Managed Agents 上，請在代理工具集的 web_search 項目上設定這些欄位；請參閱限制網頁搜尋與網頁擷取的網域。

在地化

user_location 參數可讓您根據使用者的位置將搜尋結果在地化。請至少提供 city、region、country 或 timezone 其中之一。

type：位置類型（必須為 approximate）
city：城市名稱
region：地區或州
country：兩個字母的 ISO 3166-1 alpha-2 國家代碼。API 會以 400 錯誤拒絕不支援的國家代碼。
timezone：IANA 時區 ID。

在 Claude Managed Agents 上，代理工具集的 web_search 項目接受具有相同欄位的 user_location 物件。當您建立或更新代理，或建立或更新提供此設定的工作階段時，API 會以 400 錯誤拒絕不支援的 country 代碼。請參閱限制網頁搜尋與網頁擷取的網域。

回應包含

response_inclusion 參數控制當搜尋結果已被同一回合中已完成的程式碼執行呼叫所使用時，搜尋結果區塊在 API 回應中的呈現方式。設定 "response_inclusion": "excluded" 可將這些巢狀的 server_tool_use 與結果區塊配對從回應中完全移除，為不需要將原始搜尋內容回傳給用戶端的代理式工作流程降低輸出 token 費用。預設值為 "full"。來自直接呼叫的結果，或來自在完成前暫停的程式碼執行呼叫的結果，一律會完整回傳，以便在下一回合送回。

JSON

{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

回應

以下是回應結構範例：

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "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's response with citations
    {
      "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"
}

此範例顯示的是直接搜尋。當搜尋透過動態篩選執行時，回應中也會包含程式碼執行工具的結果區塊，且每個巢狀的 server_tool_use 與 web_search_tool_result 配對都帶有 caller 欄位，用以識別發出該呼叫的程式碼執行呼叫。

搜尋結果

搜尋結果包含：

url：來源頁面的 URL
title：來源頁面的標題
page_age：網站上次更新的時間
encrypted_content：在多回合對話中必須回傳的加密內容

若要延續包含搜尋結果的對話，請將助理的內容區塊原封不動地送回，包括每筆結果的 encrypted_content。API 會在後續回合解密該內容，以在 Claude 的上下文中還原搜尋結果。若 encrypted_content 遺失或遭修改，請求會失敗並回傳 400 驗證錯誤。

引用

網頁搜尋一律啟用引用，每個 web_search_result_location 包含：

url：被引用來源的 URL
title：被引用來源的標題
encrypted_index：在多回合對話中必須回傳的參照
cited_text：最多 150 個字元的被引用內容

網頁搜尋引用欄位 cited_text、title 和 url 不計入輸入或輸出 token 用量。

錯誤

當網頁搜尋工具遇到錯誤（例如達到速率限制）時，Claude API 仍會回傳 200（成功）回應。錯誤會以下列結構呈現在回應主體中：

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

發生錯誤時，content 是單一錯誤物件，而非結果區塊清單。搜尋成功但沒有符合結果時，會回傳空的 content 清單，而非錯誤。

可能的錯誤代碼如下：

too_many_requests：超過速率限制
invalid_tool_input：無效的搜尋查詢參數
max_uses_exceeded：超過網頁搜尋工具的最大使用次數
query_too_long：查詢超過最大長度
request_too_large：搜尋請求過大，通常是因為網域篩選清單過長
unavailable：發生內部錯誤

`pause_turn` 停止原因

API 可能會暫停長時間執行的搜尋回合，並回傳 stop_reason: "pause_turn"。若要繼續，請在新的請求中將暫停的助理訊息原封不動地送回。

若 Claude 在同一組平行工具呼叫中同時呼叫網頁搜尋與您的某個用戶端工具，API 會改為回傳 stop_reason: "tool_use"，且暫不執行搜尋。若要繼續，請回傳用戶端工具結果，API 會在下一個請求中執行搜尋。請參閱在同一回合中混用伺服器工具與用戶端工具。

關於伺服器端迴圈與 pause_turn 的處理方式，請參閱伺服器工具指南中的伺服器端迴圈與 pause_turn。

提示快取

若要跨回合快取工具定義，請參閱搭配提示快取的工具使用。

串流

啟用「streaming」（串流）後，您會在串流中收到搜尋事件。搜尋執行期間會有一段暫停：

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's decision to search

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_search"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search executes

// Search results streamed
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's response with citations (omitted in this example)

批次請求

您可以在 Messages Batches API 中包含網頁搜尋工具。透過 Messages Batches API 進行的網頁搜尋工具呼叫，其計價與一般 Messages API 請求中的呼叫相同。

為保護共用容量，Batches API 會依組織對網頁搜尋請求進行節流，因此包含大量搜尋的大型批次可能需要較長時間才能完成。您可以在 Claude Console 的速率限制頁面查看您組織的網頁搜尋速率限制。若要申請更高的限制，請從該頁面聯絡銷售團隊。

用量與定價

除了 token 用量之外，網頁搜尋的使用也會另外計費：

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 6039,
    "cache_read_input_tokens": 7123,
    "cache_creation_input_tokens": 7345,
    "server_tool_use": {
      "web_search_requests": 1
    }
  }
}

網頁搜尋在 Claude API 上的價格為每 1,000 次搜尋 $10 美元，另加搜尋所產生內容的標準 token 費用。在整個對話過程中擷取的網頁搜尋結果會計為 input tokens（輸入 token），包括在單一回合中執行的搜尋迭代，以及後續的對話回合。

每次網頁搜尋計為一次使用，無論回傳的結果數量多寡。若網頁搜尋過程中發生錯誤，該次網頁搜尋將不會計費。

後續步驟

網頁擷取工具

從特定 URL 擷取並讀取內容，以即時網頁內容擴充 Claude 的上下文。

伺服器工具

使用由 Anthropic 執行的工具：server_tool_use 區塊、pause_turn 接續，以及網域篩選。

工具參考

Anthropic 提供之工具的目錄，以及選用工具定義屬性的參考。

網頁搜尋的運作方式

Claude 何時進行搜尋

動態篩選

如何使用網頁搜尋

工具定義

最大使用次數

網域篩選

在地化

回應包含

回應

搜尋結果

引用

錯誤

pause_turn 停止原因

提示快取

串流

批次請求

用量與定價

後續步驟

網頁搜尋的運作方式

Claude 何時進行搜尋

動態篩選

如何使用網頁搜尋

工具定義

最大使用次數

網域篩選

在地化

回應包含

回應

搜尋結果

引用

錯誤

`pause_turn` 停止原因

提示快取

串流

批次請求

用量與定價

後續步驟