AI助手对话
更新时间：2026-03-13
POST
https://qianfan.baidubce.com/v2/agent/ai_assistant/run
本接口用于与“AI助手”智能体进行对话。支持智能调度、通用问答、图像问答三种模式。
若需调用图像问答功能，请遵循以下流程：
权限说明
调用本文API，需使用API Key鉴权方式。使用API Key鉴权调用API流程，具体调用流程，请查看认证鉴权。
请求参数
Headers 参数
除公共头域外，无其它特殊头域
Body 参数
conversation_id
string
会话ID，为空时自动创建新会话
可选
end_user_id
string
终端用户ID，若传入，则只返回该用户的历史记录。
用户自定义上传，长度限制为 6 ～ 63 字符。
可选
messages
array
消息列表，支持传入多轮对话信息
必选
显示子属性
隐藏子属性
items
object {2}
显示子属性
隐藏子属性
role
string
角色
user：用户assistant：AI助手
必选
content
array
内容列表
必选
显示子属性
隐藏子属性
items
object
anyOf {2}
可选择符合一个或多个
显示子属性
隐藏子属性
items
object {2}
type = text
显示子属性
隐藏子属性
text
string
正文文本内容
必选
type
string
内容类型，固定为text
必选
items
object {2}
type = file
显示子属性
隐藏子属性
file
object {1}
文件内容
必选
显示子属性
隐藏子属性
type
string
内容类型，固定为file
必选
scene_mode
string
场景模式，默认值 auto。
可选值:
auto：智能调度general_qa：通用问答image_qa：图像问答
可选
scene_mode_settings
string
为当前scene_mode启用高级配置参数，结构为 JSON 字符串，不同的场景模式支持各自的参数。
- 自动模式：
auto - 及时响应：
disabled - 深度思考：
enabled
例：选择通用问答中深度思考模式，"scene_mode_settings": "{\"deep_think\":\"auto\"}"
可选
user_profile
object {2}
用户个性化信息
可选
显示子属性
隐藏子属性
device
string
用户的设备信息
可选
location_info
object {5}
用户位置信息
可选
显示子属性
隐藏子属性
province
string
当前位置所在省份。天气/新闻/票务查询时需传入
可选
city
string
当前位置所在市。天气/新闻/票务查询时需传入
可选
district
string
当前位置所在区。天气/新闻类查询时需传入
可选
town
string
当前位置所在县/街道。天气/新闻类查询时需传入
可选
detail
string
详细地址与门牌号
可选
stream
boolean
是否启用流式返回，默认值 true
可选
additional_knowledge
object {2}
将你的私有/本地知识注入模型，与联网搜索结果一起作为回答依据
可选
显示子属性
隐藏子属性
priority
integer
搜索结果的优先级，取值范围：-1 到 1，默认值为 0。
- -1：最高，私有知识优先被采用，覆盖搜索结果
- 0：中等，与百度搜索结果同级，按相关性混合使用
- 1：最低，仅当其他知识不足时作为补充参考
例如：-1 为优先级最高，若与百度搜索结果优先级相同，则优先使用定制化知识点
可选
data
object {4}
数据对象
可选
显示子属性
隐藏子属性
content
string
知识正文内容
必选
title
string
知识点标题
可选
url
string
知识点 URL 地址
可选
release_date
string
发布日期
可选
请求结构
POST /v2/agent/ai_assistant/run HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: Bearer <API Key>
Content-Type: application/json
{
"conversation_id": "dd445e78-****-499d-97af-739520965ea1",
"stream": true,
"scene_mode": "image_qa",
"end_user_id": "user-001",
"messages": [{
"role": "user",
"content": [
{
"type": "file",
"file": {
"id": "file-g5v9tgjw"
}
},
{
"type": "text",
"text": "请分析这张图片中的内容。"
}
]
}]
}示例代码
请求示例
curl -X POST "https://qianfan.baidubce.com/v2/agent/ai_assistant/run" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer bce-v3/ALTAK-yd********ftZDTn7/125eeb1c5e9ddc8cf3edf18ef6d03f1517ec9408" \
-d '{
"stream": true,
"messages": [
{
"role": "user",
"content": [{"type": "text", "text": "我想减肥，有什么建议？"}]
},
{
"role": "assistant",
"content": [{"type": "text", "text": "建议从饮食控制和运动两方面入手..."}]
},
{
"role": "user",
"content": [{"type": "text", "text": "具体每天应该摄入多少卡路里？"}]
}
],
"scene_mode": "general_qa",
"scene_mode_settings": "{\"deep_think\":\"enabled\"}",
"user_profile": {
"device": "iPhone",
"location_info": {
"province": "北京市",
"city": "北京市",
"district": "海淀区"
}
}
}'返回响应
Headers 参数
除公共头域外，无其它特殊头域
返回参数
trace_id
string
请求追踪ID，用于问题排查
必选
message_id
string
消息唯一标识，用于消息反馈、重新生成等操作
必选
conversation_id
string
会话ID
必选
actions
object {3}
Agent 执行的动作、状态信息、工具请求和工具结果等事件
可选
显示子属性
隐藏子属性
scene_mode
string
场景路由模型
可选
processing_state
object {2}
AI 助手在本次请求中的处理状态信息
- 在流式响应中，该参数通过事件形式返回，用于驱动前端实时交互与状态展示
- 在非流式响应中，该参数仅返回最终状态
- 该字段不包含任何模型推理或思考过程内容，也不代表模型内部实现细节。
可选
显示子属性
隐藏子属性
phase
string
当前处理阶段标识
- thinking：正在进行深度分析或复杂推理
- search_begin：正在联网搜索中
- search_finish：搜索完成并输出搜索数量
- generating：正在生成最终回答内容
- done：本次请求已处理完成
必选
description
string
用于展示当前处理阶段的自然语言说明
可选
steps
oneOf {3}
多选一且必需“只能”符合其中一个
执行步骤列表，记录 AI 助手处理请求的完整执行轨迹。包含思考、工具调用、搜索等所有处理步骤。
- 在流式响应中，通过事件形式增量返回步骤信息
- 在非流式响应中，返回完整的步骤历史
可选
显示子属性
隐藏子属性
steps
object {5}
ReasoningStep
显示子属性
隐藏子属性
id
string
步骤唯一标识
同一 conversation 内唯一，用于区分不同步骤的数据或对同一步骤的数据拼接。
必选
parent_id
string
父步骤 ID。
- 空：表示顶层步骤
- 非空：表示该步骤是parent_id步骤的子步骤，用于构建执行树结构
可选
type
string
内容：reasoning
可选
text
string
文本内容：type=reasoning时
可选
status
string
- preparing：准备中
- done：完成
可选
steps
object {5}
ToolCallsStep
显示子属性
隐藏子属性
id
string
步骤唯一标识 同一 conversation 内唯一，用于区分不同步骤的数据或对同一步骤的数据拼接。
必选
parent_id
string
父步骤 ID。
- 空：表示顶层步骤
- 非空：表示该步骤是parent_id步骤的子步骤，用于构建执行树结构
可选
type
string
内容：tool_call
可选
tool_call
object {4}
工具调用的资源返回内容：type=tool_call时
可选
显示子属性
隐藏子属性
name
string
工具名称
必选
name_cn
string
工具中文名
可选
icon
string
工具的图标地址（如工具 favicon或工具网站的logo）
可选
args
string
工具输入参数（通常为 JSON 字符串）。
可选
status
string
- preparing：准备中
- done：完成
可选
steps
object {4}
ReferencesStep
显示子属性
隐藏子属性
id
string
步骤唯一标识 同一 conversation 内唯一，用于区分不同步骤的数据或对同一步骤的数据拼接。
必选
parent_id
string
父步骤 ID。
- 空：表示顶层步骤
- 非空：表示该步骤是parent_id步骤的子步骤，用于构建执行树结构
可选
type
string
内容：references
必选
references
array
引用内容：type=references时
必选
显示子属性
隐藏子属性
items
object {9}
显示子属性
隐藏子属性
id
number
引用序号，用于正文中标注引用（如 [1]、[2]）
必选
title
string
引用来源的标题
必选
url
string
引用来源的链接地址
必选
type
string
检索资源类型。返回值如下：
- web：网页
- image：图像
- video：视频
可选
website
string
来源站点或平台名称
必选
icon
string
来源平台的图标地址
可选
content
string
引用内容的摘要或片段
可选
date
string
内容发布时间
可选
web_anchor
string
网站锚文本或网站标题
必选
messages
object {2}
Agent 回复的消息
可选
显示子属性
隐藏子属性
role
string
角色，固定为 assistant
必选
content
oneOf {5}
多选一且必需“只能”符合其中一个
内容列表
必选
显示子属性
隐藏子属性
content
object {2}
文本内容
显示子属性
隐藏子属性
type
string
内容类型，固定为text
必选
text
string
正文文本内容（当 type = text 时必填）
必选
content
object {2}
图像内容
显示子属性
隐藏子属性
type
string
内容类型，固定为images
必选
images
array
多图资源
必选
显示子属性
隐藏子属性
items
object {4}
显示子属性
隐藏子属性
url
string
图片资源地址
必选
alt
string
资源说明文本
可选
title
string
资源标题
可选
thumbnail
string
缩略图地址
可选
content
object {2}
视频内容
显示子属性
隐藏子属性
type
string
内容类型，固定为videos
必选
videos
array
多视频资源
必选
显示子属性
隐藏子属性
items
object {4}
显示子属性
隐藏子属性
url
string
视频资源地址
必选
alt
string
资源说明文本
可选
title
string
资源标题
可选
hover_image
string
视频封面图
可选
content
object {2}
文件内容
显示子属性
隐藏子属性
type
string
内容类型，固定为file
必选
file
object {5}
文件内容（当 type = file 时必填）
必选
显示子属性
隐藏子属性
id
string
文件唯一标识
必选
name
string
文件名（含扩展名）
可选
size
string
文件大小（字节），前端可格式化为 KB/MB
可选
url
string
下载地址，有效期 30 天
必选
thumbnail
string
缩略图地址（PPT/PDF 首页预览）
可选
content
object {2}
卡片内容
显示子属性
隐藏子属性
type
string
内容类型，固定为card
必选
card
object {3}
富媒体卡片内容（当 type = card 时必填）
必选
显示子属性
隐藏子属性
type
string
卡片类型，支持media、file、code、weather、stock、link、chart、table、location
必选
title
string
卡片标题
可选
data
anyOf {10}
可选择符合一个或多个
卡片数据，结构根据 type 变化
必选
显示子属性
隐藏子属性
data
object {3}
type=media
显示子属性
隐藏子属性
layout
string
布局方式：grid / carousel / masonry，默认 grid
可选
columns
integer
列数，1-4，默认 3
可选
items
array
媒体列表
必选
显示子属性
隐藏子属性
items
object {10}
显示子属性
隐藏子属性
type
string
媒体类型：image / video
必选
url
string
资源地址
必选
thumbnail
string
缩略图/封面
可选
width
integer
宽度（像素）
可选
height
integer
高度（像素）
可选
duration
number
视频时长（秒）
可选
alt
string
替代文本
可选
caption
string
说明文字
可选
source
string
资源来源
可选
source_url
string
来源的图标url
可选
data
object {2}
type=code
显示子属性
隐藏子属性
language
string
编程语言
必选
code
string
代码内容
必选
data
object {4}
type=file
显示子属性
隐藏子属性
url
string
文件下载地址
必选
filename
string
文件名
必选
size
integer
文件大小（字节）
必选
format
string
文件格式
必选
data
object {5}
type=weather
显示子属性
隐藏子属性
city
string
城市名称
必选
temperature
number
温度（摄氏度）
必选
weather
string
天气状况
必选
humidity
integer
湿度百分比
可选
wind
string
风力风向
可选
data
object {5}
type=stock
显示子属性
隐藏子属性
symbol
string
股票代码
必选
name
string
股票名称
必选
price
number
当前价格
必选
change
number
涨跌幅百分比
必选
volume
integer
成交量
可选
data
object {4}
type=link
显示子属性
隐藏子属性
url
string
链接地址
必选
title
string
链接标题
必选
description
string
链接描述
可选
image
string
预览图地址
可选
data
object {3}
type=chart
显示子属性
隐藏子属性
chart_type
string
图表类型：line / bar / pie / scatter
必选
data
object {0}
图表数据
必选
显示子属性
隐藏子属性
暂无参数
options
object {0}
图表配置项
可选
显示子属性
隐藏子属性
暂无参数
data
object {2}
type=table
显示子属性
隐藏子属性
headers
array
表头，string 数组
必选
显示子属性
隐藏子属性
items
string
rows
array
数据行，二维 string 数组
必选
显示子属性
隐藏子属性
items
string
data
object {4}
type=location
显示子属性
隐藏子属性
name
string
地点名称
必选
address
string
详细地址
必选
lat
number
纬度
必选
lng
number
经度
必选
data
object {2}
type=aladdin
显示子属性
隐藏子属性
type
string
阿拉丁卡片类型
可选
data
object {0}
阿拉丁卡片结构化信息
可选
显示子属性
隐藏子属性
暂无参数
follow_ups
array
追问内容
可选
显示子属性
隐藏子属性
items
string
追问
references
array
正文内容参考的引用内容
可选
显示子属性
隐藏子属性
items
object {9}
显示子属性
隐藏子属性
id
number
引用序号，用于正文中标注引用（如 [1]、[2]）
必选
title
string
引用来源的标题
必选
url
string
引用来源的链接地址
必选
type
string
检索资源类型。返回值如下：
- web：网页
- image：图像
- video：视频
可选
website
string
来源站点或平台名称
必选
icon
string
来源平台的图标地址
可选
content
string
引用内容的摘要或片段
可选
date
string
内容发布时间
可选
web_anchor
string
网站锚文本或网站标题
必选
entities
array
实体百科词条信息
可选
显示子属性
隐藏子属性
items
object {6}
显示子属性
隐藏子属性
keyword
string
实体名称
必选
offset
integer
实体首字偏移量
必选
length
integer
实体字数
必选
lemma_title
string
百度词条名称
必选
lemma_url
string
百度词条链接
必选
lemma_id
integer
百度词条ID
必选
code
integer
错误码，成功时为 0
可选
message
string
错误信息，成功时为空
可选
JSON
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "actions": {"processing_state": {"phase": "thinking", "description": "正在思考"}}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "actions": {"processing_state": {"phase": "search_begin", "description": "正在搜索"}}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "actions": {"steps": [{"id": "203f2853-7a6b-4d3e-9612-be5c2dc0c387", "type": "references", "references": [{"id": 1, "title": "健康减肥食谱一日三餐怎么安排 - 专家文章", "url": "http://k.sina.com.cn/article_7857201856_1d45362c001902zjfa.html", "type": "web", "website": "新浪网", "content": "每日总热量摄入应比日常消耗减少500-750千卡,成年女性建议控制在1200-1500千卡,男性1500-1800千卡。", "date": "2026-03-08 13:59:00"}], "status": "running"}]}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "actions": {"processing_state": {"phase": "search_finish", "description": "搜索到6篇资料"}}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "actions": {"processing_state": {"phase": "generating", "description": "正在生成"}}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "messages": {"role": "assistant", "content": [{"type": "text", "text": "# 减肥期间每日卡路里摄入建议"}]}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "messages": {"role": "assistant", "content": [{"type": "text", "text": "- **成年女性**：$1200-1500$ 千卡 ^[1][4][5][6]^"}]}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "messages": {"role": "assistant", "content": [{"type": "text", "text": "- **成年男性**：$1500-1800$ 千卡 ^[1][2][6]^"}]}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "actions": {"processing_state": {"phase": "done", "description": "已完成"}}}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "references": [{"id": 1, "title": "健康减肥食谱一日三餐怎么安排 - 专家文章", "url": "http://k.sina.com.cn/article_7857201856_1d45362c001902zjfa.html", "type": "web", "website": "新浪网", "content": "每日总热量摄入应比日常消耗减少500-750千卡,成年女性建议控制在1200-1500千卡,男性1500-1800千卡。", "date": "2026-03-08 13:59:00"}, {"id": 3, "title": "体重110斤但想健康减重的人,应该遵循怎样的科学饮食原则?", "url": "http://k.sina.com.cn/article_7879922980_1d5ae152406801fr1o.html", "type": "web", "website": "新浪网", "content": "根据国家卫健委《肥胖食养指南》,成人减重期每日能量摄入可比正常需求减少20%左右,每月减重4-8斤(2–4公斤)最为合理。", "date": "2026-03-12 14:56:00"}]}
data: {"trace_id": "c04ad33d-fe9a-41f7-b4cc-666673e6598e", "conversation_id": "268a978d-8f90-47aa-8716-f960a742f4b8", "follow_ups": [{"item": "减肥期间如何保证营养均衡？"}, {"item": "有哪些低卡路里的食物推荐？"}, {"item": "运动对减肥有什么帮助？"}]}