WebSearch

WebSearch 是 WebAgent 的定型 API 之一。你给一批查询，它跨搜索引擎取结果、去重、重排，可选地附摘要，返回结构化命中列表。

和 DeepResearch 不同：DeepResearch 产出成文报告，跑几分钟到几十分钟；WebSearch 产出结构化结果列表，默认同步阻塞、秒级返回。要的是「命中」而不是「报告」时走这个。

什么时候用

• 你要的是一批可程序处理的搜索结果（title / url / snippet），不是成文报告。
• 你想在一次调用里跑多个查询，并拿到跨引擎去重后的统一列表。
• 你需要秒级返回，能接受同步阻塞。

需要成文研究报告时用 DeepResearch。需要 agent 自己定检索路径、跨页操作时用 DoAnything。

跑一次搜索

HTTP 端点：

POST /v1/projects/{pid}/web_search/runs
Authorization: Bearer wa_...

请求字段：

字段	类型	必填	说明
queries	string[]	是	一批查询
engines	string[]	否	限定搜索引擎；不传 = 默认引擎集
max_results_per_query	int	否	每个查询最多取多少条；不传用服务端默认
rerank	bool	否	跨引擎结果统一重排
summarize	bool	否	为结果附摘要；开启会增加成本和耗时
freshness	string	否	限定结果时效
site_whitelist / site_blacklist	string[]	否	限定 / 排除站点
language	string	否	结果语言偏好
objective	string	否	检索意图说明，用于重排和摘要

完整 schema 见 OpenAPI spec 的 WebSearchRequest。

示例：

from web_agent.v1 import Client

async with Client(api_key="wa_...", project_id="proj_demo") as client:
    run = await client.web_search.run(
        queries=["best Python ORM 2026", "SQLAlchemy vs Tortoise"],
        max_results_per_query=10,
        rerank=True,
    )
    for hit in run["results"]["results"]:
        print(hit["final_rank"], hit["title"], hit["url"])

结果

run 的 results 字段（WebSearchResults）：

字段	说明
results	命中列表，每项是一个 SearchResultItem
total_unique_results	去重后的结果总数
is_summarized	是否附了摘要（summarize=true 时为真）
engine_answer	引擎直出的答案（部分引擎提供）

每个 SearchResultItem：

字段	说明
title / url	标题与链接
canonical_url	规范化后的 URL，去重以此为准
snippet	引擎返回的摘要片段
summary	WebAgent 生成的摘要（summarize=true 时有）
final_rank / original_rank	重排后 / 重排前的排名
source_engine	命中来自哪个引擎
source_query	命中对应哪条查询
dedup_count	这条结果被多少个引擎/查询命中——越高越可信

异步与续期

WebSearch 默认同步返回。查询量大或开了 summarize 时耗时变长，可订阅事件流跟进：

GET /v1/projects/{pid}/web_search/runs/{run_id}/events

事件流走 SSE 约定。其它操作：cancel（取消）、refine（按新意图重跑同一批查询）、send_followup（追加查询）。

接下来

• DeepResearch —— 要成文报告时走这个
• Track —— 要的是「持续监控某个查询的变化」
• API 概览 —— 共享约定；字段全集见 OpenAPI spec