Assistant

更新时间：2024-12-11

本文档描述 Assistants API 中与 Assistant 相关的接口。

1.创建Assistant

功能介绍

创建一个Assistant

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants

请求方式：POST

请求参数

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
model	模型名	是	string	枚举 - ERNIE-4.0-8K - ERNIE-3.5-8K
name	assistant名	否	string	只允许中文，数字，大小写字母，下划线，中划线，最大长度为128个字符
description	assistant描述	否	string	最大长度限制 512个字符
response_format	回复格式	否	string	枚举： - text（默认） - json_object
instructions	系统人设指令	否	string	建议填写，能够提升模型的整体效果长度限制4096个字符，所有用户输入的token和需要小于4096 默认配置在run的过程中可动态修改。概述Agent的整体功能和定位，需要它扮演一个什么样的"角色。 1. 可以参考“你是xxx，你具有xx的特点，你可以做xxx，你需要满足用户xxx的需求”这样的结构。 2. 可以指定一些与能力边界相关要求（对于哪些类型的问题，无法回答）示例：你是一个音乐智能语音助手，可以通过调用技能的方式满足用户听音乐，看电影，追剧，刷短视频，听有声读物，信息问答等需求。你无法提供与政治和政策相关的内容；当用户提出与音乐、视频等娱乐信息不相关的问题时，你需要委婉地拒绝用户。
thought_instructions	思考规范	否	string	建议填写，能够提升模型的整体效果长度限制4096个字符，所有用户输入的token和需要小于4096 默认配置在run的过程中可动态修改。与业务逻辑和规则相关的指令。希望模型遵守的行为规范和准则、要求都尽可能清晰、详尽地在这里给出描述。包括但不限于：在什么情况下需要调用什么工具；在调用xxx工具之前需要先调用xxx工具获取什么信息； xxx工具填参的要求和偏好；（优先设定在工具描述中，如果较复杂，可以在这里强调）在模型判断结果无法满足用户时采取什么行动（换一个工具，或者改变参数调同一个工具，或是告知用户无法满足但努力基于当前信息提供结果，等）；示例：你需要遵循以下要求： 1.当用户给出特定的歌曲名，或者给出特定歌手，或者给出特定风格的音乐时，优先调用music_player工具 2.如果发现用户给出的是歌词，或者判断不出歌曲的名字、歌手时，请优先调用调用web_search工具获取歌名以及歌手，然后再去调用music_player工具 3.当web_search返回结果存在内容错误、质量差、不相关、资源陈旧以及信息量不足等情况时，你可以尝试优化查询词并重新调用web_search。
chat_instructions	回复规范	否	string	建议填写，能够提升模型的整体效果长度限制4096个字符，所有用户输入的token和需要小于4096 默认配置在run的过程中可动态修改与模型最终给出的回复内容相关的指令。包括但不限于： 1. 语气偏好 2. 回复格式要求 3. 回复内容的丰富程度 4. 开头和结尾的形式要求，例如在结尾时需要向用户提问引导话题深入进行示例： 1.你需要对用户的需求和问题给予耐心细致的回应；根据用户的输入，灵活调整对话内容，确保对话流畅自然。 2.当需要推荐电影给用户时，你需要按照以下格式输出：[电影名称](url)：推荐理由 3.可以在回复中适当插入emoji表情，提升亲切感
model_parameters	模型参数	否	`ModelParameters`	模型超参定义，包含思考模型和回复模型
tools	默认启用的工具列表	否	array [`Tool`] Tool的结构，请参见公共类型定义.请求对象	默认配置在run的过程中可动态修改建议 <= 5个，整体挂载工具个数 <= 10
file_ids	默认挂载的文件	否	array [string]	默认配置在run的过程中可动态修改整体最多不超过10个文件
metadata	元信息	否	map<string, string>	一组可以附加到对象的16个键值对。这对于以结构化格式存储关于对象的附加信息非常有用。键的长度最多为64个字符，值的长度最多可为512个字符

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "name": "chat_bot",
    "model": "ERNIE-4.0-8K",
    "description": "聊天助手"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
id	string	Assistant ID
object	string	对象类型，返回值固定为assistant
name	string	Assistant的名称
description	string	Assistant的描述
instructions	string	系统人设指令
tools	array [`Tool`]	预设工具
created_at	integer	创建的时间戳
thought_instructions	string	思考规范指令
chat_instructions	string	回复规范指令
response_format	string	响应格式
file_ids	array [`string`]	Assistant关联的文件列表
metadata	map<string, string>

响应示例

{
    "id": "asst_c088497ea43f41ebb75d0b859d6e2fb8",
    "object": "assistant",
    "name": "chat_bot",
    "description": "聊天助手",
    "instructions": "",
    "tools": [],
    "metadata": {},
    "created_at": 1712680718831,
    "thought_instructions": "",
    "chat_instructions": "",
    "response_format": "text",
    "file_ids": []
}

2.修改Assistant

功能介绍

根据assistant_id修改一个已创建的Assistant

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/update

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
assistant_id	Assistant对象的id	是	string	创建assistant接口响应中的id字段的值
model	模型名	否	string	枚举 - ERNIE-4.0-8K - ERNIE-3.5-8K
name	assistant名	否	string	只允许数字，大小写字母，下划线，中划线，最大长度为64个字符
description	assistant描述	否	string	最大长度限制 512个字符
response_format	回复格式	否	string	枚举： - text（默认） - json_object
instructions	系统人设指令	否	string	建议填写，能够提升模型的整体效果长度限制4096个字符，所有用户输入的token和需要小于4096 默认配置在run的过程中可动态修改。概述Agent的整体功能和定位，需要它扮演一个什么样的"角色。 1. 可以参考“你是xxx，你具有xx的特点，你可以做xxx，你需要满足用户xxx的需求”这样的结构。 2. 可以指定一些与能力边界相关要求（对于哪些类型的问题，无法回答）示例：你是一个音乐智能语音助手，可以通过调用技能的方式满足用户听音乐，看电影，追剧，刷短视频，听有声读物，信息问答等需求。你无法提供与政治和政策相关的内容；当用户提出与音乐、视频等娱乐信息不相关的问题时，你需要委婉地拒绝用户。
thought_instructions	思考规范	否	string	建议填写，能够提升模型的整体效果长度限制4096个字符，所有用户输入的token和需要小于4096 默认配置在run的过程中可动态修改。与业务逻辑和规则相关的指令。希望模型遵守的行为规范和准则、要求都尽可能清晰、详尽地在这里给出描述。包括但不限于：在什么情况下需要调用什么工具；在调用xxx工具之前需要先调用xxx工具获取什么信息； xxx工具填参的要求和偏好；（优先设定在工具描述中，如果较复杂，可以在这里强调）在模型判断结果无法满足用户时采取什么行动（换一个工具，或者改变参数调同一个工具，或是告知用户无法满足但努力基于当前信息提供结果，等）；示例：你需要遵循以下要求： 1.当用户给出特定的歌曲名，或者给出特定歌手，或者给出特定风格的音乐时，优先调用music_player工具 2.如果发现用户给出的是歌词，或者判断不出歌曲的名字、歌手时，请优先调用调用web_search工具获取歌名以及歌手，然后再去调用music_player工具 3.当web_search返回结果存在内容错误、质量差、不相关、资源陈旧以及信息量不足等情况时，你可以尝试优化查询词并重新调用web_search。
chat_instructions	回复规范	否	string	建议填写，能够提升模型的整体效果长度限制4096个字符，所有用户输入的token和需要小于4096 默认配置在run的过程中可动态修改与模型最终给出的回复内容相关的指令。包括但不限于： 1. 语气偏好 2. 回复格式要求 3. 回复内容的丰富程度 4. 开头和结尾的形式要求，例如在结尾时需要向用户提问引导话题深入进行示例： 1.你需要对用户的需求和问题给予耐心细致的回应；根据用户的输入，灵活调整对话内容，确保对话流畅自然。 2.当需要推荐电影给用户时，你需要按照以下格式输出：[电影名称](url)：推荐理由 3.可以在回复中适当插入emoji表情，提升亲切感
model_parameters	模型参数	否	`ModelParameters`	模型超参定义，包含思考模型和回复模型
tools	默认启用的工具列表	否	array [`Tool`] Tool的结构，请参见公共类型定义.请求对象	默认配置在run的过程中可动态修改建议 <= 5个，整体挂载工具个数 <= 10
file_ids	默认挂载的文件	否	array [string]	默认配置在run的过程中可动态修改整体最多不超过10个文件
metadata	元信息	否	map<string, string>	一组可以附加到对象的16个键值对。这对于以结构化格式存储关于对象的附加信息非常有用。键的长度最多为64个字符，值的长度最多可为512个字符

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/update' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "assistant_id":"asst_c088497ea43f41ebb75d0b859d6e2fb8"
    "name": "travel_bot",
    "model": "ERNIE-4.0-8K",
    "description": "旅游助手"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
id	string	Assistant ID
object	string	对象类型，返回值固定为assistant
name	string	Assistant的名称
description	string	Assistant的描述
instructions	string	系统人设指令
tools	array [`Tool`]	预设工具
created_at	integer	创建的时间戳
thought_instructions	string	思考规范指令
chat_instructions	string	回复规范指令
response_format	string	响应格式
file_ids	array [`string`]	Assistant关联的文件列表
metadata	map<string, string>

响应示例

{
    "id": "asst_c088497ea43f41ebb75d0b859d6e2fb8",
    "object": "assistant",
    "name": "travel_bot",
    "description": "旅游助手",
    "instructions": "",
    "tools": [],
    "metadata": {},
    "created_at": 1712680718831,
    "thought_instructions": "",
    "chat_instructions": "",
    "response_format": "text",
    "file_ids": []
}

3. 查询assistant列表

功能介绍

查询当前用户已创建的assistant列表

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/list

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
limit	列举结果数量上限	否	integer	默认值 - 20
order	排列顺序	否	string	按照Assistant对象的创建时间进行排序，默认desc，枚举： - desc（默认） - asc
after	查询指定assistant_id之后创建的Assistant	否	string	返回的列表中包含了指定id的对象
before	查询指定assistant_id之前创建的Assistant	否	string	返回的列表中包含了指定id的对象

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/list' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "limit": 20
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
object	string	结构类型，返回值固定为 list
data	array[`Object`]	Assistant对象列表
+id	string	Assistant ID
+object	string	对象类型，值固定为assistant
+name	string	Assistant的名称
+description	string	Assistant的描述
+instructions	string	系统人设指令
+tools	array [`Tool`]	预设工具
+created_at	integer	创建的时间戳
+thought_instructions	string	思考规范指令
+chat_instructions	string	回复规范指令
+response_format	string	响应格式
+file_ids	array [`string`]	Assistant关联的文件列表
+metadata	map<string, string>
first_id	string	返回的列表中第一条assistant的id
last_id	string	返回的列表中最后一条assistant的id
has_more	bool	在当前查询顺序下，除当前已获得的列表数据之外，是否还有更多项目可被继续查询

响应示例

{
    "object": "list",
    "data": [
        {
            "id": "asst_b71d860a5c3d449692dc5fdaa8d1d791",
            "object": "assistant",
            "name": "chat_bot_2",
            "description": "这是一个聊天助手",
            "instructions": "你是百度制作的AI助手",
            "tools": [],
            "metadata": {},
            "created_at": 1713377300260,
            "thought_instructions": "",
            "chat_instructions": "",
            "response_format": "json_object",
            "file_ids": []
        },
        {
            "id": "asst_cbb0fbeac9c242a5a40bbe66ddffd151",
            "object": "assistant",
            "name": "chat_bot_2",
            "description": "这是一个聊天助手",
            "instructions": "你是百度制作的AI助手",
            "tools": [],
            "metadata": {},
            "created_at": 1713377299561,
            "thought_instructions": "",
            "chat_instructions": "",
            "response_format": "text",
            "file_ids": []
        },
        {
            "id": "asst_ed8a223e75d2494690934e1e9214313a",
            "object": "assistant",
            "name": "chat_assistant",
            "description": "description",
            "instructions": "instructions",
            "tools": [
                {
                    "type": "code_interpreter"
                }
            ],
            "metadata": {},
            "created_at": 1713377297397,
            "thought_instructions": "thought_instructions",
            "chat_instructions": "每个回复的开头加一句我是高级的AI机器人",
            "response_format": "json_object",
            "file_ids": [
                "undefined"
            ]
        },
        {
            "id": "asst_d87aa1a25e88432389bf2065da360301",
            "object": "assistant",
            "name": "weather_report",
            "description": "这是一个天气查询助手",
            "instructions": "instructions",
            "tools": [
                {
                    "type": "function",
                    "function": {
                        "name": "get_cur_whether",
                        "description": "这是一个查询天气的工具",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "location": {
                                    "type": "string",
                                    "description": "省，市名，例如：河北省"
                                },
                                "unit": {
                                    "type": "string",
                                    "enum": [
                                        "摄氏度",
                                        "华氏度"
                                    ]
                                }
                            },
                            "required": [
                                "location"
                            ]
                        },
                        "responses": {}
                    }
                }
            ],
            "metadata": {},
            "created_at": 1713364477851,
            "thought_instructions": "thought_instructions",
            "chat_instructions": "chat_instructions",
            "response_format": "text",
            "file_ids": []
        }
    ],
    "first_id": "asst_b71d860a5c3d449692dc5fdaa8d1d791",
    "last_id": "asst_d87aa1a25e88432389bf2065da360301",
    "has_more": true
}

4. 查询assistant

功能介绍

根据assistant_id查询Assistant信息

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/query

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
assistant_id	Assistant对象的id	是	string

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/query' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "assistant_id": "asst_47af9f5660e24d09b7c2d9c6e34bee47"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
id	string	Assistant ID
object	string	对象类型，值固定为assistant
name	string	Assistant的名称
description	string	Assistant的描述
instructions	string	系统人设指令
tools	array [`Tool`]	预设工具
created_at	integer	创建的时间戳
thought_instructions	string	思考规范指令
chat_instructions	string	回复规范指令
response_format	string	响应格式
file_ids	array [`string`]	Assistant关联的文件列表
matadata	map<string, string>

响应示例

{
    "id": "asst_47af9f5660e24d09b7c2d9c6e34bee47",
    "object": "assistant",
    "name": "chat_bot",
    "description": "聊天助手",
    "instructions": "",
    "tools": [
        {
            "type": "code_interpreter"
        }
    ],
    "metadata": {},
    "created_at": 1712680718831,
    "thought_instructions": "",
    "chat_instructions": "",
    "response_format": "text",
    "file_ids": []
}

5. 删除assistant

功能介绍

根据assistant_id删除指定Assitant

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/delete

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
assistant_id	Assistant对象的id	是	string

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/delete' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "assistant_id": "asst_47af9f5660e24d09b7c2d9c6e34bee47"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
id	string	Assistant ID
object	string	对象类型，值固定为assistant.delete
deleted	bool	删除成功标记

响应示例

{
    "id": "asst_47af9f5660e24d09b7c2d9c6e34bee47",
    "object": "assistant.deleted",
    "deleted": true
}

6. 挂载File到Assistant

功能介绍

指定file_id和assistant_id，挂载File到对应的Assistant

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/files

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
assistant_id	Assistant对象的id	是	string
file_id	File对象的id	是	string

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/files' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "assistant_id": "asst_b71d860a5c3d449692dc5fdaa8d1d791"
    "file_id":"file-537701076095045"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
id	string	File对象的id，值等于入参
object	string	对象类型，值固定为assistant.file
created_at	integer	创建的时间戳
assistant_id	string	Assistant对象的id，值等于入参

响应示例

{
    "id": "file-537701076095045",
    "object": "assistant.file",
    "created_at": 1713439860928,
    "assistant_id": "asst_b71d860a5c3d449692dc5fdaa8d1d791"
}

7. 查询Assistant挂载的File列表

功能介绍

查询Assistant挂载的File列表

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/files/list

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
assistant_id	Assistant对象的id	是	string
limit	列举结果数量上限	否	integer	默认值 - 20
order	排列顺序	否	string	按照Assistant对象的创建时间进行排序，默认desc，枚举： - desc（默认） - asc
after	查询指定file_id之后创建的file_id列表	否	string	返回的列表中包含了指定id的对象
before	查询指定file_id之前创建的file_id列表	否	string	返回的列表中包含了指定id的对象

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/files/list
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "assistant_id": "asst_b71d860a5c3d449692dc5fdaa8d1d791"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
object	string	结构类型，返回值固定为list
data	array[`Object`]	File列表
+id	string	File对象的id
+object	string	对象类型，值固定为assistant.file
+created_at	integer	创建的时间戳
+assistant_id	string	Assistant对象的id，值等于入参
first_id	string	返回的列表中第一条File的id
last_id	string	返回的列表中最后一条File的id
has_more	bool	在当前查询顺序下，除当前已获得的列表数据之外，是否还有更多项目可被继续查询

响应示例

{
    "object": "list",
    "data": [
        {
            "id": "file-537701076095045",
            "object": "assistant.file",
            "created_at": 1708660019145,
            "assistant_id": "asst_b71d860a5c3d449692dc5fdaa8d1d791"
        }
    ],
    "first_id": "file-537701076095045",
    "last_id": "file-537701076095045",
    "has_more": false
}

8. 解绑Assistant挂载的File

功能介绍

指定assistant_id和file_id，解绑Assistant中对应File的关联

请求说明

基本信息

请求地址：https://appbuilder.baidu.com/v2/assistants/files/delete

请求方式：POST

请求参数

Header

请参考公共类型定义中，公共请求头的定义

Body

参数	语义	是否必填	取值/类型	备注
assistant_id	Assistant对象的id	是	string
file_id	File对象的id	是	string

请求示例

curl -X POST 'https://appbuilder.baidu.com/v2/assistants/files/delete' \
-H "Authorization: Bearer $APPBUILDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
    "assistant_id": "asst_b71d860a5c3d449692dc5fdaa8d1d791"
    "file_id":"file-537701076095045"
}'

响应说明

响应参数

Header

请参考公共类型定义中，公共响应头的定义

Body

字段	类型	描述
id	string	File对象的id
object	string	对象类型，值固定为assistant.file.delete
deleted	bool	删除成功标记

响应示例

{
    "id": "file-537701076095045",
    "object": "assistant.file.deleted",
    "deleted": true
}

千帆AppBuilder

Assistant

1.创建Assistant

功能介绍

请求说明

基本信息

请求参数

Header

Body

请求示例

响应说明

响应参数

Header

Body

响应示例

2.修改Assistant

功能介绍

请求说明

基本信息

请求参数

Header

Body

请求示例

响应说明

响应参数

Header

Body

响应示例

3. 查询assistant列表

功能介绍

请求说明

基本信息

请求参数

Header

Body

请求示例

响应说明

响应参数

Header

Body

响应示例

4. 查询assistant

功能介绍

请求说明

基本信息

请求参数

Header

Body

请求示例

响应说明

响应参数

Header

Body

响应示例

5. 删除assistant

功能介绍

请求说明

基本信息

请求参数

Header

Body

请求示例

响应说明

响应参数

Header

Body

响应示例

6. 挂载File到Assistant

功能介绍

请求说明

基本信息

请求参数

Header

Body

请求示例

响应说明

响应参数

Header

Body

响应示例