Agent Search 不只是搜索 API：一套面向 AI Agent 的评估框架

判断一个 Agent Search 是否好用，不要先数它接了多少搜索引擎。先看它能否把查询、路由、失败、证据和成本变成 Agent 可以检查的契约。

普通搜索面向人：给出十个链接，人会自己改关键词、打开网页、排除广告，再决定答案是否可信。

Agent Search 面向循环。Agent 会连续发起查询、读取结果、修改计划，甚至把搜索结论交给下一个工具。如果搜索层把“上游失败”包装成“没有结果”，或者一次返回几十段没有来源的摘要，错误就会沿着整个任务继续传播。

因此，Agent Search 不是“搜索 API 加一个 MCP 外壳”。更准确的定义是：它是一套把检索过程转换成可执行、可约束、可追溯证据的接口。

Agent Search 和普通网页搜索有什么不同？

一个完整的 Agent 搜索回路至少包含七步：

1. 把任务目标改写成查询；
2. 选择语言、来源和时间范围；
3. 在预算内调用一个或多个检索来源；
4. 区分有效结果、低质量结果和上游失败；
5. 判断证据是否足够，是否需要升级到另一条检索路径；
6. 把来源、片段和限制压缩成模型能消费的证据包；
7. 保留执行记录，让调用方知道这次搜索实际发生了什么。

搜索 API 通常只负责第三步。Agent Search 的产品价值，主要出现在第三步前后的判断与边界。

七个评估维度

1. 查询契约是否明确？

先检查输入是否只接受一个 query 字符串，还是能表达语言、站点、结果数、时间范围和证据体积等约束。

更重要的是：系统不能支持某个过滤条件时，是否会明确拒绝？一个无法统一执行“最近 24 小时”的多源路由器，应该返回“不支持该过滤条件”，而不是悄悄忽略它并给出看似新鲜的结果。

2. 多源是否真的增加了独立证据？

“接入 16 个引擎”不是质量结论。多个适配器可能依赖同一个索引，十条结果也可能都在复述同一篇文章。

真正值得检查的是：

• 本次实际调用了哪些来源；
• 结果覆盖了多少个独立 provider family；
• 去重发生在 URL、标题还是语义层；
• 系统何时停止继续搜索。

多源的意义不是把更多链接塞进上下文，而是在有限调用内增加独立、可核验的证据。

3. 付费升级是否由策略控制？

配置 API Key 不应该等于默认授权付费流量。一个可控的 Agent Search 应该把“只用免费来源”“免费优先”“质量不足时升级”和“付费优先”分成明确策略。

这样，Agent 才能在任务价值、质量门槛和预算之间做选择，而不是把成本藏在重试和 fallback 里。

4. 失败是否保持可见？

这是最容易被忽略，也最影响 Agent 判断的一项。

至少要区分：

• 查询真的没有匹配结果；
• 某个来源超时或限流；
• 凭据或权限错误；
• 过滤条件不受支持；
• 抽取成功，但内容不足以支撑答案。

如果所有情况最后都变成空数组，Agent 无法判断应该换关键词、换来源、等待重试，还是停止回答。

5. 返回的是证据包，还是一段无法检查的答案？

对需要继续推理的 Agent，理想输出不是越长越好。一个有用的证据包应该保留标题、URL、相关片段、来源信息、失败信息和本次执行边界。

摘要可以帮助阅读，但不应该抹掉出处。完整正文也不应该无条件进入上下文。结果数量、完整结果数量、片段长度和总证据体积，都应该有独立预算。

6. 预算和停止条件是否可观察？

只限制“返回 10 条结果”还不够。检索过程还需要调用次数、总耗时、候选结果和证据体积的边界。

评估时要问：系统是达到质量门槛后提前停止，还是每次都扇出到所有来源？一次结果不足时，它为什么升级？这些决定有没有出现在响应元数据中？

7. 质量结论能否复现？

搜索结果会随时间、地区和上游网络变化。任何“更准”“更快”或“更省 Token”的结论，都应该同时说明：

• 版本、提交和运行日期；
• 查询集与中英文比例；
• 允许使用的来源；
• 网络环境、失败和重试策略；
• Tokenizer、统计口径和原始证据是否保留；
• 这项实验没有证明什么。

固定 fixture 可以验证格式与回归，但不能自动证明实时搜索质量。实时跑分可以反映一次环境，却不能直接变成长期 SLA。

一张可以直接使用的检查表

如果一个产品在这七项里只能回答“我们接了很多引擎”，它更像一个 provider 聚合器，还不是完整的 Agent Search。

用 Agent Search MCP 走一遍这套框架

我维护的 Agent Search MCP 就是围绕这些问题设计的一个开源实现。它不是这套框架的唯一答案，但可以作为一份可检查的样本。

截至 2026-08-07，仓库主分支的能力表列出 16 个适配器：9 个零密钥来源和 7 个可选 API Provider。稳定公开分发版本仍是 3.2.0。这两个事实需要分开看：主分支会继续演进，评估时应该锁定实际安装的版本，而不是把 README 的最新状态自动归到旧包上。

它目前提供这些可检查边界：

• free_only、free_first、quality_escalation 和 paid_first 分离免费路径与付费授权；
• 默认请求预算限制适配器尝试次数、总耗时和接纳的原始结果数；
• EVIDENCE_BUDGET_CHARS 单独限制整个响应中的查询相关证据；
• meta.execution 暴露路由决策，partialFailures 保留部分上游失败；
• 无法在多个通用来源间一致执行的 time_range 会返回 UNSUPPORTED_FILTER，而不是静默忽略；
• 搜索工具声明为只读、幂等，并支持精确结果缓存和可选的本地持久化。

仓库里的双语固定 fixture 报告：Normal 平均 2311.0 tokens，Compact 为 1655.8，相对减少 28.4%；Compact+ 为 1607.5，相对减少 30.4%。这只能证明固定结果上的格式和证据包行为，不能证明实时搜索更准、所有查询都节省同样比例，或上游永远可用。

搜索质量的评估管线也把 fixture 回归、实时 capture、盲化评审和公开质量声明分开。当前方法要求至少 30 个不同查询、完整 trace、双模型独立评审和第三方模型裁决，才可能进入公开质量结论；“管线已经实现”不等于“质量已经被证明”。

这也是我认为 Agent Search 最值得推广的地方：不是一个夸张的“免费替代所有搜索 API”口号，而是一套可以看到路由、成本、失败和证据边界的搜索路径。

十分钟怎么评估一个 Agent Search？

不要先跑排行榜。先做四类任务：

1. 普通事实查询：检查结果是否保留可打开的来源，以及执行元数据是否能解释停止原因。
2. 中文来源查询：检查它是否直接检索中文来源，而不是只翻译英文结果。
3. 时效约束查询：加入一个产品无法保证的过滤条件，确认它会明确拒绝，而不是伪装支持。
4. 故障与预算查询：限制来源或证据预算，检查部分失败是否可见，输出是否仍然可用。

然后再固定查询集，记录版本、时间、来源和原始 trace，比较 nDCG、Precision、Success、引用支持、延迟和失败披露。不要用一两个“看起来不错”的答案代替评估。

如果你想直接检查本文中的实现，可以先启动默认 MCP 路径：

$ pnpm dlx -y agent-search-mcp

再到 GitHub 查看 Agent Search MCP 的源代码、能力表和 benchmark 方法。如果你的核心问题是“它能否作为 Tavily 的免费优先替代路径”，可以继续阅读免费 Tavily 替代的边界与安装指南。

什么时候应该直接选择托管搜索 API？

如果你需要明确 SLA、厂商支持、专有索引、稳定的语义检索能力，或者不想负责运行时、缓存、日志和上游限流，托管 API 往往更合适。

自托管 Agent Search 的优势是控制权和可检查性，代价是你要负责部署与失败处理。两者不是非此即彼：一个好的路由层可以从免费来源开始，在质量门槛未满足时，再通过明确策略升级到商业 Provider。

结论

Agent Search 的核心不是“搜到更多”，而是让 Agent 知道：搜了什么、为什么停、哪里失败、证据来自哪里，以及这次搜索花了多少预算。

如果你正在为 Claude Code、Codex、Cursor 或自己的 Agent 增加网页搜索，先用本文的七项检查表评估接口，再决定是否采用某个产品。想从一个可运行的开源样本开始，可以查看 Agent Search MCP 产品页，或直接在 GitHub 审查实现。