Deepresearch Conversation

---
name: deepresearch
description: >
  调用百度千帆深度研究（DeepResearch）Agent API，完成从发起研究到获取报告的完整多轮对话流程。
  当用户需要以下操作时触发本技能：
  (1) 调用 DeepResearch API 进行深度研究；
  (2) 实现 DeepResearch Agent 的多轮对话（创建会话→发起查询→处理澄清→确认大纲→获取报告）；
  (3) 解析 DeepResearch SSE 流式响应；
  (4) 对 DeepResearch API 进行压测或批量调用；
  (5) 集成深度研究能力到自己的应用中。
metadata: { "openclaw": { "emoji": "📌", "requires": { "bins": ["python3", "curl", "requests"], "env": ["BAIDU_API_KEY", "QIANFAN_AGENT_ID"] }, "primaryEnv": "BAIDU_API_KEY" } }
---

# 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 解析：
```python
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/api.md)（含完整请求/响应示例）
- **完整调用工作流**: 参见 [references/workflow.md](references/workflow.md)（含 Python/Go 实现示例）

## 脚本使用方式

需要生成可运行代码时，优先基于 `scripts/deepresearch.py` 修改或直接调用，而非重新生成。

```bash
# 直接运行（参数通过命令行传入）
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`）