Skip to main content
API目录

生成对话

基于智能体应用管理提供的 agent_id 与 agent_version 信息,提供场景化对话、研究、写作相关能力。

请求语法

POST /deep-search-agent/chat/completions HTTP/1.1

请求参数

参数名

类型

是否必须

说明

stream

bool

必须填 true当前版本仅支持流式响应。若提供false或不提供,请求将失败

input

object

输入字段

input.request_id

str

请求ID(业务自定义)

input.messages

array[object]

对话消息

input.messages.[].role

str

角色,枚举值为:userassistant

input.messages.[].content

str

生成内容

parameters

object

配置参数字段

parameters.agent_options

object

智能体专用参数

parameters.agent_options.agent_id

string

应用ID

parameters.agent_options.agent_version

string

应用版本

parameters.agent_options.session_files

array[string]

动态文件 ID 列表,文件 ID 的获取参考文件上传文档,最大支持传入10个文件ID

返回参数

参数名

类型

是否必须

说明

request_id

str

请求ID(dashscope 平台)

code

str

状态码(成功:200)

message

str

状态信息

output

object

输出字段

output.request_id

str

请求ID(业务自定义)

output.choices

array[object]

模型输出信息

output.choices.[].finish_reason

str

生成结束原因,仅尾包输出stop

output.choices.[].message

object

对话消息

output.choices.[].message.role

str

角色,枚举值为:userassistanttool

output.choices.[].message.content

str | array[object]

生成内容/工具返回内容,当生成配置开启输出报告时,报告消息体类型为array[object]

output.choices.[].message.reasoning_content

str

思考内容,如果 content内没有内容,则尝试获取最后一轮深度思考中的reasoning_content内容

output.choices.[].message.tool_calls

array[object]

工具调用信息

output.choices.[].message.tool_calls[0].arguments

dcit[str,object]

工具调用参数

output.choices.[].message.tool_calls[0].name

str

工具调用名称

output.choices.[].message.additional_kwargs.extra_json

Any

工具调用返回时,携带结构化输出信息

output.choices.[].message.extra

dict

步骤状态信息

output.choices.[].message.extra.group

str

执行阶段

output.choices.[].message.extra.step_change

str

步骤变化事件

output.choices.[].message.extra.step

str

当前步骤

output.choices.[].message.response_metadata

dict

请求模型调用详细信息

output.usage

object

用量统计

output.usage.input_tokens

int

输入 tokens

output.usage.output_tokens

int

输出 tokens

output.usage.total_tokens

int

总 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_start

planning

开始规划

step 状态变为 planning, 表示对应状态的开头(包含当前包)。

plan_end

planning

结束规划

step 开始变成其他状态,事件发生时 step 仍为 planning,表示对应状态的结尾(包含当前包)。

think_start

thinking

开始思考

plan 事件同理

think_end

thinking

结束思考

plan 事件同理

report_start

reporting

开始总结

plan 事件同理

report_end

reporting

结束总结

plan 事件同理

generation_start

generating

开始生成

plan 事件同理

generation_end

generating

结束生成

plan 事件同理

tool_call_start

tool_calling

开始工具调用

表示工具调用开始(开始流式收集工具调用信息,此时还无法吐出工具调用详情(name、arguments等))。

tool_calling

tool_calling_{工具名称}

工具调用中

会输出tool_call的具体参数和工具名称,tool_calling状态变为tool_calling_{工具名称}

tool_return

tool_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=YOUR_ACCESS_KEY_ID&x-oss-signature=YOUR_SIGNATURE"
            },
            {
              "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=YOUR_ACCESS_KEY_ID&x-oss-signature=YOUR_SIGNATURE"
            }
          ],
          "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"
}

调用示例

# 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[len('data:'):].strip()
                try:
                    obj = json.loads(json_str)
                    # 检查异常
                    if obj.get('code') != '200':
                        print("服务异常:", obj)
                    # 获取消息体
                    msg = obj.get('output', {}).get('choices', [{}])[0].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)
Managed Agents
数据连接
Skill
应用评测
应用广场
权限管理