Skip to main content

New agent application API

This topic covers the input and output parameters for using the DashScope API to call the new agent application in Alibaba Cloud Model Studio.

Related guide:Agent 2.0.
This topic is applicable only to the China (Beijing) region.

Prerequisites

Before you begin, ensure you complete the following:
  1. Create an application: Go to application management, create a new agent application in Model Studio, and record the application ID.
  2. Get an API Key: Obtain an API Key from key management and configure the API Key as an environment variable.
  3. Install the SDK (optional): Install the DashScope SDK for your programming language.

Invocation method

  • HTTP API invocation Request URL: POST https://dashscope.aliyuncs.com/api/v1/apps/APP_ID/completion
    Replace APP_ID with your actual application ID.
  • SDK invocation The Python and Java SDKs use the correct endpoint by default. To set a custom endpoint, use the base_url parameter.
Online debugging: Go to application card -> publish -> API debugging, enter the parameters, and click run.

Request body

app_idstring(Required)The application ID.Obtain this from the application card in Application Management.
In the Java SDK, this parameter is appId. For HTTP calls, replace APP_ID in the URL with your application ID.
promptstring(Required)The user input that guides the application's response.
For HTTP calls, place the prompt in the input object.
session_idstring (Optional)The identifier for the conversation history.When you pass session_id, the request automatically includes the conversation history stored in the cloud. In this case, you must pass prompt.This ID expires after 1 hour of inactivity.
In the Java SDK, use setSessionId. For HTTP calls, place the session_id in the input object.
workspace string (Optional)The workspace identifier. For more information, see Obtain Workspace ID.You need to pass the workspace ID only when you call an application in a sub-workspace.
For HTTP calls, specify the X-DashScope-WorkSpace header.
stream boolean (Optional, default: false)Specifies whether to stream the response.We recommend that you set this to true to improve the reading experience and reduce the risk of timeouts.Valid values:
  • false (default): The full response is returned only after generation is complete.
  • true (recommended): The response is streamed in chunks as it is generated. You must assemble these chunks to form the complete response.
To enable streaming output with the Java SDK, use the streamCall interface. For HTTP calls, set the X-DashScope-SSE header to enable.
incremental_output boolean (Optional, default: false)Specifies whether to enable incremental output in streaming output mode.We recommend setting this to true to improve the reading experience.Valid values:
  • false (default): Each output contains the entire sequence generated so far. The final output is the complete result.
I
I like
I like apple
I like apple.
  • true (recommended): Each chunk contains only new content. You must concatenate the chunks to get the full result.
I
 like
 apple
.
In the Java SDK, this parameter is incrementalOutput. For HTTP calls, place incremental_output in the parameters object.
enable_thinking boolean (Optional, default: false)This parameter toggles between thinking and non-thinking modes for deep-thinking models.Valid values:
  • False (default): Non-thinking mode. The final answer is returned directly in the text field.
  • True: Enables thinking mode. The model first outputs its thinking process and then returns the final answer.
Priority:
  • If this parameter is not set in the API call, the thinking mode setting configured for the model in the application is used.
  • If enable_thinking is set in the call, the API parameter takes precedence.
To obtain the content of the thinking process, you must set has_thoughts to True:
  1. The thinking process is retrieved from the thought field.
  2. The final answer is obtained from the text field.
Enabling enable_thinking may not always output the thinking process.
In the Java SDK, this parameter is enableThinking. For HTTP calls, place enable_thinking in the parameters object.
Requires Java Dashscope SDK version 2.20.0 or later.
has_thoughts boolean (Optional, default: false)Specifies whether to output the thinking process of a model that has thinking mode enabled. The process is returned in the thoughts field.Valid values:
  • True: Output the process.
  • False (default): Do not output the process.
In the Java SDK, this parameter is hasThoughts. For HTTP calls, place has_thoughts in the parameters object.
image_list array(Optional)A list of images. This parameter supports image URLs and Data URLs (Base64-encoded). The application must use an Image and Video Understanding model.The base64 encoding format can be constructed as a Data URL: data:[MIME_type];base64,{base64_image}. For a detailed description and code examples, see the Visual Understanding section.
In the Java SDK, this parameter is images. For HTTP calls, place image_list in the input object.
file_list array(Optional)A list of file URLs.
In the Java SDK, this parameter is files. For HTTP calls, place file_list in the input object.
Requires Python Dashscope SDK version 1.24.7 or later, or Java Dashscope SDK version 2.21.13 or later.
model_idstring(Optional)The model name.You can use this parameter to specify the model to be used for the current API call.Priority: If the model_id passed through the API is different from the one configured in the console, the API parameter value takes precedence.
In the Java SDK, this parameter is modelId. For HTTP calls, place model_id in the parameters object.
Requires Java Dashscope SDK version 2.19.3 or later.
  • Single-turn
  • Multi-turn
  • Streaming output
  • File Q&A
  • Visual understanding
  • Pass custom parameters
  • Python
  • Java
  • HTTP
Request example
import os
from http import HTTPStatus
from dashscope import Application
response = Application.call(
    # If not using an environment variable, set your API key directly (e.g., api_key="sk-xxx").
    # For security, we recommend using environment variables instead of hardcoding keys.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    app_id='APP_ID',  # Replace with your 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}')
    print(f'Refer to the documentation: https://help.aliyun.com/en/model-studio/developer-reference/error-code')
else:
    print(response.output.text)

Response object

status_code stringThe status code of the response.A value of 200 indicates that the request was successful. Other values indicate that the request failed.If the request fails, use code to get the error code and message to get the error message.
The Java SDK does not return this parameter. If the call fails, the SDK throws an exception. The exception includes the status_code value.
request_id stringA unique identifier for this call.
In the Java SDK, this parameter is returned as requestId.
code stringThe error code. This field is empty if the call is successful.
Only the Python SDK returns this parameter.
message stringA detailed error message. This field is empty if the request is successful.
Only the Python SDK returns this parameter.
output objectThe result of the request.

output properties

text stringThe content generated by the model.finish_reason stringThe reason the generation stopped.stop indicates a natural stop (a predefined stop sequence). null indicates a forced stop (for example, the maximum length limit is reached or the generation is manually stopped).session_idstringA unique identifier for the current conversation.Pass this ID in subsequent requests to include the conversation history.thoughtsarrayWhen you make a call, set the has_thoughts parameter to True to view the the thinking process of the Deep Thinking Model in thoughts.
thought stringThe thinking process of the model.Procedure
  1. In the console, select the Deep Thinking Model for your application and publish it.
  2. Set the has_thoughts parameter to true in your API call.
action_type stringThe type of action performed by the model. For example, reasoning indicates the thinking process of the Deep Thinking Model.action_name stringThe name of the action being executed, such as the thinking process.action stringThe step being executed.action_input_stream stringThe streaming input for the action.action_input stringThe input for the action.
usage objectUsage details for this request.

usage properties

modelsarrayInformation about the model used in this call.
model_id stringThe ID of the model used for the request.input_tokens integerThe length, in tokens, of the user input text.output_tokens integerThe length, in tokens, of the model output.
Example success response
{
    "status_code": 200,
    "request_id": "fdfc3182-bc9d-4b45-a287-cd83b13aca02",
    "code": "",
    "message": "",
    "output": {
        "text": "Hello! I am Qianwen, a large-scale language model from Alibaba Group. I can help you answer questions, create text such as stories, official documents, emails, and scripts, perform logical reasoning, write code, and more. How can I help you?",
        "finish_reason": "stop",
        "session_id": "cbb2e26ac4cc4cc3b2d114e1f73c127e",
        "thoughts": null,
        "doc_references": null,
        "workflow_message": null
    },
    "usage": {
        "models": [
            {
                "model_id": "qwen-plus-latest",
                "input_tokens": 142,
                "output_tokens": 296
            }
        ]
    }
}
Example error responseIf a request fails, the code and message fields indicate the reason for the error.The following example shows an error response when an invalid API-KEY is provided.
request_id=1d14958f-0498-91a3-9e15-be477971967b,
code=401,
message=Invalid API-key provided.

QPM limit

The default QPM limit per application is 15,000.

Error codes

If a call fails, refer to the error codes for a solution.
Managed Agent API
Flow Agent API
Sandbox API
RAG API
Long-term Memory
ParseX API
Security API
Framework Integration