Build & Manage Assistants with Assistant API - Model Studio - Alibaba Cloud - Alibaba Cloud Model Studio

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

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 parameters

Parameter 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. `{ "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

{
    "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

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

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

Parameter	Type	Default	Description
model	string	-	The model that the agent uses.
name	string	-	The name of the agent.
description	string	-	The description of the agent.
instructions	string	-	Specify agent features
tools	array	[]	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.
metadata	object	None	The information associated with the agent.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	string	None	For 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

{
   "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 name	Type	Description
status_code	integer	The HTTP status code for the call. A value of 200 indicates success. Other values indicate an error.
name	string	The name of the agent.
id	string	The agent ID, which is a UUID string.
model	string	The name of the model that the agent uses.
description	string	The description of the agent.
instructions	string	You can specify the agent feature information.
metadata	object	The metadata of the agent.
tools	array	A list of tools that the agent can use.
created_at	integer	The UNIX timestamp when the agent was created.
code	string	Indicates 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.
message	string	Indicates 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

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 Name	Input parameter descriptions	Type	Required
limit	Number of agents	int	No
order	The sort order by creation time.	str	No (default: `desc`)

Response

{
    "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

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

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

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

Response parameters

Field Name	Type	Description
has_more	boolean	Indicates whether more data is available.
last_id	string	The ID of the last assistant in the data.
first_id	string	The ID of the first assistant in the data.
data	array	A list of agent objects.
object	string	The format of the data, such as `"list"`.
request_id	string	The ID of the request.
status_code	integer	The request status code.

Retrieval Agent

HTTP

Code example

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 name	Input parameter descriptions	Type	Required
assistant_id	The ID of the agent to retrieve.	str	Yes

Response

{
    "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

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

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

Parameter	Type	Default	Description
assistant_id	string	-	The ID of the agent to retrieve.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	string	None	The 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

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 Name	Input parameter descriptions	Type	Required
assistant_id	The ID of the agent to retrieve	str	Yes
*	Other optional input parameters.	str	No
model	The ID of 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. The tools must be registered in Alibaba Cloud Model Studio.	Optional[List[Dict]]	No (default: [])
metadata	Stores other related parameters for the agent.	Dict	No

Response

{
    "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

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

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

Parameter	Type	Default	Description
assistant_id	string	-	The ID of the assistant to update.
model	string	-	The model that the agent uses.
name	string	None	The name of the agent.
description	string	None	The description of the agent.
instructions	string	None	You can specify the feature information for the agent.
tools	array	[]	The tools that the agent uses.
metadata	object	None	The information associated with the agent.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	string	None	For 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

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 Name	Description	Type	Required
assistant_id	The ID of the agent to retrieve.	str	Yes

Response

{
    "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

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

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

Parameter	Type	Default	Description
assistant_id	string	-	The ID of the agent to delete.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when `api_key` is a sub-workspace API key.
api_key	string	None	For 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 name	Type	Description
id	string	The ID of the deleted object.
object	string	The target of the request. Example: `'assistant.deleted'`
deleted	boolean	Confirm Deletion
request_id	string	The ID of the request.
status_code	integer	The request status code.

Agent object

An Assistant object that can call models and use tools.

Agent Object Example

{
    "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 name	Data type	Description
id	string	The unique identifier of the agent, which is the assistant ID.
object	string	The object type. This is always `assistant`.
created_at	integer	The 13-digit Unix timestamp, in milliseconds, when the agent was created.
model	string	The 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.
name	string	The name of the agent.
description	string	The description of the agent.
instructions	string	The system instructions that the agent uses.
tools	array	A 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.
metadata	dict	Additional information about the agent object stored in a structured format.
temperature	float	The 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_p	float	An 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_k	integer	Similar 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_tokens	integer	The maximum number of tokens that the agent can generate at one time.
request_id	string	The unique identifier of the call associated with the agent.

Error codes

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