Assistants（下线中） - 阿里云百炼

Assistant API下线中，建议迁移至Responses API：内置多种工具，并支持多轮上下文管理，可作为替代方案。

功能介绍：如果您想了解 Assistant API 的功能和基本用法，请参考Assistant API功能概览。

有效期限：所有 Assistant 实例均保存在阿里云百炼服务器上，目前没有失效日期，您可通过 assistant.id 检索智能体。

智能体应用（Agent 1.0）和 Assistant 虽然均为大模型应用，但二者的功能相互独立，使用方法也不相同。

智能体应用：仅可使用控制台进行创建、查看、更新和删除，以及通过应用调用 API进行调用。
Assistant：仅可使用 Assistant API 创建、查看、更新、删除和调用 Assistant 。

创建智能体

创建一个新的智能体。

HTTP
SDK

代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/assistants' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "qwen-max",
    "name": "智能小助手",
    "description": "这是一个智能小助手",
    "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
    "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

assistant = Assistants.create(
        # 建议您优先配置环境变量。若没有配置环境变量，请用百炼API Key将下行替换为：api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # 此处以qwen-max为例，可按需更换模型名称。模型列表：https://help.aliyun.com/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.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"
}

输出参数输出一个智能体对象列表。

代码示例

from dashscope import Assistants
import os

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.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 os

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.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "instructions": "你是一个搜索助手",
    "name": "新建应用-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 os

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.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 os

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	智能体关联的调用的唯一标识符。

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。

​创建智能体

​列出智能体

​检索智能体

​更新智能体

​删除智能体

​智能体对象

​错误码

创建智能体

列出智能体

检索智能体

更新智能体

删除智能体

智能体对象

错误码