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 结尾 — 报告已生成

关键事件识别

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

1. 从对话上下文中提取（用户曾提及或粘贴过）
2. 读取环境变量 BAIDU_API_KEY
3. 以上均无 → 询问用户：「请提供千帆 API Key（格式：bce-v3/ALTAK-...）」

agent_id

1. 从对话上下文中提取（用户曾提及或粘贴过）
2. 读取环境变量 QIANFAN_AGENT_ID
3. 以上均无 → 询问用户：「请提供深度研究 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）