Assistants - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

The Assistant API simplifies the process of building Assistants. This topic describes the methods that the Assistant API provides for managing Assistants, including creating, listing, retrieving, updating, and deleting Assistants.

Introduction: To learn about the features and basic usage of the Assistant API, see Assistant API overview.

Lifetime: All Assistant instances are saved on the Model Studio server. They do not currently have an expiration date. You can retrieve an assistant using its assistant.id.

Note

Agent applications and Assistants are both model applications, but they have different features and usage.

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

Create an assistant

Creates an assistant.

HTTP

Sample code

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	Description	Type	Required
model	The model used by the assistant.	str	Yes
name	The name of the assistant.	str	No
description	The text used to describe the assistant.	str	No
instructions	The system prompt for the model in the assistant.	various	No
tools	A list of tools that can be called by the assistant. Pass authentication information for a custom plug-in. `{ "type": "${plugin_id}", "auth": { # This field is used only when user-level authentication is used "type": "user_http", "user_token": "bearer-token", } }`	Optional[List[Dict]]	No (defaults to [])
metadata	Other relevant parameters for the assistant, used to store other related information.	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

Sample 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 that can call different tools based on user needs and then provide answers. Please use tools as appropriate.",
    "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

Returns an assistant object.

SDK

Sample code

Python

from dashscope import Assistants
import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistant = Assistants.create(
        # We recommend that you configure the environment variable first. If you have not configured the environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # In this example, qwen-max is used. You can replace it with another model name as needed. For the model list, 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()
                // In this example, qwen-max is used. You can replace it with another model name as needed. For the model list, 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.")
                // We recommend that you configure the environment variable first. If you have not configured the environment variable, 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 value	Description
model	string	-	The model used by the assistant.
name	string	-	The name of the assistant.
description	string	-	The description of the assistant.
instructions	string	-	The function information of the assistant.
tools	array	[]	The tools used by the assistant. Note Pass authentication information for a custom tool. `{` `"type": "plugin_type", "auth": {"type": "user_http","user_token": "bearer-token", }` `}` When the assistant requests a plug-in, it will place the bearer token in `{"plugin_type":{"user_token": "bearer-token"}}` and add it to the header of the plug-in call.
metadata	object	None	The information associated with the assistant.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when the api_key is a sub-workspace API key.
api_key	string	None	The Model Studio API key. We recommend that you configure the API key as an environment variable.

Sample 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

Parameter	Type	Description
status_code	integer	The HTTP status code of the call. A value of 200 indicates that the call is successful. Other values indicate that the call fails.
name	string	The name of the assistant.
id	string	The assistant ID, which is a UUID string.
model	string	The name of the model used by the assistant.
description	string	The description of the assistant.
instructions	string	The function information of the assistant.
metadata	object	The metadata of the assistant.
tools	array	A list of tools that the assistant can use.
created_at	integer	The timestamp representation of when the assistant was created.
code	string	Indicates that the request fails. This is the error code. It is ignored when the request is successful. This is displayed only when a call through Python fails.
message	string	Fails. This indicates the detailed information about the failure. It is ignored on success. This is displayed only when a call through Python fails.

List assistants

Returns a list of assistants.

HTTP

Sample code

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

Parameter	Description	Type	Required
limit	The number of assistants to return.	int	No
order	Sort by creation time in ascending or descending order.	str	No (defaults to `desc`)

Sample 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 that can call different tools based on user needs and then provide answers. Please use tools as appropriate.",
            "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

Returns a list of assistant objects.

SDK

Sample code

Python

import dashscope
from dashscope import Assistants
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.list(
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, 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()
                // We recommend that you configure the environment variable first. If you have not configured the environment variable, 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 value	Description
limit	string	None	The number of assistants to return. If this parameter is not specified, the default value on the server is used.
order	string	None	The sorting method. 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 the api_key is a sub-workspace API key.
api_key	string	None	The Model Studio API key. We recommend that you configure the API key as an environment variable.

Response parameters

Parameter	Type	Description
has_more	boolean	Indicates whether there is more data to retrieve.
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 assistant objects.
object	string	The data format of the data, such as `"list"`.
request_id	string	The ID of this request.
status_code	integer	The request status code.

Retrieve an assistant

HTTP

Sample code

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

Parameter	Description	Type	Required
assistant_id	The ID of the assistant to retrieve.	str	Yes

Sample 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 that can call different tools based on user needs and then provide answers. Please use tools as appropriate.",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "text_to_image"
        },
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "request_id": "f0ec05b0-8813-984c-81b5-1166ae3478d1"
}

Response parameters

Returns the retrieved assistant object.

SDK

Sample code

Python

from dashscope import Assistants
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'from dashscope import Assistants
assistant = Assistants.retrieve(
    assistant_id='your_assistant_id',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, 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();
      // We recommend that you configure the environment variable first. If you have not configured the environment variable, 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 value	Description
assistant_id	string	-	The ID of the assistant to retrieve.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when the api_key is a sub-workspace API key.
api_key	string	None	The Model Studio API key. We recommend that you configure the API key as an environment variable.

Response parameters

For more information, see Assistant object.

Update an assistant

HTTP

Sample code

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 Applications-AssistantsAPI",
    "description": "",
    "model": "qwen-max",
}'

Request parameters

Parameter	Description	Type	Required
assistant_id	The ID of the assistant to retrieve.	str	Yes
*	Other optional input parameters.	various	No
model	The ID of the model used by the assistant.	str	Yes
name	The name of the assistant.	str	No
description	The description of the assistant.	str	No
instructions	The system prompt for the model in the assistant.	str	No
tools	A list of tools that can be called by the assistant. The tools must be registered in Model Studio.	Optional[List[Dict]]	No (defaults to [])
metadata	Other relevant parameters for the assistant, used to store other related information.	Dict	No

Sample response

{
    "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "object": "assistant",
    "created_at": 1711435564909,
    "model": "qwen-max",
    "name": "New Applications-AssistantsAPI",
    "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

Returns the updated assistant object.

SDK

Sample code

Python

from dashscope import Assistants
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'from dashscope import Assistants
assistants = Assistants.update(
    'assistant_id', 
    model='new_model_name',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, 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.")
                // We recommend that you configure the environment variable first. If you have not configured the environment variable, 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 value	Description
assistant_id	string	-	The ID of the assistant to update.
model	string	-	The model used by the assistant.
name	string	None	The name of the assistant.
description	string	None	The description of the assistant.
instructions	string	None	The function information of the assistant.
tools	array	[]	The tools used by the assistant.
metadata	object	None	The information associated with the assistant.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when the api_key is a sub-workspace API key.
api_key	string	None	The Model Studio API key. We recommend that you configure the API key as an environment variable.

Response parameters

For more information, see Assistant object.

Delete an assistant

HTTP

Sample code

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

Parameter	Description	Type	Required
assistant_id	The assistant ID to retrieve	str	Yes

Sample response

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

Response parameters

Returns the deletion status of the assistant.

SDK

Sample code

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',
    # We recommend that you configure the environment variable first. If you have not configured the environment variable, 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();     
        // We recommend that you configure the environment variable first. If you have not configured the environment variable, 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 value	Description
assistant_id	string	-	The ID of the assistant to delete.
workspace	string	None	The workspace ID of Model Studio. This parameter is required only when the api_key is a sub-workspace API key.
api_key	string	None	The Model Studio API key. We recommend that you configure the API key as an environment variable.
*	various	None	Other optional input parameters (e.g., 'tools' as list, 'metadata' as dict)

Response parameters

Parameter	Type	Description
id	string	The ID of the deleted object.
object	string	The target of this request. Example: `'assistant.deleted'`
deleted	boolean	Whether the object is deleted.
request_id	string	The ID of this request.
status_code	integer	The request status code.

Assistant object

An Assistant object can call a model and use tools.

Sample object

{
    "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 that can call different tools based on user needs and then provide answers. Please use tools as appropriate.",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "temperature": null,
    "top_p": null,
    "top_k": null,
    "max_tokens": null,
    "request_id": "b1778226-3865-9006-9e95-56329a710322"
}

Parameter	Data type	Description
id	string	The unique identifier of the assistant, which is the assistant ID.
object	string	The object type, which is always `assistant`.
create_at	integer	The 13-digit UNIX timestamp (in milliseconds) when the assistant was created.
model	string	The name of the model used by the assistant. You can view all available models in Overview of Assistant API features, or see Models for more details.
name	string	The name of the assistant.
description	string	The description of the assistant.
instructions	string	The system instructions used by the assistant.
tools	array	A list of tools enabled on the assistant. The tool can be an official plug-in (code_interpreter, or text_to_image), retrieval-augmented generation (RAG), or function calling.
metadata	dict	Additional information about the assistant 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 sampling with temperature, called nucleus sampling. In this sampling method, the model considers the results of tokens with a cumulative probability mass of top_p. A value of 0.1 means that only the tokens that comprise the top 10% of the probability mass are considered. We generally recommend that you 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 assistant can generate at one time.
request_id	string	The unique identifier of the call associated with the assistant.

Troubleshooting errors

If a call fails and returned an error message, see Error messages for troubleshooting.