10 月 2 日，Cloudflare 上线 Web Search API（Beta）：把网页搜索做成一个走 AI Gateway 的接口，Agent 不再需要自己猜 URL 再去抓页面。首发接入 Ceramic.ai、Exa、Linkup 三家，按各家标价计费、不加价，也可以带上自己的 Key。
模型的知识停在训练时间，这是所有带检索的 Agent 都要面对的起点。现实中的常见做法是让模型自己编一个搜索链接去请求，结果撞上 404、抓到过期快照，或者拿回一堆解析不了的结构。Web Search API 想解决的就是这一段：把「取回实时网页结果」从 Agent 的临时拼装，变成一个可计费、可观测、可管权限的基础设施调用。
发生了什么：一个接口，两条调用路径
调用方式有两种，都强制经过 AI Gateway。REST 路径是向 https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/websearch/ 发 POST，用的 API Token 需要带 Account > Workers AI > Read 和 Account > AI Gateway > Read 两个权限。Worker 里则更短：加一个 ai binding，直接调 env.AI.websearch({ gatewayId, query, provider, limit })，返回标准 Response，再 response.json() 取值。
参数不多，边界写得很死：query 必填，长度 1 到 1024 字符；provider 目前是 ceramic（默认）、exa、linkup 三选一；limit 默认 10，最小 1、最大 10——单次请求最多只能拿回 10 条结果。此外 options.gateway.id 是必填对象，每个账号自带的那个网关就叫 default。返回结构是 items 数组，每条含 url、title、description，外加一个 metadata，里面有 query、requestId 和 latencyMs。文档特别注明：可选字段只在 provider 返回时才会出现。
完整工作场景：把它当成模型的一个工具
官方给出的集成方式和普通的 function calling 没有区别，分四步：在模型调用里声明一个 web_search 函数工具 → 检查 completion.tool_calls?.[0] → 用工具参数里的查询串执行 env.AI.websearch() → 把结果 JSON.stringify 之后作为 tool 角色的消息回填，再请求一次最终回答。整段逻辑不依赖任何新概念，改动量就是替换掉原来那段「自己发 HTTP 请求去搜」的代码。
计费与密钥的处理是这次比较实用的部分。默认情况下搜索消耗 AI Gateway 的额度，按三家合作方的标价结算且不加价；调用会正常出现在网关的可观测日志里。如果你已经和某家 provider 有合约，可以在 AI Gateway 的 Provider Keys 里存一个 Key 并起个别名，请求时传 byokAlias，账单直接由 provider 出。密钥不会随请求发出——网关自己查表，存储时用 Secrets Store 加密。凭证解析规则很明确：传了 byokAlias 但别名没配置，请求直接返回 400，不会悄悄回退到额度扣费；不传别名时，才先看有没有 default 别名的 Key，没有再走额度。
为什么这改变了 Agent 的检索层
过去这一段通常由团队自己拼：写个抓取脚本、接一家搜索 API、自己写重试和缓存，然后在成本、限流、合规上各踩一遍坑。把搜索收进 AI Gateway 之后，几件事同时落到了平台上：出账口径统一（推理和搜索一张账单）、调用可观测（同一条日志链路）、权限可管（管理员能限制哪些 provider 可达）、密钥可托管（BYOK 但不出网）。对已经有网关的中大型团队，这些是省掉一整层自建代码的收益。
从「同样的检索需求，过去要自己写多少东西」的角度看，差别更直观。自建方案里，你需要自己实现查询转发与重试、自己维护 provider 的响应格式差异、自己处理超时与降级、自己把调用日志接到已有的观测体系、自己管密钥轮换，还要在合规上单独解释数据去了哪里。这个接口把其中大部分压成了配置项：换 provider 是改一个枚举值，换 Key 是改一个别名，观测和出账跟着网关走。它没有让检索变得更强，但让检索变得更容易被当成基础设施来管。
更关键的是来源可追溯这一条被写进了合作条款。三家伙伴承诺遵守 Cloudflare 的 Verified bots 要求：爬虫要表明身份、遵守 robots.txt、提供结果来源，并且响应里必须包含被抓取内容的链接。对做 RAG 的团队来说，「每条结果都能指回原文地址」比多几个候选结果更重要。
限制与需要注意的地方
先说没写进文档的部分：官方没有公布任何单价金额、速率上限、配额、延迟指标、支持区域，也没有公布一份完整的 provider 能力对照表。响应结构只描述到 items 一层，没有单独的引用（citations）字段，也没有列出错误码清单。这意味着现在还不适合把它当作容量规划的依据，需要自己压测。
另外几点边界值得记下。单次最多 10 条结果，需要更宽召回时只能多次调用，成本随之上升。Zero Data Retention 方面，Cloudflare 只说会「标注支持 ZDR 的合作方」，但没有给出名单，有数据留存要求的团队需要自行核对。还有一个正在路上的变化：Cloudflare 表示会在 AI Gateway 里内置原生工具，网页搜索会是第一批，届时上面那段手写 function tool 的胶水代码可以删掉——在那之前，仍然需要自己注册工具。最后，账单一律走 AI Gateway 额度，如果你的组织对「AI 支出统一走网关」有内部限制，需要先确认这条路径是否符合预算归属规则。
如何试用
准备三样东西就能开始：一个 Cloudflare 账号、一个 AI Gateway（每个账号都自带名为 default 的那个），以及网关额度或已存好的 provider Key。最快的一次验证是一条 curl：向 /client/v4/accounts/$ACCOUNT_ID/ai/websearch/ POST 一个 JSON，带上 query、provider（如 exa）、limit 和 options.gateway.id，用带 Workers AI 与 AI Gateway 读权限的 Token 做 Bearer 认证。返回的 items 里应当能看到每条结果的 url、title、description 和 metadata.latencyMs。建议第一次先用 limit: 3 跑通链路，确认模型能正确消费这三个字段，再决定是否接入生产。
如果不想手写工具描述，也可以先等一等：Cloudflare 已表示会把网页搜索作为 AI Gateway 内置原生工具的第一批，届时这段胶水代码可以直接删掉。
信息来源
- Cloudflare 博客：Introducing Web Search API via AI Gateway（2026-10-02）https://blog.cloudflare.com/introducing-web-search-api/
- Cloudflare Changelog：Web Search API（2026-10-02）https://developers.cloudflare.com/changelog/post/2026-10-02-introducing-web-search-api/
- Cloudflare 开发者文档：Web Search 使用指南 https://developers.cloudflare.com/web-search/how-to-use/
HiFox：将 Agent 变成真正的队友
另外，我们也在思考，AI 如何从个人提效走进团队协作。
HiFox 是一个让人和 AI Agent 在同一个工作现场协作的平台：你可以像给同事分派任务一样指派 Agent，在任务看板中跟踪进度、查看结果，让 Agent 成为团队里的队友。
👉 立即体验 HiFox：https://hifox.com
AI Coding 交流群
如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，
欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。
