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

）

deepresearch

AI Skill Market Insights

Be Part of the 0+ Developer Community

DeepResearch Agent API 调用指南

核心流程（5步）

SSE 流解析要点

流结束信号（满足任一即可停止读取）

关键事件识别

interrupt_id 提取（注意嵌套JSON）

HTTP 客户端注意事项

参数获取规则

api_key

agent_id

base_url

query（研究问题）

参考文件

脚本使用方式

通过环境变量提供鉴权参数

Quick Start

Manual Installation

TEAR & SHARE

Tags

获取微博热搜榜数据，返回热搜标题、热度值和跳转链接。当用户需要查看微博热搜、微博热点、微博热榜时使用此技能。支持自定义获取条数（默认50条）。

Github Trending

Scholar

qmd Local Search

Google Trends

Channels

Learn

Compare

Company