1. 先聊清楚Agent 为什么非要联网不可如果你跟我一样过去半年在折腾各种 AI Agent一定撞到过同一个尴尬场面问它“帮我看看今天某品牌的发布会说了什么”它一本正经地编出一段发布会通稿时间、地点、嘉宾全都有就是没一句是真的。这不是模型笨而是底层逻辑决定的。大语言模型的知识来自训练时拍进去的数据存在一个固定的知识截止日期。截止日期之后发生的事情它根本没见过。更麻烦的是模型没有“我不知道”这个概念遇到没见过的问题它会按照概率分布顺理成章地生成一段看起来像答案的文字。这个在行业里有个专门的说法叫“幻觉”但实际体验就是一本正经地胡说八道。所以我从一开始就坚信一个判断Agent 要落地第一件事不是把模型换得多大而是给它接上有实时信息输入的管道。这个管道的核心就是联网搜索能力。Agent 接收用户问题之后先去网络上检索相关资料再把检索结果连同问题一起交给模型让模型基于真实信息作答。模型不再凭空推理而是站在实时数据上做归纳和提炼准确率完全不是一个级别。但接搜索这件事看起来简单真正做起来坑不少。你要么自己写爬虫去抓网页要么对接各种搜索服务的 API。而搜索 API 这个行的水很深有的按次数收费贵得离谱有的返回结果质量差到没法用有的文档写得语焉不详接入光调参就折腾一星期。前阵子我注意到 Cloudflare 悄悄上线了 Web Search API就专门花时间研究加实测了一轮。这 API 本身就是给需要联网能力的 Agent 场景设计的直接通过 Cloudflare 的全球边缘网络发起搜索拿回来的结果直接用结构化数据返回还支持把结果做一轮模型重排。说白了这就是“给 Agent 接上实时联网”的一个很顺手的方案。这篇文章把我从读文档到跑通、再到实际嵌入 Agent 工作流的完整过程都记录下来顺便把里面踩到的坑一并交代清楚。2. Web Search API 到底是啥一个被低估的搜索入口2.1 一句话理解它的定位Cloudflare 本身是做全球网络基础设施的它的优势从来不是“搜得多准”而是“在世界各地的边缘节点上有极低延迟的响应能力”。Web Search API 就是基于这套基础设施做的搜索接口让你不用自己搭搜索组件直接调 API 就能拿到一组网页结果。它的返回结果跟你在搜索引擎页面上看到的东西类似包含标题、URL、描述这些结构化字段。区别在于它是给程序用的不是给浏览器用的。在 Agent 场景里这就意味着你的大模型应用可以随时发一个查询拿到一组链接和摘要然后再决定下一步怎么做。整个过程可以完全自动化不需要人肉眼去看页面。2.2 我关心的其实是那两个不同的调用模式Cloudflare 这个 Web Search API 分两个层级一个叫 Web Search一个叫 Web Search Preview。官方文档写得很简短但我实测之后发现差别非常大这个必须单独拎出来说。Web Search是完整版。你给它一个查询它先执行搜索然后把原始结果丢给配套的模型做一轮重排和提炼最终返回的是一份经过模型处理过的、更结构化的答案。它天然适合“Agent 需要自己理解搜索内容”的场景。Web Search Preview则是轻量版。它只做搜索不做模型重排返回原始网页标题和摘要列表。响应更快成本更低适合那些只需要拿到链接列表、后续自己处理结果的场景。我当时看到这个区分就觉得很合理因为这正好对应了 Agent 开发中的两种典型需求——有的 Agent 希望直接拿到答案有的 Agent 更希望拿到材料自己做判断。2.3 为什么我不建议自己写爬虫可能有人会问我直接写个脚本抓搜索引擎结果不就行了何必多此一举我在早期项目里确实这么干过后来放弃了原因有三条。第一条是稳定性。搜索页面的 HTML 结构三天两头就变你的解析规则刚调好就失效了每周得花大量时间去修复。第二条是反爬。搜索引擎对自动化抓取有严格的频率限制到了某个阈值你的 IP 就会被临时限制整个流程直接瘫痪。第三条是结构。你自己抓回来的 HTML 是一堆乱七八糟的标签和脚本要从中提取出干净的标题、时间、正文清洗成本非常可观。专业的搜索 API 直接把这些脏活干完了返回给你的是结构清晰的 JSON。顺带说一句很多搜索 API 返回的数据本身就附带排名信号比如来源域名权重、结果匹配度这些信号能直接帮助 Agent 判断该优先信任哪一条结果。3. 开通与鉴权实战从创建账号到发出第一个请求3.1 准备阶段最容易忽略的东西要先说一个非常容易踩的坑Cloudflare Web Search API 并不是单独的一个控制台入口它属于 Cloudflare 的开发者平台服务。你需要在控制台里进入 Workers AI 相关的功能区找到 Web Search 服务确认你的账号已经绑定了支付方式。这一步很多人忽略导致后面调用时碰到各种摸不着头脑的报错。当然实际操作中以你控制台里能看到的服务列表为准。我最初犯的错就是以为开完账号就能直接调 API结果把 curl 命令发出去之后收到一条莫名其妙的错误排查半天才发现是服务没激活。这个放在后面踩坑部分详细说。3.2 创建 API Token 的权限细节鉴权方式是标准的 API Token。在控制台的“My Profile → API Tokens”里创建但这里有大学问——创建时选择的权限模板会直接影响你能调什么接口。我一开始图省事直接选了一个全局权限模板结果安全上心里不踏实。后来调整成只给 Workers AI 相关权限调用一切正常。这里我的建议是权限范围能收多窄就收多窄只勾选你实际要用的服务权限。Token 泄漏不可怕可怕的是泄漏的 Token 拥有全量权限。创建完成后Cloudflare 会给你一次机会把 Token 完整复制下来之后就不再显示了。务必立刻存到安全的地方推荐放到你服务器环境变量里别硬编码到代码里。3.3 一个最小可运行的调用示例下面这个 Python 示例是我跑通之后精简出来的直接复制就能用。请求的核心是一个 POST目标地址是你的账号 ID 加上对应的服务路径鉴权头带Authorization: Bearer 你的TOKEN。import requests ACCOUNT_ID 你的账号ID API_TOKEN 你的API_TOKEN url fhttps://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/cf/cloudflare/... # 具体的服务路径以官方文档为准 headers { Authorization: fBearer {API_TOKEN}, Content-Type: application/json, } payload { query: Cloudflare Web Search API price, max_results: 5, } resp requests.post(url, headersheaders, jsonpayload) data resp.json() print(data[result][results] if resp.status_code 200 else data)注意上面代码里我故意把服务路径省略了一部分。原因很简单这类服务的具体调用路径和参数格式迭代比较快我实测用的路径跟官方文档过一阵子可能对不上。你真正动手的时候以 Cloudflare 官方文档里列出的 URL 为准重点理解这个调用模式。如果你不想先装 Python 环境用 curl 验证更快curl -X POST \ https://api.cloudflare.com/client/v4/accounts/你的账号ID/ai/run/服务路径 \ -H Authorization: Bearer 你的TOKEN \ -H Content-Type: application/json \ --data {query:latest AI agent frameworks,max_results:5}返回 JSON 里有一组结果每个结果包含标题、链接、描述和来源信息。从这个结构开始你的 Agent 就已经具备联网感知能力了。4. 参数拆解与结果处理真正的分水岭在这里4.1 query 怎么写结果质量差一个档次很多人以为 query 就是把用户的问题原样丢进去。我实测下来发现这是结果质量最大的分水岭。搜索引擎对自然语言的解析能力其实一般。你问“我想知道最近AI大模型的价格”搜索引擎优先匹配的是“AI”“大模型”“价格”这些词但网页返回顺序未必符合你的真实意图。相反你把 query 改造成几个精准关键词比如AI 大模型 API 定价 2026效果会好非常多。这种差异在中文搜索里尤其明显因为中文分词机制对长句的理解本身就有损耗。我的做法是在 Agent 里内置一个 query 改写环节模型把用户的自然语言问题先改写成一个适合搜索引擎的关键词组合再拿去搜索。这一步多消耗一点 token但换来的是结果质量的巨大提升。4.2 领域与语言偏向别忘了返回结果的本地化这是我在实测中发现的另一个细节。Web Search API 的参数里可以设置地域和语言偏好但实际测试下来如果你不主动控制返回结果的本地化程度会很不稳定。举个我实际遇到的情况不带任何地域参数搜索“附近电动车充电桩政策”返回的结果里有不少英文页面明显是面向国际用户的。但对于中国用户来说本地政策信息才是真正有用的。这时候需要在请求参数里加上对应的地域和语言限定结果列表会立刻变成以中文来源为主的页面。我的建议是在调用 API 之前先判断用户问题的语言再根据语言设置对应的地域偏好和结果语言。这本质上是一个很简单的映射逻辑但对体验的提升是肉眼可见的。4.3 返回内容的基本结构哪些字段真正有用Web Search API 返回的数据结构里字段比你想的要多但核心就几个。我平时只关注 4 个标题用于展示和快速判断内容主题。URL用于做深入页面抓取如果后续还需要读取全文的话。描述/摘要这是 Agent 做答案生成的主要材料节省了大量网页读取成本。来源信息包括来源站点本身的信息可用于判断可信度。特别提醒一点描述字段并不一定完整覆盖网页的全部内容。搜索引擎截取的摘要有时候只展示了网页某个角落的片段但这已经够用了。更关键的是你不需要为每一个结果都打开网页抓取全文摘要足够应对大部分问题这也是搜索 API 省成本的核心原因。对于需要读取全文的场景比如深度研究类 Agent正确的顺序是先用 Web Search 找到候选 URL再用自己的页面抓取模块选择性抓取排名前几的页面。不要一上来就全量抓取那样成本和延迟会爆掉。4.4 结果排序与截断策略把“相关”变成“有用”拿到返回结果之后我强烈建议不要直接全量塞给大模型。理由是搜索 API 返回的结果按常规相关性排序但相关性不等于可用性。有些结果标题看着相关实则是三年前的旧闻有些结果摘要内容互相重复还有些结果来源明显是低质量内容农场。我的实测策略是三层过滤第一层时间过滤。如果查询涉及时效性内容比如新闻事件、政策变化、价格信息优先保留摘要中带近期时间表述的结果。第二层去重。多个 URL 指向同一来源或摘要内容高度相似时只保留一个。第三层来源质量。对来源做白名单/黑名单判断比如我个人会偏好官方站点、权威媒体对纯 SEO 聚合站打低分。这三层过滤用代码实现并不复杂。但效果非常直接——丢给大模型的内容变干净了生成答案时的幻觉率大幅下降。5. 把搜索能力真正嵌进 Agent 工作流实践与取舍5.1 关键决策什么时候触发搜索接入 API 只是第一步真正难的是搞清 Agent 在什么情况下需要搜索。如果你让 Agent 每轮对话都先搜索一把延迟和成本都受不了。但如果完全依赖模型内部知识那搜索能力又等于白接。我这里用的策略是意图判断具体来说就是让模型自己决定要不要搜索。在系统提示词里预设一条指令要求模型判断用户问题是否存在以下情形之一涉及实时信息、涉及训练截止日期之后的事件、涉及具体的价格或参数、涉及用户没有明确给出上下文的公共事件。满足任意一条就调用搜索工具否则直接回答。这套逻辑实现起来其实就是给模型一个搜索工具然后依赖函数调用机制来触发。实测下来触发准确率能达到七八成剩下两成多是因为模型把一些明明可以用内部知识回答的问题也拿去搜索了属于过度搜索。但过度搜索的代价比不搜索少得多至少答案不会编造。5.2 Prompt 注入别把搜索材料随便糊上去拿到搜索结果之后把它们直接往里一塞就完事这是我见过最多人犯的错。搜索结果是一堆碎片信息可能来自不同立场、不同时间、不同质量的来源。如果你直接把这一堆东西原样塞进模型上下文模型的输出会变得非常不稳定甚至会因为相互矛盾的搜索摘要而给出摇摆不定的答案。我的做法是为搜索结果设置一个专门的上下文区域用清晰的分隔标记并给每条结果编上序号和来源标签。然后在提示词里告诉模型以下内容来自实时搜索结果你应当优先参考带编号的内容并在回答中标注信息来源序号。贴一下我用的提示词片段以下是实时搜索结果每个条目以 [R1]、[R2] 等编号开头。 回答以下问题时请仅依据这些检索结果提供的信息同时在文末列出你引用的编号。 如果检索结果中没有你需要的信息请明确回答“搜索结果未覆盖该信息”不要自行推测。这个设计有两个直接红利第一模型的回答可溯源用户能点开链接验证信任度显著提升第二当搜索结果与模型内部知识冲突时模型有明确指令优先采纳检索结果而不是凭借内部记忆硬撑。5.3 缓存与降本每次都搜索是最愚蠢的做法我一度天真地以为反正按次计费多搜几次无所谓。后来拿到账单才发现高频调用场景下搜索成本累积起来相当夸张。于是我开始做结果缓存。具体思路是对于同一用户的重复问题哪怕是不同话术表达先在本地存一份查询到结果的映射。如果命中缓存并且缓存时间没有过期一般设 10 到 30 分钟就直接返回缓存结果不再调用 API。只有缓存缺失时才走实时搜索。这个策略对两类 Agent 特别有效一类是客服机器人用户反复问的是同样几个问题另一类是资讯聚合类 Agent同一时段内多条会话问的几乎都是同一个热点事件。加一层缓存之后搜索 API 的调用量大概能砍掉一半以上。5.4 多轮对话里的上下文衔接多轮对话场景比单轮要复杂一些因为用户的后续问题往往省略了上下文。比如用户先问“帮我查一下最近发布的 AI 手机”你搜了一轮接着用户问“那这款的续航怎么样”如果你直接拿这句话去搜索搜索引擎根本不知道“这款”指的是哪款手机。所以我在多轮架构里做了一个很关键的处理每轮搜索之前先把对话历史里最近几轮的信息压缩成一段“搜索上下文”加到 query 前面。比如上面这个例子实际发出去的 query 是“最近发布的 AI 手机 X1 续航表现”而不是“续航怎么样”。这个办法没有增加任何额外的 API 调用只是把 Prompt 组装逻辑改了一下但效果立竿见影。对话类 Agent 在此之后很少再出现因为缺少上下文而搜出一堆无关结果的状况。6. 实测踩坑记录这些问题官方文档不会告诉你6.1 首次直接调用被 403服务激活问题我的第一个踩坑经历是 403 报错。那时候我刚创建完 Token兴致勃勃地复制了 curl 命令准备跑第一个请求结果返回 403 Forbidden。我当时第一反应是 Token 权限不够去控制台重新生成好几遍 Token权限一路加到全量问题依旧。后来才发现问题根本不在 Token而是 Web Search 服务在我的账号下没有正式激活——API 地址已经存在但服务并没有在账号层面开通自然拒绝请求。这个问题的排查看起来费时间实际上就是去控制台把对应服务启用一下、绑定账户即可。如果你碰到类似 403别急着怀疑 Token先检查服务本身的状态。6.2 限流与 429别等到被卡死了才看文档另一个高频问题是 429 限流。免费额度阶段调用频率比较高的话很快会触发限流。官方约定俗成是按账号维度计算调用频率超出后返回 429。我的处理方式是做两层防护。第一层是客户端限流在代码里控制每分钟的调用总量宁可排队也不要突发请求。第二层是重试退避捕获 429 响应之后不做即时重试而是等待若干秒后再试最多重试三次。如果还是 429就让 Agent 告诉用户“当前搜索服务繁忙请稍后再试”而不是无限重试导致雪上加霜。另外限流也受你当前账号套餐影响。免费档和付费档的额度上限完全不同建议在正式上线前先确认自己账号档位的配额数字合理评估调用量。6.3 返回结果的时效陷阱搜索到了不等于新闻是新的这是我用下来觉得最值得警惕的坑。Web Search API 返回的结果排序主要看相关性不保证时效性。搜索一个最近刚发生的事件时返回列表里可能混入大量几周甚至几个月前的内容而且它们在列表中的排位还不低。排查完我发现原因也不难理解网页的发布时间并不总是显式标记在摘要里搜索引擎只能靠页面内容和 URL 特征去推断推断错了排位自然就不对。应对办法是在结果处理阶段做一层时间判断从摘要文本中提取时间描述“昨日”、“本周”、“2026 年 1 月”等措辞或 URL 上带的日期再结合结果的来源分类给出一个时间置信分过滤掉明显不满足时效要求的结果。这个办法不能 100% 命中但能把时效性错误率降低一个量级。6.4 摘要内容被噪声污染来自 SEO 站的“伪相关”结果这个坑对接入效果影响最大。搜索“为什么我的服务器总是断连”返回结果里经常混进来一批 SEO 聚合站标题看着很对症点进去却是一堆工具广告和无关内容堆砌摘要也是东拼西凑的。我还发现一个规律这类低质结果往往集中出现在某些特定域名后缀和特定站点结构上因为它们批量生产页面、批量被搜索引擎收录自然容易占据结果位置。长期使用之后可以慢慢积累一个黑名单域名列表在前置过滤阶段直接剔除。黑名单的好处不只是过滤低质结果还能显著降低下游摘要生成的噪声干扰。Agent 不用再花力气辨别哪条摘要能信哪条不能信回答内容的稳定性和可读性都会跟着上升。6.5 成本预估免费额度耗尽之后到底贵不贵如果只是自己写个小项目玩免费额度完全够用但要上线服务成本预估就得摆到桌面上。Cloudflare 的 Web Search API 计费是按照每次搜索以及重排所用的模型资源分别算的实际成本跟你的调用量强相关。我的估算经验是一个中等体量的 Agent 应用每天大概几千次搜索请求月成本基本在可接受的范围内比商业搜索服务便宜很多。但如果你把“每轮对话都搜索”当成默认行为成本会快速膨胀。这也是我在第 5 章强调缓存和搜索触发策略的原因——用得好成本是可控的用不好隐形成本很容易超出预期。7. 一点个人总结折腾完 Cloudflare Web Search API、把它暂时接入自己的模拟项目之后我最大的感受是实时联网搜索这件事已经从一个“加分项”变成了 Agent 方案的“必有项”。但这篇文章写到最后我更想表达的是API 本身永远只是工具真正的价值在你怎么设计搜索触发机制、怎么清洗结果、怎么构造 Prompt 上下文。同样的 API有人接出来是高级玩具有人接出来是可落地产品差距全在这些细节里。给还没动手的读者一句实在话别追求一步到位也别一上来就搞复杂的 RAG 流程。先打通 API拿到一批真实搜索数据观察结果质量再从简单的函数调用开始接入 Agent。等你跑通了第一条链路后面的事情会水到渠成。