New Agent Application API Reference - 阿里云百炼 Agent Studio

This document describes the input and output parameters for invoking Alibaba Cloud Bailian’s new agent applications using the DashScope API.

Prerequisites

Before getting started, ensure you have completed the following steps:

Create an Application: Go to Application Management to create a new Bailian agent application and obtain its Application ID.
Obtain an API Key: Retrieve your API key via API Key Management, then configure it as an environment variable.
Install SDK (Optional): If using an SDK, install the corresponding DashScope SDK for your programming language.

Invocation Methods

HTTP API Call Endpoint: POST https://dashscope.aliyuncs.com/api/v1/apps/{APP_ID}/completion
Replace {APP_ID} with your actual Application ID.
SDK Call Python and Java SDKs are preconfigured with the correct endpoint by default. You may also customize it using the base_url parameter.

Online Debugging: Navigate to Application Card → Publish → API Debug, enter required parameters, and click Run to test.

Request Body

Parameter	Type	Required	Description
`app_id`	string	Yes	Application identifier. Obtain it from the application card in Application Management. In Java SDK, use `appId`; in HTTP calls, substitute it into the URL path where `{APP_ID}` appears.
`prompt`	string	Yes	User input instruction guiding the application to generate a response. In HTTP calls, include this inside the `input` object.
`session_id`	string	No	Session identifier for maintaining conversation history. When provided, the request automatically includes previously stored dialogue history from the cloud. This ID expires after 1 hour of inactivity. In Java SDK, set via `setSessionId`; in HTTP calls, include in the `input` object.
`workspace`	string	No	Business workspace identifier. Required only when calling applications deployed under a sub-workspace. In HTTP calls, specify via header `X-DashScope-WorkSpace`.
`stream`	boolean	No	Whether to enable streaming responses. Default: `false`. Recommended: `true`. In Java SDK, use `streamCall`; in HTTP, set header `X-DashScope-SSE` to `enable`.
`incremental_output`	boolean	No	Whether to enable incremental output in streaming mode. Default: `false`. Recommended: `true`. In Java SDK, use `incrementalOutput`; in HTTP, include in the `parameters` object.
`enable_thinking`	boolean	No	Toggle deep-thinking model between “thinking” and “non-thinking” modes. Default: `false`. When `true`, the model outputs its reasoning process before returning the final answer. In Java SDK, use `enableThinking`; in HTTP, include in the `parameters` object.
`has_thoughts`	boolean	No	Whether to return the model’s internal reasoning steps. Default: `false`. When `true`, reasoning is available in the `thoughts` field. In Java SDK, use `hasThoughts`; in HTTP, include in the `parameters` object.
`image_list`	array	No	List of images. Supports image URLs and Data URLs (Base64-encoded). A vision-language model must be selected in the application configuration. In Java SDK, use `images`; in HTTP, include in the `input` object.
`file_list`	array	No	List of file URLs. In Java SDK, use `files`; in HTTP, include in the `input` object.
`model_id`	string	No	Model name. Overrides console-configured defaults to explicitly specify the model used for this call. In Java SDK, use `modelId`; in HTTP, include in the `parameters` object.
`dialog_round`	integer	No	Number of prior dialogue rounds to include as context. Sets the maximum number of historical turns passed to the model. In Java SDK, use `dialogRound`; in HTTP, include in the `parameters` object.
`biz_params`	object	No	Custom plugin parameters defined by the application. In Java SDK, use `bizParams`; in HTTP, include in the `input` object.

`biz_params` Properties

Parameter	Type	Description
`user_prompt_params`	object	Custom prompt variable definitions. Variable names must be unique within one application; up to 10 variables allowed.
`user_defined_params`	object	Custom plugin parameter definitions. Keys correspond to plugin `TOOL_ID`s; values are parameter objects required by each plugin.

Code Examples

Single-Turn Conversation

import os
from http import HTTPStatus
from dashscope import Application

response = Application.call(
    # If no environment variable is configured, replace the line below with your Bailian API Key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',  # Replace with your actual Application ID
    prompt='Who are you?')

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)

Multi-Turn Conversation

Multi-turn conversations maintain context using session_id:

First request: Do not provide session_id; the response will include a newly generated session_id.
Subsequent requests: Include the session_id returned in the previous response to continue the conversation.
Validity: session_id remains valid for 1 hour after the most recent request.

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='Who are you?')

    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='What skills do you have?',
        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()

Streaming Response

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='Who are you?',
    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}')

Response Object

Parameter	Type	Description
`status_code`	string	HTTP status code. `200` indicates success. Not returned by Java SDK — exceptions are thrown on failure.
`request_id`	string	Unique identifier for this request. In Java SDK, returned as `requestId`.
`code`	string	Error code. Empty on success. Returned only by Python SDK.
`message`	string	Detailed error message. Ignored on success. Returned only by Python SDK.
`output`	object	Result payload.
`usage`	object	Token usage statistics for this request.

`output` Properties

Parameter	Type	Description
`text`	string	Model-generated response text.
`finish_reason`	string	Reason for response termination: `stop` means natural completion; `null` means forced interruption (e.g., due to max length or manual stop).
`session_id`	string	Unique identifier for the current conversation. Include in subsequent requests to retain history.
`thoughts`	array	Reasoning trace from deep-thinking models, visible only when `has_thoughts=true`.

`thoughts` Properties

Parameter	Type	Description
`thought`	string	Model’s internal reasoning step.
`action_type`	string	Action type returned by the LLM, e.g., `reasoning` for deep-thinking model steps.
`action_name`	string	Name of the executed action, e.g., “reasoning”.
`action`	string	Executed step description.
`action_input_stream`	string	Streamed input parameter result.
`action_input`	string	Input parameters passed to the action.

`usage` Properties

Parameter	Type	Description
`models`	array	List of models invoked in this request.
`models[].model_id`	string	ID of the model used.
`models[].input_tokens`	integer	Number of tokens in the user input.
`models[].output_tokens`	integer	Number of tokens in the model’s generated output.

Successful Response Example

{
    "status_code": 200,
    "request_id": "fdfc3182-bc9d-4b45-a287-cd83b13aca02",
    "code": "",
    "message": "",
    "output": {
        "text": "Hello! I am Qwen, a large-scale language model developed by Alibaba Group.",
        "finish_reason": "stop",
        "session_id": "cbb2e26ac4cc4cc3b2d114e1f73c127e",
        "thoughts": null,
        "doc_references": null
    },
    "usage": {
        "models": [
            {
                "model_id": "qwen-plus-latest",
                "input_tokens": 142,
                "output_tokens": 296
            }
        ]
    }
}

Error Response Example

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

QPM Limits

Default QPM (queries per minute) limit per application is 15,000.

Error Codes

If the API call fails and returns an error, refer to the Error Code Documentation for troubleshooting.

​Prerequisites

​Invocation Methods

​Request Body

​biz_params Properties

​Code Examples

​Single-Turn Conversation

​Multi-Turn Conversation

​Streaming Response

​Response Object

​output Properties

​thoughts Properties

​usage Properties

​Successful Response Example

​Error Response Example

​QPM Limits

​Error Codes