网页搜索工具

构建工具

网络搜索工具

网络搜索工具为 Claude 提供实时网络内容的直接访问权限，允许它用超出知识截断日期的最新信息回答问题。

网络搜索工具为 Claude 提供实时网络内容的直接访问权限，允许它用超出知识截断日期的最新信息回答问题。响应包括从搜索结果中获取的来源引用。

最新的网络搜索工具版本（web_search_20260209）支持与 Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6 的动态过滤。Claude 可以编写并执行代码来过滤搜索结果，然后再将其加载到上下文窗口中，只保留相关信息并丢弃其余部分。这导致更准确的响应，同时减少了令牌消耗。之前的工具版本（web_search_20250305）仍然可用，但不支持动态过滤。

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

有关零数据保留资格和 allowed_callers 解决方法，请参阅 Server tools。

有关模型支持，请参阅 Tool reference。

网络搜索的工作原理

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

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

动态过滤

网络搜索是一项令牌密集型任务。使用基本网络搜索，Claude 需要将搜索结果拉入上下文，从多个网站获取完整 HTML，并在推理所有内容后才能得出答案。通常，大部分内容是无关的，这可能会降低响应质量。

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

动态过滤特别适用于：

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

动态过滤需要启用 code execution tool。改进的网络搜索工具在 Claude API 和 Microsoft Azure 上可用。在 Google Vertex AI 上，基本网络搜索工具（不支持动态过滤）可用。

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

client = anthropic.Anthropic()

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

如何使用网络搜索

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

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

client = anthropic.Anthropic()

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

  // 可选：限制每个请求的搜索次数
  "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 的域过滤，请参阅 Server tools。

本地化

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

在直接向最终用户显示 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 停止原因后继续，请参阅 Server tools。

提示缓存

有关在轮次间缓存工具定义，请参阅 Tool use with prompt caching。

流式传输

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

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 的带引用的响应（本示例中省略）

批处理请求

您可以在 Messages Batches API 中包括网络搜索工具。通过 Messages Batches API 的网络搜索工具调用的价格与常规 Messages 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.

后续步骤

Server tools

Anthropic 执行工具的共享机制。

Tool reference

所有 Anthropic 提供的工具的目录。

Was this page helpful?

构建工具

网络搜索工具

网络搜索工具为 Claude 提供实时网络内容的直接访问权限，允许它用超出知识截断日期的最新信息回答问题。

网络搜索工具为 Claude 提供实时网络内容的直接访问权限，允许它用超出知识截断日期的最新信息回答问题。响应包括从搜索结果中获取的来源引用。

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

有关零数据保留资格和 allowed_callers 解决方法，请参阅 Server tools。

有关模型支持，请参阅 Tool reference。

网络搜索的工作原理

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

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

动态过滤

动态过滤特别适用于：

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

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

client = anthropic.Anthropic()

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

如何使用网络搜索

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

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

client = anthropic.Anthropic()

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

  // 可选：限制每个请求的搜索次数
  "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 的域过滤，请参阅 Server tools。

本地化

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

错误

当网络搜索工具遇到错误（例如达到速率限制）时，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 停止原因后继续，请参阅 Server tools。

提示缓存

有关在轮次间缓存工具定义，请参阅 Tool use with prompt caching。

流式传输

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

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 的带引用的响应（本示例中省略）

批处理请求

您可以在 Messages Batches API 中包括网络搜索工具。通过 Messages Batches API 的网络搜索工具调用的价格与常规 Messages 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
  }
}

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.

后续步骤

Server tools

Anthropic 执行工具的共享机制。

Tool reference

所有 Anthropic 提供的工具的目录。

Was this page helpful?

网络搜索的工作原理

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域过滤

本地化

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批处理请求

使用和定价

后续步骤

网络搜索的工作原理

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域过滤

本地化

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批处理请求

使用和定价

后续步骤

`pause_turn` 停止原因

`pause_turn` 停止原因