资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

Assistant

本文档描述 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
}