Claude Web Search

Claude Web Search 让支持该能力的 Claude 模型在回答时检索网络，并在协议允许时返回搜索结果块和引用。它适合需要近期事实、来源核对或限定站点检索的任务。

AGTCloud 可能通过 Chat 兼容入口或 Anthropic Messages 结构提供 Claude 能力。二者的启用字段和返回结构不同，应按当前模型详情选择入口。

不要把搜索工具版本写成永久配置

Anthropic 原生搜索工具使用带版本的类型名称。可用版本和模型支持范围可能变化，请使用当前模型详情和对应 Reference 登记的值，不要从旧项目复制固定模型或工具版本。

通过 Chat 兼容入口启用搜索

旧文档记录的 AGTCloud 主路径是在 Chat 请求中添加 web_search_options：

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "查找今天与人工智能监管有关的重要消息，并列出来源。"
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

正文通常从 Assistant Message 读取；引用是否以结构化 Annotation、链接或文本形式返回，取决于当前模型和入口。不要在没有响应依据时自行生成引用。

理解 Anthropic 原生工具结构

使用支持原生 Claude Web Search 的 Messages 入口时，搜索工具位于 tools 中。下面只说明协议结构，工具类型应替换为当前模型文档提供的版本：

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "查找今天与人工智能监管有关的重要消息，并列出来源。"
    }
  ],
  "tools": [
    {
      "type": "WEB_SEARCH_TOOL_VERSION",
      "name": "web_search",
      "max_uses": 5
    }
  ]
}

max_uses、域名过滤、用户位置和动态过滤只在对应工具版本支持时使用。完整 Messages 容器和 Content Block 结构见 Anthropic Messages Reference。

读取搜索结果和引用

原生 Messages 响应可能包含以下不同类型的 Content Block：

server_tool_use：表示模型发起了服务端搜索工具调用。
web_search_tool_result：包含搜索结果或工具错误。
text：模型给用户的最终回答。
citations：在响应提供时，将回答片段与网页来源关联。

客户端应按 type 分支处理，不能把全部 Content Blocks 当作普通字符串拼接。

{
  "content": [
    {
      "type": "text",
      "text": "根据检索结果……",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://example.com/article",
          "title": "来源标题"
        }
      ]
    }
  ]
}

示例用于说明引用与文本属于同一响应结构；实际字段以当前响应和 Messages Reference 为准。

域名、位置和动态过滤

在工具版本支持时，可以使用：

allowed_domains：只允许指定域名。
blocked_domains：排除指定域名；不要与允许列表同时配置。
user_location：提供城市、地区、国家和时区等本地化信息。
动态过滤：让支持的工具组合进一步筛选搜索结果。

这些选项会影响来源范围，但不能保证网页内容正确。高风险业务仍应验证来源、时间和多方一致性。

区分搜索工具错误和 HTTP 错误

搜索工具失败不一定意味着整个 HTTP 请求失败。原生响应可能仍返回成功状态，但在 web_search_tool_result 中包含错误对象。

情况	处理方式
HTTP 认证或参数错误	按状态码处理，不进入正常 Content Block 解析
搜索工具返回错误块	记录错误类型，决定改写问题、减少搜索范围或降级为非搜索回答
搜索成功但没有引用	展示回答时明确没有可核对来源，不生成虚假链接
达到搜索次数限制	停止继续搜索，向用户说明结果可能不完整

原生搜索与自定义工具的区别

Claude Web Search 由模型或服务端搜索工具执行。自定义 Tool Calling 则由你的应用调用自有搜索服务并回传结果。需要控制索引、访问权限或内部数据时，使用Tool Calling更合适。

上线前检查

当前模型和协议明确支持所用 Web Search 字段。
工具类型版本来自当前文档，而不是旧模型示例。
Content Block、搜索结果、文本和引用分别解析。
工具错误不会被当作正常搜索结果。
域名和位置数据只在业务需要时发送。
搜索内容不能直接触发高风险工具或绕过授权。

Chat 字段见 Chat Completions Reference，请求失败时参阅错误与排障。