面向AI Agent的搜索API：从选型到接入的完整指南

最近在关注 AI Agent 工具链的时候，看到 Show HN 上有个项目叫 Keenable，定位写得很直接：A different web search API for AI agents。简单说，它想做的不是又一个通用搜索接口，而是让搜索 API 返回的内容更适合 AI Agent 直接消费。不管你是搭 RAG、做实时问答、还是让 Agent 自己检索资料再写结论，这类接口都值得专门评估一轮。这里不替项目背书，只按实际接入和评估的顺序，拆一拆这类 API 该怎么看、怎么接、怎么排查。

1. AI Agent 用搜索 API，和普通用户搜索完全不同

1.1 通用搜索返回的原始结果，直接喂给 Agent 很费劲

传统 web search API 最初不是给 LLM 设计的。它面向的是网页聚合、站点监控、自定义搜索页，还有广告和流量分析这类场景。所以返回结构里经常带着大量展示字段、格式化信息、统计字段、品牌标识。这些东西做网页端渲染没问题，但塞进模型上下文就有问题。

上下文窗口是有限的。原始 JSON 越大，token 消耗越高，模型要处理的无关信息越多。Agent 真正需要的是“这个链接讲什么、发布时间是什么、有没有可直接引用的结论”，而不是把一套搜索引擎结果页原样丢给它。

还有一个更实际的问题。如果接口返回的摘要写得不干净，你就要在代码里再写一层解析逻辑。解析逻辑一多，边界情况就多了。今天这个字段为空，明天那个字段变成了嵌套对象，后天某个结果没有 URL。很多所谓“Agent 不稳定”，不是模型不行，是喂给模型的搜索数据本身就脏。

1.2 Keenable 这类“Agent 优先”接口想在哪些点上做差异

从项目标题看，Keenable 强调的 different，核心是“为 AI Agent 重新设计搜索 API”。按这个定位去理解，和通用搜索接口的差异一般会体现在几个方向：

• 响应结构更精简，字段直接对应模型使用场景，而不是展示场景。
• 结果更强调“可引用来源”，URL、发布时间、摘要这些字段要干净完整。
• 对实时性、时效性查询更友好，能表达“最近一周”“最近一天”这类条件。
• 更适合循环式调用，也就是 Agent 里常见的“搜索 → 抽取 → 生成 → 再搜索”闭环。

这里要说明一下，这些是基于标题和同类项目普遍做法的推测，不代表 Keenable 文档里一定有完全一样的特性。接入之前，一定要以实际返回的响应为唯一依据。先跑一次真实请求，看看字段是不是你要的样子，再决定要不要继续集成。

这个趋势本身是确定的：Agent 需要搜索，但 Agent 和普通用户对搜索结果的消费方式完全不同。普通用户看前三条链接就能判断要不要点进去，Agent 却需要在一个任务里多次搜索、组合多路结果、最后还要带着来源生成回答。所以搜索 API 不能只在参数上多加一个 model=agent 就算完。

2. 接入前，先判断这个搜索 API 适不适合自己的场景

2.1 只有这些场景才值得给 Agent 加实时搜索

不是所有 Agent 都需要实时搜索。很多人一看到“支持搜索”就觉得必须加，结果把响应速度拖慢了，成本变高了，答案反而被无关网页带偏。

适合用搜索 API 的场景，我一般归纳成四类：

• RAG 里做实时事实补充，比如模型知识截止时间之后的新信息、新版本、新政策。
• 让 Agent 自己查资料再写回答，比如竞品对比、新闻摘要、技术方案调研。
• 带引用来源的问答系统，用户要求每个结论都能点回原文。
• 定时信息监控，某个关键词出现新动态时触发通知或生成简报。

如果只是用模型训练好的知识回答固定问题，不需要实时搜索，那加搜索意义不大。先明确场景，再选接口。反过来选型，后面大概率要返工。

2.2 通用搜索 API、Agent 专用搜索 API、自建爬虫怎么选

不同方案在新手阶段看起来都能“搜到东西”，但落地差异很大。这里用表格把关键维度排一下：

学习 Demo 阶段用通用 API 完全没问题。但如果你要写一个循环搜索、连续追问、批量处理查询列表的 Agent，尽量选面向 Agent 的接口，或者至少确认通用 API 的返回结构能稳定清洗。这里不要只被“通用”两个字骗了，通用意味着你要自己处理的东西也多。

2.3 评估质量不要只看一条样例查询

很多项目演示都只挑一条能搜出漂亮结果的 query。这个不够。你想判断一个搜索 API 到底能不能用，至少换几类问题去测：

• 事实型问题，比如“某个软件最新版本是多少”。
• 时效型问题，比如“某个公司最近一个月发布了什么”。
• 长尾问题，生僻技术名词、冷门产品型号。
• 中英混合问题，关键词里带英文缩写、中文全称混着来。

每类问题看三件事：有没有结果、结果是不是当下的、摘要能不能直接回答问题。三条里有一条不行，就要慎重。尤其是长尾查询，最能暴露接口背后的索引覆盖范围。搜热门词谁都能行，搜冷门词才是分水岭。

3. 最小接入流程：把一次搜索变成 Agent 可用的上下文

3.1 环境准备和前置条件

搜索 API 类项目通常需要先有账号或者 API Key。Keenable 具体怎么申请、有没有免费额度，以项目文档为准。这里只说通用准备：

• 一个能发 HTTPS 请求的环境，本地脚本、后端服务、云函数都行。
• 准备好请求库，Python 用 requests 或 httpx，Node 用 axios 或 fetch。
• 确认查询参数文档，至少要知道查询关键词和其他必填参数。
• 把 API Key 放到环境变量里，不要写进代码仓库。

这里最容易忽略的是环境变量加载。很多人把 Key 写在脚本里，换一台机器就报 401，查半天才发现是配置没带过去。

3.2 单次搜索请求的通用结构

一次搜索请求通常包含几个核心部分：关键词、返回结果数量、语言和地区、时效窗口。不同服务商字段名可能不一样，这里给一个通用格式示例：

GET /search ?q=Keenable web search API &limit=5 &region=global &language=en &time_limit=month

对应的 curl 也类似：

curl -s "https://api.example.com/search?q=Keenable+web+search+API&limit=5" \ -H "Authorization: Bearer $KEY"

注意把 api.example.com 换成实际地址。第一次调试时不要加太多高级参数，先把 limit 设为 3 到 5，确认能返回 title、url、snippet 这几个核心字段。有些接口还支持返回正文片段、相关搜索词、站点过滤，这些等主流程通了再加。

3.3 结果交给 LLM 前，先做三步清洗

这一步很关键，直接跳过的话，后面 prompt 怎么调都别扭。

第一步，过滤无效条目。空摘要、空 URL、明显重复的条目直接丢掉。

第二步，统一字段。把不同来源返回的字段名整理成项目内部统一的 schema，这样以后换服务商不用改业务代码。建议在项目里先定义好 SearchResult 这个数据结构，至少包含 title、url、snippet、published_at。

第三步，拼接上下文。建议按这个顺序拼进 prompt：

1. 查询问题。
2. 每条结果的序号、标题、URL。
3. 每条结果的摘要，标注来源编号。
4. 要求模型优先使用带编号的来源回答。

给一个简单的 Python 示意：

def build_context(results): chunks = [] for i, r in enumerate(results, 1): chunks.append(f"[{i}] {r.title}\n{r.url}\n{r.snippet}") return "\n\n".join(chunks)

清洗后的上下文才应该进 prompt。原始结果先落盘或者打日志，方便后面排查。经常出现一种情况：Agent 回答内容差，你以为是大模型问题，结果回头一查，搜索接口返回的原始摘要就是乱的。

3.4 第一次接入成功怎么判断

成功的标准不是“接口返回了 JSON”，而是：

• 结果数量等于请求的 limit，或者达到服务商上限。
• 每条摘要都不是空壳，也没有重复页面。
• 对时间敏感的问题，日期信息满足要求。
• Agent 能引用对应来源生成回答，而不是把搜索词原样复述一遍。
• 从发请求到拿到结果，单次耗时可接受，常见应该从几百毫秒到几秒不等。

达到这些，再进入批量阶段。不要第一步就跑一千条查询，那样你很难分清是参数问题还是服务商限制。

4. 参数、成本和延迟：别只看“能返回结果”

4.1 一个 Agent 任务会消耗多次搜索，不是一次

很多人第一次做 Agent 加搜索时，觉得一次任务就是“搜一次、答一次”。实际复杂度比这高。

一个典型的研究型 Agent 任务可能是这样：

• 先做一次宽泛搜索，确定主题方向。
• 根据第一轮结果，拆成两个子问题，各搜一次。
• 对某个结果页面做内容抓取。
• 最后核对一个时效信息，再搜一次。

这一个任务就可能产生 4 到 6 次搜索请求。如果批量队列里有 100 个任务，请求量就是数百甚至上千次。所以评估成本时，不要只问“单次贵不贵”，要估算“一个完整任务平均多少次”。这也是为什么很多 Agent 方案会加一层缓存：同一个 query 在短时间内重复搜索，直接命中缓存，能省掉大量请求。

4.2 限流、超时和重试要提前设计

搜索 API 是外部依赖，不是本地库，一定会遇到限流、超时、服务抖动。不建议把外部请求的失败率和本地代码 bug 混在一起调。

我一般会按这个顺序做：

1. 先用单线程、并发 1 到 2 跑一个小样本，看成功率和延迟。
2. 记录 p50 和 p95 延迟，判断超时阈值设在哪里合适。
3. 遇到 429 或 5xx，写重试逻辑，退避时间递增，比如 1 秒、2 秒、4 秒。
4. 连续失败超过 3 次，标记该任务失败，不要无限重试。
5. 把请求 ID、参数、响应状态码全部落日志。

这里不要一上来就开最大并发。先看看单个并发下稳定不稳定，再往上加。很多搜索接口的限流是阶梯式的，你冲到某个阈值突然全挂，日志一片飘红，排查起来很痛苦。

4.3 返回条数不是越多越好

新手容易把 limit 设成 20，觉得搜得全。实际在 Agent 场景里，这不是越多越好。

结果多了，token 成本上升，模型更容易被无关结果带偏。而且搜索结果前面几条质量最高，越往后噪音越大。我的经验是：一般问答先试 5 条，内容聚合类任务再试 10 条。如果 5 条里都找不到答案，继续加到 10 条也很难救回来，更值得去做的是改查询词，而不是加结果数量。

5. 常见问题与排查链路

5.1 搜索质量差，先查查询词和地区语言参数

搜索质量差的表象很多：结果不相关、时间太旧、结果全是同一个站、摘要答非所问。遇到这些先别怀疑 API 能力，按顺序排查：

1. 查询词是不是太宽泛，比如只给一个名词，没有上下文。
2. 地区、语言参数是不是没设对，导致返回了大量错误地区的结果。
3. 时效参数是不是默认了最近一周或一年，和你的需求不匹配。
4. 返回条数是不是太少，3 条以下容易全是噪音。
5. 是否对摘要做了二次清洗，把原始返回和清洗后内容做对比。

多数情况下，问题出在第 1 和第 2 步，也就是查询构造和地区语言参数。这里有个很常见的坑：用户搜的是中文内容，但语言参数设成了英文，返回结果全是不相关的英文页面。先看参数，再动代码。

5.2 超时、空结果、限流的标准排查顺序

遇到这类问题，直接从现象判断会绕弯路。建议按下面这个检查表走：

排查的总体顺序是：先看现象，再看输入，再看环境，再看参数，最后才怀疑服务商。很多问题其实是路径、权限、依赖版本或者输入格式造成的，跟搜索 API 本身没有关系。

5.3 批量任务要提前处理输出命名和失败恢复

批量搜索结果很容易出现两个问题：所有输出写进同一个文件，分不清是哪条查询的结果；任务跑到一半失败，又要全部重跑。

更稳妥的做法是：

• 每条查询用一个唯一任务 ID，输出文件名带上任务 ID 和查询摘要。
• 原始响应和 processed 结果分开存，保留原始 JSON。
• 维护一个任务状态文件，标记 pending、done、failed。
• 重新运行时跳过 done，只处理 failed 和 pending。

这个设计和具体 API 无关，但任何批量场景都建议提前做。搜索 API 本身再稳定，网络服务也会有偶发问题。任务状态记录能帮你在失败后快速恢复，不用重新请求已经完成的 todo。批量跑得慢不可怕，跑完找不到结果才可怕。

6. 边界、替代方案和更长期的落地思路

6.1 什么时候不该自己从零写搜索

有些团队一看到“搜索 API”，就想着不如自己写爬虫，顺带建一个数据库。如果只是做一个 Agent 演示，或者内部工具，非常不建议走这条路。

自建爬虫意味着你要处理：网站反爬策略、页面结构变化、去重、分页、编码、robots 规则、存储、更新频率。每一项都可能消耗数周时间，而且会随着目标网站改版随时失效。对大多数 Agent 项目来说，用服务商提供的搜索 API 换取开发时间是划算的。

这就像你没必要为了给 Agent 加个邮件功能就自己写一个邮件服务器一样。用成熟的外部能力，把精力留在业务逻辑上。

6.2 什么时候需要换更重的混合方案

如果业务到了这些阶段，再继续只用搜索 API 可能不够：

• 需要某个垂直领域的结构化数据，比如商品价格、论文元数据、法律文书。
• 需要对同一批页面做深度抓取并建索引，而不只是读摘要。
• 对搜索响应延迟有极苛刻要求，需要自建缓存和预索引。
• 需要自定义排序规则，而不是服务商的默认相关性。

这时候可以考虑混合方案：搜索 API 负责发现入口，页面抓取服务负责拿正文，向量数据库负责二次检索。这是更工程化的做法，也是搜索 API 场景下更合理的延伸。搜索 API 不一定是最优方案，但通常是第一版最稳的起点。

6.3 几条用完一轮后的实操建议

• 先跑单条，再开并发。能跑通和能稳定跑是两件事。
• 原始返回一定留存。结果不好时，没有原始 JSON 就很难判断是 API 问题还是清洗问题。
• 字段统一越早做越好，换服务商时能省很多事。
• 不要追求一次搜索解决所有问题。Agent 的价值在于多轮迭代，搜一次不够就再搜一次。
• 如果连续调整查询词和参数仍然质量差，就换查询词本身，别硬调参数。

这类“Agent 专用搜索 API”项目会越来越多。评估它们的时候，最该关注的不是功能列表有多长，而是响应结构、限流策略、时效性、批量场景下的稳定性，能不能撑住实际任务。先看返回值长得像不像设计给模型用的，再谈接入。这条判断标准，在 Keenable 或者其他同类 API 上都适用。