Web fetch 工具
从特定 URL 获取并读取内容，以实时网页内容增强 Claude 的上下文。
Web fetch 工具允许 Claude 从指定的网页和 PDF 文档中检索完整内容。
最新的 web fetch 工具版本（web_fetch_20260318）支持 dynamic filtering（动态过滤）：Claude 可以编写并执行代码，在获取的内容进入 "context window"（上下文窗口）之前对其进行过滤，仅保留相关信息并丢弃其余部分。这在保持响应质量的同时减少了令牌消耗。动态过滤适用于 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 还为智能体工作流添加了 response inclusion（响应包含）控制。之前的版本（支持动态过滤和缓存绕过的 web_fetch_20260309、仅支持动态过滤的 web_fetch_20260209、支持基本获取的 web_fetch_20250910）仍然可用。
Web fetch（无论是否带有动态过滤）可在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上使用。在 Microsoft Foundry 上，托管在 Azure 上的部署仅支持基本的 web fetch 工具（web_fetch_20250910，不带动态过滤）。托管在 Anthropic 上的部署支持所有版本。Web fetch 目前在 Amazon Bedrock 或 Google Cloud 上不可用。
有关零数据保留（Zero Data Retention）资格和 allowed_callers 变通方法，请参阅服务器工具。
有关模型支持，请参阅工具参考。
Web fetch 的工作原理
Web fetch 是一种服务器工具：API 在请求期间获取内容并将结果插入对话中。您无需运行任何内容或返回 tool_result。例外情况是当 Claude 在同一组并行工具调用中同时调用 web fetch 和您的某个客户端工具时：API 会在该获取运行之前返回带有 stop_reason: "tool_use" 的响应，然后在您发回客户端 tool_result 块时运行该获取。请参阅在一个回合中混合使用服务器工具和客户端工具。
当您将 web fetch 工具添加到 API 请求中时：
- Claude 根据提示和可用的 URL 决定何时获取内容。
- API 从指定的 URL 检索完整的文本内容。
- 对于 PDF，API 以 base64 编码数据的形式返回内容，并像直接附加的 PDF 文档一样处理它。
- Claude 分析获取的内容并提供带有可选引用的响应。
Claude 何时获取
当请求指向特定页面或文档时，Claude 会进行获取：
- 对话中（或之前的工具结果中）提供了 URL
- 用户在没有 URL 的情况下指明了特定资源（某篇特定文章、README、定价页面或文档章节），并且同时启用了 web search 工具，以便 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-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)如何使用 web fetch
在您的 API 请求中提供 web fetch 工具：
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)工具定义
Web fetch 工具支持以下参数：
{
"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 参数限制执行的 web fetch 次数。失败的获取也计入限制。如果 Claude 尝试的获取次数超过允许的次数，web_fetch_tool_result 将是一个带有 max_uses_exceeded 错误代码的错误。目前没有默认限制。
域名过滤
有关使用 allowed_domains 和 blocked_domains 进行域名过滤，请参阅服务器工具。
在 Claude Managed Agents 上，请在智能体工具集的 web_fetch 条目上设置这些字段，其中列出的每个域名必须是不带路径的纯主机名；请参阅限制 web search 和 web fetch 域名。
内容限制
max_content_tokens 参数限制包含在上下文中的内容量。如果获取的内容超过此限制，工具会将其截断。这有助于在获取大型文档时控制令牌使用量。该限制适用于文本内容，不适用于 PDF 等二进制内容。
在 Claude Managed Agents 上，智能体工具集的 web_fetch 条目也接受 max_content_tokens；请参阅限制 web search 和 web fetch 域名。
缓存绕过
use_cache 参数控制是否可以返回缓存的内容。设置 "use_cache": false 可绕过缓存并获取最新内容。默认值为 true。仅在用户明确请求最新内容或获取快速变化的来源时才禁用缓存，因为绕过缓存会增加延迟。
{
"tools": [
{
"type": "web_fetch_20260309",
"name": "web_fetch",
"use_cache": false
}
]
}响应包含
response_inclusion 参数控制当获取结果在同一回合中被已完成的代码执行调用消费时，获取结果块在 API 响应中的呈现方式。设置 "response_inclusion": "excluded" 可将这些嵌套的 server_tool_use 和结果块对从响应中完全删除，从而为不需要将原始页面内容回传给客户端的智能体工作流降低输出令牌成本。默认值为 "full"。来自直接调用的结果，或来自在完成之前暂停的代码执行调用的结果，始终会完整返回，以便在下一回合中发回。
{
"tools": [
{
"type": "web_fetch_20260318",
"name": "web_fetch",
"response_inclusion": "excluded"
}
]
}引用
与始终启用引用的 web search 不同，web fetch 的引用是可选的，默认禁用。设置 "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"
}
}错误
当 web fetch 工具遇到错误时，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：超出 web fetch 工具的最大使用次数unavailable：发生内部错误
URL 验证
出于安全原因，web fetch 工具只能获取之前在对话上下文中出现过的 URL。这包括：
- 用户消息中的 URL
- 客户端工具结果中的 URL
- 来自之前 web search 或 web fetch 结果的 URL
该工具无法获取仅出现在 Claude 自身输出中或仅出现在系统提示中的 URL。要使系统提示中的 URL 可被获取，请同时将其包含在用户消息中。其他服务器端工具的结果，例如代码执行、MCP 连接器或工具搜索，也不是允许的来源。客户端工具结果即使回显了 Claude 生成的文本（例如，打印其输入的命令，或引用该文本的错误消息），也仍是允许的来源。
该工具还会拒绝看起来包含凭据（例如 API 密钥或密码）的 URL，除非该凭据出现在系统提示中或用户消息的文本中。仅出现在工具结果中的凭据不算在内。此时会返回 url_not_allowed 错误。要获取此类 URL，请将其包含在用户消息中。
组合搜索和获取
当同时启用 web search 和 web fetch 工具，并且用户在未提供 URL 的情况下指明了特定页面或文档时（例如，"阅读 anthropics/anthropic-sdk-python 仓库中的 README"），Claude 会使用 web search 定位它，然后获取结果。以下示例在一个请求中要求进行搜索和分析：
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：
- 使用 web search 查找相关文章。
- 选择最有希望的结果。
- 使用 web fetch 检索完整内容。
- 提供带有引用的详细分析。
提示缓存
要跨回合缓存工具定义，请参阅工具使用与提示缓存。
流式传输
启用 "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 中包含 web fetch 工具。通过 Messages Batches API 进行的 web fetch 工具调用与常规 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 个令牌
后续步骤
Was this page helpful?