brave search api 是什么

如果你在给 Agent 加联网搜索，多半搜到过 Brave Search API 这个名字，但点进去只有一堆产品名和文档链接，看不出它到底解决什么问题。这篇不讲虚的：先说清它在你那条链路里站在哪个位置，再给一套从零开始的接入准备清单和排查顺序，最后说清哪些场景其实不该用它，改用别的路子更省事。

如果你在给 Agent 加联网搜索，搜资料时多半刷到过 Brave Search API 这个名字。点进官网，满屏产品名和文档链接，看完还是不知道它到底替你把哪件事办了。这篇就干一件事：说清它在你那条链路里站在哪个位置，接之前要确认哪几件事，出问题时按什么顺序查。

先说结论方向：它本质上是一个「程序版的搜索引擎」，负责把外面的网页捞回来，至于捞回来之后怎么用、要不要给模型看、引用哪几条，全是你代码里的事。把它和聊天模型混为一谈，是接入阶段最常见的认知偏差。想横向比一下别的方案，可以到 /tools 里翻工具目录，先建立整体印象再决定要不要深挖。

一句话定位：它是一个「返回网页结果」的接口

你发一个查询词，它回一批网页条目，每条里通常带着标题、原始链接、一段摘要描述，还有域名、抓取时间之类的元信息。它不会给你一段写好的答案，也不会替你做推理。换句话说，它给你的是原材料，不是菜。

查询词

你发过去的那串很短的关键词或短语，不是用户的整句提问

结果条目

一条网页记录，一般包含标题、链接、摘要和元信息

摘要

一段被截断的描述文字，用来判断这条值不值得点进去，通常不够直接当答案

二次抓取

拿到链接后再去把正文抓下来，这一步不在搜索接口的职责范围内

还有个容易踩的坑：很多人以为调了搜索接口就等于 Agent 联网了。其实不是。接口只负责「找到」，不负责「读懂」和「说出来」。中间那段上下文拼接、筛选、引用编号，全是你的活。

为什么做 Agent 的人会盯上它，而不是自己爬

模型自己的知识有截止点，今天发生的事它不知道，联网就是把这段补上。这个道理大家都懂，真正让人纠结的是：既然要联网，为什么不自己写个爬虫？

• 自己爬要处理反爬、页面结构变化、编码解析、重复内容、失效链接，维护量随时间只增不减；
• 搜索接口把这些脏活挡在外面，你拿到的是结构化字段，代码里少写一大段解析逻辑；
• 单个站点抓取还能靠写死规则撑住，一旦覆盖范围扩大到「全网随便查」，自建基本不现实；
• 如果你只需要固定几个站点的内容，那直接抓那几个站更准更快，不必绕一层搜索接口；
• 要注意：接口能搜到的范围和网页版搜索并不完全一致，涉及具体覆盖度差异，到站内产品对照页面核对当时的说明。

所以判断逻辑很清楚：你的查询目标是开放的、会变的，就用接口；目标是固定的、你比搜索引擎更懂那几个站的，就自己抓。两者不冲突，很多 Agent 是「先查自己库，查不到再走外部搜索」。

一次请求大概会拿回什么

接口返回的是结构化数据，不是渲染好的网页。你要提前想清楚：哪些字段后面真的会用，哪些只是看着有用。字段映射这一步做早了，后面改起来会轻松很多。

• 网页标题：用来做初步相关性判断，也可能直接进上下文；
• 原始链接：二次抓取和引用标注都靠它；
• 摘要描述：长度有限，通常只够判断「这条值不值得点进去」；
• 站点域名：做来源筛选、去重、可信度分级时很关键；
• 抓取时间之类的元信息：判断内容新旧，做时间范围过滤时会用到。

有些接口形态还能单独拿新闻、图片、问答摘要等不同来源的结果。具体能调哪几类、各自字段长什么样，别凭印象记，到 /tools 的工具详情页对照当时的说明核对一遍更稳。

接之前先确认这 5 件事

这一步最容易被跳过。很多人拿到 Key 就开始写代码，结果跑到线上才发现额度、并发、条款都对不上。下面这五项，最好在写第一行代码之前问清楚。

1. 额度与超额行为问清楚有没有独立 Key、额度上限是多少、超额之后是直接拒绝还是降速。这决定你的重试逻辑怎么写。
2. 请求频率限制Agent 一轮对话可能触发好几次搜索，并发一上来容易撞墙。先确认限流规则，再设计你的调用节奏。
3. 结果的使用范围能不能商用、能不能缓存、缓存多久，条款里通常有说法。别默认可以缓存，这事踩坑的人不少。
4. 地区与语种参数有没有地区或语种偏好参数，中文查询和英文查询的结果质量差别可能不小，接之前各测几条。
5. 网络连通性要不要走海外网络，本地开发环境和线上环境分别测一次。别等上线才发现只有本地能通。

这五项里，前两项和你的代码结构直接相关，后三项属于合规和部署层面。真要排优先级，先解决网络连通性和额度行为，卡住的是能不能跑；条款和语种属于跑起来之后再优化的事。

串进 Agent 的典型链路怎么写

链路顺序大致固定：模型判断需不需要搜，生成查询词，调搜索接口，把结果塞回上下文，模型基于结果作答。听起来简单，真正决定效果的是中间两步的细节。

• 查询词别直接用用户原话，让模型改写成更短的检索式，命中率通常更高；
• 结果条数不要一把全塞进上下文，先按域名或摘要相关性筛一遍，再决定放哪几条；
• 给每条结果编上编号，让模型在回答里标注引用来源，后面核对会方便很多；
• 同一轮对话里如果搜了多次，注意去重，不同查询词可能命中同一个链接；
• 上下文里最好带上链接和时间，模型引用时才有东西可标。

有个细节值得单独说：很多人把原始搜索结果一股脑塞给模型，然后抱怨模型答得泛。问题往往不在模型，而在你给它的素材太杂。筛一轮再给，效果差别很明显。

搜索接口决定你能拿到什么，筛选和拼接决定模型能说好什么。

结果不好的时候，按这个顺序排查

「结果不准」是个很笼统的描述，直接归因到接口本身，十有八九会查错方向。下面这个顺序是从便宜到贵排的，前面几步不用改代码就能验证。

1. 先看查询词是不是太口语、太长、带了无关的修饰。换成关键词组合再试一次，这一步能排掉大半问题。
2. 再看是不是被拦了并发或额度被限制时，报错信息里一般能看出来。对照你的调用日志确认。
3. 然后看时间返回的条目是不是太旧。加上时间范围参数再跑一次，很多「答得不对」其实是「答得太旧」。
4. 最后才怀疑接口换一个完全不同的查询词交叉验证。别只拿一个失败案例下结论，样本不够会误判。
5. 建立自己的基线到 /tools/speed-test 量一下你自己的延迟和成功率，跑一段时间再看，别凭单次感觉判断要不要加备用通道。

什么情况下你不该用它

不是说它不好，而是有些场景用它会绕远路。判断标准还是那句：你要素材还是要结论，以及你的查询目标是开放还是封闭。

还有一种情况常被忽略：如果你的用户提问本身就带明确站点指向，比如「某官网上的公告」，那直接路由到该站抓取，比先搜一遍再筛更快也更稳。

上手清单：从零到跑通一遍

把上面这些收成一份能照着做的清单。每一项都有一个明确的完成标志，没到那一步就别往下走，不然出错时很难定位是哪一层的问题。

1. 跑通最裸的一次请求只发一个查询词，把返回的 JSON 打出来看。完成标志是你能肉眼读懂每个字段的含义。
2. 做字段映射把你要用的字段映射到自己的数据结构，确定哪些字段后面真的会被消费。
3. 加超时和重试搜索接口偶尔会慢一下，别让整个 Agent 卡死在一个请求上。完成标志是手动制造一次超时，验证能正常降级。
4. 写回归用例固定几个题目，改完代码重跑一遍，看结果有没有变差。这是防止改一处崩一处的唯一办法。
5. 记录调用次数和失败率跑一段时间再回看。完成标志是你手里有一份自己的数据，而不是靠感觉判断。

这份清单里的数字都不用记死。额度、延迟、成功率这些会随时间变，你该做的是养成「跑一段时间再回看」的习惯。至于各家接口当下的具体价格和参数对照，去站内页面看当时的数字更靠谱，别信任何写死的截图。