通义深度搜索-生成对话
产品链接面向深度的查询问答和调研分析需求场景,多步骤推理规划研究路径,生成有洞察、可溯源、图文并茂的长文报告-大模型服务平台百炼(Model Studio)-阿里云帮助中心
本产品（通义深度搜索）对外服务接口目录。所有接口使用 DashScope HTTP 协议对外提供服务。
基于智能体应用管理提供的 agent_id 与 agent_version 信息，提供场景化对话、研究、写作相关能力。
请求语法
POST /deep-search-agent/chat/completions HTTP/1.1请求参数
参数名类型是否必须说明streambool是必须填 true，当前版本仅支持流式响应。若提供false或不提供，请求将失败inputobject是输入字段input.request_idstr否请求ID（业务自定义）input.messagesarray是对话消息input.messages.[].rolestr是角色，枚举值为：user、assistantinput.messages.[].contentstr是生成内容parametersobject是配置参数字段parameters.agent_optionsobject是智能体专用参数parameters.agent_options.agent_idstring是应用IDparameters.agent_options.agent_versionstring是应用版本parameters.agent_options.session_filesarray否动态文件 ID 列表，文件 ID 的获取参考文件上传文档，最大支持传入10个文件ID返回参数
参数名类型是否必须说明request_idstr是请求ID（dashscope 平台）codestr是状态码（成功：200）messagestr是状态信息outputobject是输出字段output.request_idstr否请求ID（业务自定义）output.choicesarray是模型输出信息output.choices.[].finish_reasonstr是生成结束原因，仅尾包输出stopoutput.choices.[].messageobject是对话消息output.choices.[].message.rolestr是角色，枚举值为：user、assistant、tooloutput.choices.[].message.contentstr | array是生成内容/工具返回内容，当生成配置开启输出报告时，报告消息体类型为arrayoutput.choices.[].message.reasoning_contentstr否思考内容，如果 content内没有内容，则尝试获取最后一轮深度思考中的reasoning_content内容output.choices.[].message.tool_callsarray否工具调用信息output.choices.[].message.tool_calls.argumentsdcit否工具调用参数output.choices.[].message.tool_calls.namestr否工具调用名称output.choices.[].message.additional_kwargs.extra_jsonAny否工具调用返回时，携带结构化输出信息output.choices.[].message.extradict否步骤状态信息output.choices.[].message.extra.groupstr否执行阶段output.choices.[].message.extra.step_changestr否步骤变化事件output.choices.[].message.extra.stepstr否当前步骤output.choices.[].message.response_metadatadict否请求模型调用详细信息output.usageobject否用量统计output.usage.input_tokensint否输入 tokensoutput.usage.output_tokensint否输出 tokensoutput.usage.total_tokensint否总 tokens计划枚举
执行阶段（**group**）描述说明planning计划中对应plan模型，即系统处于任务规划阶段，该阶段包含 start 和 end 事件generating生成中表示为写作模型，表示系统正处于报告生成阶段，此阶段不区分详细事件变化，无 start/end 事件；step 状态仅包括 thinking 和 generating，且不会调用工具。当前步骤（**step**）描述和说明planning计划中thinking思考中reporting总结中（法律场景特有）generating生成中tool_calling工具调用中tool_calling_工具调用中，附带工具名称
[*]由于模型原因 step_change 值可能为不存在，请尽可能使用持久化的标志step
[*]空包情况下 step、step_change、group 字段的值可能不存在
[*]plan、think、generation 均由 xxx_start 事件 和 xxx_end 事件两个事件组成
[*]tool_call 由 tool_call_start、tool_calling、tool_return 三个事件组成
[*]tool_call_start 表示工具调用开始（开始流式收集工具调用信息，此时还无法吐出工具调用详情（name、args等））、tool_calling 表示获取到完整工具调用的参数并会抛出完整的工具调用参数tool_return 表示工具调用返回结果，同时会携带结构化的工具返回信息。
步骤变化事件 (**step_change**)事件发生时 **step** 的值事件名称解释说明plan_startplanning开始规划step 状态变为 planning, 表示对应状态的开头（包含当前包）。plan_endplanning结束规划step 开始变成其他状态，事件发生时 step 仍为 planning，表示对应状态的结尾（包含当前包）。think_startthinking开始思考与 plan 事件同理think_endthinking结束思考与 plan 事件同理report_startreporting开始总结与 plan 事件同理report_endreporting结束总结与 plan 事件同理generation_startgenerating开始生成与 plan 事件同理generation_endgenerating结束生成与 plan 事件同理tool_call_starttool_calling开始工具调用表示工具调用开始（开始流式收集工具调用信息，此时还无法吐出工具调用详情（name、arguments等））。tool_callingtool_calling_{工具名称}工具调用中会输出tool_call的具体参数和工具名称，tool_calling状态变为tool_calling_{工具名称}。tool_returntool_calling_{工具名称}工具返回会携带工具返回信息， step 开始变成其他状态，事件发生时 step 仍为 tool_calling_{工具名称}。示例
请求示例
{
"input": {
"messages": [
{
"role": "user",
"content": "现在日期"
}
]
},
"parameters": {
"agent_options": {
"agent_id": "aid-xxx",
"agent_version": "beta"
}
}
}返回示例
data: {
"code": "200",
"message": "",
"output": {
"choices": [{
"finish_reason": "",
"message": {
"content": "",
"additional_kwargs": {},
"response_metadata": {},
"tool_calls": [],
"reasoning_content": "",
"role": "assistant",
"extra": {
"group": "planning",
"step_change": "think_start",
"step": "thinking"
}
}
}]
},
"usage": null,
"request_id": "5b853312-8d0c-42ff-9d26-08339d5ff38e"
}当生成配置开启输出报告时，模型尾包会给出 html 和 md 的存储地址和路径，content 中 type 的含义参考如下
[*]file_path：文件存储路径用于后续导出pdf和二次获取以下文件下载链接
[*]md_file_url：md下载链接
[*]html_file_url：html下载链接
{
"status_code": 200,
"code": "",
"message": "",
"output": {
"choices": [
{
"finish_reason": "stop",
"message": {
"content": [
{
"type": "file_path",
"text": "msearch/agents/files/upload/536fa835-a381-4870-99c1-79dee3ab946c"
},
{
"type": "md_file_url",
"text": "https://msearch-cloud.oss-cn-hangzhou.aliyuncs.com/msearch/agents/files/upload/536fa835-a381-4870-99c1-79dee3ab946c.md?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-date=20250904T151053Z&x-oss-expires=900&x-oss-credential=LTAI5tCLjk1ruCfq2caq****%2F20250904%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=9f9af4642f3611b1b8210bd801f10610236656a016e6bda67e2239ecf59b644f"
},
{
"type": "html_file_url",
"text": "https://msearch-cloud.oss-cn-hangzhou.aliyuncs.com/msearch/agents/files/upload/536fa835-a381-4870-99c1-79dee3ab946c.html?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-date=20250904T151053Z&x-oss-expires=900&x-oss-credential=LTAI5tCLjk1ruCfq2caq****%2F20250904%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=34164425671a0f26a39adacd12735d9ec127aec8caa68f8e1de6e252f5889a9c"
}
],
"additional_kwargs": {},
"response_metadata": {
"model_name": "deep-research-generation",
"agent_name": "writing_agent"
},
"tool_calls": [],
"reasoning_content": "",
"role": "assistant"
}
}
]
},
"usage": null,
"request_id": "3070fa78-c5d5-4bad-b2fc-e20787f6eb75"
}调用示例
Python示例:
# coding=utf-8
import os
import json
import requests
split_line = "\n-------------------------------------生成报告链接---------------------------------------------------\n"
chat_completions_url = 'https://dashscope.aliyuncs.com/api/v2/apps/deep-search-agent/chat/completions'
headers = {
'Authorization': f'Bearer {os.getenv("DASHSCOPE_API_KEY", "")}',# 配置 API KEY
'Content-Type': 'application/json'
}
if __name__ == "__main__":
params = {
"input": {
"messages": [{"role": "user", "content": "目前国内主流多模态模型分别有哪些，根据性能和效果做下评估"}]# 传入请求消息
},
"parameters": {
"agent_options": {# 设置 agent 选项
"agent_id": "${agent_id}",# 应用ID，可在应用管理页面获取到，例如：aid-8fd***e00
"agent_version": "${agent_version}"# 应用版本，beta 测试版本 / release 发布版本
}
},
"stream": True
}
response = requests.post(chat_completions_url, headers=headers, json=params, stream=True)
resultlist = []
stage = ''
action = ''
content = ''
reasoning_content = ''
for chunk in response.iter_lines():
if chunk:
chunk_str = chunk.decode('utf-8').strip()
if chunk_str.startswith('data:'):
json_str = chunk_str.strip()
try:
obj = json.loads(json_str)
# 检查异常
if obj.get('code') != '200':
print("服务异常：", obj)
# 获取消息体
msg = obj.get('output', {}).get('choices', [{}]).get('message', {})
extra_flags = msg.get('extra', {})# 获取模型状态标记字段
if stage != extra_flags.get('group', ''):# 获取 模型当前阶段
print(f"agent stage: {extra_flags.get('group', '')}")
stage = extra_flags.get('group', '')
if action != extra_flags.get('step', '') and extra_flags.get('step', ''):# 获取 模型当前阶段
print(f"agent action: {extra_flags.get('step', '')}")
action = extra_flags.get('step', '')
role = msg.get('role', '')# 获取模型角色 assistant or role
content = msg.get('content')# 获取生成内容
toolcalls = msg.get('tool_calls', [])# 获取工具调用
if toolcalls:
print(f'{toolcalls}')
if not content:# 如果 content内没有内容，则尝试获取最后一轮深度思考中的reasoning_content内容
content = msg.get('reasoning_content', '')
if isinstance(content, str):
if role == "tool":
print("\n" + content + "\n", end='')# 前后都换行
else:
print(content, end='')# 流式输出
else:
# 注意 content 可能不是字符串
print(split_line, content)
# 可按需保存
resultlist.append(obj)
except Exception as e:
print("异常解析:", e)java示例:
import java.io.*;
import java.net.*;
import java.util.*;
import com.alibaba.fastjson.*;
import java.nio.charset.StandardCharsets;
public class DeepSearchStreamDemo {
// 配置 API KEY
public final static String CHAT_COMPLETIONS_URL = "https://dashscope.aliyuncs.com/api/v2/apps/deep-search-agent/chat/completions";
public final static String API_KEY = System.getenv("DASHSCOPE_API_KEY");
public static void main(String[] args) throws Exception {
// 构造参数
Map<String, Object> params = new HashMap<>();
// input.messages
List<Map<String, Object>> messages = new ArrayList<>();
Map<String, Object> msgObj = new HashMap<>();
msgObj.put("role", "user");
msgObj.put("content", "${prompt}");
messages.add(msgObj);
// input
Map<String, Object> input = new HashMap<>();
input.put("messages", messages);
// parameters.agent_options
Map<String, Object> agentOptions = new HashMap<>(); //
agentOptions.put("agent_id", "${agent_id}");// 应用ID，可在应用管理页面获取到，例如：aid-8fd***e00
agentOptions.put("agent_version", "${agent_version}"); // 应用版本，beta 测试版本 / release 发布版本
// parameters
Map<String, Object> parameters = new HashMap<>();
parameters.put("agent_options", agentOptions);
params.put("input", input);
params.put("parameters", parameters);
params.put("stream", true);
String body = JSON.toJSONString(params);
// HTTP 请求
URL apiUrl = new URL(CHAT_COMPLETIONS_URL);
HttpURLConnection conn = (HttpURLConnection) apiUrl.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Authorization", "Bearer " + API_KEY);
conn.setRequestProperty("Content-Type", "application/json");
// 发送 body
try (OutputStream os = conn.getOutputStream()) {
os.write(body.getBytes(StandardCharsets.UTF_8));
}
// 处理流式响应
InputStream inputStream = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8));
String line;
String stage = "";
String action = "";
List<JSONObject> resultList = new ArrayList<>();
while ((line = reader.readLine()) != null) {
if (!line.trim().isEmpty()) {
String chunkStr = line.trim();
if (chunkStr.startsWith("data:")) {
String jsonStr = chunkStr.substring(5).trim();
try {
JSONObject obj = JSON.parseObject(jsonStr);
// 检查异常
if (!"200".equals(obj.getString("code"))) {
System.out.print("服务异常: " + obj);
}
// 获取output->choices->message
JSONObject msg = null;
if (obj.containsKey("output")) {
JSONObject output = obj.getJSONObject("output");
if (output != null && output.containsKey("choices")) {
JSONArray choices = output.getJSONArray("choices");
if (choices != null && !choices.isEmpty()) {
JSONObject firstChoice = choices.getJSONObject(0);
if (firstChoice.containsKey("message")) {
msg = firstChoice.getJSONObject("message");
}
}
}
}
if (msg == null) {
continue;
}
// 获取 extra_flags 字段
JSONObject extraFlags = msg.containsKey("extra") && msg.get("extra") != null
? msg.getJSONObject("extra") : new JSONObject();
// agent stage
String stageNew = extraFlags.containsKey("group") && extraFlags.get("group") != null
? extraFlags.getString("group") : "";
if (!stage.equals(stageNew)) {
System.out.println("agent stage: " + stageNew);
}
stage = stageNew;
// agent action
String actionNew = extraFlags.containsKey("step") && extraFlags.get("step") != null
? extraFlags.getString("step") : "";
if (!action.equals(actionNew) && !actionNew.isEmpty()) {
System.out.println("agent action: " + actionNew);
}
action = actionNew;
String role = msg.containsKey("role") && msg.get("role") != null
? msg.getString("role") : "";
Object contentObj = msg.get("content");
String content = null;
boolean isContentString = false;
// content 是字符串类型
if (contentObj instanceof String) {
content = contentObj.toString();
isContentString = true;
}
// 字符串为空时补 reasoning_content
if (isContentString && content.isEmpty()) {
Object reasoningContentObj = msg.get("reasoning_content");
if (reasoningContentObj instanceof String) {
content = reasoningContentObj.toString();
}
}
// 工具调用
if (msg.containsKey("tool_calls") && msg.get("tool_calls") instanceof List) {
JSONArray toolCalls = msg.getJSONArray("tool_calls");
if (!toolCalls.isEmpty()) {
System.out.println(toolCalls);
}
}
// -------输出内容判断--------
if (isContentString) {
// 是字符串，无论空不空都直接打印（和Python一致）
if ("tool".equals(role)) {
System.out.print("\n" + content + "\n");
} else {
System.out.print(content);
}
} else {
// 不是字符串（比如Object/Array）时打印分隔线，再打印内容
System.out.println("\n------------------------------------------------------------------生成报告链接------------------------------------------------------------------");
System.out.println(contentObj != null ? contentObj.toString() : "null");
}
// ------end----
// 可按需保存
resultList.add(obj);
} catch (Exception e) {
System.out.println("异常解析: " + e);
}
}
}
}
reader.close();
}
}点击下方访问产品链接：
面向深度的查询问答和调研分析需求场景,多步骤推理规划研究路径,生成有洞察、可溯源、图文并茂的长文报告-大模型服务平台百炼(Model Studio)-阿里云帮助中心
欢迎加入讨论钉钉群，在这里您可以与其他用户进行深入交流，分享使用经验或获取更多技术支持，群号102415041551。
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！
页:
[1]