Claude Platform Docs
Messages工具

Web fetch 工具

从特定 URL 获取并读取内容，以实时网页内容增强 Claude 的上下文。

用法因产品而异

Messages API
在请求的 tools 中添加 web_fetch 工具。
Managed Agents
在智能体工具集中默认开启，不支持 max_uses、citations 或 cache_control。

网页获取工具允许 Claude 从指定的网页和 PDF 文档中检索完整内容。

最新的网页获取工具版本（web_fetch_20260318）支持 dynamic filtering（动态过滤）：Claude 可以编写并执行代码，在获取的内容进入 “context window”（上下文窗口）之前对其进行过滤，仅保留相关信息并丢弃其余部分。这在保持响应质量的同时减少了令牌消耗。动态过滤适用于 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 上的部署支持所有版本。

有关零数据保留资格和 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
  • 用户在没有 URL 的情况下指明了特定资源（某篇特定文章、README、定价页面或文档章节），并且同时启用了网页搜索工具，使 Claude 能够先定位该资源（请参阅组合搜索和获取）

对于不引用特定页面的常识性或开放式问题，Claude 不会执行获取。"总结这篇文章：<url>"会触发获取。"REST API 设计的最佳实践是什么？"则会被直接回答。

动态过滤

获取完整的网页和 PDF 会迅速消耗令牌，尤其是当只需要从大型文档中获取特定信息时。使用 web_fetch_20260209 或更高版本时，Claude 可以编写并运行代码，在将获取的内容加载到上下文之前对其进行过滤。

这种动态过滤特别适用于：

  • 从长文档中提取特定章节
  • 处理来自网页的结构化数据
  • 从 PDF 中过滤相关信息
  • 在处理大型文档时降低令牌成本

要启用动态过滤，请使用 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 参数限制包含在上下文中的内容量。如果获取的内容超过此限制，工具会将其截断。这有助于在获取大型文档时控制令牌使用量。该限制是近似值：实际使用的输入令牌数可能会略有不同。该限制适用于文本内容，不适用于 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 和结果块对从响应中完全移除，适用于不需要原始页面内容的智能体工作流。令牌用量不受影响，因为 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) 协议
  • 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（网页抓取）的使用除标准令牌费用外不收取任何额外费用：

{
  "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 上无需额外费用即可使用。您只需为成为对话上下文一部分的抓取内容支付标准令牌费用。

为防止无意中抓取会消耗过多令牌的大型内容，请使用 max_content_tokens 参数，根据您的使用场景和预算考虑设置适当的限制。

典型内容的令牌使用量示例：

  • 普通网页（10 kB）：约 2,500 个令牌
  • 大型文档页面（100 kB）：约 25,000 个令牌
  • 研究论文 PDF（500 kB）：约 125,000 个令牌

后续步骤

代码执行工具

在沙盒容器中运行 Python 和 Bash 代码，以分析数据、生成文件并迭代解决方案。

服务器工具

使用由 Anthropic 运行的工具：server_tool_use 块、pause_turn 续接以及域名过滤。

工具参考

Anthropic 提供的工具目录以及可选工具定义属性的参考。

可用性

Web fetch 工具
API
  • Messages API
  • Managed Agents
模型
  • 所有模型

数据处理

数据处理概览

适用的端点

  • /v1/messages 使用 web_fetch 工具
零数据保留具备资格

不包括 涵盖的模型

获取的网页内容在 API 响应中返回。Web fetch 的动态过滤不具备 ZDR 或 HIPAA 资格。网站发布者可能会根据其自身政策保留请求数据（例如获取的 URL 和请求元数据）。

HIPAA不具备资格

此页面对您有帮助吗？