DeepResearch

DeepResearch 是 WebAgent 的定型 API 之一。你给一个 topic，它做多轮检索、交叉核对，产出一份带引用和置信度的 Markdown 研究报告。

和 DoAnything 不同：DoAnything 产物形态不定，agent 自己决定返回什么；DeepResearch 产物形态固定——永远是研究报告，因此能给字段稳定的结果契约（final_md + citations + confidence）。知道自己要的就是一份报告时，走这个 API。

什么时候用

• 你要的产物明确是一份研究报告，而不是一个开放任务的结果。
• 你需要引用可追溯、覆盖面可衡量，而不只是一段摘要。
• 任务允许跑几分钟到几十分钟——DeepResearch 是长程任务。

需要的是「查一批关键词、拿结构化命中」而不是成文报告时，用 WebSearch。需要的是开放任务时，用 DoAnything。

跑一次 research

HTTP 端点：

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

请求字段：

字段	类型	必填	说明
topic	string	是	研究主题
depth	string	否	light / standard / deep——决定检索轮数和成本。默认 standard
output_format	string	否	报告形态。默认 report
target_audience	string	否	报告写给谁看，影响行文深浅
require_outline_approval	bool	否	true 时在大纲阶段停下等你批准，见下文。默认 true
max_duration_minutes	int	否	时长兜底
domain_whitelist / domain_blacklist	string[]	否	限定 / 排除检索域名
callback_url	string	否	终态时回调的 URL

完整 schema 见 OpenAPI spec 的 CreateResearchRequest。

示例：

from web_agent.v1 import Client

async with Client(api_key="wa_...", project_id="proj_demo") as client:
    run = await client.deep_research.run(
        topic="2026 年开源向量数据库格局",
        depth="standard",
        require_outline_approval=False,
    )
    print(run["run_id"], run["status"])

阶段（phase）

一个 research run 会依次走过这些 phase，status 仍是 running 时 phase 告诉你跑到哪了：

phase	含义
brief	解析 topic，确定研究目标
plan	规划检索路径
hitl_outline	大纲就绪，等你批准（仅 require_outline_approval=true 时出现）
gather	多轮检索、抽取来源
crosscheck	跨来源交叉核对
synthesize	成稿，附引用和置信度

大纲审批（人在回路）

require_outline_approval=true 时，run 跑到 hitl_outline 阶段会停下，等你确认大纲再继续。这样可以在花掉检索成本之前先纠正方向。

run = await client.deep_research.run(topic="...", require_outline_approval=True)
# run 停在 hitl_outline，通过 intervene 批准或调整大纲
await client.deep_research.intervene(run["run_id"], response={"approved": True})

不需要这一步时设 require_outline_approval=False，run 会一路跑到终态。

结果

run 进入终态后，result 字段（ResearchResultPayload）包含：

字段	说明
final_md	研究报告正文，Markdown
final_artifact_id	报告作为 artifact 的 id，可用 artifacts 端点取原文件
citations_count	引用数量
confidence_summary	置信度概要
partial_sections	未完成时已产出的章节

取 artifact：

artifacts = await client.deep_research.list_artifacts(run["run_id"])
blob = await client.deep_research.get_artifact(run["run_id"], artifacts[0]["id"])

异步与长程

DeepResearch 默认同步，但 deep 档可能跑很久。需要不阻塞时用异步模式，订阅事件流跟进：

run = await client.deep_research.run_async(topic="...", depth="deep")

async for event in client.deep_research.events.stream(run["run_id"]):
    print(event.type, event.data)

事件流端点 …/deep_research/runs/{run_id}/events 走 SSE 约定：带数字 id，断线后用 Last-Event-ID 续传。

其它生命周期操作：cancel（取消）、feedback（对结果打分）、send_followup（在已有报告上追加要求）、refine（按反馈重跑）。

接下来

• WebSearch —— 不要成文报告、只要结构化命中时走这个
• DoAnything —— 开放任务用 DoAnything
• 计费与额度 —— depth 怎么影响成本
• API 概览 —— 共享约定；字段全集见 OpenAPI spec