網頁搜尋工具

讓 Claude 存取最新的網路內容並附上引用來源，支援選用的動態篩選與網域控制。

用法因產品而異

Messages API

在請求的 tools 中加入 web_search 工具。max_uses、網域清單與 user_location 等設定皆放在該工具上。

Managed Agents

在代理工具集中預設開啟，不提供 max_uses、citations 或 cache_control。

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

使用 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 設定，請參閱伺服器工具。

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

若要在傳送請求之前檢查模型是否接受網路搜尋，請從 Models API 讀取其 capabilities.server_tools.web_search.supported 值。使用 Models API 說明了此欄位。

網路搜尋的運作方式

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

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

Claude 何時進行搜尋

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

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

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

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

觸發行為可透過您的系統提示來引導：您可以鼓勵 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 Managed Agents 工作階段，請參閱限制網路搜尋與網頁擷取網域。

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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
  "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"]。關於如何設定，請參閱 ZDR 與 allowed_callers。web_search_20260318 及更新版本也接受 response_inclusion。

最大使用次數

max_uses 參數限制單一回合中的搜尋次數。單一事實查詢通常使用 1–3 次搜尋；比較性或多實體的研究可能使用 10 次以上。

失敗的搜尋也會計入限制。如果 Claude 直接呼叫網路搜尋的次數超過允許值，web_search_tool_result 會是帶有 max_uses_exceeded 錯誤代碼的錯誤。如果 Claude 從程式碼執行中呼叫網路搜尋的次數超過允許值，該程式碼執行會以錯誤結束。

一個回合可以跨越多個請求。當請求是在 pause_turn 之後恢復，或其最後一則訊息僅包含 tool_result 區塊時，該請求即延續同一回合。該回合中先前請求的搜尋會計入限制，除非 Claude 是透過動態篩選從程式碼執行中執行這些搜尋。

網域篩選

請提供 allowed_domains 或 blocked_domains，不可同時提供兩者。若請求同時包含兩者，API 會回傳 400 錯誤。項目為不含 scheme 的純網域，可選擇性加上路徑，例如 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；請參閱網路工具設定。

回應納入

response_inclusion 參數控制當搜尋結果已被同一回應中已完成的程式碼執行呼叫使用時，搜尋結果區塊如何出現在 API 回應中。設定 "response_inclusion": "excluded" 可將這些巢狀的 server_tool_use 與結果區塊配對從回應中完全移除，適用於不需要原始搜尋內容的代理式工作流程。Token 用量不受影響，因為 Claude 讀取的是程式碼的輸出，而非這些區塊。預設值為 "full"。API 一律會完整回傳來自直接呼叫的結果，或來自在完成前暫停的程式碼執行呼叫的結果，以便您在下一個請求中傳回。

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。

提示快取

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

串流

啟用串流後，您會在串流中收到搜尋事件。搜尋執行期間會有暫停：

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 runs

// 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)

批次請求

您可以在 Message Batches API 中包含網路搜尋工具。透過 Message 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 費用。在整個對話過程中擷取的網頁搜尋結果，無論是在單一回合內執行的搜尋迭代中，還是在後續的對話回合中，都會計為輸入 token。

每次網頁搜尋計為一次使用，無論回傳的結果數量多寡。發生錯誤而失敗的網頁搜尋不會計費。

後續步驟

網頁擷取工具

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

伺服器工具

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

工具參考

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

可用性

網頁搜尋工具在所有模型上可供使用，且具備零資料保留和HIPAA 就緒資格。

API 支援

Messages API

用法

在請求的 tools 中加入 web_search 工具。max_uses、網域清單與 user_location 等設定皆放在該工具上。

狀態可用

雲端平台

Claude API
Claude Platform on AWS
Claude Models on Google CloudAnthropic managed
Microsoft FoundryHosted on Anthropic

狀態可用

雲端平台

Claude Models on Google CloudGoogle managed
Microsoft FoundryHosted on Azure

僅支援基本網頁搜尋工具（web_search_20250305），不含動態篩選。

Managed Agents

用法

屬於代理工具集的一部分，加入工具集後即預設開啟。網域清單與 user_location 放在工具集的 web_search 項目上；不提供 max_uses、citations 與 cache_control。

狀態可用

雲端平台

Claude API
Claude Platform on AWS

資料處理

資料處理概覽

適用端點

/v1/messages 搭配 web_search 工具

零資料保留符合資格

不含涵蓋的模型

即時網頁搜尋結果會在 API 回應中傳回。網頁搜尋的動態篩選不符合 ZDR 或 HIPAA 的適用資格。

HIPAA符合資格

網頁搜尋的動態篩選不符合 ZDR 或 HIPAA 的適用資格。

網路搜尋的運作方式

Claude 何時進行搜尋

動態篩選

如何使用網路搜尋

工具定義

最大使用次數

網域篩選

在地化

回應納入

回應

搜尋結果

引用

錯誤

pause_turn 停止原因

提示快取

串流

批次請求

用量與定價

後續步驟

可用性

API 支援

資料處理

網路搜尋的運作方式

Claude 何時進行搜尋

動態篩選

如何使用網路搜尋

工具定義

最大使用次數

網域篩選

在地化

回應納入

回應

搜尋結果

引用

錯誤

`pause_turn` 停止原因

提示快取

串流

批次請求

用量與定價

後續步驟

可用性

API 支援

資料處理