Assistants（下線中） - Alibaba Cloud Model Studio

Assistant API下線中，建議遷移至Responses API：內建多種工具，並支援多輪上下文管理，可作為替代方案。

功能介紹：如果您想瞭解 Assistant API 的功能和基本用法，請參考Assistant API功能概覽。

有效期間限：所有 Assistant 執行個體均儲存在阿里雲百鍊伺服器上，目前沒有失效日期，您可通過 assistant.id 檢索智能體。

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

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

建立智能體

建立一個新的智能體。

HTTP
SDK

程式碼範例

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

輸出參數一個智能體對象。

程式碼範例

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)

輸入參數

參數	類型	預設值	說明
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到環境變數。

返回結果

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

程式碼範例

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

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

程式碼範例

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'
)

輸入參數

參數	類型	預設值	說明
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到環境變數。

輸出參數

欄位名	欄位類型	欄位描述
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
SDK

程式碼範例

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

輸出參數輸出檢索到的智能體對象。

程式碼範例

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)

輸入參數

參數	類型	預設值	說明
assistant_id	string	-	指定要查詢的智能體 ID
workspace	string	None	阿里雲百鍊的Workspace ID，僅當 api_key 為子業務空間 API Key 時才需要傳入。
api_key	string	None	阿里雲百鍊的API Key，建議您配置API Key到環境變數。

輸出參數請參考智能體對象。

更新智能體

HTTP
SDK

程式碼範例

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

輸出參數輸出更新後的智能體對象。

程式碼範例

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

輸入參數

參數	類型	預設值	說明
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到環境變數。

輸出參數請參考智能體對象。

刪除智能體

HTTP
SDK

程式碼範例

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

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

程式碼範例

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

輸入參數

參數	類型	預設值	說明
assistant_id	string	-	指定要刪除的智能體 ID
workspace	string	None	阿里雲百鍊的Workspace ID，僅當 api_key 為子業務空間 API Key 時才需要傳入。
api_key	string	None	阿里雲百鍊的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中選取的，而不考慮它們的累積機率品質。不要同時調整此參數和`temperature`或`top_p`。
max_tokens	integer	智能體能夠一次性產生Token的最大數量。
request_id	string	智能體關聯的調用的唯一識別碼。

錯誤碼

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

​建立智能體

​列出智能體

​檢索智能體

​更新智能體

​刪除智能體

​智能體對象

​錯誤碼

建立智能體

列出智能體

檢索智能體

更新智能體

刪除智能體

智能體對象

錯誤碼