Cloudflare Web Search API 是一项目前处于 beta 阶段的联网搜索接口，供 AI Agent 和其他应用查询互联网中的实时信息。AI Agent 指能够根据任务调用外部工具的 AI 程序；接入搜索后，应用可以先检索网页信息，再把结果交给模型组织回答，而不必让模型猜测网址或只依赖训练数据。

这项 API 通过 Cloudflare 的 AI Gateway 运行。AI Gateway 是管理 AI 服务请求的网关；在这里，搜索调用会出现在网关日志中，并按所选搜索提供商的公开 API 价格计入 AI Gateway credits，Cloudflare 不额外加价。beta 阶段可选的提供商包括 Ceramic.ai、Exa 和 Linkup，也可以使用自己的提供商 API key。

Web Search API 适合解决什么问题

模型的训练数据有截止时间，因而可能不知道近期发生的事；即使知道某个主题，也不一定能准确给出相关网页地址。Web Search API 让应用能够针对用户问题发起实时搜索，再将搜索结果作为生成回答的依据。它负责检索信息，不会自动保证最终答案准确，也不意味着应用可以省略对结果的处理与核验。

一种常见的接入方式是“检索—生成”：应用根据用户问题组织搜索查询，调用 Web Search API 获取结果，再将结果交给模型归纳。应用仍需决定如何呈现答案、是否提供来源，以及搜索失败时如何处理。以下分别介绍 REST API 和 Cloudflare Worker 中的调用方式。

通过 REST API 发起搜索

REST API 是通过 HTTP 请求调用服务的接口形式。调用 Web Search API 时，需要使用 Cloudflare 账户 ID 构造请求地址，并在 Authorization 请求头中提供 Bearer Token；请求体则以 JSON 格式传入搜索词、提供商、结果数量和 AI Gateway 配置 ID。下面的示例搜索盐湖城临近秋季时的活动，指定 Ceramic，并将结果数量设为 5：

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/websearch/" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "What are some fun things to do in Salt Lake City as fall approaches?",
    "provider": "ceramic",
    "limit": 5,
    "options": {
      "gateway": {
        "id": "default"
      }
    }
  }'

示例中的 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_API_TOKEN 是需要替换为实际值的环境变量。query 指定搜索内容，provider 选择搜索提供商，limit 设置返回结果数量；options.gateway.id 指定使用的 AI Gateway 配置。示例使用的 default 是配置 ID，并非搜索提供商名称。

在 Cloudflare Worker 中调用

如果应用运行在 Cloudflare Worker 中，也可以通过 AI binding 调用 Web Search API。binding 是 Worker 访问 Cloudflare 服务的绑定入口；使用下面的代码时，Worker 环境需要提供名为 AI 的绑定。此示例改用 Exa，收到响应后再通过 response.json() 解析 JSON 数据：

const response = await env.AI.websearch({
  gatewayId: "default",
  query: "What are some fun things to do in Salt Lake City as fall approaches?",
  provider: "exa",
  limit: 5,
});
const results = await response.json();

REST 请求通过 options.gateway.id 指定网关配置，而 Worker 示例使用 gatewayId。两种调用都要提供搜索查询、提供商和结果数量；示例中的提供商可以分别选择 Ceramic、Exa 或 Linkup。代码展示了响应的 JSON 解析方式，但应用仍需要根据实际返回数据决定如何把结果传给模型或展示给用户。

计费、日志与数据保留

Web Search API 的搜索请求会经过 AI Gateway，因此可以在对应的网关日志中查看。费用按所选提供商的公开 API 价格计入 AI Gateway credits，Cloudflare 不额外加价；如果希望使用自己的提供商 API key，也可以采用该方式。具体接入时，应根据使用的提供商和账户配置准备相应凭据。

Cloudflare 表示，通过 Cloudflare 发出的请求在 Ceramic.ai、Exa 和 Linkup 这三家提供商处均支持 Zero Data Retention，即零数据保留；三家也都承诺遵循 Cloudflare 的已验证爬虫标准。这些说明针对的是经 Cloudflare 发出的请求及提供商承诺，不应被理解为搜索结果必然完整、准确，或应用在自身环节无需管理数据。

接入时需要留意的边界

由于接口目前处于 beta，正式用于产品前，应先确认应用能够正确处理搜索响应和调用失败。排查 REST 调用时，可依次检查账户 ID、Bearer Token、JSON 请求体中的字段，以及 provider 和 AI Gateway 配置 ID 是否符合预期；也可以查看 AI Gateway 日志，确认请求是否经过网关。Worker 调用则要确认环境中存在可用的 AI binding，并为网络请求和 JSON 解析添加适当的异常处理。

搜索结果可以为模型提供较新的信息，但检索本身并不等于事实校验。对于时效性强或影响较大的回答，应用应结合业务需求检查来源和内容，并明确搜索失败时的处理方式；如果问题不需要实时网络信息，直接调用模型可能更简单。Web Search API 的价值在于让联网检索接入 AI Gateway 的调用与日志体系，而不是替代应用对答案的判断。

原始来源： https://developers.cloudflare.com/changelog/post/2026-10-02-introducing-web-search-api/