# Web fetch tool

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

---

Web fetch tool 允许 Claude 从指定网页和 PDF 文档检索完整内容。

最新版本的 web fetch tool（`web_fetch_20260209`）支持 [Claude Mythos Preview](https://anthropic.com/glasswing)、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 的**动态过滤**。Claude 可以编写和执行代码，在获取的内容到达上下文窗口之前进行过滤，只保留相关信息并丢弃其余内容。这在保持响应质量的同时减少 token 消耗。之前的工具版本（`web_fetch_20250910`）仍然可用，但不支持动态过滤。

<Note>
对于 [Claude Mythos Preview](https://anthropic.com/glasswing)，web fetch 在 Claude API 和 Microsoft Foundry 上可用。目前在 Amazon Bedrock 或 Vertex AI 上对 Mythos Preview 不可用。
</Note>

<Note>
使用[反馈表](https://forms.gle/NhWcgmkcvPCMmPE86)提供关于模型响应质量、API 本身或文档质量的反馈。
</Note>

零数据留存资格和 `allowed_callers` 变通方案，请参见[服务器工具](/docs/en/agents-and-tools/tool-use/server-tools#zdr-and-allowed-callers)。

<Warning>
在 Claude 处理不受信任的输入与敏感数据的环境中启用 web fetch tool 会带来数据泄露风险。仅在可信环境或处理非敏感数据时使用此工具。

为了最小化泄露风险，Claude 不允许动态构造 URL。Claude 只能获取用户明确提供的 URL 或来自先前 web search 或 web fetch 结果的 URL。但是，使用此工具时仍存在应仔细考虑的残余风险。

如果担心数据泄露，请考虑：
- 完全禁用 web fetch tool
- 使用 `max_uses` 参数限制请求数量
- 使用 `allowed_domains` 参数限制到已知安全域名
</Warning>

模型支持参见[工具参考](/docs/en/agents-and-tools/tool-use/tool-reference)。

## Web fetch 的工作原理

当你将 web fetch tool 添加到 API 请求时：

1. Claude 根据提示和可用 URL 决定何时获取内容。
2. API 从指定 URL 检索完整文本内容。
3. 对于 PDF，自动执行文本提取。
4. Claude 分析获取的内容并提供带可选引用的响应。

<Note>
Web fetch tool 目前不支持使用 JavaScript 动态渲染的网站。
</Note>

### 动态过滤

获取完整网页和 PDF 会快速消耗 token，特别是当只需要从大型文档中获取特定信息时。使用 `web_fetch_20260209` 工具版本，Claude 可以编写和执行代码，在将获取的内容加载到上下文之前进行过滤。

此动态过滤特别适用于：
- 从长文档中提取特定部分
- 处理网页中的结构化数据
- 从 PDF 中过滤相关信息
- 处理大型文档时减少 token 成本

<Note>
动态过滤需要启用 [code execution tool](/docs/en/agents-and-tools/tool-use/code-execution-tool)。Web fetch tool（带和不带动态过滤）在 Claude API、[AWS 上的 Claude Platform](/docs/en/build-with-claude/claude-platform-on-aws) 和 [Microsoft Foundry](/docs/en/build-with-claude/claude-in-microsoft-foundry) 上可用。目前在 Amazon Bedrock 或 Vertex AI 上不可用。
</Note>

要启用动态过滤，请使用 `web_fetch_20260209` 工具版本：

<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-7",
        "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_20260209",
            "name": "web_fetch"
        }]
    }'
```

```bash CLI
ant messages create <<'YAML'
model: claude-opus-4-7
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_20260209
    name: web_fetch
YAML
```

```python Python hidelines={1..2}
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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_20260209", "name": "web_fetch"}],
)
print(response)
```

```typescript TypeScript hidelines={1..5,-3..-1}
import { Anthropic } from "@anthropic-ai/sdk";

const anthropic = new Anthropic();

async function main() {
  const response = await anthropic.messages.create({
    model: "claude-opus-4-7",
    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_20260209", name: "web_fetch" }]
  });

  console.log(response);
}

main().catch(console.error);
```

```csharp C# hidelines={1..3}
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 4096,
    Messages = [new() { Role = Role.User, Content = "Fetch the content at https://example.com/research-paper and extract the key findings." }],
    Tools = [new ToolUnion(new WebFetchTool20260209())]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 4096,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Fetch the content at https://example.com/research-paper and extract the key findings.")),
		},
		Tools: []anthropic.ToolUnionParam{
			{OfWebFetchTool20260209: &anthropic.WebFetchTool20260209Param{}},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

```java Java hidelines={1..5}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.WebFetchTool20260209;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(4096L)
        .addUserMessage("Fetch the content at https://example.com/research-paper and extract the key findings.")
        .addTool(WebFetchTool20260209.builder().build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}
```

```php PHP hidelines={1..4}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->messages->create(
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => 'Fetch the content at https://example.com/research-paper and extract the key findings.']
    ],
    model: 'claude-opus-4-7',
    tools: [[
        'type' => 'web_fetch_20260209',
        'name' => 'web_fetch',
    ]],
);
echo $message;
```

```ruby Ruby hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-4-7",
  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_20260209",
    name: "web_fetch"
  }]
)
puts message
```
</CodeGroup>

## 如何使用 web fetch

在 API 请求中提供 web fetch tool：

<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-7",
        "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
        }]
    }'
```

```bash CLI
ant messages create \
  --model claude-opus-4-7 \
  --max-tokens 1024 \
  --message '{role: user, content: "Please analyze the content at https://example.com/article"}' \
  --tool '{type: web_fetch_20250910, name: web_fetch, max_uses: 5}'
```

```python Python hidelines={1..2}
import anthropic

client = anthropic.Anthropic()

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

```typescript TypeScript hidelines={1..5,-3..-1}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const response = await client.messages.create({
    model: "claude-opus-4-7",
    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
      }
    ]
  });

  console.log(response);
}

main().catch(console.error);
```

```csharp C# hidelines={1..3}
using Anthropic;
using Anthropic.Models.Messages;

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus4_7,
    MaxTokens = 1024,
    Messages = [new() { Role = Role.User, Content = "Please analyze the content at https://example.com/article" }],
    Tools = [new ToolUnion(new WebFetchTool20250910() { MaxUses = 5 })]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```

```go Go hidelines={1..11,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Please analyze the content at https://example.com/article")),
		},
		Tools: []anthropic.ToolUnionParam{
			{OfWebFetchTool20250910: &anthropic.WebFetchTool20250910Param{
				MaxUses: anthropic.Int(5),
			}},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
```

```java Java hidelines={1..5}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.WebFetchTool20250910;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_7)
        .maxTokens(1024L)
        .addUserMessage("Please analyze the content at https://example.com/article")
        .addTool(WebFetchTool20250910.builder()
            .maxUses(5L)
            .build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}
```

```php PHP hidelines={1..4}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => 'Please analyze the content at https://example.com/article']
    ],
    model: 'claude-opus-4-7',
    tools: [[
        'type' => 'web_fetch_20250910',
        'name' => 'web_fetch',
        'max_uses' => 5,
    ]],
);
echo $message;
```

```ruby Ruby hidelines={1..2}
require "anthropic"

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-4-7",
  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
  }]
)
puts message
```
</CodeGroup>

### 工具定义

Web fetch tool 支持以下参数：

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

  // 可选：限制每个请求的获取次数
  "max_uses": 10,

  // 可选：仅从这些域名获取
  "allowed_domains": ["example.com", "docs.example.com"],

  // 可选：永不从这些域名获取
  "blocked_domains": ["private.example.com"],

  // 可选：为获取的内容启用引用
  "citations": {
    "enabled": true
  },

  // 可选：最大内容长度（以 token 为单位）
  "max_content_tokens": 100000
}
```

#### 最大使用次数

`max_uses` 参数限制执行的 web fetch 次数。如果 Claude 尝试超过允许的获取次数，`web_fetch_tool_result` 是一个错误，错误码为 `max_uses_exceeded`。目前没有默认限制。

#### 域名过滤

有关使用 `allowed_domains` 和 `blocked_domains` 进行域名过滤，请参见[服务器工具](/docs/en/agents-and-tools/tool-use/server-tools#domain-filtering)。

#### 内容限制

`max_content_tokens` 参数限制上下文中包含的内容量。如果获取的内容超出此限制，工具会截断它。这有助于在获取大型文档时控制 token 使用量。

<Note>
`max_content_tokens` 参数限制是近似的。实际使用的输入 token 数量可能略有不同。
</Note>

#### 引用

与 web search 始终启用引用不同，web fetch 的引用是可选的。设置 `"citations": {"enabled": true}` 以让 Claude 引用获取文档中的特定段落。

<Note>
直接向最终用户显示 API 输出时，必须包含对原始来源的引用。如果你在显示给最终用户之前对 API 输出进行修改，包括重新处理和/或与你自己的材料结合，请根据与法律团队的咨询适当显示引用。
</Note>

### 响应

以下是示例响应结构：

```json Output
{
  "role": "assistant",
  "content": [
    // 1. Claude 决定获取
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. 获取请求
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. 获取结果
    {
      "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 带引用的分析（如果启用）
    {
      "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`：内容检索的时间戳

<Note>
Web fetch tool 缓存结果以提高性能并减少冗余请求。返回的内容可能不总是反映 URL 处的最新版本。缓存行为是自动管理的，可能会随时间变化以优化不同的内容类型和使用模式。
</Note>

对于 PDF 文档，内容以 base64 编码数据返回：

```json 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"
  }
}
```

#### 错误

当 web fetch tool 遇到错误时，Claude API 返回 200（成功）响应，错误在响应体中表示：

```json Output
{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_error",
    "error_code": "url_not_accessible"
  }
}
```

可能的错误码：

- `invalid_input`：无效的 URL 格式
- `url_too_long`：URL 超出最大长度（250 个字符）
- `url_not_allowed`：URL 被域名过滤规则和模型限制阻止
- `url_not_accessible`：获取内容失败（HTTP 错误）
- `too_many_requests`：超出速率限制
- `unsupported_content_type`：不支持的内容类型（仅文本和 PDF）
- `max_uses_exceeded`：超出最大 web fetch tool 使用次数
- `unavailable`：发生内部错误

## URL 验证

出于安全原因，web fetch tool 只能获取先前出现在对话上下文中的 URL。这包括：

- 用户消息中的 URL
- 客户端工具结果中的 URL
- 来自先前 web search 或 web fetch 结果的 URL

该工具无法获取 Claude 生成的任意 URL 或来自基于容器的服务器工具（Code Execution、Bash 等）的 URL。

## 组合搜索和获取

Web fetch 与 web search 无缝配合，实现全面的信息收集：

```python Python hidelines={1..2}
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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. 使用 web search 查找相关文章
2. 选择最有前途的结果
3. 使用 web fetch 检索完整内容
4. 提供带引用的详细分析

## Prompt caching

有关跨轮次缓存工具定义，请参见[工具使用与 prompt caching](/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching)。

## 流式传输

启用流式传输后，获取事件作为流的一部分，在内容检索期间有暂停：

```sse 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 决定获取

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// 获取 URL 流式传输
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// 获取执行期间暂停

// 获取结果流式传输
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 继续响应...
```

## 批量请求

你可以在 [Messages Batches API](/docs/en/build-with-claude/batch-processing) 中包含 web fetch tool。通过 Messages Batches API 的 web fetch tool 调用与常规 Messages API 请求中的定价相同。

## 使用量和定价

Web fetch 使用量**没有额外费用**，仅标准 token 成本：

```json
{
  "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 tool 在 Claude API 上**无额外费用**。你只需为成为对话上下文一部分的获取内容支付标准 token 成本。

为了防止无意中获取会消耗过多 token 的大型内容，请使用 `max_content_tokens` 参数根据你的用例和预算考虑设置适当的限制。

典型内容的示例 token 使用量：
- 平均网页（10 kB）：约 2,500 个 token
- 大型文档页面（100 kB）：约 25,000 个 token
- 研究论文 PDF（500 kB）：约 125,000 个 token

## 下一步

<CardGroup>
  <Card href="/docs/en/agents-and-tools/tool-use/server-tools" title="服务器工具">
    Anthropic 执行工具的共享机制。
  </Card>
  <Card href="/docs/en/agents-and-tools/tool-use/tool-reference" title="工具参考">
    所有 Anthropic 提供的工具目录。
  </Card>
</CardGroup>