Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
网络搜索工具使 Claude 能够直接访问实时网络内容，从而能够使用超出其知识截止日期的最新信息来回答问题。响应中包含对搜索结果来源的引用。
在 web_search_20260209 及更高版本中，Claude 可以编写并运行代码，在搜索结果进入 "context window"（上下文窗口）之前对其进行过滤（即动态过滤），仅保留相关信息。动态过滤适用于 Claude 4.6 及更高版本的模型以及 Claude Mythos Preview。
网络搜索工具提供三个版本：
本页面的示例使用 web_search_20250305 进行基础搜索，使用 web_search_20260318 进行动态过滤。
有关网络搜索的零数据保留资格以及相关的 allowed_callers 配置，请参阅服务器工具。
有关模型支持情况，请参阅工具参考。
当您将网络搜索工具添加到 API 请求中时：
当请求依赖于当前的、不断变化的或超出其训练数据范围的信息时，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",
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)在您的 API 请求中提供网络搜索工具：
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-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)网络搜索工具支持以下参数：
{
"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，不含协议前缀。
有关完整的域名过滤规则，请参阅服务器工具指南中的域名过滤。
user_location 参数允许您根据用户的位置对搜索结果进行本地化。请至少提供 city、region、country 或 timezone 中的一项。
type：位置类型（必须为 approximate）city：城市名称region：地区或州/省country：两字母的 ISO 3166-1 alpha-2 国家/地区代码。API 会以 400 错误拒绝不支持的国家/地区代码。timezone：IANA 时区 ID。response_inclusion 参数控制当搜索结果在同一回合中被已完成的代码执行调用消费后，搜索结果块在 API 响应中的呈现方式。设置 "response_inclusion": "excluded" 可将这些嵌套的 server_tool_use 和结果块对从响应中完全删除，从而为不需要将原始搜索内容回传给客户端的智能体工作流降低输出令牌成本。默认值为 "full"。来自直接调用的结果，或来自在完成前暂停的代码执行调用的结果，始终会完整返回，以便在下一回合中回传。
{
"tools": [
{
"type": "web_search_20260318",
"name": "web_search",
"response_inclusion": "excluded"
}
]
}以下是一个响应结构示例：
{
"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：来源页面的 URLtitle：来源页面的标题page_age：网站最后更新的时间encrypted_content：在多轮对话中必须回传的加密内容要继续包含搜索结果的对话，请将助手的内容块按原样回传，包括每个结果的 encrypted_content。API 会在后续回合中解密该内容，以在 Claude 的上下文中恢复搜索结果。如果 encrypted_content 缺失或被修改，请求将失败并返回 400 验证错误。
网络搜索始终启用引用，每个 web_search_result_location 包括：
url：被引用来源的 URLtitle：被引用来源的标题encrypted_index：在多轮对话中必须回传的引用标识cited_text：最多 150 个字符的被引用内容网络搜索引用字段 cited_text、title 和 url 不计入输入或输出令牌使用量。
当网络搜索工具遇到错误（例如达到速率限制）时，Claude API 仍会返回 200（成功）响应。错误会使用以下结构在响应正文中表示：
{
"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。
有关跨回合缓存工具定义的信息，请参阅工具使用与提示缓存。
启用流式传输后，您将在流中收到搜索事件。搜索运行期间会有一段暂停：
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 提供的工具目录以及可选工具定义属性的参考。
Was this page helpful?