Assistant_大模型服务平台百炼(Model Studio)-阿里云帮助中心

Assistant API 是百炼应用的开发工具，旨在帮助您快速、方便地构建 AI 对话助手。本文详细阐述了 Assistant API 中 Assistant 类的各项功能，涵盖了智能体的创建、列举、检索、更新以及删除等操作。

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

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

创建智能体

HTTP

代码示例

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，用户需要在百炼中被注册, 自定义tool鉴权信息传递 `{ "type": "plugin_type", "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

代码示例

Python

from dashscope import Assistants
import os

assistant = Assistants.create(
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        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;

public class Main {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Assistants assistants = new Assistants();
        // build assistant parameters
        AssistantParam param = AssistantParam.builder()
                .model("qwen-max")
                .name("intelligent guide")
                .description("a smart guide")
                .instructions("You are a helpful assistant.")
                .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	DashScope workspace id
api_key	string	None	DashScope 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	key，value对对象信息，描述智能体信息。
tools	array	智能体可以用的tool列表。
created_at	integer	智能体创建的时间戳表示。
code	string	表示请求失败，表示错误码，请求成功时忽略。只有在通过Python调用失败时会显示。
message	string	失败，表示失败详细信息，成功忽略。只有在通过Python调用失败时会显示。

列出智能体

用于返回智能体列表。

HTTP

代码示例

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

输出参数

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

SDK

代码示例

Python

from dashscope import Assistants
assistants = Assistants.list(limit=1,
                             order='desc',
                             after='',
                             before='')

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;

public class Main {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
      Assistants assistants = new Assistants();
      GeneralListParam listParam = GeneralListParam.builder().limit(10l).build();
      ListResult<Assistant> assistant = assistants.list(listParam);
    }
}

输入参数

参数	类型	默认值	说明
limit	string	-	指定列出assistant的数目
order	string		排序方式，示例值：desc、asc
after	string
before	string
workspace	string	None	百炼的workspace id，如果为主账号空间则无需指定
api_key	string	None	DashScope 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.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

代码示例

Python

from dashscope import Assistants
assistant = Assistants.retrieve('assistant_id')

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;

public class Main {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
      Assistants assistants = new Assistants();
      Assistant assistant = assistants.retrieve("assistant_id");
      // use assistant
    }
}

输入参数

参数	类型	默认值	说明
assistant_id	string	-	指定要查询的智能体id
workspace	string	None	百炼的workspace id，如果为主账号空间则无需指定
api_key	string	None	DashScope api key，可以通过环境变量等方法设置。

输出参数

请参考

更新智能体

HTTP

代码示例

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-allinone",
    "name": "新建应用-assistantAPI",
    "description": "",
    "instructions": "你是一个搜索助手",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "text_to_image"
        },
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "request_id": "b0993831-a98b-9e71-b235-75174df9046e"
}

输出参数

输出更新后的智能体对象。

SDK

代码示例

Python

from dashscope import Assistants
assistants = Assistants.update('assistant_id', model='new_model_name')

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;

public class Main {
    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.")
      .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	string	None	DashScope API key，可以通过环境变量等方法设置。

输出参数

请参考智能体对象。

删除智能体

HTTP

代码示例

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

输出参数

输出删除智能体后的状态。

SDK

代码示例

Python

from dashscope import Assistants
assistants = Assistants.delete('assistant_id')

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;

public class Main {
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
      Assistants assistants = new Assistants();     
      DeletionStatus assistant = assistants.delete("assistant_id");
    }
}

输入参数

参数	类型	默认值	说明
assistant_id	string	-	指定要删除的智能体 id
workspace	string	None	百炼的workspace id，如果为主账号空间则无需指定
api_key	string	None	DashScope 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`。
create_at	integer	创建智能体时的 Unix 时间戳（以秒为单位）。
model	string	智能体使用的模型名。您可以在功能概览查看所有可用模型，或者查看模型列表以了解它们的详情。
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	智能体关联的调用的唯一标识符。