网页搜索工具 · LHQ 的网络日志

API 支持：用法因产品而异。

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 进行动态过滤。

注意

对于 Claude Mythos Preview，网络搜索在 Claude API、Claude Models on Google Cloud (Google managed) 和 Microsoft Foundry 上受支持。

有关网络搜索的零数据保留（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 错误，提示您进行设置。

注意

网络搜索工具（带或不带动态过滤）可在 Claude API、Claude Platform on AWS、Claude Models on Google Cloud (Anthropic managed) 和 Microsoft Foundry 上使用。在 Microsoft Foundry 上，托管在 Azure 上的部署仅支持基础网络搜索工具（web_search_20250305，不带动态过滤）。托管在 Anthropic 上的部署支持所有版本。在 Claude Models on Google Cloud (Google managed) 上，仅提供基础网络搜索工具（不带动态过滤）。

以下示例使用 web_search_20260318：

cURL

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "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"
    }]
  }'

CLI

ant messages create <<'YAML'
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
YAML

Python

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)

TypeScript

const client = new Anthropic();

const response = await 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" }]
});

console.log(response);

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus5_5,
    MaxTokens = 4096,
    Messages = [new UserMessageParam { Content = "Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio." }],
    Tools = [new ToolUnion(new WebSearchTool20260318())]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	MaxTokens: 4096,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")),
	},
	Tools: []anthropic.ToolUnionParam{
		{OfWebSearchTool20260318: &anthropic.WebSearchTool20260318Param{}},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)

Java

import com.anthropic.models.messages.WebSearchTool20260318;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_5_5)
        .maxTokens(4096L)
        .addUserMessage("Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.")
        .addTool(WebSearchTool20260318.builder().build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}

PHP

$client = new Client();

$message = $client->messages->create(
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => 'Search for the current prices of AAPL and GOOGL, then calculate which has a better P/E ratio.'],
    ],
    model: 'claude-opus-5-5',
    tools: [
        [
            'type' => 'web_search_20260318',
            'name' => 'web_search',
        ],
    ],
);

echo $message;

Ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: Anthropic::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"
  }]
)
puts message

如何使用网络搜索

注意

网络搜索默认为您的组织启用，除非管理员已在 Claude Console 中将其禁用，管理员还可以在该处限制其搜索的域名。如果已禁用，包含该工具的 Messages API 请求将失败，并返回 400 invalid_request_error，提示网络搜索未启用，而不是在搜索结果中返回错误代码。

有关您组织的网络搜索设置如何在 Claude Managed Agents 会话中生效，请参阅限制网络搜索和网络获取域名。

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

cURL

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in NYC?"
      }
    ],
    "tools": [{
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 5
    }]
  }'

CLI

ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: What is the weather in NYC?}' \
  --tool '{type: web_search_20250305, name: web_search, max_uses: 5}'

Python

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)

TypeScript

const client = new Anthropic();

const response = await 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
    }
  ]
});

console.log(response);

AnthropicClient client = new();

var parameters = new MessageCreateParams
{
    Model = Model.ClaudeOpus5_5,
    MaxTokens = 1024,
    Messages = [new UserMessageParam { Content = "What's the weather in NYC?" }],
    Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 5 })]
};

var message = await client.Messages.Create(parameters);
Console.WriteLine(message);

client := anthropic.NewClient()

response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	Model:     anthropic.ModelClaudeOpus5_5,
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{
		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in NYC?")),
	},
	Tools: []anthropic.ToolUnionParam{
		{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{
			MaxUses: anthropic.Int(5),
		}},
	},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(response)

Java

import com.anthropic.models.messages.WebSearchTool20250305;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_5_5)
        .maxTokens(1024L)
        .addUserMessage("What's the weather in NYC?")
        .addTool(WebSearchTool20250305.builder()
            .maxUses(5L)
            .build())
        .build();

    Message response = client.messages().create(params);
    IO.println(response);
}

PHP

$client = new Client();

$message = $client->messages->create(
    maxTokens: 1024,
    messages: [
        ['role' => 'user', 'content' => "What's the weather in NYC?"],
    ],
    model: 'claude-opus-5-5',
    tools: [
        [
            'type' => 'web_search_20250305',
            'name' => 'web_search',
            'max_uses' => 5,
        ],
    ],
);

echo $message;

Ruby

client = Anthropic::Client.new

message = client.messages.create(
  model: Anthropic::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
  }]
)
puts message

工具定义

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

JSON

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

  // Optional: Limit the number of searches for each 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"]。有关如何配置，请参阅 ZDR 和 allowed_callers。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；请参阅网络工具设置。

响应包含

注意

需要 web_search_20260318 或更高版本。

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

注意

当直接向最终用户展示 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"
  }
}

发生错误时，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)

批量请求

您可以在 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 提供的工具目录以及可选工具定义属性的参考。

可用性

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

API 支持

Messages API

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

状态	云平台
可用	Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), Microsoft Foundry (hosted on Anthropic)
可用¹	Claude Models on Google Cloud (Google managed), Microsoft Foundry (hosted on Azure)

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

Managed Agents

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

状态	云平台
可用	Claude API, Claude Platform on AWS

数据处理

数据处理概览

项目	零数据保留	HIPAA
状态	具备资格（不包括涵盖的模型）	具备资格
详细信息	实时网页搜索结果在 API 响应中返回。网页搜索的动态过滤不具备 ZDR 或 HIPAA 资格。	网页搜索的动态过滤不具备 ZDR 或 HIPAA 资格。

适用的端点：

/v1/messages 使用 web_search 工具

网络搜索的工作原理

Claude 何时搜索

动态过滤

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应包含

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

用量和定价

后续步骤

可用性

API 支持

Messages API

Managed Agents

数据处理

`pause_turn` 停止原因