Skip to main content
Flow Agent API

新版智能体应用 API 参考

通过 DashScope API 调用阿里云百炼新版智能体应用的输入与输出参数

本文介绍 DashScope API 调用阿里云百炼新版智能体应用的输入与输出参数。

前置准备

开始前，请确保您已完成以下操作：
  1. 创建应用： 前往应用管理创建阿里云百炼新版智能体应用并获取应用 ID。
  2. 获取 API Key： 通过密钥管理获取并配置环境变量。
  3. 安装 SDK（可选）： 若使用 SDK 调用，请安装相应语言的 DashScope SDK。

调用方式

  • HTTP 接口调用 请求地址：POST https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion
    其中 APP_ID 需替换为您的实际应用 ID。
  • SDK 调用 Python/Java SDK 已默认配置正确的 endpoint，也可通过 base_url 参数自定义。
在线调试：通过应用卡片 -> 发布 -> API 调试路径进入调试页面后，填写参数并点击运行即可。

请求体

参数类型必选说明
app_idstring是应用标识。在应用管理的应用卡片上获取。Java SDK 中为 appId，HTTP 调用时放入 URL 中替换 APP_ID。
promptstring是用户的输入指令，用于指导应用生成回复。HTTP 调用时放入 input 对象中。
session_idstring否历史对话标识。传入时请求将自动携带云端存储的对话历史。该 ID 在连续 1 小时内无请求后自动失效。Java SDK 中为 setSessionId，HTTP 调用时放入 input 对象中。
workspacestring否业务空间标识。仅调用子业务空间的应用时需传递。HTTP 调用时指定 Header 中的 X-DashScope-WorkSpace。
streamboolean否是否以流式输出方式回复，默认 false。推荐设为 true。Java SDK 通过 streamCall 接口调用；HTTP 在 Header 中指定 X-DashScope-SSE 为 enable。
incremental_outputboolean否流式输出模式下是否开启增量输出，默认 false。推荐设为 true。Java SDK 中为 incrementalOutput，HTTP 调用时放入 parameters 对象中。
enable_thinkingboolean否切换深度思考模型的思考/非思考模式，默认 false。设为 true 时模型先输出思考过程再返回最终答案。Java SDK 中为 enableThinking，HTTP 调用时放入 parameters 对象中。
has_thoughtsboolean否是否输出模型思考过程，默认 false。设为 true 时可在 thoughts 字段中查看。Java SDK 中为 hasThoughts，HTTP 调用时放入 parameters 对象中。
image_listarray否图片列表。支持图像 URL 和 Data URL（Base64 编码）。应用内需选择视觉理解模型。Java SDK 中为 images，HTTP 调用时放入 input 对象中。
file_listarray否文件 URL 列表。Java SDK 中为 files，HTTP 调用时放入 input 对象中。
model_idstring否模型名称。通过此参数指定本次调用使用的模型。优先级高于控制台配置。Java SDK 中为 modelId，HTTP 调用时放入 parameters 对象中。
dialog_roundinteger否携带的上下文轮数。设置输入模型的最大历史对话轮数。Java SDK 中为 dialogRound，HTTP 调用时放入 parameters 对象中。
biz_paramsobject否应用自定义插件传递参数。Java SDK 中为 bizParams，HTTP 调用时放入 input 对象中。

biz_params 属性

参数类型说明
user_prompt_paramsobject自定义提示词变量参数信息。一个应用内的变量名不可重复，且上限 10 个。
user_defined_paramsobject自定义插件参数信息。键为插件的 TOOL_ID，值为该插件所需的参数对象。

代码示例

单轮对话

import os
from http import HTTPStatus
from dashscope import Application

response = Application.call(
    # 若没有配置环境变量，可用百炼API Key将下行替换为：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',  # 替换为实际的应用 ID
    prompt='你是谁？')

if response.status_code != HTTPStatus.OK:
    print(f'request_id={response.request_id}')
    print(f'code={response.status_code}')
    print(f'message={response.message}')
else:
    print(response.output.text)

多轮对话

多轮对话通过 session_id 维护会话上下文：
  1. 首次请求：无需传入 session_id，响应中会返回新生成的 session_id。
  2. 后续请求：携带上一次响应的 session_id 即可延续对话。
  3. 有效期：session_id 在最后一次请求后 1 小时内有效。
import os
from http import HTTPStatus
from dashscope import Application

def call_with_session():
    response = Application.call(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='APP_ID',
        prompt='你是谁？')

    if response.status_code != HTTPStatus.OK:
        print(f'request_id={response.request_id}')
        return response

    responseNext = Application.call(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        app_id='APP_ID',
        prompt='你有什么技能?',
        session_id=response.output.session_id)

    if responseNext.status_code != HTTPStatus.OK:
        print(f'request_id={responseNext.request_id}')
    else:
        print(f'{responseNext.output.text}\n session_id={responseNext.output.session_id}')

if __name__ == '__main__':
    call_with_session()

流式输出

import os
from http import HTTPStatus
from dashscope import Application

responses = Application.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',
    prompt='你是谁？',
    stream=True,
    incremental_output=True)

for response in responses:
    if response.status_code != HTTPStatus.OK:
        print(f'request_id={response.request_id}')
        print(f'code={response.status_code}')
        print(f'message={response.message}')
    else:
        print(f'{response.output.text}')

响应对象

参数类型说明
status_codestring返回的状态码。200 表示请求成功。Java SDK 不返回该参数，调用失败会抛出异常。
request_idstring本次调用的唯一标识符。Java SDK 返回参数为 requestId。
codestring错误码，调用成功时为空值。仅 Python SDK 返回。
messagestring错误详细信息，请求成功则忽略。仅 Python SDK 返回。
outputobject调用结果信息。
usageobject本次请求使用的数据信息。

output 属性

参数类型说明
textstring模型生成的回复内容。
finish_reasonstring完成原因。stop 为自然结束，null 为强制中断（达到最大长度限制或手动停止）。
session_idstring当前对话的唯一标识。在后续请求中传入可携带历史对话记录。
thoughtsarray将 has_thoughts 设为 True 时，可查看深度思考模型的思考过程。

thoughts 属性

参数类型说明
thoughtstring模型的思考过程。
action_typestring大模型返回的执行步骤类型，如 reasoning 表示深度思考模型的思考过程。
action_namestring执行的 action 名称，如思考过程。
actionstring执行的步骤。
action_input_streamstring入参的流式结果。
action_inputstring输入参数。

usage 属性

参数类型说明
modelsarray本次调用的模型信息。
models[].model_idstring本次应用调用到的模型 ID。
models[].input_tokensinteger用户输入文本转换成 Token 后的长度。
models[].output_tokensinteger模型生成回复转换为 Token 后的长度。

成功响应示例

{
    "status_code": 200,
    "request_id": "fdfc3182-bc9d-4b45-a287-cd83b13aca02",
    "code": "",
    "message": "",
    "output": {
        "text": "你好！我是千问，阿里巴巴集团旗下的超大规模语言模型。",
        "finish_reason": "stop",
        "session_id": "cbb2e26ac4cc4cc3b2d114e1f73c127e",
        "thoughts": null,
        "doc_references": null
    },
    "usage": {
        "models": [
            {
                "model_id": "qwen-plus-latest",
                "input_tokens": 142,
                "output_tokens": 296
            }
        ]
    }
}

异常响应示例

request_id=1d14958f-0498-91a3-9e15-be477971967b,
code=401,
message=Invalid API-key provided.

QPM 限制

单应用默认 QPM（每分钟请求数）为 15000。

错误码

如果调用失败并返回报错信息，请参阅错误码文档进行解决。
Managed Agent API
Flow Agent API
RAG API
Connector API
Memory API
框架集成
  • 框架