Claude Platform Docs
Messages工具

網頁擷取工具

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

用法因產品而異

Messages API
在請求的 tools 中加入 web_fetch 工具。
Managed Agents
在代理工具集中預設開啟，不提供 max_uses、citations 或 cache_control。

網頁擷取工具讓 Claude 能夠從指定的網頁和 PDF 文件中取得完整內容。

最新的網頁擷取工具版本（web_fetch_20260318）支援動態篩選：Claude 可以撰寫並執行程式碼，在擷取的內容進入「context window」（上下文視窗）之前對其進行篩選，僅保留相關資訊並捨棄其餘部分。這能在維持回應品質的同時降低 token 消耗。動態篩選適用於 Claude 4.6 及更新的模型以及 Claude Mythos Preview。web_fetch_20260318 也為代理式工作流程新增了回應包含控制。其他版本（用於動態篩選和快取略過的 web_fetch_20260309、僅用於動態篩選的 web_fetch_20260209、用於基本擷取的 web_fetch_20250910）可供使用。

網頁擷取（無論是否使用動態篩選）可在 Claude API、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 和 Microsoft Foundry 上使用。在 Microsoft Foundry 上，託管於 Azure 的部署僅支援基本網頁擷取工具（web_fetch_20250910，不含動態篩選）。託管於 Anthropic 的部署則支援所有版本。

關於「Zero Data Retention」（零資料保留）資格以及 allowed_callers 的因應做法，請參閱伺服器工具。

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

網頁擷取的運作方式

網頁擷取是一種伺服器工具：API 會在請求期間擷取內容，並將結果插入對話中。您不需要執行任何動作，也不需要回傳 tool_result。例外情況是當 Claude 在同一組平行工具呼叫中同時呼叫網頁擷取和您的某個用戶端工具時：API 會在該擷取執行之前回傳帶有 stop_reason: "tool_use" 的回應，然後在您送回用戶端 tool_result 區塊時執行擷取。請參閱在同一輪中混合使用伺服器工具與用戶端工具。

當您將網頁擷取工具加入 API 請求時：

  1. Claude 根據提示和可用的 URL 決定何時擷取內容。
  2. API 從指定的 URL 取得完整的文字內容。
  3. 對於 PDF，API 會以 base64 編碼資料回傳內容，並以與直接附加的 PDF 文件相同的方式處理。
  4. 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-5-5",
    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)

如何使用網頁擷取

關於您組織的網頁擷取設定如何套用於 Claude Managed Agents 工作階段，請參閱限制網頁搜尋和網頁擷取網域。

在您的 API 請求中提供網頁擷取工具：

client = anthropic.Anthropic()

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

工具定義

網頁擷取工具支援以下參數：

JSON
{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optional: Limit the number of fetches
  "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: Don't fetch URLs that appear only in client-side tool results
  "url_sources": {
    "client_tool_results": { "type": "none" }
  },

  // 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 錯誤代碼的錯誤。如果 Claude 從程式碼執行中呼叫網頁擷取的次數超過允許的數量，該次程式碼執行會以錯誤結束。沒有預設限制。

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

網域篩選

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

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

內容限制

max_content_tokens 參數限制包含在上下文中的內容量。如果擷取的內容超過此限制，工具會將其截斷。這有助於在擷取大型文件時控制 token 用量。此限制為近似值：實際使用的輸入 token 數量可能會有少量差異。此限制適用於文字內容，不適用於 PDF 等二進位內容。

如果擷取的 PDF 會使請求超過 PDF 頁數或大小限制，web_fetch_tool_result 會是帶有 content_too_large 錯誤代碼的錯誤。對話中已有的 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 用量不受影響，因為 Claude 讀取的是程式碼的輸出，而非這些區塊。預設值為 "full"。API 一律會完整回傳來自直接呼叫的結果，或來自在完成前暫停的程式碼執行呼叫的結果，以便您在下一個請求中將其送回。

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}

引用

與一律啟用引用的網頁搜尋不同，網頁擷取的引用為選用功能，且預設為停用。設定 "citations": {"enabled": true} 可讓 Claude 引用擷取文件中的特定段落。

回應

以下是回應結構的範例：

Output
{
  "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：被擷取的 URL
  • content：包含擷取內容的文件區塊
  • retrieved_at：取得內容時的時間戳記

對於 PDF 文件，內容會以 base64 編碼資料回傳：

Output
{
  "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 會收到錯誤結果並繼續該輪。例如：

Output
{
  "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) 的 scheme
  • url_too_long：URL 超過最大長度（250 個字元）
  • url_not_allowed：URL 被網域篩選規則（包括您組織的設定）或 Anthropic 端的限制所封鎖，例如私有位址、robots.txt，以及看似包含您未提供之憑證的 URL
  • url_not_in_prior_context：URL 未曾在對話中出現過，或僅出現在 url_sources 排除的來源中（請參閱 URL 驗證）
  • url_not_accessible：無法擷取內容（HTTP 錯誤）
  • too_many_requests：超過速率限制
  • unsupported_content_type：不支援的內容類型（僅支援文字、HTML 和 PDF）
  • content_too_large：擷取的 PDF 會使請求超過 PDF 頁數或大小限制（請參閱內容限制）
  • max_uses_exceeded：超過網頁擷取工具的最大使用次數
  • unavailable：發生內部錯誤

URL 驗證

基於安全考量，網頁擷取工具只能擷取先前已出現在對話上下文中的 URL。這包括：

  • 使用者訊息中的 URL
  • 用戶端工具結果中的 URL
  • 來自先前網頁搜尋或網頁擷取結果的 URL

此工具無法擷取僅出現在 Claude 自身輸出中或僅出現在系統提示中的 URL。若要讓系統提示中的 URL 可被擷取，請同時將其包含在使用者訊息中。其他伺服器端工具的結果，例如程式碼執行、MCP 連接器或工具搜尋，也不是允許的來源。預設情況下，即使用戶端工具結果回顯了 Claude 產生的文字（例如會印出其輸入的指令，或引用該文字的錯誤訊息），它們仍是允許的來源。

此工具也會拒絕看似包含憑證（例如 API 金鑰或密碼）的 URL，除非該憑證出現在系統提示中或使用者訊息的文字中。僅出現在工具結果中的憑證不予計入。結果會是 url_not_allowed 錯誤。若要擷取此類 URL，請將其包含在使用者訊息中。

URL 來源

選用的 url_sources 參數可讓您關閉三種允許來源中的任一種，或將工具結果限制為特定工具。每個來源各有一個鍵，且每個鍵的預設值皆為 {"type": "all"}：

  • user_input：使用者訊息中的 URL。其 type 為 "all" 或 "none"。
  • client_tool_results：用戶端工具結果中的 URL。其 type 為 "all"、"none"，或是指名工具的 "only" 或 "except" 篩選器，如以下範例所示。
  • server_tool_results：來自先前網頁搜尋或網頁擷取結果的 URL。它接受相同的值，其篩選器指名 web_search 或 web_fetch。

例如，執行 Claude 所撰寫程式碼的工具會回傳該程式碼印出的任何內容，包括 Claude 放入其中的任何 URL。若要讓該工具的結果不再被視為來源，請在 "except" 篩選器中指名該工具：

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "url_sources": {
        "client_tool_results": {
          "type": "except",
          "tools": [{ "type": "tool_reference", "name": "run_code" }]
        }
      }
    },
    {
      "name": "run_code",
      "description": "Run Python code and return its output",
      "input_schema": {
        "type": "object",
        "properties": { "code": { "type": "string" } },
        "required": ["code"]
      }
    }
  ]
}

篩選器以 tool_reference 物件列出工具。每個名稱都必須符合請求 tools 陣列中的某個工具：對於 client_tool_results 為用戶端工具，對於 server_tool_results 則為伺服器工具。否則，請求會失敗並回傳錯誤。在 "except" 下，您之後加入 tools 的工具會被視為來源。在 "only" 下則不會。

run_code 以外的用戶端工具也可能回傳 Claude 撰寫的文字，例如在引用該文字的錯誤訊息中。若要排除所有用戶端工具結果，請將 client_tool_results 設定為 {"type": "none"}。

如果某個 URL 僅出現在 url_sources 排除的來源中，擷取它會回傳 url_not_in_prior_context 錯誤。

結合搜尋與擷取

當同時啟用網頁搜尋和網頁擷取工具，且使用者指名特定頁面或文件但未提供 URL 時（例如「閱讀 anthropics/anthropic-sdk-python 儲存庫中的 README」），Claude 會使用網頁搜尋找到它，然後擷取結果。以下範例在一個請求中要求進行搜尋和分析：

client = anthropic.Anthropic()

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

  1. 使用網頁搜尋找到相關文章。
  2. 選擇最有希望的結果。
  3. 使用網頁擷取取得完整內容。
  4. 提供附有引用的詳細分析。

提示快取

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

串流

啟用「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 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 runs

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

批次請求

您可以在 Message Batches API 中包含網頁擷取工具。透過 Message 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
    }
  }
}

網頁擷取工具可在 Claude API 上使用，無需額外費用。您只需為成為對話上下文一部分的擷取內容支付標準 token 費用。

為防止無意間擷取會消耗過多 token 的大型內容，請使用 max_content_tokens 參數，根據您的使用情境與預算考量設定適當的限制。

典型內容的 token 使用量範例：

  • 一般網頁（10 kB）：約 2,500 個 token
  • 大型文件頁面（100 kB）：約 25,000 個 token
  • 研究論文 PDF（500 kB）：約 125,000 個 token

後續步驟

程式碼執行工具

在沙箱容器中執行 Python 和 Bash 程式碼，以分析資料、產生檔案並反覆改進解決方案。

伺服器工具

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

工具參考

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

可用性

網頁擷取工具
API
  • Messages API
  • Managed Agents
模型
  • 所有模型

資料處理

資料處理概覽

適用端點

  • /v1/messages 搭配 web_fetch 工具
零資料保留符合資格

不含 涵蓋的模型

擷取的網頁內容會在 API 回應中傳回。網頁擷取的動態篩選不符合 ZDR 或 HIPAA 的適用資格。網站發布者可能會依其自身政策保留請求資料（例如擷取的 URL 與請求中繼資料）。

HIPAA不符合資格

這個頁面有幫助嗎？