Keenable Web Search API：面向AI Agent的搜索接口接入实践

这两年做 AI Agent 的开发者几乎都会在“联网搜索”这个环节补课。模型再强训练数据也有截止日期推理再完整回答一个实时事件也容易一本正经地胡说。于是大家开始给 Agent 接搜索能力有人用爬虫自己抓网页有人接传统搜索引擎的 API有人干脆把任意搜索结果塞进提示词。结果发现问题往往不是“搜不到”而是“搜到了但模型不会用”。Keenable 就是在这个背景下出现的一个 Web Search API 项目。它在 Hacker News 上的标题写得很有意思A different web search API for AI agents。我理解这句话的潜台词是市面上大多数搜索接口是为“人在浏览器里阅读”设计的而不是为“模型在推理链路里消费”设计的。Keenable 想做的是把搜索结果的形态、结构和语义从“给人看”切换成“给 Agent 用”。这篇文章不是 Keenable 官方文档的翻译而是从 Agent 工程角度梳理为什么 Agent 需要一套不一样的搜索 API、这类 API 的通用能力是什么、如何用最快的方式把它接入一个可运行的 Agent 循环以及在生产环境里会遇到哪些坑。看完之后你至少可以完成两件事一是对“Agent 搜索”的选型有一个相对清晰的判断二是手里多一份可以直接改着用的接入代码。1. 为什么 AI Agent 需要一套“不一样”的 Web Search API1.1 模型的两大通病知识截止与事实幻觉先说一个所有 Agent 开发者都绕不开的底层矛盾大语言模型的参数里保存的是“训练时刻的知识”它没有实时感知世界的能力。你问它“今天北京天气如何”“某开源项目本周发了什么版本”“某 API 的最新定价是多少”它要么用自己的旧知识猜测要么诚实地说不知道。更麻烦的是很多模型在被追问时会编造一个“看起来合理”的答案这就是幻觉hallucination问题的来源。解决这个问题的标准方法之一就是引入外部信息检索把搜索结果作为上下文交给模型。这也是 RAGRetrieval-Augmented Generation检索增强生成和 Agent 工具调用中最核心的链路。这里真正的技术难点在于搜索结果的质量直接决定了大模型回答的质量。如果检索到的是无关页面模型就会基于噪声给出错误答案如果检索到的内容格式混乱模型需要花大量上下文去理解和清洗反而降低了推理效率。这也是“联网搜索”这件事在 Agent 时代被反复提及的原因。但这里有一个经常被忽略的细节搜索这个动作在人类使用场景和机器使用场景里诉求完全不同。人在搜索引擎里搜索时期望得到的是“一个可点击的网页列表”自己会判断哪个链接靠谱然后点进去阅读。Agent 不行Agent 的“阅读”成本极高——它每读一个网页都要消耗 token、时间和一次工具调用。如果搜索结果返回一堆包含导航、广告、脚本、CSS 的 HTMLAgent 根本消化不了或者逻辑直接被噪声带偏。1.2 传统搜索 API 与 Agent 的“错配”现在开发者能用的搜索方案并不少可以直接调传统搜索引擎的开放接口也可以抓取 HTML 后自己解析还可以用各种商业搜索 API。问题是这些方案大多默认服务的对象是人。传统搜索结果返回的字段通常围绕“页面”设计标题、URL、摘要、发布时间、站点名。这些信息对人有意义但对模型来说噪声太高。真正需要的是“网页里哪句话回答了当前问题”“这段内容的权威性如何”“原文里有哪些关键实体和数值”。如果这些信息让 Agent 自己去网页里提取一次搜索任务的延迟和 token 消耗都会翻倍而且解析失败的概率非常高。更麻烦的是不同网站的 HTML 结构完全不一样今天能解析的规则明天站点改版就会失效。这也是很多自建爬虫方案在小规模时能用、一旦上线就频繁出问题的主要原因。另一个错配在接口形态。Agent 调用工具时希望 API 是确定性的、结构化的、低延迟的而且错误信息要足够清晰。传统搜索接口往往是为了流量和广告场景设计的它不会考虑“这个结果能不能直接被模型作为推理依据使用”也不会对结果做针对事实问答的排序。这就要求出现一类“面向 Agent 的搜索 API”它们重新设计请求参数和响应结构把搜索结果压缩成模型友好的上下文甚至在服务端就完成内容抽取、去噪、去重和相关性排序。1.3 判断搜索 API 的竞争重心已经从“召回”转向“可消费性”如果只看表面很多人会以为搜索 API 的比拼重点是“能不能搜到更多网页”。其实在 Agent 场景里搜索结果的“可消费性”比召回率更决定体验。所谓可消费性包括三层含义第一结果结构容易被模型解析字段语义清晰第二内容噪声低模型不需要二次清洗第三单次搜索返回的信息量与 token 成本的比值高。Keenable 把自己定位成“a different web search API”我理解它强调的“不同”重点不是“结果更多”而是“结果更符合 Agent 的消费方式”。这不是一个简单的产品文案差异而是工程体系的重构从索引设计、排序目标、到响应字段都需要围绕“机器阅读”来重新设计。实际上Tavily、Brave Search API 等产品也都在做类似的事情Keenable 属于同一赛道里的新选手。这个赛道之所以突然热闹起来恰恰是因为 Agent 从 demo 走向生产环境后真实需求被放大了。2. Keenable 是什么面向 AI Agent 的 Web Search API 定位与能力拆解2.1 项目定位从“网页搜索”到“模型搜索”从项目标题和公开信息来看Keenable 是一个面向 AI Agent 的 Web Search API核心使用场景是让 Agent 在运行过程中按需获取实时信息并把这些信息转换成自己能直接理解的输入。它解决的问题是传统搜索与 Agent 工具调用之间的“语义鸿沟”。你可以把它理解为“一个知道如何和模型对话的搜索引擎”你给它一个 query它还给你一组已经整理好、可以被放进提示词的搜索结果。为什么说“语义鸿沟”是这个项目要解决的核心问题因为搜索 API 和模型之间本质上是两个系统在对话。搜索系统按网页索引组织信息模型按 token 序列理解语义。中间缺少一层“翻译”把网页级的信息转换成“问题-答案-证据”式的结构化内容。Keenable 这类产品想做的就是这层翻译。它不是简单的代理转发而是对搜索结果的再加工。2.2 一个合格的 Agent 搜索 API 应该具备哪些能力虽然我们看不到 Keenable 官方文档的全部细节具体参数和字段以官方文档为准但从这类产品的基本设计出发可以整理出一份评估清单。一个面向 Agent 的搜索 API至少有五个能力维度值得关注结构化响应响应 JSON 设计成模型容易解析的层级包含 query、results 以及片段、来源、时间等字段而不是返回一堆 HTML。内容净化在服务端去除广告、导航、脚本等噪声返回可读正文或摘要避免模型在无关信息上浪费上下文。相关性优先排序算法偏向“回答当前问题”而不是“点击最大化”。面向人的搜索会把吸引点击的标题排在前面面向 Agent 的搜索应该把能回答问题的片段排在前面。低延迟与轻量单次搜索目标控制在几百毫秒到一两秒响应体控制在几 KB避免把整个网页塞给调用方。与 Agent 生态兼容返回格式方便接入工具调用tool / function calling流程也能被 Claude Code、Codex、自研 Agent 框架等当作搜索工具使用。这五个维度其实也回答了“为什么不能直接用免费公开接口顶替”的问题。免费接口通常不稳定也没有为 Agent 优化结果结构而自建爬虫又要处理反爬、解析、容错、IP 池一系列问题。对大多数团队来说用一款专门的 Agent 搜索 API是在开发速度和结果质量之间最平衡的起点。2.3 Keenable 与传统搜索 API 的本质区别用一句话概括传统搜索 API 返回“网页”Keenable 这类 API 返回“答案素材”。对 Agent 来说“网页”是中间产物还要花步骤去理解“答案素材”则可以直接参与推理。另外一个区别在“深度”上传统搜索往往只给摘要如果摘要没覆盖到答案Agent 就得再访问原始页面面向 Agent 的搜索 API 通常会提供摘要加正文片段必要时还能返回关键实体、时间戳、引用来源。这个差别直接决定了 Agent 是“一次搜索就能回答”还是“搜索→抓取→解析→重试”循环。后者的体验有多差做过生产级 Agent 的人都有体会一次任务可能因为一次网页解析失败整个链路就断了。所以面向 Agent 的搜索 API 真正的价值不在“搜索”本身而在“把搜索变成稳定的基础设施”。3. 搜索方案选型Keenable 与自建爬虫、传统搜索 API 的对比3.1 几种常见实现方式的对比为了帮你建立选型判断这里把 Agent 接搜索的几种常见方案放在一起对比。注意表格里的“面向 Agent 的搜索 API”一栏既包括 Keenable也包括 Tavily 等同赛道产品。方案优点缺点适合场景自建爬虫requests BeautifulSoup成本低、可控反爬严、易封 IP、解析成本高固定小规模站点传统搜索引擎开放 API稳定、覆盖广字段偏人类阅读、噪声大、价格随量上涨对结构化要求不高的场景面向 Agent 的搜索 APIKeenable 等结构化、低噪声、为模型设计生态新、文档和稳定性需评估Agent / RAG 核心链路模型自带联网搜索接入最简单封闭、难以自定义、可观测性差快速原型验证从工程角度看这里没有“唯一正确答案”。如果你只是想验证一个 Demo用模型自带的联网搜索最快如果你要面向用户提供稳定的 Agent 服务那就需要一个可控、可观测、可以限流和降级的搜索层。Keenable 这样专门为 Agent 设计的 API适合放在 Agent 核心链路里作为工具调用的一环而不是随便接一下就不管了。3.2 什么情况下建议用 Keenable 这类 API我给出的判断是当你的 Agent 需要频繁地基于实时信息做决策并且对回答质量和稳定性的要求高于对成本敏感度时值得优先考虑。典型场景包括客服机器人需要查询最新政策研究助理需要聚合近期新闻代码助手需要查找最新文档和 issue自动化脚本需要追踪竞品动态。这类场景有一个共同点搜索结果的形态直接影响下游逻辑。搜索结果返回得好Agent 一次推理就能给出答案返回得差Agent 就要陷入“反复搜索、反复尝试”的低效循环。对这类场景来说搜索 API 不再是可有可无的辅助而是决定产品体验的核心组件。3.3 什么情况下不建议也提醒一句如果团队已经有成熟的搜索基础设施并且有专门人力维护爬虫和内容解析流水线自建方案在长期成本上可能更低。另外如果你的 Agent 运行在完全隔离的内网环境根本接触不到公网搜索那任何 Web Search API 都不适用。选型时要把“数据是否允许出网”作为硬前提否则方案再先进也无法落地。还有一点需要注意外部搜索 API 会把你的查询词发送到服务端处理。如果业务涉及用户隐私数据、内部代码片段、未公开的商业信息你要先评估这层数据外发的合规风险再决定是否使用外部搜索服务。4. 快速接入 Keenable环境准备与基础调用4.1 准备 API Key 与环境接入一个搜索 API 的第一步就是获取 API Key。通常流程是注册账号、创建应用、生成一个带权限范围的密钥。这一步没什么技术含量但有两个习惯建议从一开始就养成第一密钥不要写进代码放在环境变量或本地 .env 文件里第二为不同环境开发、测试、生产准备不同的 Key方便隔离和审计。export KEENABLE_API_KEYyour_api_key_here export KEENABLE_BASE_URLhttps://your-keenable-api-endpoint.example这里要特别强调一下KEENABLE_BASE_URL。因为不同版本的接口域名、地区节点可能不同把 base URL 也配置成环境变量能让代码在迁移环境时不需要改动。很多人在接入初期把地址写死在代码里一旦服务商调整域名就要重新发布一次应用完全没有必要。4.2 基础请求curl 快速验证在写 Python 代码之前先用一个 curl 命令确认账号、Key 和网络链路都没有问题。下面是按常见 REST 搜索 API 惯例写的一个示例请求。注意不同的服务端点名和参数名会有差异本文示例统一采用 Search、SearchDepth、MaxResults 这类通行命名实际以你接入的服务文档为准但验证思路完全一致。curl -X POST ${KEENABLE_BASE_URL}/search \ -H Authorization: Bearer ${KEENABLE_API_KEY} \ -H Content-Type: application/json \ -d { query: 2025 AI agent framework comparison, max_results: 5, search_depth: standard }如果一切正常你会得到一个 JSON 响应里面通常包含 query、results 数组以及每条结果的标题、URL、摘要或正文片段等信息。如果返回 401说明 Key 有问题如果返回 400多半是请求参数不符合要求如果返回 402表示当前 Key 没有可用余额。这一步宁可慢一点也要先把它跑通否则后面写的所有代码都会在同一个坑里反复踩。4.3 看懂响应结构一个典型的 Agent 搜索响应大致长这样。字段命名按常见设计列示实际以官方返回为准{ query: 2025 AI agent framework comparison, results: [ { title: LangGraph vs CrewAI vs AutoGen in 2025, url: https://example.com/langgraph-vs-crewai, snippet: In 2025, LangGraph is preferred for stateful workflows, while CrewAI focuses on role-based collaboration., published_date: 2025-06-10 } ] }注意真正面向 Agent 的搜索 API 往往会在一开始就返回“摘要片段”或“直接答案”而不是让你逐个打开 URL。开发者需要做的只是把这些片段按统一格式拼进提示词。有些 API 还会返回相关性分数、内容类型news / blog / official docs等字段这些字段对 Agent 判断“该优先参考哪个链接”非常有帮助。5. Python 实战在 Agent 循环中接入 Keenable 搜索 API5.1 准备工作与依赖下面的实战用一个最小化的 Agent 循环来演示用户提问 → 判断需要联网 → 调用搜索 API → 把搜索结果改写成上下文 → 交给大模型生成最终回答。为了方便复现我们只依赖 requests 和一个 OpenAI 兼容的模型客户端。如果你的模型服务不是 OpenAI 兼容格式替换成你自己的 SDK 即可。DeepSeek、Kimi、Qwen 这些国内常用模型服务大多提供 OpenAI 兼容接口只需要把 OpenAI 客户端的 base_url 换成对应地址代码结构完全不用改。pip install requests openai python-dotenv本文示例在 Python 3.10 环境下编写。如果你使用旧版本把str | None这种类型注解改成普通写法即可不影响逻辑。5.2 封装一个可复用的搜索客户端先写一个简单的客户端类。不要小看这一步把 API Key、超时、重试、错误处理都封装在同一个地方后面接多个 Agent 时就不用在每个 Agent 里复制同样的逻辑。# 文件路径search_client.py import os import time import requests class KeenableSearchClient: Keenable 搜索 API 的极简客户端字段名以官方文档为准 def __init__( self, api_key: str | None None, base_url: str | None None, ): self.api_key api_key or os.environ.get(KEENABLE_API_KEY) if not self.api_key: raise ValueError(缺少 KEENABLE_API_KEY请检查环境变量) self.base_url base_url or os.environ.get( KEENABLE_BASE_URL, https://your-keenable-api-endpoint.example ) self.session requests.Session() def search(self, query: str, max_results: int 5, max_retries: int 3) - dict: url f{self.base_url}/search payload { query: query, max_results: max_results, search_depth: standard, } headers { Authorization: fBearer {self.api_key}, Content-Type: application/json, } for attempt in range(max_retries): try: response self.session.post( url, jsonpayload, headersheaders, timeout10 ) if response.status_code in (429, 500, 502, 503, 529): wait_time 2 ** attempt 0.5 * attempt time.sleep(wait_time) continue response.raise_for_status() return response.json() except requests.exceptions.RequestException as exc: if attempt max_retries - 1: raise RuntimeError(search failed after retries) from exc time.sleep(2 ** attempt) raise RuntimeError(search failed after retries)这段代码里真正值得关注的是对 429/5xx/529 的处理。529 通常表示服务端过载429 表示限流这两类错误都是临时的合理重试往往能解决问题但 401、403、402 这类错误是永久性的不应该盲目重试否则只会浪费请求次数和时间。判断“哪些错误值得重试”这是 Agent 工程里最基础也最容易被忽视的意识。5.3 构建一个最小化 Agent 循环接下来用一个非常简单的循环把“搜索 大模型”串起来。这个示例不会引入复杂框架目的是让你看清数据链路什么时候调用搜索、搜索结果如何进入提示词、最终答案如何生成。# 文件路径agent_demo.py import os from openai import OpenAI from search_client import KeenableSearchClient client OpenAI(api_keyos.environ.get(OPENAI_API_KEY)) search_client KeenableSearchClient() def build_context(query: str, results: list) - str: 把搜索结果改写成模型友好的上下文文本。 lines [] for idx, r in enumerate(results, start1): title r.get(title, 无标题) url r.get(url, ) snippet r.get(snippet, ) lines.append(f[{idx}] {title}\n来源: {url}\n内容: {snippet}\n) return f用户查询: {query}\n\n实时搜索结果如下:\n \n.join(lines) def ask_with_search(question: str) - str: # 1. 调用搜索 API search_resp search_client.search(question, max_results5) # 2. 把结果组装成上下文 context build_context(question, search_resp.get(results, [])) # 3. 让模型基于“用户问题 搜索上下文”生成回答 messages [ { role: system, content: ( 你是一个擅长使用实时信息的助手。请优先依据用户提供的搜索结果回答 不要编造搜索结果中没有的信息。如果信息不足请明确说明。