全部產品
Search
文件中心

Alibaba Cloud Model Studio:Assistants

更新時間:Feb 12, 2026

Assistant API 旨在簡化 Assistant(一種大模型應用)的構建流程。本文詳細介紹了 Assistant API 提供的各項 Assistant 管理方法,包括 Assistant 的建立、列舉、檢索、更新和刪除操作。

功能介紹:如果您想瞭解 Assistant API 的功能和基本用法,請參考Assistant API功能概覽
有效期間限:所有 Assistant 執行個體均儲存在阿里雲百鍊伺服器上,目前沒有失效日期,您可通過 assistant.id 檢索智能體。
說明

智能體應用和 Assistant 雖然均為大模型應用,但二者的功能相互獨立,使用方法也不相同。

  • 智能體應用:僅可使用控制台進行建立、查看、更新和刪除,以及通過應用調用 API進行調用。

  • Assistant:僅可使用 Assistant API 建立、查看、更新、刪除和調用 Assistant 。

建立智能體

建立一個新的智能體。

HTTP

程式碼範例

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": {}
}'

輸入參數

參數名

描述

參數類型

是否必須

model

智能體所使用的模型

str

name

智能體使用的名字

str

description

用於描述智能體的文字

str

instructions

System prompt 用於智能體裡的大模型

str

tools

一個可以被智能體調用tools list.

自訂外掛程式的鑒權資訊傳遞

{
 "type": "${外掛程式id}",
     "auth": {  # 當使用“使用者級鑒權”時,才使用這一欄位
         "type": "user_http",
         "user_token": "bearer-token",
         } 
 }

Optional[List[Dict]]

否(default=[])

metadata

其他相關參數用於智能體,用於儲存其他相關參數

Dict

temperature

用於控制隨機性和多樣性的程度。

float

top_p

產生時,核採樣方法的機率閾值。

float

top_k

產生時,採樣候選集的大小。

integer

返回結果

{
    "id": "asst_49079f4b-d1e8-4015-a12e-2dcdd1f18d84",
    "object": "assistant",
    "created_at": 1711713885724,
    "model": "qwen-max",
    "name": "智能小助手",
    "description": "這是一個智能小助手",
    "instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "temperature": null,
    "top_p": null,
    "top_k": null,
    "max_tokens": null,
    "request_id": "b1778226-3865-9006-9e95-56329a710322"
}

輸出參數

一個智能體對象

SDK

程式碼範例

from dashscope import Assistants
import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistant = Assistants.create(
        # 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # 此處以qwen-max為例,可按需更換模型名稱。模型列表:https://www.alibabacloud.com/help/zh/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)
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()
                // 此處以qwen-max為例,可按需更換模型名稱。模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
                .model("qwen-max")
                .name("intelligent guide")
                .description("a smart guide")
                .instructions("You are a helpful assistant.")
                // 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊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

    }
}

輸入參數

參數

類型

預設值

說明

model

string

-

指定用於智能體所使用的模型

name

string

-

指定智能體名稱

description

string

-

智能體描述

instructions

string

-

指定智能體功能資訊

tools

array

[]

智能體使用的tools

說明

自訂tool鑒權資訊傳遞

{

"type": "plugin_type", "auth": {"type": "user_http","user_token": "bearer-token", }

}

assistant在請求外掛程式時會將bearer放在{"plugin_type":{"user_token": "bearer-token"}}添加到調用plugin的header裡.

metadata

object

None

智能體關聯資訊

workspace

string

None

阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。

api_key

string

None

阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)

返回結果

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

輸出參數

欄位名

欄位類型

欄位描述

status_code

integer

為調用http status code,200表示調用成功,其他表示調用出錯。

name

string

智能體名稱。

id

string

智能體ID,為uuid字串。

model

string

智能體使用的模型名稱。

description

string

智能體描述資訊。

instructions

string

指定智能體功能資訊。

metadata

object

智能體的中繼資料。

tools

array

智能體可以用的tool列表。

created_at

integer

智能體建立的時間戳記表示。

code

string

表示請求失敗,表示錯誤碼,請求成功時忽略。只有在通過Python調用失敗時會顯示。

message

string

失敗,表示失敗詳細資料,成功忽略。只有在通過Python調用失敗時會顯示。

列出智能體

用於返回智能體列表。

HTTP

程式碼範例

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"

輸入參數

輸入參數名字

輸入參數的描述

參數類型

是否必須

limit

建立智能體的數量

int

order

按照建立時間升序或降序

str

否(預設為desc

返回結果

{
    "object": "list",
    "data": [
        {
            "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
            "object": "assistant",
            "created_at": 1711435564909,
            "model": "qwen-max",
            "name": "智能小助手",
            "description": "這是一個智能小助手",
            "instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
            "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"
}

輸出參數

輸出一個智能體對象列表。

SDK

程式碼範例

import dashscope
from dashscope import Assistants
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.list(
    # 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    limit=1,
    order='desc'
)
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()
                // 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .limit(10l)
                .build();
      ListResult<Assistant> assistant = assistants.list(listParam);
    }
}

輸入參數

參數

類型

預設值

說明

limit

string

None

指定列出assistant的數目,如果未指定則使用服務端預設值。

order

string

None

排序方式,可選值:desc(降序)、asc(升序),如果未指定則使用服務端預設值。

workspace

string

None

阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。

api_key

string

None

阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)

輸出參數

欄位名

欄位類型

欄位描述

has_more

boolean

表示是否還有更多資料可以擷取。

last_id

string

data中最後一個assistant的ID。

first_id

string

data中第一個assistant的ID。

data

array

智能體對象列表。

object

string

data的資料格式,如"list"

request_id

string

本次請求的ID。

status_code

integer

請求狀態代碼。

檢索智能體

HTTP

程式碼範例

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"

輸入參數

輸入參數名字

輸入參數的描述

參數類型

是否必須

assistant_id

待檢索的智能體 ID

str

返回結果

{
    "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "object": "assistant",
    "created_at": 1711435564909,
    "model": "qwen-max",
    "name": "智能小助手",
    "description": "這是一個智能小助手",
    "instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "text_to_image"
        },
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "request_id": "f0ec05b0-8813-984c-81b5-1166ae3478d1"
}

輸出參數

輸出檢索到的智能體對象

SDK

程式碼範例

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',
    # 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

print(assistant)
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();
      // 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
      String apiKey = System.getenv("DASHSCOPE_API_KEY");
      Assistant assistant = assistants.retrieve("assistant_id", apiKey);
    }
}

輸入參數

參數

類型

預設值

說明

assistant_id

string

-

指定要查詢的智能體 ID

workspace

string

None

阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。

api_key

string

None

阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)

輸出參數

請參考智能體對象

更新智能體

HTTP

程式碼範例

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"
}'

輸入參數

輸入參數名字

輸入參數的描述

參數類型

是否必須

assistant_id

待檢索的智能體 ID

str

*

其他可選的輸入參數

str

model

智能體所使用的大模型 ID

str

name

智能體使用的名字

str

description

用於描述智能體的文字

str

instructions

System prompt 用於智能體裡的大模型

str

tools

一個可以被智能體調用tools list,使用者需要在阿里雲百鍊中被註冊

Optional[List[Dict]]

否(default=[])

metadata

其他相關參數用於智能體,用於儲存其他相關參數

Dict

返回結果

{
    "id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
    "object": "assistant",
    "created_at": 1711435564909,
    "model": "qwen-max",
    "name": "建立應用-assistantAPI",
    "description": "",
    "instructions": "你是一個搜尋助手",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "text_to_image"
        },
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "request_id": "b0993831-a98b-9e71-b235-75174df9046e"
}

輸出參數

輸出更新後的智能體對象

SDK

程式碼範例

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',
    # 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY")
)
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.")
                // 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        
        Assistant assistant = assistants.update("assistant_id", param);
    }
}

輸入參數

參數

類型

預設值

說明

assistant_id

string

-

指定需要更新的assistant ID

model

string

-

指定用於智能體所使用的模型

name

string

None

指定智能體名稱

description

string

None

智能體描述

instructions

string

None

指定智能體功能資訊。

tools

array

[]

智能體使用的tools

metadata

object

None

智能體關聯資訊

workspace

string

None

阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。

api_key

string

None

阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)

輸出參數

請參考智能體對象

刪除智能體

HTTP

程式碼範例

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"

輸入參數

輸入參數名字

輸入參數的描述

參數類型

是否必須

assistant_id

待檢索的智能體 ID

str

返回結果

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

輸出參數

輸出刪除智能體後的狀態。

SDK

程式碼範例

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',
    # 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY")
)
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();     
        // 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        DeletionStatus assistant = assistants.delete("assistant_id", apiKey);
    }
}

輸入參數

參數

類型

預設值

說明

assistant_id

string

-

指定要刪除的智能體 ID

workspace

string

None

阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。

api_key

string

None

阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)

輸出參數

欄位名

欄位類型

欄位描述

id

string

刪除的對象的ID

object

string

本次請求目標,樣本:'assistant.deleted'

deleted

boolean

是否刪除

request_id

string

本次請求的ID。

status_code

integer

請求狀態代碼。

智能體對象

一個能夠調用模型並使用工具的Assistant對象。

智能體對象樣本

{
    "id": "asst_49079f4b-d1e8-4015-a12e-2dcdd1f18d84",
    "object": "assistant",
    "created_at": 1711713885724,
    "model": "qwen-max",
    "name": "智能小助手",
    "description": "這是一個智能小助手",
    "instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "temperature": null,
    "top_p": null,
    "top_k": null,
    "max_tokens": null,
    "request_id": "b1778226-3865-9006-9e95-56329a710322"
}

參數名

資料類型

描述

id

string

智能體唯一識別碼,即 assistant ID。

object

string

物件類型,始終為assistant

created_at

integer

建立智能體時的 Unix 13位時間戳記(以毫秒為單位)。

model

string

智能體使用的模型名。您可以在Assistant API功能概覽查看所有可用模型,或者查看模型列表以瞭解它們的詳情。

name

string

智能體的名稱。

description

string

智能體的描述。

instructions

string

智能體使用的系統指令。

tools

array

智能體上啟用的工具列表。工具的類型可以是官方外掛程式(code_interpreter 代碼解譯器、quark_search 夸克搜尋、text_to_image 文生圖)、知識檢索增強(RAG)或函數調用(Function Calling)。

metadata

dict

以結構化格式儲存的智能體對象的附加資訊。

temperature

float

採樣溫度,其取值在 0 到 2 之間。較高的值(如 1)會使輸出更加隨機;而較低的值(如 0.2)則會使輸出更加集中和確定。

top_p

float

一種替代溫度採樣的方法,稱為核採樣。在這種採樣方法中,大模型選取具有前 top_p 的累積機率品質的Token結果。其值為 0.1 表示僅考慮構成前 10% 機率品質的Token。

通常建議調整此參數或temperature,但不要同時調整兩者。

top_k

integer

與top_p類似,但樣本是從 k 個最高機率的Token中選取的,而不考慮它們的累積機率品質。

不要同時調整此參數和temperaturetop_p

max_tokens

integer

智能體能夠一次性產生Token的最大數量。

request_id

string

智能體關聯的調用的唯一識別碼。

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤資訊進行解決。