Messages工具

網頁搜尋工具

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

最新的網頁搜尋工具版本（web_search_20260318）支援動態過濾，適用於 Claude Fable 5、Claude Opus 4.8、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6。Claude 可以編寫並執行程式碼，在搜尋結果進入「context window」（上下文視窗）之前對其進行過濾，只保留相關資訊並捨棄其餘內容。這能產生更準確的回應，同時減少 token 消耗。web_search_20260318 也為代理式工作流程新增了回應包含控制功能。先前的版本（web_search_20260209 僅支援動態過濾，web_search_20250305 為基本搜尋）仍然可用。

對於 Claude Mythos Preview，網頁搜尋在 Claude API、Microsoft Foundry 和 Vertex AI 上受支援。在 Amazon Bedrock 或 Claude Platform on AWS 上，Mythos Preview 不支援網頁搜尋。

關於零資料保留（Zero Data Retention）資格與 allowed_callers 解決方法，請參閱伺服器工具。

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

網頁搜尋的運作方式

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

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

Claude 何時進行搜尋

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

近期事件、新聞或公告
當前價格、匯率、比分或統計數據
關於特定組織、人物或產品的資訊（這些資訊可能已有變化）
明確要求搜尋或查詢某些內容

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

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

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

動態過濾

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

使用 web_search_20260209 或更新版本時，Claude 可以編寫並執行程式碼來對查詢結果進行後處理。Claude 不再對完整的 HTML 檔案進行推理，而是在將搜尋結果載入上下文之前動態過濾，只保留相關內容並捨棄其餘部分。

動態過濾特別適用於：

搜尋技術文件
文獻回顧與引用驗證
技術研究
回應依據與驗證

動態過濾需要啟用程式碼執行工具。網頁搜尋工具（無論是否啟用動態過濾）可在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上使用。在 Vertex AI 上，僅提供基本網頁搜尋工具（不含動態過濾）。Amazon Bedrock 上不提供網頁搜尋。

若要啟用動態過濾，請使用 web_search_20260209 或任何更新版本。以下範例使用 web_search_20260209：

client = anthropic.Anthropic()

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

如何使用網頁搜尋

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

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

client = anthropic.Anthropic()

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

最大使用次數

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

簡單的事實性查詢通常使用 1–3 次搜尋；比較性或多實體研究可能使用 10 次或更多。對於延遲敏感的查詢，max_uses: 3 可限制成本，同時很少造成截斷。對於研究型代理，請將 max_uses 設為 15–20 或完全省略。

網域過濾

關於使用 allowed_domains 和 blocked_domains 進行網域過濾，請參閱伺服器工具。

在地化

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

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

回應包含

需要 web_search_20260318 或更新版本。

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

{
  "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"
}

搜尋結果

搜尋結果包含：

url：來源頁面的 URL
title：來源頁面的標題
page_age：網站最後更新的時間
encrypted_content：加密內容，在多回合對話中必須傳回以用於引用

引用

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

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

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

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

錯誤

當網頁搜尋工具遇到錯誤（例如達到速率限制）時，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"
  }
}

以下是可能的錯誤代碼：

too_many_requests：超過速率限制
invalid_input：無效的搜尋查詢參數
max_uses_exceeded：超過網頁搜尋工具的最大使用次數
query_too_long：查詢超過最大長度
unavailable：發生內部錯誤

`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 費用。在整個對話過程中擷取的網路搜尋結果會被計為輸入 token，包括在單一回合中執行的搜尋迭代以及後續對話回合中的結果。

每次網路搜尋都計為一次使用，無論傳回的結果數量為何。如果在網路搜尋期間發生錯誤，該次網路搜尋將不會被計費。

後續步驟

伺服器工具

Anthropic 執行工具的共用機制。

工具參考

所有 Anthropic 提供工具的目錄。

Was this page helpful?

Messages工具

網頁搜尋工具

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

對於 Claude Mythos Preview，網頁搜尋在 Claude API、Microsoft Foundry 和 Vertex AI 上受支援。在 Amazon Bedrock 或 Claude Platform on AWS 上，Mythos Preview 不支援網頁搜尋。

關於零資料保留（Zero Data Retention）資格與 allowed_callers 解決方法，請參閱伺服器工具。

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

網頁搜尋的運作方式

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

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

Claude 何時進行搜尋

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

近期事件、新聞或公告
當前價格、匯率、比分或統計數據
關於特定組織、人物或產品的資訊（這些資訊可能已有變化）
明確要求搜尋或查詢某些內容

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

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

動態過濾

動態過濾特別適用於：

搜尋技術文件
文獻回顧與引用驗證
技術研究
回應依據與驗證

若要啟用動態過濾，請使用 web_search_20260209 或任何更新版本。以下範例使用 web_search_20260209：

client = anthropic.Anthropic()

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

如何使用網頁搜尋

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

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

client = anthropic.Anthropic()

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

最大使用次數

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

網域過濾

關於使用 allowed_domains 和 blocked_domains 進行網域過濾，請參閱伺服器工具。

在地化

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

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

回應包含

需要 web_search_20260318 或更新版本。

{
  "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"
}

搜尋結果

搜尋結果包含：

url：來源頁面的 URL
title：來源頁面的標題
page_age：網站最後更新的時間
encrypted_content：加密內容，在多回合對話中必須傳回以用於引用

引用

網頁搜尋一律啟用引用，每個 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"
  }
}

以下是可能的錯誤代碼：

too_many_requests：超過速率限制
invalid_input：無效的搜尋查詢參數
max_uses_exceeded：超過網頁搜尋工具的最大使用次數
query_too_long：查詢超過最大長度
unavailable：發生內部錯誤

`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 請求中的呼叫相同。

使用量與定價

網路搜尋的使用費用會在 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
    }
  }
}

每次網路搜尋都計為一次使用，無論傳回的結果數量為何。如果在網路搜尋期間發生錯誤，該次網路搜尋將不會被計費。

後續步驟

伺服器工具

Anthropic 執行工具的共用機制。

工具參考

所有 Anthropic 提供工具的目錄。

Was this page helpful?

網頁搜尋的運作方式

Claude 何時進行搜尋

動態過濾

如何使用網頁搜尋

工具定義

最大使用次數

網域過濾

在地化

回應包含

回應

搜尋結果

引用

錯誤

pause_turn 停止原因

提示快取

串流

批次請求

使用量與定價

後續步驟

網頁搜尋的運作方式

Claude 何時進行搜尋

動態過濾

如何使用網頁搜尋

工具定義

最大使用次數

網域過濾

在地化

回應包含

回應

搜尋結果

引用

錯誤

pause_turn 停止原因

提示快取

串流

批次請求

使用量與定價

後續步驟

網頁搜尋的運作方式

Claude 何時進行搜尋

動態過濾

如何使用網頁搜尋

工具定義

最大使用次數

網域過濾

在地化

回應包含

回應

搜尋結果

引用

錯誤

`pause_turn` 停止原因

提示快取

串流

批次請求

使用量與定價

後續步驟

網頁搜尋的運作方式

Claude 何時進行搜尋

動態過濾

如何使用網頁搜尋

工具定義

最大使用次數

網域過濾

在地化

回應包含

回應

搜尋結果

引用

錯誤

`pause_turn` 停止原因

提示快取

串流

批次請求

使用量與定價

後續步驟