本文档介绍智能体会话API接口的输入输出参数。调用该接口可获取智能体的大模型回复、参考资料、富媒体卡片数据，实现追问、引用角标、图文混排、百科划线词等高级产品功能。

接口限流：火山账号维度，默认300 RPM。

认证方式

接口详情

智能体会话

URL

URL	API Key接入：https://open.feedcoopapi.com/agent_api/agent/chat/completion Access Key接入：https://mercury.volcengineapi.com?Action=ChatCompletion&Version=2026-01-01
Method	POST
Header	API Key接入： Authorization: Bearer <API_KEY> Content-Type：application/json ServiceName: ask_echo Access Key接入： Content-Type：application/json 此接入方式基于火山引擎访问控制的AK/SK鉴权，统一使用 ServiceName=ask_echo，接口验签及请求公共参数逻辑遵循火山引擎官网的统一规范，详情请参见：签名方法--API签名调用指南-火山引擎；

请求体ChatCompletionRequest

参数	类型	必须	描述
bot_id	String	是	智能体ID，在控制台创建智能体后获取
messages	Array[Message]	是	要求 messages 数组不可为空。我们最多使用传入的10条消息。如果消息超过10条，则仅保留数组中最后10条消息。特殊情况：如果第一个消息为system 类型，则始终保留该消息。上下文窗口越大，总结的上下文越全，但响应时间和消耗的Token也会变多，需根据实际场景合理选择。 system 类型消息的字符上限是1万，超过会被截断。示例单轮对话示例 "messages": [ {"role": "user","content": "你好"}] 多轮对话示例 "messages": [ {"role":"system","content": "你是一个联网问答助手"}, {"role":"user","content": "你好"}, {"role":"assistant","content":"需要什么帮助"}, {"role":"user","content":"自我介绍下"} ]
stream	Boolean	否	是否启用流式响应，默认 false（非流式）。建议流式调用。
user_id	String	否	用户身份标识
device_id	String	否	设备身份标识
location_info	LocationInfo	否	当前地理位置信息（使用出行工具时必传，其他情况选传）
navigation_info	NavigationInfo	否	当前导航信息（使用出行工具搜导航周边时必传）
knowledge	String	否	背景知识注入字段，需要带入环境信息、背景知识时使用 "knowledge":"当前正在驾驶问界M8增程MAX版，车内正在播放音乐《天黑黑》"
model	String	否	默认无需传递 model=thinking，开启深度思考模式 model=auto_thinking，开启自动深度思考模式 model=reasoning_search，开启边想边搜模式 model=symptom_check：（小荷健康）症状自查，仅支持文本输入 model=triage_navigation：（小荷健康）分诊导诊，仅支持文本输入 model=report_interpretation：（小荷健康）报告解读，图片输入必填 model=medication_guidance：（小荷健康）用药指导，图片输入选填
extension_options	ExtensionOptions	否	扩展配置参数。在特定场景下开白启用，使用前请咨询销售/售前/售后同学。不承诺扩展参数在随意传入情况下的接口稳定返回。
memory	String	否	用户的个性化记忆数据。示例如下。用户画像：性别男。青年。家乡是湖北省武汉市。居住地是北京。职业为工程师。左撇子。有过敏性鼻炎。常去的公园是北京颐和园，常去的商场是北京西单大悦城。上班出门时间是9:00。上班到公司时间是10:00。下班时间是20:00。下班到家时间是21:00。用户兴趣：用户对计算机科学与技术领域有深入且专业的兴趣，可能具备相关从业背景。其提问内容涉及搜索/推荐系统、机器学习、软件开发（Python、Java、ADB）等多个方向，表明用户需要专业、精准的技术解答和方案。用户关注消费电子产品，特别是智能手机及核心组件（如处理器）。提问聚焦于具体型号的价格、发售日期、技术参数（如芯片制程）及供应链信息，需要精准、及时的产品情报。用户每周六都会去健身房健身，记录时间2026年2月26日。用户下周一乘坐飞机，出发地是北京，到达地是深圳，出发时间是2026年3月2日，记录时间2026年2月26日。

Message

参数	类型	必须	描述
role	String	是	user：表示用户的输入的问题或指令 assistant：表示AI助手的回复 system：SystemPrompt
content	String/Object	是	对话消息列表文本对话场景： "content": "You are a helpful assistant." 多模态场景：图片参数要求：图片张数：目前最多支持10张，超过10张会报参数错误数据类型：支持WebUrl和DataUrl 建议使用Base64后的DataUrl，WebUrl需要下载，可能存在下载延迟和不稳定问题样例： WebUrl：https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg DataUrl：data:{MIME Type};base64,{base64_image} data:image/jpeg;base64,{base64_image} 图片格式支持：JPEG、PNG、GIF、WEBP、BMP、TIFF、HEIC、HEIF（详情见图片格式说明）图片大小：单张图片推荐大小：<=500KB 最大限制： WebUrl传入 APIKey接入：单张图片大小<10M，超出会报参数错误 TOP网关接入：请求体整体长度不能超过8M DataUrl传入 APIKey接入：单张图片Base64编码后长度<20M，超出会报参数错误 TOP网关接入：请求体整体长度不能超过8M 单图片尺寸判断，如果图片超出下面的限制，会直接报错，传入图片满足下面条件（单位 px）：宽 > 14 且高>14 宽*高范围： [196, 36000000] "content": [ { "type": "text", "text": "What'\''s in this image?" }, { "type": "image_url", "image_url": { "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" } } ] 文件参数要求：支持对可在公网访问的文件url进行内容解析文件格式支持：pdf、doc、docx、ppt、pptx、xls、xlsx、csv、txt、text、epub、mobi、xml "content": [ { "type": "text", "text": "请描述这个文档的内容" }, { "type": "file_url", "file_url": { "url": "https://example.docx" } } ]
reasoning_content	String	否	如果选择了深度思考模式，会在总结前输出模型的思考过程，通过此字段透出。

LocationInfo

参数	类型	必须	描述	备注
province	String	否	当前位置所在省份。天气/新闻/票务查询需传。	组合传入（建议）参数传入哪一层级，则读取哪一层级返回总结
city	String	否	当前位置所在市。天气/新闻/票务查询需传。
district	String	否	当前位置所在区。天气/新闻类查询需传。
town	String	否	当前位置所在县/街道。天气/新闻类查询需传。
longitude	Number	否	当前位置经度。使用出行工具时必传，需与纬度组合传入。	组合传入
latitude	Number	否	当前位置纬度。使用出行工具时必传，需与经度组合传入。	组合传入

NavigationInfo

参数	类型	必须	描述	备注
destination	LocationInfo	否	目的地信息，搜导航周边时需传	经纬度必传
via	Array[LocationInfo]	否	途经点信息，搜导航周边时需传	经纬度必传，途径点依次按顺序传入，最多支持3个

ExtensionOptions

参数	类型	必须	描述
filter_emoji	Boolean	否	为true时，过滤大模型输出的emoji表情
enable_processing_state	Boolean	否	为true时，输出智能体执行的关键过程，仅流式输出生效，详情见高级功能-输出关键执行过程
disable_source_type_douyin_video	Boolean	否	为true时，关闭控制台已经配置的抖音视频内容源
disable_follow_up	Boolean	否	为true时，关闭控制台已经开启的追问功能
disable_citation	Boolean	否	为true时，关闭控制台已经开启的引用角标功能
disable_image_text_mix	Boolean	否	为true时，关闭控制台已经开启的图文混排功能
disable_baike_highlight	Boolean	否	为true时，关闭控制台已经开启的百科划线词功能
disable_text_to_image	Boolean	否	为true时，关闭控制台已经开启的搜图功能
enable_search_lite	Boolean	否	为true时，开启控制台关闭的极速模式（耗时短，但效果会变差）
browsing_mode	Number	否	此参数用于控制联网行为，优先级高于控制台配置，影响文搜和图搜链路的处理逻辑参数值： 1 - 自动联网：等价于控制台默认的“自动联网”设置 2 - 强制联网：文搜链路至少使用一个搜索源进行联网搜索与总结图搜链路尽可能尝试联网，但不保证一定联网 3 - 关闭联网：完全关闭联网能力，不使用任何联网资源进行搜索或总结
card_position	String	否	用于控制Cards字段返回位置。推荐元数据帧出卡，该方式会降低TTFT 不传或first_frame-首帧出卡 meta_frame-元数据帧出卡
enable_followup_in_response	Boolean	否	为true时，开启结尾强化追问功能
disable_ecom_link	Boolean	否	为true时，禁用电商意图，电商链接不会用于总结和出卡
disable_video_text_mix	Boolean	否	为true时，关闭控制台已经开启的视频文本混排
learn_mode	String	否	用于控制是否使用解题链路不传则不走入解题链路传入auto_learning则会根据意图判断走入解题链路注意：model=thinking/auto_thinking/reasoning_search/symptom_check/triage_navigation/report_interpretation/medication_guidance时，该参数不生效
reasoning_effort	String	否	用于控制思维链（reasoning_content）的长度，枚举值：high/medium/low 不传，使用系统预设思考长度（high）传入不可用值： String类型，使用系统预设思考长度非String类型，返回参数校验错误
sites	Array[String]	否	限定搜索的站点范围，最多支持20个。需填入完整域名，示例： ["aliyun.com", "news.qq.com"]
block_hosts	Array[String]	否	屏蔽搜索站点，最多支持20个。和限定搜索站点范围相比，屏蔽站点的优先级更高。需填入完整域名，示例： ["aliyun.com", "news.qq.com"]
search_auth_info_level	Number	否	指定仅在非常权威站点内搜索（非常权威站点请参考：站点权威度分级说明）。默认不限制。参数值： 1：限制搜索站点为【非常权威】 0：不限制搜索站点的权威等级
time_range	String	否	用于过滤搜索内容的发布时间范围。不传或传空字符串时，不限制发布时间。参数值： OneDay：搜索最近 24 小时内发布的内容 OneWeek：搜索最近 7 天内发布的内容 OneMonth：搜索最近 30 天内发布的内容 OneYear：搜索最近 365 天内发布的内容 yyyy-mm-dd..yyyy-mm-dd：搜索指定日期范围内发布的内容，开始日期从当天 00:00:00 起，结束日期到当天 23:59:59 止注意：新闻增值包场景：送往总结的搜索内容不受该字段限制。图文视频混排场景：送往总结的搜索内容受该字段限制；文中展示的图片和视频内容不受该字段限制。

响应体ChatCompletionResponse

字段	类型	必须	说明
id	String	是	响应的唯一标识符
object	String	是	响应对象的类型 Chat chat.completion.chunk：流式聊天回复内容 chat.completion：完整聊天回复内容
choices	Array[Choice]	是	返回项
created	Number	是	响应创建时间戳(秒)
references	Array[Reference]	否	大模型参考内容，流式只在首帧出
search_results	Array[Reference]	否	搜索到的结果，最多30个，流式只在首帧出
follow_ups	Array[FollowUp]	否	追问内容，控制台开通权限后可返回
usage	TokenUsage	否	token消耗量，流式只在尾帧出
cards	Array[Card]	否	富媒体卡片的结构化数据，卡片类型和详细字段见：智能体会话API-富媒体卡片数据通过请求体card_position参数可控制出卡位置，流式默认只在首帧出
thinking_references	Array[Reference]	否	边想边搜链路中思考过程中的参考资料

Choice

字段	类型	必须	说明
delta	Object	否	流式响应使用。包含增量更新内容 role: 角色标识 content: 文本片段
message	Object	否	非流式响应使用。包含完整的回复消息，和delta结构一致
finish_reason	String	是	生成终止的原因，可能的值： stop：API 返回完整的模型输出 tool_calls：插件调用 length：达到最大token限制 content_filter：内容被过滤 null：生成尚未完成
index	Number	是	当前选择的索引编号。在单个响应中通常为 0，在多选择配置下可能有多个索引

Reference

字段名	类型	必须	说明
id	String	是	引用内容唯一ID
source_type	String	是	内容源
site_name	String	否	站点名，与SourceType存在映射，枚举场景优先使用SourceType
title	String	否	标题
publish_time	Number	否	发布时间，UnixSecond时间戳部分情况为0，例如部分搜索引擎结果
url	String	否	落地页，部分搜索引擎结果没有URL
logo_url	String	否	部分站点无logo
cover_image	Object	否	封面图 { "url": "https://xxx", // 封面图链接 "width": 123, // 封面图宽，不保证提供 "height": 123, // 封面图高，不保证提供 }

FollowUp

字段	类型	必须	说明
item	String	是	追问

TokenUsage

字段名	类型	必须	说明
prompt_tokens	Number	是	本次请求中模型输入 token 数量（包含意图、改写、总结等环节）
completion_tokens	Number	是	本次请求中模型输出的 token 数量（包含意图、改写、总结等环节）
total_tokens	Number	是	本次请求消耗的总 token 数量（输入 + 输出）

Card

富媒体卡片的结构化数据，卡片类型和详细字段见：智能体会话API-富媒体卡片数据

通过请求体card_position参数可控制出卡位置，流式默认只在首帧出

ValueAddSignal

字段名	类型	必须	说明
learning	Boolean	否	标记本次请求是否走入豆包爱学解题链路，流式默认在首帧返回
health	Boolean	否	标记本次请求是否走入小荷健康链路，流式默认在首帧返回

请求示例

响应示例

非流式响应

流式响应

流式响应帧类型说明

帧类型	说明	举例
处理状态帧	输出处理过程中调用的工具用于端上渲染，提升交互体验	开启请求传入参数： "extension_options" : { "enable_processing_state": true, // 默认false } 结束在处理状态帧结束，内容帧首帧之前，输出一帧空帧，标记处理状态结束 "finish_reason":"processing_finish" 举例 { "id": "202503271640468507AA4C950F0039CEA0", "object": "chat.completion.chunk", "choices": [ { "delta": { "role": "assistant", "content": "", "tool_calls": null, "processing_state": { "action": "planning", "description": "正在理解问题" } }, "message": null, "finish_reason": "", "index": 0 } ], "created": 1743064848, "references": null }
内容帧-首帧	总结输出的首帧首帧返回的结构化数据 Reference Cards（可调整到元数据帧）
内容帧-中间帧	大模型总结输出文本类型总结文本：content 思考过程：reasoning_content	{ "id": "202503271640468507AA4C950F0039CEA0", "object": "chat.completion.chunk", "choices": [ { "delta": { "role": "assistant", "content": "是", "tool_calls": null }, "message": null, "finish_reason": "", "index": 0 } ], "created": 1743064848, "references": null }
内容帧-尾帧	总结输出的最后一帧 finish_reason=stop	{ "id": "202503271640468507AA4C950F0039CEA0", "object": "chat.completion.chunk", "choices": [ { "delta": { "role": "assistant", "content": "是", "tool_calls": null }, "message": null, "finish_reason": "stop", "index": 0 } ], "created": 1743064848, "references": null }
元数据帧	总结输出完成后的补充帧元数据帧返回的结构化数据 FollowUp TokenUsage	{ // ..... "follow_ups": [ { "item": "美的玲珑变频中央空调价格多少" }, { "item": "美的风尊空调静音效果如何" }, { "item": "科龙静省电空调噪音分贝是多少" } ], "usage": { "prompt_tokens": 9266, "completion_tokens": 571, "total_tokens": 9837 } }
结束帧	输出[DONE] 无论成功失败都是最后一帧
错误帧	输出错误原因，只会出一次	{ "error": { "code": "invalid_parameter", "message": "unsupported content type: <nil>", "param": "messages", "type": "validation_error" } }

高级功能

引用角标

说明：在总结输出中插入引用标记，指示文本来源于哪个参考资料

格式：[ref_x]，其中 x 为参考资料的编号

生效场景：流式输出

开启方法：控制台开启开关

注意事项：

客户端可根据需要自定义处理引用角标的展示效果

图文/视频混排

说明：在输出内容中穿插图片，以Markdown格式呈现

生效场景：仅支持流式输出

开启方法：控制台开启开关

输出格式：

文本内容以常规方式输出

图片以Markdown语法输出：![image](url)

图片/视频信息会作为独立帧返回

混排帧会包含图片的元数据在 delta.image_info 中，字段如下：

字段名	类型	必须	说明
width	Number	否	图片像素宽，可能为0
height	Number	否	图片像素高，可能为0
image_url	String	是	图片链接
source_url	String	否	图片源站链接

如果需要渲染多图的客户，全量图片信息的元数据在delta.image_infos 中，字段类型为image_info的数组，详情见下方数据参考

视频元数据在delta.video_infos中，字段类型为video_info的数组，详情见下方参考

video_info字段

字段名	类型	必须	说明
id	String	是	抖音视频id
cover_image	Object	否	封面图，样例： { "url": "https://example.com/images/cover.jpg", "width": 1920, "height": 1080 }
width	Number	否	视频像素宽，可能为0
height	Number	否	视频像素高，可能为0
url	String	否	视频H5页面链接，可能为空（抖音视频请联系售前人员开白）
duration	Number	否	视频时长，可能为0
play_url	String	否	播放链接，可能为空
source_type	String	是	内容源

注意事项：

支持Markdown渲染的客户端无需特殊处理

返回数据参考：

百科划线词

说明：在输出内容中，将自动识别百科词条并以下划线超链接形式在总结中呈现

生效场景：仅支持联网问答pro文搜/图搜流式输出

开启方法：控制台开启开关

输出格式：

下划线词条以Markdown语法输出： [百科词条名](百科url)

注意事项：

支持Markdown渲染的客户端无需特殊处理

返回数据参考：

输出关键执行过程

说明：执行过程中输出关键执行过程，提升端上交互效果

开启方法：详情见请求体ChatCompletionRequest-ExtensionOptions-enable_processing_state

过程范围和帧类型：

action	description(zh_CN)	智能体实际动作
planning	正在理解问题	智能体运行时初始化完成，开始理解用户问题
search_begin	正在搜索网页	调用联网插件，常规联网总结时返回
search_finish	已阅读X个网页 (X>0) 搜索完成 (空搜情况)	调用联网插件，常规联网总结时返回
tools_begin	正在执行工具	调用工具，常规联网总结时返回
tools_finish	工具执行完成	调用工具，常规联网总结时返回
tools_decision	采纳工具结论	调用工具，常规联网总结时返回
summary_info	信息整合完成	调用工具，常规联网总结时返回

返回数据参考：

错误处理

错误码

网关错误：

此接口基于火山引擎TOP网关发布，如果遇到网关层报错（例如验签错误），我们将返回火山引擎TOP网关错误，响应格式如下：

业务错误：

当流式输出过程中出现错误时，错误信息将在以 data: 开头的数据块中返回。字段解释如下：

字段	类型	描述	必须	备注
type	String	错误类型标识符	是	authentication_error：认证相关的错误 validation_error：请求参数验证失败的错误 permission_error：权限相关的错误 model_error：AI 模型相关的错误 bot_unavailable_error：智能体已停用、待正式开通或者试用次数已耗尽 server_error：服务器内部错误
code	String	具体错误代码	是	提供具体错误码，或者和type一致
message	String	错误描述	是	提供具体错误描述，或者和type一致
param	String	导致错误的参数名称	否	只有参数错误时会返回

错误响应

使用说明

图片格式说明

支持的图片格式如下表。

图片格式	文件扩展名	内容格式（Content Type）
JPEG	.jpg, .jpeg	image/jpeg
PNG	.png	image/png
GIF	.gif	image/gif
WEBP	.webp	image/webp
BMP	.bmp	image/bmp
TIFF	.tiff, .tif	image/tiff
HEIC	.heic	image/heic
HEIF	.heif	image/heif

调用示例

Python调用示例

前提条件

调用之前，您需要获取以下信息：

bot_id: 控制台上创建的bot id，可参考联网问答Agent操作指南

鉴权信息（任选一种即可，获取方式请参考本文档认证方式章节）：

AccessKey、SecretKey

APIKey

Python环境

Python：3.9版本及以上。

Pip：25.1.1版本及以上。

下载代码示例

askecho_demo.zip

安装依赖

解压代码包，进入代码包根目录后安装依赖。

运行代码

APIKey接入

火山引擎TOP网关接入

Java调用示例

前提条件

调用之前，您需要获取以下信息：

bot_id: 控制台上创建的bot id，可参考联网问答Agent操作指南

鉴权信息（任选一种即可，获取方式请参考本文档认证方式章节）：

AccessKey、SecretKey

APIKey

Java环境

Java：21版本及以上。

Maven：3.9.10版本及以上。

下载代码示例

AskEchoDemo.zip

解压代码

解压代码包，进入代码包根目录。

运行代码

APIKey接入

火山引擎TOP网关接入

Postman调用示例

使用APIKey直接通过Postman进行接口调用，实际参数替换为您的APIKey与botId。

联网问答Agent