网络搜索工具

网络搜索工具让 Claude 能够直接访问实时网络内容，使其能够用超出知识截止日期的最新信息来回答问题。响应中包含从搜索结果中引用的来源。

最新版本的网络搜索工具（web_search_20260209）支持动态过滤，适用于 Claude Mythos Preview、Claude Opus 4.6 和 Claude Sonnet 4.6。Claude 可以编写并执行代码，在搜索结果进入上下文窗口之前对其进行过滤，只保留相关信息并丢弃其余内容。这可以提高响应准确性，同时减少 token 消耗。之前的工具版本（web_search_20250305）仍然可用，但不支持动态过滤。

对于 Claude Mythos Preview，网络搜索在 Claude API、Microsoft Foundry 和 Google Vertex AI 上受支持。Amazon Bedrock 上的 Mythos Preview 不支持网络搜索。

有关零数据保留资格和 allowed_callers 解决方案，请参阅服务器工具。

有关模型支持，请参阅工具参考。

网络搜索的工作原理

当您在 API 请求中添加网络搜索工具时：

Claude 根据提示决定何时进行搜索。
API 执行搜索并将结果提供给 Claude。此过程在单个请求中可能重复多次。
在其轮次结束时，Claude 提供带有引用来源的最终响应。

动态过滤

网络搜索是一项 token 密集型任务。使用基本网络搜索时，Claude 需要将搜索结果拉入上下文，从多个网站获取完整的 HTML，并在得出答案之前对所有内容进行推理。通常，这些内容中有很多是无关的，这可能会降低响应质量。

使用 web_search_20260209 工具版本，Claude 可以编写并执行代码来对查询结果进行后处理。Claude 不再对完整的 HTML 文件进行推理，而是在将搜索结果加载到上下文之前动态过滤它们，只保留相关内容并丢弃其余内容。

动态过滤在以下场景中特别有效：

搜索技术文档
文献综述和引用验证
技术研究
响应基础验证

动态过滤需要启用代码执行工具。改进后的网络搜索工具在 Claude API 和 Microsoft Azure 上可用。在 Google Vertex AI 上，可以使用基本网络搜索工具（不含动态过滤）。

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

如何使用网络搜索

您的组织管理员必须在 Claude Console 中启用网络搜索。

在您的 API 请求中提供网络搜索工具：

工具定义

网络搜索工具支持以下参数：

JSON

{
  "type": "web_search_20250305",
  "name": "web_search",

  // 可选：限制每次请求的搜索次数
  "max_uses": 5,

  // 可选：仅包含来自这些域名的结果
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // 可选：永不包含来自这些域名的结果
  "blocked_domains": ["untrustedsource.com"],

  // 可选：本地化搜索结果
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

最大使用次数

max_uses 参数限制执行的搜索次数。如果 Claude 尝试的搜索次数超过允许的次数，web_search_tool_result 将返回带有 max_uses_exceeded 错误代码的错误。

域名过滤

有关使用 allowed_domains 和 blocked_domains 进行域名过滤的信息，请参阅服务器工具。

本地化

user_location 参数允许您根据用户的位置本地化搜索结果。

type：位置类型（必须为 approximate）
city：城市名称
region：地区或州
country：国家
timezone：IANA 时区 ID。

响应

以下是响应结构示例：

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude 决定搜索
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. 使用的搜索查询
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. 搜索结果
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "content": [
        {
          "type": "web_search_result",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_content": "EqgfCioIARgBIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
          "page_age": "April 30, 2025"
        }
      ]
    },
    {
      "text": "Based on the search results, ",
      "type": "text"
    },
    // 4. Claude 带引用的响应
    {
      "text": "Claude Shannon was born on April 30, 1916, in Petoskey, Michigan",
      "type": "text",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://en.wikipedia.org/wiki/Claude_Shannon",
          "title": "Claude Shannon - Wikipedia",
          "encrypted_index": "Eo8BCioIAhgBIiQyYjQ0OWJmZi1lNm..",
          "cited_text": "Claude Elwood Shannon (April 30, 1916 – February 24, 2001) was an American mathematician, electrical engineer, computer scientist, cryptographer and i..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 6039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_search_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

搜索结果

搜索结果包括：

url：来源页面的 URL
title：来源页面的标题
page_age：网站最后更新时间
encrypted_content：加密内容，必须在多轮对话中传回以供引用

引用

网络搜索始终启用引用，每个 web_search_result_location 包括：

url：引用来源的 URL
title：引用来源的标题
encrypted_index：必须在多轮对话中传回的引用。
cited_text：最多 150 个字符的引用内容

网络搜索引用字段 cited_text、title 和 url 不计入输入或输出 token 用量。

当直接向最终用户展示 API 输出时，必须包含原始来源的引用。如果您在向最终用户展示之前对 API 输出进行修改，包括重新处理和/或将其与您自己的材料合并，请根据与您的法律团队协商后适当展示引用。

错误

当网络搜索工具遇到错误（例如达到速率限制）时，Claude API 仍然返回 200（成功）响应。错误在响应体中使用以下结构表示：

Output

{
  "type": "web_search_tool_result",
  "tool_use_id": "servertoolu_a93jad",
  "content": {
    "type": "web_search_tool_result_error",
    "error_code": "max_uses_exceeded"
  }
}

以下是可能的错误代码：

too_many_requests：超出速率限制
invalid_input：无效的搜索查询参数
max_uses_exceeded：超出最大网络搜索工具使用次数
query_too_long：查询超出最大长度
unavailable：发生内部错误

`pause_turn` 停止原因

有关在 pause_turn 停止原因后继续的信息，请参阅服务器工具。

提示缓存

有关跨轮次缓存工具定义的信息，请参阅带提示缓存的工具使用。

流式传输

启用流式传输后，您将在流中接收搜索事件。搜索执行期间会有暂停：

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_search"}}

// 搜索查询流式传输
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// 搜索执行期间暂停

// 搜索结果流式传输
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "web_search_result", "title": "Quantum Computing Breakthroughs in 2025", "url": "https://example.com"}]}}

// Claude 带引用的响应（本示例中省略）

批量请求

您可以在消息批处理 API 中包含网络搜索工具。通过消息批处理 API 进行的网络搜索工具调用与常规消息 API 请求中的定价相同。

使用量和定价

Web search usage is charged in addition to token usage:

"usage": {
  "input_tokens": 105,
  "output_tokens": 6039,
  "cache_read_input_tokens": 7123,
  "cache_creation_input_tokens": 7345,
  "server_tool_use": {
    "web_search_requests": 1
  }
}

Web search is available on the Claude API for $10 per 1,000 searches, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.

Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.

后续步骤

服务器工具

Anthropic 执行工具的共享机制。

工具参考

所有 Anthropic 提供的工具目录。

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-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio."
            }
        ],
        "tools": [{
            "type": "web_search_20260209",
            "name": "web_search"
        }]
    }'

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-6",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "What is the weather in NYC?"
            }
        ],
        "tools": [{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }]
    }'

网络搜索的工作原理

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

使用量和定价

后续步骤

`pause_turn` 停止原因