网页搜索工具

让 Claude 能够访问带有引用来源的最新网页内容，并支持可选的动态过滤和域名控制。

网页搜索工具让 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 配置，请参阅服务器工具。

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

网页搜索的工作原理

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

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

Claude 何时搜索

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

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

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

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

触发行为可通过您的 "system prompt"（系统提示）进行引导：您可以鼓励 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 Console 中的这些组织级设置仅适用于 Messages API 请求。Claude Managed Agents 会话仅使用智能体工具集上每个工具的 allowed_domains 和 blocked_domains 列表；请参阅限制网页搜索和网页抓取域名。

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    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 per request
  "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"]。有关如何配置，请参阅服务器工具。web_search_20260318 及更高版本还接受 response_inclusion。

最大使用次数

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

简单的事实性查询通常使用 1–3 次搜索；比较性或多实体研究可能使用 10 次或更多。有关如何选择该值的指导，请参阅服务器工具。

域名过滤

请提供 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 对象。当您创建或更新智能体，或创建或更新提供该设置的会话时，API 会以 400 错误拒绝不受支持的 country 代码。请参阅限制网页搜索和网页抓取域名。

响应包含

response_inclusion 参数控制当搜索结果在同一回合中被已完成的代码执行调用消费时，搜索结果块在 API 响应中的呈现方式。设置 "response_inclusion": "excluded" 可将这些嵌套的 server_tool_use 和结果块对从响应中完全移除，从而为不需要将原始搜索内容回传给客户端的智能体工作流降低输出令牌成本。默认值为 "full"。来自直接调用的结果，或来自在完成前暂停的代码执行调用的结果，始终会完整返回，以便在下一回合中发送回去。

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 不计入输入或输出令牌使用量。

错误

当网页搜索工具遇到错误（例如触发 "rate limit"（速率限制））时，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。

提示缓存

要跨回合缓存工具定义，请参阅结合提示缓存的工具使用。

流式传输

启用 "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 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 executes

// 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)

批量请求

您可以在 Messages Batches API 中包含网页搜索工具。通过 Messages 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 提供的工具目录以及可选工具定义属性的参考。

网页搜索的工作原理

Claude 何时搜索

动态过滤

如何使用网页搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

用量和定价

后续步骤

网页搜索的工作原理

Claude 何时搜索

动态过滤

如何使用网页搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

`pause_turn` 停止原因

提示缓存

流式传输

批量请求

用量和定价

后续步骤