Asynchronous Invocation API Reference - 阿里云百炼 Agent Studio

This document describes how to asynchronously invoke Alibaba Cloud Bailian applications (agent applications and workflow applications) using the OpenAI-compatible Responses API. For long-running tasks, simply set background to true in your request. The API will immediately return a task ID, which you can use later to query or manage the task. This “submit first, then retrieve” approach effectively avoids request timeouts or prolonged waiting.

Streaming output (stream=true) is not supported for asynchronous tasks.

Related References

Synchronous invocation: For real-time interactive scenarios where immediate results are required, see the Synchronous Invocation API Reference.
DashScope API: For additional features, refer to the DashScope API.

Prerequisites

You have obtained an API key and configured it in your environment variables. If invoking via the OpenAI SDK, ensure the OpenAI SDK is installed.
You have created an Alibaba Cloud Bailian application and obtained its application ID.

Endpoint

SDK base_url: https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/
HTTP Endpoint: POST https://dashscope.aliyuncs.com/api/v2/apps/agent/{APP_ID}/compatible-mode/v1/responses

Replace {APP_ID} with your actual application ID.

Creating an Asynchronous Task

Set background to true in your request to create an asynchronous task:

from openai import OpenAI
import os

api_key = os.getenv("DASHSCOPE_API_KEY")
app_id = 'APP_ID'  # Replace with your actual application ID
base_url = f'https://dashscope.aliyuncs.com/api/v2/apps/agent/{app_id}/compatible-mode/v1/'

client = OpenAI(
    api_key=api_key,
    base_url=base_url
)

response = client.responses.create(
    input="Please help me generate a detailed project report",
    background=True
)

print(f"Task ID: {response.id}")
print(f"Task Status: {response.status}")

Querying Task Status

Use the task ID to check the execution status and result of an asynchronous task:

# Query task status
result = client.responses.retrieve(response.id)
print(f"Status: {result.status}")
if result.status == "completed":
    print(f"Result: {result.output}")

Canceling a Task

You may cancel an asynchronous task that has not yet completed:

client.responses.cancel(response.id)

Request Parameters

Parameter	Type	Required	Description
input	string/array	Yes	User input content.
background	boolean	Yes	Set to `true` to create an asynchronous task.
model	string	No	Model name.
previous_response_id	string	No	ID of the previous response, used for multi-turn conversations.

Response Object

Parameter	Type	Description
id	string	Unique identifier for the task.
status	string	Task status: `queued`, `in_progress`, `completed`, `failed`, or `cancelled`.
output	array	List of output messages after task completion.
usage	object	Token usage information (returned only upon completion).

Error Codes

If the API call fails and returns an error message, consult the Responses API reference for troubleshooting.

​Prerequisites

​Endpoint

​Creating an Asynchronous Task

​Querying Task Status

​Canceling a Task

​Request Parameters

​Response Object

​Error Codes

Prerequisites

Endpoint

Creating an Asynchronous Task

Querying Task Status

Canceling a Task

Request Parameters

Response Object

Error Codes