Skip to content

Assistants (Deprecated)

The assistant API simplifies building assistants, which are a type of Large Language Model (LLM) application. This topic describes the methods provided by the assistant API to manage assistants, such as creating, listing, retrieving, updating, and deleting them. Important

The Assistant API is being deprecated. Migrate to the Responses API as an alternative. The Responses API includes multiple built-in tools and supports multi-turn context management.

Features : For more information about the features and basic usage of the assistant API, see Assistant API overview. Persistence: All assistant instances are saved on the Alibaba Cloud Model Studio server and do not have an expiration date. You can retrieve an assistant using its assistant.id. Note

Agent applications and assistants are two types of LLM applications with different features and usage.

  • Agent applications: You can create, view, update, and delete agent applications only in the console. You can call them using the application calling API.

  • Assistants: You can create, view, update, delete, and call assistants only using the assistant API.

Create an agent

Creates a new assistant.

HTTP

Code example

HELPCODEESCAPE-curl
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-max",
    "name": "Intelligent assistant",
    "description": "This is an intelligent assistant",
    "instructions": "You are an intelligent assistant that can call different tools based on user query and then give responses. Please use tools when needed.",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {}
}'

Request parametersParameter name Description Type Required model The model that the agent uses. str Yes name The name of the agent. str No description The description of the agent. str No instructions The system prompt for the LLM in the agent. str No tools A list of tools that the agent can call.Passes authentication information for a custom plugin.

json
{
 "type": "${plugin_id}",
 "auth": { # This field is used only for user-level authentication.
 "type": "user_http",
 "user_token": "bearer-token",
 }
 }

Optional[List[Dict]] No (default: []) metadata Other parameters related to the agent. This parameter is used to store other related parameters. Dict No temperature Controls the degree of randomness and diversity. float No top_p The probability threshold for the nucleus sampling method during generation. float No top_k The size of the candidate set for sampling during generation. integer No

Response

HELPCODEESCAPE-json
{
    "id": "asst_49079f4b-d1e8-4015-a12e-2dcdd1f18d84",
    "object": "assistant",
    "created_at": 1711713885724,
    "model": "qwen-max",
    "name": "Intelligent Assistant",
    "description": "This is an intelligent assistant.",
    "instructions": "You are an intelligent assistant. You can call different tools based on user needs to provide answers. Use tools as needed.",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "temperature": null,
    "top_p": null,
    "top_k": null,
    "max_tokens": null,
    "request_id": "b1778226-3865-9006-9e95-56329a710322"
}

Response parameters

An assistant object.

SDK

Code example Python

HELPCODEESCAPE-python
from dashscope import Assistants
import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistant = Assistants.create(
        # Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # This example uses qwen-max. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/en/model-studio/getting-started/models
        model='qwen-max',
        name='smart helper',
        description='A tool helper.',
        instructions='You are a helpful assistant. When asked a question, use tools wherever possible.',
        tools=[{
            'type': 'search'
        }, {
            'type': 'function',
            'function': {
                'name': 'big_add',
                'description': 'Add to number',
                'parameters': {
                    'type': 'object',
                    'properties': {
                        'left': {
                            'type': 'integer',
                            'description': 'The left operator'
                        },
                        'right': {
                            'type': 'integer',
                            'description': 'The right operator.'
                        }
                    },
                    'required': ['left', 'right']
                }
            }
        }],
)
print(assistant)

Java

HELPCODEESCAPE-java
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.AssistantParam;
import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.lang.System;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Assistants assistants = new Assistants();
        // build assistant parameters
        AssistantParam param = AssistantParam.builder()
                // This example uses qwen-max. You can replace it with another model name as needed. For a list of models, see https://www.alibabacloud.com/help/en/model-studio/getting-started/models
                .model("qwen-max")
                .name("intelligent guide")
                .description("a smart guide")
                .instructions("You are a helpful assistant.")
                // Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        Assistant assistant = assistants.create(param);
        System.out.println(JsonUtils.toJson(assistant));
        // use assistant

    }
}

Request parameters

ParameterTypeDefaultDescription
modelstring-The model that the agent uses.
namestring-The name of the agent.
descriptionstring-The description of the agent.
instructionsstring-Specify agent features
toolsarray[]The tools that the agent uses. ** **Note ** Passes authentication information for a custom tool. { "type": "plugin_type", "auth": {"type": "user_http","user_token": "bearer-token", } } When the assistant requests a plugin, it places the bearer token in {"plugin_type":{"user_token": "bearer-token"}​} and adds it to the header of the plugin call.
metadataobjectNoneThe information associated with the agent.
workspacestringNoneThe workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_keystringNoneFor the Alibaba Cloud Model Studio API key, we recommend that you set it as an environment variable (This topic will be unpublished and merged into 'Configure API Key').

Response

HELPCODEESCAPE-json
{
   "tools":[
      {
         "type":"search"
      },
      {
         "function":{
            "name":"big_add",
            "description":"Add to number",
            "parameters":{
               "type":"object",
               "properties":{
                  "left":{
                     "type":"integer",
                     "description":"The left operator"
                  },
                  "right":{
                     "type":"integer",
                     "description":"The right operator."
                  }
               },
               "required":[
                  "left",
                  "right"
               ]
            }
         },
         "type":"function"
      }
   ],
   "id":"asst_714cac72-81b2-49bf-a75d-c575b90a9398",
   "object":"assistant",
   "created_at":1726033638848,
   "model":"qwen-max",
   "name":"smart helper",
   "description":"A tool helper.",
   "instructions":"You are a helpful assistant. When asked a question, use tools wherever possible.",
   "file_ids":[

   ],
   "metadata":{

   },
   "temperature":"None",
   "top_p":"None",
   "top_k":"None",
   "max_tokens":"None",
   "request_id":"00f5962e-8d9f-92fd-9320-3173fa1525d6",
   "status_code":200
}

Response parameters

Field nameTypeDescription
status_codeintegerThe HTTP status code for the call. A value of 200 indicates success. Other values indicate an error.
namestringThe name of the agent.
idstringThe agent ID, which is a UUID string.
modelstringThe name of the model that the agent uses.
descriptionstringThe description of the agent.
instructionsstringYou can specify the agent feature information.
metadataobjectThe metadata of the agent.
toolsarrayA list of tools that the agent can use.
created_atintegerThe UNIX timestamp when the agent was created.
codestringIndicates that the request failed. This is the error code. This parameter is ignored if the request is successful. This parameter is returned only when a call from Python fails.
messagestringIndicates that the request failed. This parameter provides details about the failure. This parameter is ignored if the request is successful. This parameter is returned only when a call from Python fails.

List agents

Returns a list of assistants.

HTTP

Code example

HELPCODEESCAPE-curl
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants?limit=2&order=desc' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Request parameters

Input Parameter NameInput parameter descriptionsTypeRequired
limitNumber of agentsintNo
orderThe sort order by creation time.strNo (default: desc)

Response

HELPCODEESCAPE-json
{
    "object": "list",
    "data": [
        {
            "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
            "object": "assistant",
            "created_at": 1711435564909,
            "model": "qwen-max",
            "name": "Intelligent Assistant",
            "description": "This is an intelligent assistant.",
            "instructions": "You are an intelligent assistant. You can call different tools based on user needs to provide answers. Use tools as needed.",
            "tools": [
                {
                    "type": "search"
                },
                {
                    "type": "text_to_image"
                },
                {
                    "type": "code_interpreter"
                }
            ],
            "metadata": {}
        },
        {
            "id": "asst_7af23142-52bc-4218-aa98-dfdb1128f19c",
            "object": "assistant",
            "created_at": 1711422620443,
            "model": "qwen-max",
            "name": "helpful assistant",
            "description": "",
            "instructions": "You are a helpful assistant.",
            "tools": [
                {
                    "type": "text_to_image"
                }
            ],
            "file_ids": [],
            "metadata": {}
        }
    ],
    "first_id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "last_id": "asst_7af23142-52bc-4218-aa98-dfdb1128f19c",
    "has_more": true,
    "request_id": "bc257359-ce86-9547-98be-d804effba8d1"
}

Response parameters

A list of assistant objects.

SDK

Code example Python

HELPCODEESCAPE-python
import dashscope
from dashscope import Assistants
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.list(
    # Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    limit=1,
    order='desc'
)

Java

HELPCODEESCAPE-java
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.common.GeneralListParam;
import com.alibaba.dashscope.common.ListResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
      Assistants assistants = new Assistants();
      GeneralListParam listParam = GeneralListParam.builder()
                // Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .limit(10l)
                .build();
      ListResult<Assistant> assistant = assistants.list(listParam);
    }
}

Request parameters

ParameterTypeDefaultDescription
limitstringNoneThe number of assistants to list. If this parameter is not specified, the default value on the server is used.
orderstringNoneThe sorting order. Valid values: `desc` (descending) and `asc` (ascending). If this parameter is not specified, the default value on the server is used.
workspacestringNoneThe workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_keystringNoneFor the Alibaba Cloud Model Studio API key, we recommend that you configure it in an environment variable.

Response parameters

Field NameTypeDescription
has_morebooleanIndicates whether more data is available.
last_idstringThe ID of the last assistant in the data.
first_idstringThe ID of the first assistant in the data.
dataarrayA list of agent objects.
objectstringThe format of the data, such as "list".
request_idstringThe ID of the request.
status_codeintegerThe request status code.

Retrieval Agent

HTTP

Code example

HELPCODEESCAPE-curl
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Request parameters

Input parameter nameInput parameter descriptionsTypeRequired
assistant_idThe ID of the agent to retrieve.strYes

Response

HELPCODEESCAPE-json
{
    "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "object": "assistant",
    "created_at": 1711435564909,
    "model": "qwen-max",
    "name": "Intelligent Assistant",
    "description": "This is an intelligent assistant.",
    "instructions": "You are an intelligent assistant. You can call different tools based on user needs to provide answers. Use tools as needed.",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "text_to_image"
        },
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "request_id": "f0ec05b0-8813-984c-81b5-1166ae3478d1"
}

Response parameters

The retrieved assistant object.

SDK

Code example Python

HELPCODEESCAPE-python
from dashscope import Assistants
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistant = Assistants.retrieve(
    assistant_id='your_assistant_id',
    # Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

print(assistant)

Java

HELPCODEESCAPE-java
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
      Assistants assistants = new Assistants();
      // Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
      String apiKey = System.getenv("DASHSCOPE_API_KEY");
      Assistant assistant = assistants.retrieve("assistant_id", apiKey);
    }
}

Request parameters

ParameterTypeDefaultDescription
assistant_idstring-The ID of the agent to retrieve.
workspacestringNoneThe workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_keystringNoneThe Model Studio API key. For more information, see Configure the API key as an environment variable.

Response parameters

For more information, see Assistant object.

Update an agent

HTTP

Code example

HELPCODEESCAPE-curl
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "instructions": "You are a search assistant",
    "name": "New Application-assistantAPI",
    "description": "",
    "model": "qwen-max"
}'

Request parameters

Input Parameter NameInput parameter descriptionsTypeRequired
assistant_idThe ID of the agent to retrievestrYes
*Other optional input parameters.strNo
modelThe ID of the model that the agent uses.strYes
nameThe name of the agent.strNo
descriptionThe description of the agent.strNo
instructionsThe system prompt for the LLM in the agent.strNo
toolsA list of tools that the agent can call. The tools must be registered in Alibaba Cloud Model Studio.Optional[List[Dict]]No (default: [])
metadataStores other related parameters for the agent.DictNo

Response

HELPCODEESCAPE-json
{
    "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "object": "assistant",
    "created_at": 1711435564909,
    "model": "qwen-max",
    "name": "New-Application-assistantAPI",
    "description": "",
    "instructions": "You are a search assistant.",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "text_to_image"
        },
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "request_id": "b0993831-a98b-9e71-b235-75174df9046e"
}

Response parameters

The updated assistant object.

SDK

Code example Python

HELPCODEESCAPE-python
from dashscope import Assistants
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.update(
    'assistant_id',
    model='new_model_name',
    # Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

Java

HELPCODEESCAPE-java
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.AssistantParam;
import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Assistants assistants = new Assistants();
        AssistantParam param = AssistantParam.builder()
                .model("qwen-max")
                .name("intelligent guide")
                .description("a smart guide")
                .instructions("You are a helpful assistant.  When asked a question, use tools wherever possible.")
                // Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        Assistant assistant = assistants.update("assistant_id", param);
    }
}

Request parameters

ParameterTypeDefaultDescription
assistant_idstring-The ID of the assistant to update.
modelstring-The model that the agent uses.
namestringNoneThe name of the agent.
descriptionstringNoneThe description of the agent.
instructionsstringNoneYou can specify the feature information for the agent.
toolsarray[]The tools that the agent uses.
metadataobjectNoneThe information associated with the agent.
workspacestringNoneThe workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_keystringNoneFor the Alibaba Cloud Model Studio API key, we recommend that you set the API key as an environment variable.

Response parameters

For more information, see Assistant object.

Delete an agent

HTTP

Code example

HELPCODEESCAPE-curl
curl --location --request DELETE 'https://dashscope-intl.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Request parameters

Input Parameter NameDescriptionTypeRequired
assistant_idThe ID of the agent to retrieve.strYes

Response

HELPCODEESCAPE-json
{
    "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "object": "assistant.deleted",
    "deleted": true,
    "request_id": "6af9320f-0430-9d01-b92f-d1beb6424dc5"
}

Response parameters

Outputs the status of the deleted agent.

SDK

Code example Python

HELPCODEESCAPE-python
from dashscope import Assistants
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.delete(
    'assistant_id',
    # Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

Java

HELPCODEESCAPE-java
import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.common.DeletionStatus;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Assistants assistants = new Assistants();
        // Set the environment variable. If you have not, replace the following line with your Model Studio API key: api_key="sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        DeletionStatus assistant = assistants.delete("assistant_id", apiKey);
    }
}

Request parameters

ParameterTypeDefaultDescription
assistant_idstring-The ID of the agent to delete.
workspacestringNoneThe workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_keystringNoneFor your Alibaba Cloud Model Studio API key, we recommend that you set it as an environment variable (This topic will be unpublished and merged into 'Configure API Key').

Response parameters

Field nameTypeDescription
idstringThe ID of the deleted object.
objectstringThe target of the request. Example: 'assistant.deleted'
deletedbooleanConfirm Deletion
request_idstringThe ID of the request.
status_codeintegerThe request status code.

Agent object

An Assistant object that can call models and use tools.

Agent Object Example

HELPCODEESCAPE-json
{
    "id": "asst_49079f4b-d1e8-4015-a12e-2dcdd1f18d84",
    "object": "assistant",
    "created_at": 1711713885724,
    "model": "qwen-max",
    "name": "Intelligent Assistant",
    "description": "This is an intelligent assistant.",
    "instructions": "You are an intelligent assistant. You can call different tools based on user needs to provide answers. Use tools as needed.",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "temperature": null,
    "top_p": null,
    "top_k": null,
    "max_tokens": null,
    "request_id": "b1778226-3865-9006-9e95-56329a710322"
}
Parameter nameData typeDescription
idstringThe unique identifier of the agent, which is the assistant ID.
objectstringThe object type. This is always assistant.
created_atintegerThe 13-digit Unix timestamp, in milliseconds, when the agent was created.
modelstringThe name of the model that the agent uses. You can view all available models in Assistant API overview or see Model list for more details.
namestringThe name of the agent.
descriptionstringThe description of the agent.
instructionsstringThe system instructions that the agent uses.
toolsarrayA list of tools enabled on the agent. The tool can be an official plugin (such as `code_interpreter`, `quark_search`, or `text_to_image`), retrieval-augmented generation (RAG), or function calling.
metadatadictAdditional information about the agent object stored in a structured format.
temperaturefloatThe sampling temperature, which is between 0 and 2. A higher value, such as 1, makes the output more random. A lower value, such as 0.2, makes the output more focused and deterministic.
top_pfloatAn alternative to temperature sampling, called nucleus sampling. In this sampling method, the LLM selects the token results that have a cumulative probability mass of `top_p`. A value of 0.1 means that only the tokens that make up the top 10% of the probability mass are considered.Adjust this parameter or temperature, but not both.
top_kintegerSimilar to `top_p`, but the sample is selected from the k tokens with the highest probability, regardless of their cumulative probability mass.Do not adjust this parameter and temperature or top_p at the same time.
max_tokensintegerThe maximum number of tokens that the agent can generate at one time.
request_idstringThe unique identifier of the call associated with the agent.

Error codes

If a model call fails and returns an error message, see Error messages for troubleshooting information.

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.