DeepResearch Agent API 调用指南
核心流程（5步）
Step 1: 创建会话
POST /v2/agent/deepresearch/create?agent_id={agent_id}
Body: {}
→ 获得 conversation_id
Step 2: 发起初始查询
POST /v2/agent/deepresearch/run
Body: { query, agent_id, conversation_id }
→ 读取 SSE 流，判断下一阶段
Step 3: [可选] 处理需求澄清
判断依据: events 中出现 role=assistant + event.name="/chat/chat_agent"
处理方式: 发送 query="跳过" (不带 interrupt_id)
→ 读取 SSE 流，获取大纲
Step 4: 提取大纲数据
从 SSE 事件中提取：
- interrupt_id: status="interrupt" + event.name="/toolcall/interrupt" 中的 text.data (嵌套JSON)
- structured_outline: event.name="/toolcall/structured_outline" 中的 text.data (嵌套JSON)
Step 5: 确认大纲，生成报告
POST /v2/agent/deepresearch/run
Body: { query="确认", agent_id, conversation_id, interrupt_id, structured_outline }
→ 读取 SSE 流，收到 .html 文件事件后可提前退出
SSE 流解析要点
流结束信号（满足任一即可停止读取）
status == "interrupt"— 大纲/澄清阶段结束，等待用户响应event.is_end == true && event.is_stop == true— 整个流程结束content.type == "files"且 filename 以.html结尾 — 报告已生成
关键事件识别
| 阶段 | 识别字段 |
|---|---|
| 需求澄清 | role=assistant, event.name="/chat/chat_agent" |
| 大纲生成 | event.name="/toolcall/structured_outline", status=interrupt |
| 中断等待 | status="interrupt", event.name="/toolcall/interrupt" |
| 文件生成 | content.type="files", filename 以 .md 或 .html 结尾 |
interrupt_id 提取（注意嵌套JSON）
content.text 是 { "data": "<JSON字符串>" } 结构，需两次 JSON 解析：
raw = json.loads(content["text"]) # 得到 {"data": "..."}
interrupt_data = json.loads(raw["data"]) # 得到 {"interrupt_id": "...", ...}
interrupt_id = interrupt_data["interrupt_id"]
HTTP 客户端注意事项
- 禁止设置整体超时：SSE 是长连接，应使用空闲超时（推荐 10 分钟无数据则断开）
- 禁用 gzip 压缩：发送
Accept-Encoding: identity或不发该头，避免流式数据被压缩 - 禁用 HTTP/2：强制使用 HTTP/1.1，与 curl 默认行为一致
- Authorization 头格式：
Bearer {api_key}
参数获取规则
执行前必须确认以下参数已知：
api_key
- 从对话上下文中提取（用户曾提及或粘贴过）
- 读取环境变量
BAIDU_API_KEY - 以上均无 → 询问用户：「请提供千帆 API Key（格式：bce-v3/ALTAK-...）」
agent_id
- 从对话上下文中提取（用户曾提及或粘贴过）
- 读取环境变量
QIANFAN_AGENT_ID - 以上均无 → 询问用户：「请提供深度研究 Agent ID（在千帆控制台 → 我的 Agent 页面复制）」
base_url
- 固定使用默认值：
https://qianfan.baidubce.com/v2，无需用户提供，不读取任何配置。
query（研究问题）
- 来自用户的自然语言输入，直接使用用户描述的研究主题。
参考文件
- 可执行脚本:
scripts/deepresearch.py— 完整封装了5步调用流程，可直接运行 - API 接口文档: 参见 references/api.md（含完整请求/响应示例）
- 完整调用工作流: 参见 references/workflow.md（含 Python/Go 实现示例）
脚本使用方式
需要生成可运行代码时，优先基于 scripts/deepresearch.py 修改或直接调用，而非重新生成。
# 直接运行（参数通过命令行传入）
python3 scripts/deepresearch.py \
--query "研究小米汽车发展历程" \
--api-key "bce-v3/ALTAK-..." \
--agent-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# 通过环境变量提供鉴权参数
export BAIDU_API_KEY="bce-v3/ALTAK-..."
export QIANFAN_AGENT_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
python3 scripts/deepresearch.py --query "研究小米汽车发展历程"
依赖: 仅需标准库 + requests（pip install requests）