qianfan-deepresearch

---

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 解析：

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）