网页搜索工具

让 Claude 访问最新的网络内容，并提供引用来源、可选的动态过滤和域名控制。

用法因产品而异

Messages API

在请求的 tools 中添加 web_search 工具。max_uses、域名列表和 user_location 等设置放在该工具上。

Managed Agents

在智能体工具集中默认开启，不支持 max_uses、citations 或 cache_control。

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

使用 web_search_20260209 及更高版本时，Claude 可以编写并运行代码，在搜索结果到达 “context window”（上下文窗口）之前对其进行过滤（dynamic filtering，动态过滤），只保留相关信息。动态过滤适用于 Claude 4.6 及更高版本的模型以及 Claude Mythos Preview。

网络搜索工具有三个可用版本：

web_search_20250305：基础网络搜索
web_search_20260209：增加了动态过滤
web_search_20260318：增加了面向智能体工作流的响应包含控制

本页示例使用 web_search_20250305 进行基础搜索，使用 web_search_20260318 进行动态过滤。

有关网络搜索的零数据保留（Zero Data Retention）资格以及相关的 allowed_callers 配置，请参阅服务器工具。

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

要在发送请求之前检查某个模型是否接受网络搜索，请从 Models API 读取其 capabilities.server_tools.web_search.supported 值。使用 Models API 介绍了该字段。

网络搜索的工作原理

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

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

Claude 何时搜索

当请求依赖于最新的、不断变化的或超出其训练数据的信息时，Claude 会进行搜索：

近期事件、新闻或公告
当前价格、汇率、比分或统计数据
可能已发生变化的特定组织、人物或产品的信息
明确要求搜索或查找某些内容的请求

当请求依赖于稳定的知识时，Claude 会直接回答而不进行搜索：

既定事实、数学、科学基础知识或编程概念
创意写作或头脑风暴
对对话中已提供内容的分析
对话轮次和问候

可以通过您的系统提示来引导触发行为：您可以鼓励 Claude 更积极地搜索，或者倾向于直接回答。如需强制限制，请使用 max_uses 限制一个轮次中的搜索次数。

动态过滤

使用基础网络搜索时，每个搜索结果都会被加载到 Claude 的上下文窗口中，而其中许多内容可能与请求无关。使用 web_search_20260209 或更高版本时，Claude 会先编写并运行代码来过滤结果，因此只有相关内容才会进入上下文窗口。这可以减少搜索密集型请求的令牌使用量。

动态过滤从代码执行内部运行网络搜索：在 web_search_20260209 及更高版本上，该工具的 allowed_callers 字段默认为 ["code_execution_20260120"]，并且在运行动态过滤时，API 会自动为请求提供所需的代码执行。您无需自行将代码执行工具添加到 tools 中。以这种方式进行的代码执行调用除标准令牌费用外不产生额外费用。

要直接调用网络搜索而不使用动态过滤，请设置 allowed_callers: ["direct"]。不支持程序化工具调用的模型需要此设置。如果没有此设置，API 会返回 400 错误，提示您进行设置。

以下示例使用 web_search_20260318：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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_20260318", "name": "web_search"}],
)
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": "What's the weather in NYC?"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 5}],
)
print(response)

工具定义

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

JSON

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

  // Optional: Limit the number of searches
  "max_uses": 5,

  // Optional: Only include results from these domains.
  // Use allowed_domains or blocked_domains, not both.
  "allowed_domains": ["example.com", "trusteddomain.org"],

  // Optional: Never include results from these domains
  "blocked_domains": ["untrustedsource.com"],

  // Optional: Localize search results
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

所有网络搜索工具版本都接受 allowed_callers，它控制 Claude 是直接调用网络搜索，还是通过动态过滤从代码执行中调用。在 web_search_20260209 及更高版本上，其默认值为 ["code_execution_20260120"] 而不是 ["direct"]。有关如何配置，请参阅 ZDR 和 allowed_callers。web_search_20260318 及更高版本还接受 response_inclusion。

最大使用次数

max_uses 参数限制单个轮次中的搜索次数。单一事实查询通常使用 1–3 次搜索；比较性或多实体研究可能使用 10 次或更多。

失败的搜索也计入限制。如果 Claude 直接调用网络搜索的次数超过允许值，web_search_tool_result 将是一个带有 max_uses_exceeded 错误代码的错误。如果 Claude 从代码执行中调用网络搜索的次数超过允许值，代码执行运行将以错误结束。

一个轮次可以跨越多个请求。当请求在 pause_turn 之后恢复，或其最后一条消息仅包含 tool_result 块时，该请求会延续一个轮次。该轮次中先前请求的搜索会计入限制，除非 Claude 是通过动态过滤从代码执行中运行这些搜索的。

域名过滤

提供 allowed_domains 或 blocked_domains，不能同时提供两者。如果请求同时包含两者，API 将返回 400 错误。条目为不带协议方案的裸域名，可附带可选路径，例如 example.com 或 example.com/blog。

有关完整的域名过滤规则，请参阅服务器工具指南中的域名过滤。

在 Claude Managed Agents 上，请在智能体工具集的 web_search 条目上设置这些字段；请参阅限制网络搜索和网络获取域名。

本地化

user_location 参数允许您根据用户的位置对搜索结果进行本地化。请至少提供 city、region、country 或 timezone 中的一项。

type：位置类型（必须为 approximate）
city：城市名称
region：地区或州
country：两个字母的 ISO 3166-1 alpha-2 国家代码（API 会以 400 错误拒绝不受支持的代码）
timezone：IANA 时区 ID

在 Claude Managed Agents 上，智能体工具集的 web_search 条目也接受 user_location；请参阅网络工具设置。

响应包含

response_inclusion 参数控制当搜索结果被同一响应中已完成的代码执行调用使用时，搜索结果块在 API 响应中的呈现方式。设置 "response_inclusion": "excluded" 可将这些嵌套的 server_tool_use 和结果块对从响应中完全删除，适用于不需要原始搜索内容的智能体工作流。令牌用量不受影响，因为 Claude 读取的是代码的输出，而不是这些块。默认值为 "full"。来自直接调用的结果，或来自在完成前暂停的代码执行调用的结果，API 始终会完整返回，以便您可以在下一个请求中将其发送回去。

JSON

{
  "tools": [
    {
      "type": "web_search_20260318",
      "name": "web_search",
      "response_inclusion": "excluded"
    }
  ]
}

响应

以下是一个响应结构示例：

Output

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to search
    {
      "type": "text",
      "text": "I'll search for when Claude Shannon was born."
    },
    // 2. The search query used
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01WYG3ziw53XMcoyKL4XcZmE",
      "name": "web_search",
      "input": {
        "query": "claude shannon birth date"
      }
    },
    // 3. Search results
    {
      "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's response with citations
    {
      "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"
}

此示例展示的是直接搜索。当搜索通过动态过滤运行时，响应还会包含代码执行工具的结果块，并且每个嵌套的 server_tool_use 和 web_search_tool_result 对都带有一个 caller 字段，用于标识发起它的代码执行调用。

搜索结果

搜索结果包括：

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

要继续包含搜索结果的对话，请将助手的内容块按接收时的原样发送回去，包括每个结果的 encrypted_content。API 会在后续请求中解密该内容，以在 Claude 的上下文中恢复搜索结果。如果 encrypted_content 缺失或被修改，请求将失败并返回 400 验证错误。

引用

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

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

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

错误

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

Output

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

发生错误时，content 是单个错误对象，而不是结果块列表。搜索成功但没有匹配结果时，会返回空的 content 列表，而不是错误。

以下是可能的错误代码：

too_many_requests：超出速率限制
invalid_tool_input：搜索查询参数无效
max_uses_exceeded：超出网络搜索工具的最大使用次数
query_too_long：查询超出最大长度
request_too_large：搜索请求过大，通常是因为域名过滤列表过长
unavailable：发生内部错误

`pause_turn` 停止原因

API 可能会暂停长时间运行的搜索轮次并返回 stop_reason: "pause_turn"。要继续，请在新请求中将暂停的助手消息原样发送回去。

如果 Claude 在同一组并行工具调用中同时调用了网络搜索和您的某个客户端工具，API 会改为返回 stop_reason: "tool_use"，并且暂不运行搜索。要继续，请返回客户端工具结果，API 会在下一个请求中运行搜索。请参阅在一个轮次中混合使用服务器工具和客户端工具。

有关服务器端循环和 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's decision to search

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

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"latest quantum computing breakthroughs 2025\"}"}}

// Pause while search runs

// Search results streamed
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's response with citations (omitted in this example)

批量请求

您可以在 Message Batches API 中包含网络搜索工具。通过 Message Batches API 进行的网络搜索工具调用与常规 Messages API 请求中的定价相同。

为了保护共享容量，Batches API 会对每个组织的网络搜索请求进行限流，因此包含大量搜索的大型批次可能需要更长时间才能完成。您可以在 Claude Console 的速率限制页面上查看您组织的网络搜索速率限制。如需申请更高的限制，请从该页面联系销售团队。

用量和定价

除令牌用量外，网页搜索的使用会额外计费：

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

网络搜索在 Claude API 上的价格为每 1,000 次搜索 10 美元，另加搜索生成内容的标准令牌费用。在整个对话过程中检索到的网络搜索结果都会计为输入令牌，包括在单个轮次中运行的搜索迭代以及后续的对话轮次。

每次网页搜索计为一次使用，与返回的结果数量无关。因错误而失败的网页搜索不会计费。

后续步骤

网络获取工具

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

服务器工具

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

工具参考

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

可用性

网页搜索工具在所有模型上可用，并具备零数据保留和HIPAA 就绪资格。

API 支持

Messages API

用法

在请求的 tools 中添加 web_search 工具。max_uses、域名列表和 user_location 等设置放在该工具上。

状态可用

云平台

Claude API
Claude Platform on AWS
Claude Models on Google CloudAnthropic managed
Microsoft FoundryHosted on Anthropic

状态可用

云平台

Claude Models on Google CloudGoogle managed
Microsoft FoundryHosted on Azure

仅支持基础网页搜索工具（web_search_20250305），不支持动态过滤。

Managed Agents

用法

属于智能体工具集，添加工具集后默认开启。域名列表和 user_location 放在工具集的 web_search 条目上；max_uses、citations 和 cache_control 不可用。

状态可用

云平台

Claude API
Claude Platform on AWS

数据处理

数据处理概览

适用的端点

/v1/messages 使用 web_search 工具

零数据保留具备资格

不包括涵盖的模型

网络搜索的工作原理

Claude 何时搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

用量和定价

后续步骤

可用性

API 支持

数据处理

网络搜索的工作原理

Claude 何时搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

`pause_turn` 停止原因

提示缓存

流式传输

批量请求

用量和定价

后续步骤

可用性

API 支持

数据处理