工具

网络搜索工具

网络搜索工具让 Claude 能够直接访问实时网络内容，使其能够利用超出知识截止日期的最新信息来回答问题。Claude 会自动引用搜索结果中的来源作为其回答的一部分。

请通过我们的反馈表单分享您使用网络搜索工具的体验。

支持的模型

网络搜索可在以下模型上使用：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7（已弃用）(claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5（已弃用）(claude-3-5-haiku-latest)

网络搜索的工作原理

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

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

如何使用网络搜索

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

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

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

工具定义

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

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 错误代码的错误。

域名过滤

使用域名过滤时：

域名不应包含 HTTP/HTTPS 协议（使用 example.com 而不是 https://example.com）
子域名会自动包含（example.com 涵盖 docs.example.com）
指定子域名会将结果限制为仅该子域名（docs.example.com 仅返回该子域名的结果，而不是 example.com 或 api.example.com 的结果）
支持子路径，并匹配路径之后的所有内容（example.com/blog 匹配 example.com/blog/post-1）
您可以使用 allowed_domains 或 blocked_domains，但不能在同一请求中同时使用两者。

通配符支持：

每个域名条目只允许一个通配符（*），且必须出现在域名部分之后（在路径中）
有效：example.com/*、example.com/*/articles
无效：*.example.com、ex*.com、example.com/*/news/*

无效的域名格式将返回 invalid_tool_input 工具错误。

请求级别的域名限制必须与在 Console 中配置的组织级别域名限制兼容。请求级别的域名只能进一步限制域名，不能覆盖或扩展超出组织级别列表的范围。如果您的请求包含与组织设置冲突的域名，API 将返回验证错误。

本地化

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

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

响应

以下是一个示例响应结构：

{
  "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 不计入输入或输出 token 用量。

当直接向最终用户显示 API 输出时，必须包含指向原始来源的引用。如果您在向最终用户显示之前对 API 输出进行了修改，包括重新处理和/或将其与您自己的材料合并，请在咨询您的法律团队后适当显示引用。

错误

当网络搜索工具遇到错误时（例如达到速率限制），Claude API 仍然返回 200（成功）响应。错误在响应体中使用以下结构表示：

{
  "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 停止原因，这表示 API 暂停了一个长时间运行的回合。您可以将响应原样在后续请求中传回，让 Claude 继续其回合，或者修改内容以中断对话。

提示缓存

网络搜索与提示缓存兼容。要启用提示缓存，请在请求中添加至少一个 cache_control 断点。系统在执行工具时会自动缓存到最后一个 web_search_tool_result 块。

对于多轮对话，在最后一个 web_search_tool_result 块上或之后设置 cache_control 断点以重用缓存内容。

例如，在多轮对话中使用提示缓存与网络搜索：

import anthropic

client = anthropic.Anthropic()

# 第一个请求，包含网络搜索和缓存断点
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# 将 Claude 的响应添加到对话中
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 第二个请求，在搜索结果之后设置缓存断点
messages.append({
    "role": "user",
    "content": "Should I expect rain later this week?",
    "cache_control": {"type": "ephemeral"}  # 缓存到此处
})

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# 第二个响应将受益于缓存的搜索结果
# 同时仍然能够在需要时执行新的搜索
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

流式传输

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

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.

Was this page helpful?

工具

网络搜索工具

请通过我们的反馈表单分享您使用网络搜索工具的体验。

支持的模型

网络搜索可在以下模型上使用：

Claude Opus 4.6 (claude-opus-4-6)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Sonnet 3.7（已弃用）(claude-3-7-sonnet-20250219)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Haiku 3.5（已弃用）(claude-3-5-haiku-latest)

网络搜索的工作原理

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

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

如何使用网络搜索

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

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

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

工具定义

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

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 错误代码的错误。

域名过滤

使用域名过滤时：

域名不应包含 HTTP/HTTPS 协议（使用 example.com 而不是 https://example.com）
子域名会自动包含（example.com 涵盖 docs.example.com）
指定子域名会将结果限制为仅该子域名（docs.example.com 仅返回该子域名的结果，而不是 example.com 或 api.example.com 的结果）
支持子路径，并匹配路径之后的所有内容（example.com/blog 匹配 example.com/blog/post-1）
您可以使用 allowed_domains 或 blocked_domains，但不能在同一请求中同时使用两者。

通配符支持：

每个域名条目只允许一个通配符（*），且必须出现在域名部分之后（在路径中）
有效：example.com/*、example.com/*/articles
无效：*.example.com、ex*.com、example.com/*/news/*

无效的域名格式将返回 invalid_tool_input 工具错误。

本地化

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

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

响应

以下是一个示例响应结构：

{
  "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 不计入输入或输出 token 用量。

错误

当网络搜索工具遇到错误时（例如达到速率限制），Claude API 仍然返回 200（成功）响应。错误在响应体中使用以下结构表示：

{
  "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` 停止原因

提示缓存

对于多轮对话，在最后一个 web_search_tool_result 块上或之后设置 cache_control 断点以重用缓存内容。

例如，在多轮对话中使用提示缓存与网络搜索：

import anthropic

client = anthropic.Anthropic()

# 第一个请求，包含网络搜索和缓存断点
messages = [
    {
        "role": "user",
        "content": "What's the current weather in San Francisco today?"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)

# 将 Claude 的响应添加到对话中
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 第二个请求，在搜索结果之后设置缓存断点
messages.append({
    "role": "user",
    "content": "Should I expect rain later this week?",
    "cache_control": {"type": "ephemeral"}  # 缓存到此处
})

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "user_location": {
            "type": "approximate",
            "city": "San Francisco",
            "region": "California",
            "country": "US",
            "timezone": "America/Los_Angeles"
        }
    }]
)
# 第二个响应将受益于缓存的搜索结果
# 同时仍然能够在需要时执行新的搜索
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

流式传输

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

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.

Was this page helpful?

支持的模型

网络搜索的工作原理

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

用量和定价

支持的模型

网络搜索的工作原理

如何使用网络搜索

工具定义

最大使用次数

域名过滤

本地化

响应

搜索结果

引用

错误

pause_turn 停止原因

提示缓存

流式传输

批量请求

用量和定价

`pause_turn` 停止原因

`pause_turn` 停止原因