给智能体接上实时联网搜索：从一次调用到可用工具

用 Cloudflare Web Search API 给自建智能体接上实时联网：从一次 REST 调用开始，到把它包成模型可调用的工具，再到接进低代码平台，附常见报错的排查方向。

这篇教程解决什么

模型有一个绕不过去的限制：它的知识停在训练截止的那个时间点。你问它「上个月某个产品更新了什么」，它要么说不知道，要么凭印象编一个看着很像的答案 —— 后者比前者危险得多。

这篇教程做的事，是给一个自建智能体接上「现在去查一下」的能力。用的是 Cloudflare 在 2026 年 10 月 2 日进入 beta 的 Web Search API：它挂在 AI Gateway 上，发一个查询进去，返回结构化的标题、链接与摘要，可以直接塞进模型上下文。官方文档里对它的定位说得挺准 —— 智能体需要实时信息时，常见的做法是「猜一个 URL 然后 curl 它」，于是调用记录里经常出现 404；Web Search API 把这件事换成了一次真正的查询。

读完你应该能做到三件事：发通第一次搜索调用、把它包装成模型可以自己决定要不要用的工具、以及在低代码平台里复用这条链路。

这篇不覆盖什么，先说清免得白读：

• 不比较三家搜索服务商的结果质量。官方说明里三家返回的字段结构一致，但质量差异要靠你自己的查询集去试，本篇不做这个评测。
• 不讲向量库与私有语料的检索（RAG）。那是另一条路，解决的是「从自己的资料里找」，与「查公开网页」是两件事，混在一起会出问题。
• 不写价格。搜索请求会消耗 AI Gateway 额度或你自己的服务商额度，具体费率以官网为准。

开始前的准备

按官方文档的 prerequisites，需要四样东西：

1. 一个 Cloudflare 账号。没有就先注册。
2. 一个 AI Gateway。每个账号自带一个名为 default 的网关，也可以新建。后面所有请求都要指定走哪个网关。
3. 额度或自有密钥。要么在账号上充 AI Gateway credits，要么在网关上存一个搜索服务商的 API key（自带的那种方式，详见第 6 步）。
4. 一个 API token，且必须同时具备两项权限：Account > Workers AI > Read 与 Account > AI Gateway > Read。少一项会在第 2 步直接失败。

另外准备一个能发 HTTP 请求的后端环境。如果你想走 Workers 那条路，还需要本地装好 Wrangler。

前置成本要提前算清楚，这是很多人做完才发现的部分：

• 搜索请求和模型推理请求走同一个网关，因此搜索会出现在你的网关日志里，并产生费用。也就是说，一个智能体每次「查一下」都是有价的，按调用次数累积。
• 如果你不指定自有密钥，费用走 AI Gateway 额度；具体费率以官网为准，且不同服务商之间差异不小。
• 请求会经过境外节点，涉及内网数据或敏感查询时需要自行评估。

步骤详解

第 1 步：确认网关与凭据

登录 Cloudflare 控制台，进 AI Gateway 页面，确认你要用的网关名称（用默认的 default 也行，本篇全程以它为例）。记下两样东西：Account ID 与刚创建的 API token。

判断这一步成功的标准很朴素：把这两个值填进环境变量后，第 2 步的调用能返回 200。如果第 2 步报权限错，问题在这一步，不在调用本身。

第 2 步：用 REST 接口发第一次搜索

接口是一个 POST 请求，路径为 /ai/websearch/，拼在账号维度下：

```

POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/websearch/

```

请求体里四个字段够用了：query（必填，最长 1024 字符）、provider（可选，ceramic / exa / linkup，不填默认 ceramic）、limit（可选，1 到 10，默认 10）、options.gateway.id（必填，指定网关）。

一个完整可用的 curl 长这样（写成一行，避免换行符被吞掉）：

```

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":"Cloudflare Web Search API 请求限额","provider":"ceramic","limit":5,"options":{"gateway":{"id":"default"}}}'

```

看到什么算成功：返回 200，并且响应体里有一个 items 数组，其中至少一项带 url 与 title。此时先不要急着接模型 —— 把返回的链接手动打开一两个，确认内容确实是你要的那种「实时信息」，而不是一堆无关页面。这一步的手动核对省不得，它能提前暴露查询词写得不好的问题。

第 3 步：读返回结果，只保留需要的字段

响应结构很简单：

```

{ "items": [ { "url": "...", "title": "...", "description": "..." } ], "metadata": { "query": "...", "requestId": "...", "latencyMs": 612 } }

```

三个细节值得注意：

• description 是可选字段 —— 服务商没返回就不存在。所以下游代码不能直接读它，要先判空，否则偶发崩溃会很难查。
• metadata.requestId 与 latencyMs 建议原样记进你自己的日志。等线上出现「智能体这次答得很慢」这类反馈时，这两个值是定位依据。
• items 里的 url 要原样保留并随答案一起输出。让答案能点回出处，是这类功能能不能被信任的分界线。

第 4 步：把搜索包成模型可调用的工具

关键的一步不是「调通搜索」，而是让模型自己判断什么时候该搜。做法是声明一个函数工具，模型决定调用时，你去执行搜索，再把结果作为工具返回内容塞回对话，让模型基于它作答。

官方示例给了完整形态：先用 env.AI.run 带上 tools 声明发起一轮，检查返回里的 tool_calls；若命中 web_search，就用模型给出的 arguments.query 去调 env.AI.websearch()；再把搜索结果作为一个 role: "tool" 的消息追加进 messages，发起第二轮 env.AI.run，得到最终回答。

这个「两轮调用」的结构值得单独强调：搜索不在第一轮完成，它是第一轮的结果。 把这个过程想成模型先说「我需要查 X」，你替它查完，它再说答案。少一轮都不成立。

第 5 步：在 Worker 里改成 binding 调用

如果智能体跑在 Cloudflare Workers 上，可以省掉 REST 那一层。先在 Wrangler 配置里加 AI binding：

```

{ "name": "web-search-worker", "main": "src/index.ts", "compatibility_date": "2026-10-02", "ai": { "binding": "AI" } }

```

然后在代码里直接调 env.AI.websearch({ gatewayId: "default", query: "...", provider: "exa", limit: 5 })，返回值是标准 Response，用 response.json() 读结果。

注意一处与 REST 的差异：REST 里网关写在 options.gateway.id，binding 里是平铺的 gatewayId。两者语义相同、写法不同，照抄时容易套错。

第 6 步：接入自有服务商密钥（可选）

不想走 AI Gateway 额度时，可以用自己的服务商密钥。配置路径在控制台：AI Gateway → 选中网关 → Provider Keys → 添加 Ceramic.ai / Exa / Linkup 的 key，并给它起一个别名（例如 default）。列表里没有的服务商，选 Configure custom providers 添加。配好后在请求里同时传 provider 与 byokAlias。

你的密钥不会出现在请求里 —— 网关按别名取出存的 key，存的时候用 Secrets Store 加密。

第 7 步：接进低代码平台

不写代码也能用上这条链路。扣子 Coze、Dify、n8n 这类平台通常都提供「自定义工具」或「HTTP 请求」节点，把第 2 步那个 POST 原样填进去即可：地址、Authorization 头、JSON 请求体三个部分对上，节点就能返回 items，再由平台的智能体节点消费。

具体的节点名与字段名以各平台当前版本为准 —— 这部分迭代快，照着几个月前的截图填容易对不上。判断是否接成功的标准不变：让智能体答一个训练截止之后的问题，看它给出的链接能不能打开、内容对不对得上。

常见坑与排错

• 权限少一项就会失败。官方文档明确要求 token 同时有 Workers AI Read 与 AI Gateway Read。只配了其中一个，症状是鉴权类错误，而它看起来和「token 写错了」完全一样 —— 先核对权限再怀疑凭据。
• 写了 byokAlias 但网关上没配对应密钥，会返回 400，且不会回落到额度。这是官方写明的取舍行为：显式指定别名意味着「我要求用这把钥匙」，配错就报错，而不是悄悄换一种付费方式。反过来，不写别名时，若网关存有该服务商的 default 别名密钥，会优先用它；没有才走额度。想强制走自有密钥就必须同时传 provider 与 alias。
• limit 最大是 10，query 最长 1024 字符。想靠加大 limit 提升答案质量是错的，超出部分会被截掉。真要提升质量，改的是查询词本身。
• 别把 token 放在前端。鉴权头必须留在后端，这一条对任何带计费的接口都成立，搜索接口尤其容易被忽视，因为它看起来「只是查一下」。
• 搜索结果不等于页面已被抓取。拿到的是标题、链接与摘要，不是正文。摘要不足以支撑结论时，要另取一次页面内容 —— 不要把摘要当原文引用。
• 中文查询的召回不稳定。这与服务商的索引覆盖有关，不是接口问题。遇到中文查询效果不好时，先试换成产品名或英文原名再查，往往比调参数有效。

进阶用法

把服务商做成可切换的配置项。 三个服务商返回结构一致，切换只是改一个字符串。所以值得把它提到配置里，而不是写死在代码里 —— 这样你可以在真实查询集上分别跑一遍，按「得到一条有出处的正确答案」的平均成本来选，而不是按印象选。官方也提示了：不同服务商在摘要长度、是否自带正文片段等行为上并不相同，会直接影响进模型的输入长度。

把「公开网页」与「自有语料」分成两个工具。 给模型两个可调用的工具，一个查公开网页，一个查你已索引的内部资料，并在提示里说清边界。好处是答案里能区分「这句话来自公开页面」还是「来自内部文档」—— 对企业场景来说，这个区分比答案本身更重要。

给搜索加一层缓存。 同一个查询在短时间内被反复触发是很常见的（尤其是智能体自己重试时）。按 query 做一层短期缓存，能直接省掉一部分调用，也顺带减少日志噪音。

常见问题

不写代码能用上吗？

能。低代码平台里的 HTTP 请求节点可以把第 2 步那个 POST 原样填进去，取回 items 后交给智能体节点消费，见第 7 步。代价是你拿不到 requestId 与 latencyMs 这类观测字段，排查问题时信息少一些。另外要注意，把带计费的调用放进一个可被公开触发的工作流时，限流要自己加。

一次搜索最多能拿多少条结果？

10 条，这是官方文档写明的上限，limit 超过 10 会被约束。查询词本身最长 1024 字符。如果 10 条不够用，通常是查询词太宽泛导致的 —— 先收敛查询词，而不是想办法绕过限额。

用自己的服务商密钥会怎样计费？

由服务商按你们之间的协议直接计费，不走 AI Gateway 额度。配置方式见第 6 步：在网关上存密钥并起别名，请求里传 byokAlias。要留意前面提到的行为 —— 别名配错会直接报错，不会静默改用额度。

和直接给模型开联网开关有什么区别？

两类做法不在同一层。模型厂商自带的联网能力，搜索与模型是绑在一起的；Web Search API 把这两者拆开了 —— 模型从哪来、检索从哪来，可以分别选。它额外的收益是搜索与推理进同一份日志：一次智能体运行里，查了什么、查了几次、花了多久、花在哪，都能对上。对要控成本或要审计的场景，这个可观测性往往比能力本身更有用。

检索到的内容可以直接当作事实引用吗？

不可以，要保留出处并核对。接口返回的是标题、链接与摘要，摘要由服务商生成，不能等同于原文。使用时的底线是：答案里带上 url，摘要不足以支撑结论时打开原页面核对。另外，结果里有 last-modified 之类字段时也不要当成发布或更新时间来用 —— 那不是一回事。

相关工具与内容

• 分类：AI 智能体、AI 搜索、AI 编程
• 可接这条链路的工具：Dify、扣子 Coze、n8n、Zapier、Make
• 相关内容：AI Gateway 上线搜索接口（快讯）、2026年四季度 AI 工具怎么选、秘塔AI搜索评测