WebSearch
WebSearch 是批量搜索 API。输入一个或多个查询，返回去重后的结构化搜索结果，供应用或 agent 直接消费。创建接口总是返回异步 run；Node SDK 的 wait() 负责等待终态，不能把它描述成 wait=true 的同步接口。本页先介绍它解决的问题和核心能力，再给出当前调用方式。
它解决什么问题
- agent 需要实时网页信息：模型训练数据有截止时间，固定知识库覆盖不了正在变化的事实。WebSearch 让应用把"查一下网上现在怎么说"变成一次结构化 API 调用。
- 自建搜索聚合成本高：多引擎调用、跨引擎去重、结果重排、摘要生成都由服务端完成，应用只处理结构化的
WebSearchResults。 - 一批问题一次提交：单个 run 支持 1–20 条查询，适合"同一主题多角度检索"的批处理形态，不必逐条排队。
- 检索范围要可控：
site_whitelist/site_blacklist限定或排除站点，freshness过滤时效，language与objective说明语言偏好和检索意图。
核心能力
| 能力 | 说明 |
|---|---|
| 批量查询 | 一次 run 提交 1–20 条查询 |
| 多引擎 | engines 指定搜索引擎，跨引擎结果统一返回 |
| 去重与重排 | 跨查询、跨引擎去重（total_unique_results），rerank 启用 LLM 重排 |
| 摘要 | summarize 为每条结果生成摘要 |
| 范围控制 | freshness、language、site_whitelist / site_blacklist、objective |
| 结构化结果 | 每条命中包含标题、URL、snippet 等字段，可直接程序消费 |
| 纯异步流水线 | 无人工交互事件，适合作为多步 agent 流程的取数环节 |
典型场景
- 围绕关键词批量检索公开信息，作为内容规划的输入（见 SEO 内容规划智能体）。
- 按候选对象逐个检索公开信号，汇总成结构化画像（见 销售线索智能体、招聘寻源智能体）。
什么时候用
- 需要的是结构化搜索命中列表，由应用侧自行加工和判断。
- 检索目标是公开网页，不需要登录或页面操作。
- 秒级到分钟级返回即可满足流程需要。
需要打开页面执行动作用 DoAnything；需要一份带引用的成稿报告用 DeepResearch；需要长期监控页面变化用 Track。
请求字段
http
POST /api/v1/projects/{pid}/web_search/runs
Authorization: Bearer wa_...
Content-Type: application/json| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
queries | string[] | 是 | 1–20 条查询 |
engines | string[] | 否 | 指定搜索引擎 |
max_results_per_query | int | 否 | 1–50，默认 10 |
rerank | bool | 否 | 是否启用 LLM 重排 |
summarize | bool | 否 | 是否为每条结果生成摘要 |
freshness | month / year | 否 | 时效过滤 |
language | string | 否 | 语言偏好 |
objective | string | 否 | 检索意图 |
site_whitelist / site_blacklist | string[] | 否 | 限定或排除域名 |
Node SDK
ts
const search = await qoni.webSearch.run({
token,
prompt: ["browser automation 2026", "agentic browser"],
maxResultsPerQuery: 5,
siteWhitelist: ["github.com"],
});
const result = await search.wait();
console.log(result.output);高层句柄支持 status()、events()、wait()、cancel() 和 attach()。不要使用不存在的 runAsync()、refine()、sendFollowup() 或 client.web_search.get()。
结果结构
output / results 对应 WebSearchResults：
results：命中列表，包含标题、URL、snippet 等字段。total_unique_results：去重后的结果数。is_summarized：是否生成了摘要。engine_answer：部分搜索引擎提供的答案摘要，可能为空。
dedup_count 只表示同一结果被多少查询或引擎命中，不代表事实一定正确。
事件与生命周期
http
GET /api/v1/projects/{pid}/web_search/runs/{run_id}
GET /api/v1/projects/{pid}/web_search/runs/{run_id}/events
POST /api/v1/projects/{pid}/web_search/runs/{run_id}/cancelWebSearch 不产生人工交互事件，也没有 messages/refine/follow-up 路径。需要继续追问时，新建一个 run。