消息工具

网络搜索工具

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

最新的网络搜索工具版本（web_search_20260318）支持动态过滤，适用于 Claude Fable 5、Claude Opus 4.8、Claude Mythos 5、Claude Mythos Preview、Claude Opus 4.7、Claude Opus 4.6 和 Claude Sonnet 4.6。Claude 可以编写并执行代码，在搜索结果进入上下文窗口之前对其进行过滤，仅保留相关信息并丢弃其余内容。这可以在减少令牌消耗的同时生成更准确的响应。web_search_20260318 还为智能体工作流添加了响应包含控制。之前的版本（仅支持动态过滤的 web_search_20260209，以及支持基础搜索的 web_search_20250305）仍然可用。

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

有关"Zero Data Retention"（零数据保留）资格和 allowed_callers 解决方法，请参阅服务器工具。

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

网络搜索的工作原理

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

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

Claude 何时进行搜索

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

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

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

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

触发行为可以通过您的系统提示进行引导：您可以鼓励 Claude 更积极地搜索，或倾向于直接回答。如需硬性约束，可使用 max_uses 来限制每个请求的搜索次数上限。

动态过滤

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

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

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

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

动态过滤需要启用代码执行工具。网络搜索工具（无论是否启用动态过滤）在 Claude API、Claude Platform on AWS 和 Microsoft Foundry 上均可用。在 Vertex AI 上，仅基础网络搜索工具（不含动态过滤）可用。网络搜索在 Amazon Bedrock 上不可用。

要启用动态过滤，请使用 web_search_20260209 或任何更高版本。以下示例使用 web_search_20260209：

client = anthropic.Anthropic()

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

最大使用次数

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

简单的事实性查询通常使用 1–3 次搜索；比较性或多实体研究可能使用 10 次或更多。对于延迟敏感的查询，max_uses: 3 可以限制成本，同时很少会导致截断。对于研究型智能体，可将 max_uses 设置为 15–20，或完全省略该参数。

域名过滤

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

本地化

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

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

响应包含

需要 web_search_20260318 或更高版本。

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

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

搜索结果

搜索结果包括：

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": "srvtoolu_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'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 美元，另加搜索生成内容的标准令牌费用。在整个对话过程中检索到的网络搜索结果均计为输入令牌，包括单轮对话中执行的搜索迭代以及后续对话轮次中的结果。

每次网络搜索计为一次使用，无论返回多少条结果。如果在网络搜索过程中发生错误，该次网络搜索将不会计费。

后续步骤

服务器工具

Anthropic 执行的工具的共享机制。

工具参考

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

Was this page helpful?

消息工具

网络搜索工具

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

有关"Zero Data Retention"（零数据保留）资格和 allowed_callers 解决方法，请参阅服务器工具。

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

网络搜索的工作原理

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

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

Claude 何时进行搜索

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

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

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

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

动态过滤

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

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

要启用动态过滤，请使用 web_search_20260209 或任何更高版本。以下示例使用 web_search_20260209：

client = anthropic.Anthropic()

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

最大使用次数

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

域名过滤

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

本地化

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

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

响应包含

需要 web_search_20260318 或更高版本。

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

搜索结果

搜索结果包括：

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": "srvtoolu_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'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 请求中的定价相同。

使用量和定价

网络搜索的使用费用在令牌使用费用之外单独收取：

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

每次网络搜索计为一次使用，无论返回多少条结果。如果在网络搜索过程中发生错误，该次网络搜索将不会计费。

后续步骤

服务器工具

Anthropic 执行的工具的共享机制。

工具参考

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

Was this page helpful?

网络搜索的工作原理

Claude 何时进行搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

使用量和定价

后续步骤

网络搜索的工作原理

Claude 何时进行搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

使用量和定价

后续步骤

网络搜索的工作原理

Claude 何时进行搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

`pause_turn` 停止原因

提示缓存

流式传输

批量请求

使用量和定价

后续步骤

网络搜索的工作原理

Claude 何时进行搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

`pause_turn` 停止原因

提示缓存

流式传输

批量请求

使用量和定价

后续步骤