網頁擷取工具
從特定 URL 擷取並讀取內容，以即時網頁內容擴充 Claude 的上下文。
網頁擷取工具（web fetch tool）讓 Claude 能夠從指定的網頁和 PDF 文件中擷取完整內容。
最新的網頁擷取工具版本（web_fetch_20260318）支援動態過濾（dynamic filtering）：Claude 可以撰寫並執行程式碼，在擷取的內容進入「context window」（上下文視窗）之前先行過濾，只保留相關資訊並捨棄其餘部分。這能在維持回應品質的同時減少 token 消耗。動態過濾適用於 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 以及 Claude Sonnet 4.6。web_fetch_20260318 也為代理式工作流程新增了回應包含控制。先前的版本（web_fetch_20260309 支援動態過濾與快取繞過、web_fetch_20260209 僅支援動態過濾、web_fetch_20250910 為基本擷取）仍可使用。
網頁擷取（無論是否使用動態過濾）可在 Claude API、Claude Platform on AWS 以及 Microsoft Foundry 上使用。在 Microsoft Foundry 上，託管於 Azure 的部署僅支援基本網頁擷取工具（web_fetch_20250910，不含動態過濾）。託管於 Anthropic 的部署支援所有版本。網頁擷取目前無法在 Amazon Bedrock 或 Google Cloud 上使用。
關於零資料保留（Zero Data Retention）資格以及 allowed_callers 的替代方案，請參閱伺服器工具。
關於模型支援，請參閱工具參考。
網頁擷取的運作方式
網頁擷取是一種伺服器工具（server tool）：API 會在請求期間擷取內容，並將結果插入對話中。您不需要執行任何操作或回傳 tool_result。例外情況是當 Claude 在同一組平行工具呼叫中同時呼叫網頁擷取與您的某個用戶端工具時：API 會在該擷取執行之前以 stop_reason: "tool_use" 回傳回應，然後在您送回用戶端 tool_result 區塊時執行擷取。請參閱在同一輪中混合使用伺服器工具與用戶端工具。
當您將網頁擷取工具加入 API 請求時：
- Claude 會根據提示和可用的 URL 決定何時擷取內容。
- API 從指定的 URL 擷取完整的文字內容。
- 對於 PDF，API 會以 base64 編碼資料的形式回傳內容，並像直接附加的 PDF 文件一樣處理。
- Claude 分析擷取的內容，並提供附有選用引用的回應。
Claude 何時進行擷取
當請求指向特定頁面或文件時，Claude 會進行擷取：
- 對話中（或先前的工具結果中）提供了 URL
- 使用者指名特定資源（某篇文章、README、定價頁面或文件章節）但未提供 URL，且同時啟用了網頁搜尋工具，讓 Claude 能先找到它（請參閱結合搜尋與擷取）
對於未提及特定頁面的一般知識或開放式問題，Claude 不會進行擷取。「摘要這篇文章：<url>」會觸發擷取。「REST API 設計的最佳實務是什麼？」則會直接回答。
動態過濾
擷取完整的網頁和 PDF 可能會快速消耗 token，尤其是當只需要大型文件中的特定資訊時。使用 web_fetch_20260209 或更新版本時，Claude 可以撰寫並執行程式碼，在將擷取的內容載入上下文之前先行過濾。
這種動態過濾特別適用於：
- 從長篇文件中擷取特定章節
- 處理網頁中的結構化資料
- 從 PDF 中過濾相關資訊
- 在處理大型文件時降低 token 成本
若要啟用動態過濾，請使用 web_fetch_20260209 或任何更新版本。以下範例使用 web_fetch_20260318：
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
}
],
tools=[{"type": "web_fetch_20260318", "name": "web_fetch"}],
)
print(response)如何使用網頁擷取
在您的 API 請求中提供網頁擷取工具：
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Please analyze the content at https://example.com/article",
}
],
tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)工具定義
網頁擷取工具支援以下參數：
{
"type": "web_fetch_20250910",
"name": "web_fetch",
// Optional: Limit the number of fetches per request
"max_uses": 10,
// Optional: Only fetch from these domains
"allowed_domains": ["example.com", "docs.example.com"],
// Optional: Never fetch from these domains (cannot be combined with allowed_domains)
"blocked_domains": ["private.example.com"],
// Optional: Enable citations for fetched content
"citations": {
"enabled": true
},
// Optional: Maximum content length in tokens
"max_content_tokens": 100000
}較新的工具版本新增了兩個選用參數：use_cache 需要 web_fetch_20260309 或更新版本（請參閱快取繞過），而 response_inclusion 需要 web_fetch_20260318 或更新版本（請參閱回應包含）。
最大使用次數
max_uses 參數限制執行網頁擷取的次數。失敗的擷取也會計入限制。如果 Claude 嘗試的擷取次數超過允許值，web_fetch_tool_result 會是帶有 max_uses_exceeded 錯誤代碼的錯誤。目前沒有預設限制。
網域過濾
關於使用 allowed_domains 和 blocked_domains 進行網域過濾，請參閱伺服器工具。
在 Claude Managed Agents 上，請在代理工具集的 web_fetch 項目上設定這些欄位，其中列出的每個網域都必須是不含路徑的純主機名稱；請參閱限制網頁搜尋與網頁擷取網域。
內容限制
max_content_tokens 參數限制納入上下文的內容量。如果擷取的內容超過此限制，工具會將其截斷。這有助於在擷取大型文件時控制 token 用量。此限制適用於文字內容，不適用於 PDF 等二進位內容。
在 Claude Managed Agents 上，代理工具集的 web_fetch 項目也接受 max_content_tokens；請參閱限制網頁搜尋與網頁擷取網域。
快取繞過
use_cache 參數控制是否可回傳快取內容。設定 "use_cache": false 可繞過快取並擷取最新內容。預設值為 true。請僅在使用者明確要求最新內容或擷取快速變動的來源時停用快取，因為繞過快取會增加「latency」（延遲）。
{
"tools": [
{
"type": "web_fetch_20260309",
"name": "web_fetch",
"use_cache": false
}
]
}回應包含
response_inclusion 參數控制當擷取結果在同一輪中被已完成的程式碼執行呼叫所使用時，擷取結果區塊在 API 回應中的呈現方式。設定 "response_inclusion": "excluded" 可將這些巢狀的 server_tool_use 與結果區塊配對從回應中完全移除，為不需要將原始頁面內容回傳給用戶端的代理式工作流程降低輸出 token 成本。預設值為 "full"。來自直接呼叫的結果，或來自在完成前暫停的程式碼執行呼叫的結果，一律會完整回傳，以便在下一輪中送回。
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}引用
與一律啟用引用的網頁搜尋不同，網頁擷取的引用是選用的，且預設為停用。設定 "citations": {"enabled": true} 可讓 Claude 引用擷取文件中的特定段落。
回應
以下是回應結構範例：
{
"role": "assistant",
"content": [
// 1. Claude's decision to fetch
{
"type": "text",
"text": "I'll fetch the content from the article to analyze it."
},
// 2. The fetch request
{
"type": "server_tool_use",
"id": "srvtoolu_01234567890abcdef",
"name": "web_fetch",
"input": {
"url": "https://example.com/article"
}
},
// 3. Fetch results
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_01234567890abcdef",
"content": {
"type": "web_fetch_result",
"url": "https://example.com/article",
"content": {
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Full text content of the article..."
},
"title": "Article Title",
"citations": { "enabled": true }
},
"retrieved_at": "2025-08-25T10:30:00Z"
}
},
// 4. Claude's analysis with citations (if enabled)
{
"text": "Based on the article, ",
"type": "text"
},
{
"text": "the main argument presented is that artificial intelligence will transform healthcare",
"type": "text",
"citations": [
{
"type": "char_location",
"document_index": 0,
"document_title": "Article Title",
"start_char_index": 1234,
"end_char_index": 1456,
"cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
}
]
}
],
"id": "msg_a930390d3a",
"usage": {
"input_tokens": 25039,
"output_tokens": 931,
"server_tool_use": {
"web_fetch_requests": 1
}
},
"stop_reason": "end_turn"
}擷取結果
擷取結果包含：
url：所擷取的 URLcontent：包含擷取內容的文件區塊retrieved_at：擷取內容時的時間戳記
對於 PDF 文件，內容會以 base64 編碼資料的形式回傳：
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_02",
"content": {
"type": "web_fetch_result",
"url": "https://example.com/paper.pdf",
"content": {
"type": "document",
"source": {
"type": "base64",
"media_type": "application/pdf",
"data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
},
"citations": { "enabled": true }
},
"retrieved_at": "2025-08-25T10:30:02Z"
}
}錯誤
當網頁擷取工具遇到錯誤時，Claude API 會回傳 200（成功）回應，並在回應主體中表示該錯誤。Claude 會看到錯誤結果並繼續該輪對話。例如：
{
"type": "web_fetch_tool_result",
"tool_use_id": "srvtoolu_a93jad",
"content": {
"type": "web_fetch_tool_result_error",
"error_code": "url_not_accessible"
}
}以下是可能的錯誤代碼：
invalid_tool_input：無效的工具輸入，例如格式錯誤的 URL 或非 HTTP(S) 協定url_too_long：URL 超過最大長度（250 個字元）url_not_allowed：URL 被網域過濾規則（包括您組織的設定）或 Anthropic 端的限制（例如私有位址、robots.txt，以及看似包含您未提供之憑證的 URL）所封鎖url_not_in_prior_context：URL 未曾出現在對話的先前內容中（請參閱 URL 驗證）url_not_accessible：擷取內容失敗（HTTP 錯誤）too_many_requests：超過速率限制unsupported_content_type：不支援的內容類型（僅支援文字、HTML 和 PDF）max_uses_exceeded：超過網頁擷取工具的最大使用次數unavailable：發生內部錯誤
URL 驗證
基於安全考量，網頁擷取工具只能擷取先前曾出現在對話上下文中的 URL。這包括：
- 使用者訊息中的 URL
- 用戶端工具結果中的 URL
- 來自先前網頁搜尋或網頁擷取結果的 URL
此工具無法擷取僅出現在 Claude 自身輸出中，或僅出現在「system prompt」（系統提示）中的 URL。若要讓系統提示中的 URL 可被擷取，請同時將其包含在使用者訊息中。其他伺服器端工具的結果，例如程式碼執行、MCP 連接器或工具搜尋，也不是允許的來源。用戶端工具結果即使回顯了 Claude 所產生的文字（例如會印出其輸入的指令，或引用該文字的錯誤訊息），仍屬於允許的來源。
此工具也會拒絕看似包含憑證（例如 API 金鑰或密碼）的 URL，除非該憑證出現在系統提示中或使用者訊息的文字中。僅出現在工具結果中的憑證不算數。此時會回傳 url_not_allowed 錯誤。若要擷取此類 URL，請將其包含在使用者訊息中。
結合搜尋與擷取
當網頁搜尋與網頁擷取工具同時啟用，且使用者指名特定頁面或文件但未提供 URL 時（例如「讀取 anthropics/anthropic-sdk-python 儲存庫的 README」），Claude 會使用網頁搜尋找到它，然後擷取結果。以下範例在單一請求中要求進行搜尋與分析：
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
messages=[
{
"role": "user",
"content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
}
],
tools=[
{"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
{
"type": "web_fetch_20250910",
"name": "web_fetch",
"max_uses": 5,
"citations": {"enabled": True},
},
],
)
print(response)在此工作流程中，Claude 會：
- 使用網頁搜尋尋找相關文章。
- 選擇最有希望的結果。
- 使用網頁擷取取得完整內容。
- 提供附有引用的詳細分析。
提示快取
若要跨輪次快取工具定義，請參閱搭配提示快取的工具使用。
串流
啟用「streaming」（串流）時，擷取事件會成為串流的一部分，並在內容擷取期間暫停：
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 fetch
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}
// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}
// Pause while fetch executes
// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}
// Claude's response continues...批次請求
您可以在 Messages Batches API 中包含網頁擷取工具。透過 Messages Batches API 進行的網頁擷取工具呼叫，其定價與一般 Messages API 請求中的呼叫相同。
用量與定價
Web fetch（網頁擷取）的使用除標準 token 費用外沒有額外收費：
{
"usage": {
"input_tokens": 25039,
"output_tokens": 931,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"server_tool_use": {
"web_fetch_requests": 1
}
}
}Web fetch 工具可在 Claude API 上使用，無需額外費用。您只需為成為對話上下文一部分的擷取內容支付標準 token 費用。
為防止無意間擷取會消耗過多 token 的大型內容，請使用 max_content_tokens 參數，根據您的使用情境與預算考量設定適當的限制。
典型內容的 token 使用量範例：
- 一般網頁（10 kB）：約 2,500 個 token
- 大型文件頁面（100 kB）：約 25,000 個 token
- 研究論文 PDF（500 kB）：約 125,000 個 token
後續步驟
Was this page helpful?