百宝箱开放平台 ✖️ API ✖️ 调用对话型智能体本文介绍了对话型智能体API的调用方法，支持多轮对话和多模态文件处理

通过调用本接口，开发者可以向指定智能体发起对话，支持在对话时添加上下文消息，便于智能体做出合理的回复。

前提条件

在调用本接口前，请先完成应用的发布。
若您需要通过本接口上传多模态文件，需要先开启应用配置中的多模态配置，再添加拥有多模态处理能力的大模型或插件。

请求地址

POST``https://api.tbox.cn/api/chat

请求头

参数名	是否必填	类型	说明	示例
Authorization	是	String	用于验证客户端身份的访问令牌，你可以在百宝箱中获取，获取方式可参见：授权管理。	`pat_2j4e******THUIVRH1`

请求参数

参数名	是否必填	类型	说明	示例
appId	是	String	应用 ID。	`202506e******00450562`
query	是	String	用户发给智能体的问题内容。	你好
userId	是	String	用户 ID，指使用智能体的用户 ID，需开发者自行定义与维护。	-
conversationId	否	String	会话id，用于用户多轮对话时组装上下文信息。	多轮对话时，按照SDK中之前返回的conversationId 内容传入。
files	否	List	文件列表，用于在对话中提供多模态（文档、图片、音频及视频）数据。说明：使用文件上传能力前，请先为智能体配置具有文件处理能力的大模型或插件。	-
searchEngine	否	Boolean	本次对话是否使用联网搜索。说明：使用联网搜索前，需要先开启智能体对话配置中的联网搜索开关。- true：使用联网搜索；

false：默认值，不使用联网搜索。 | true | | stream | 否 | Boolean | 是否流式返回。- true：流式（默认值）
false：非流式 | true |

File 定义

本模块参数仅在使用文件上传能力时，必传。

参数名	是否必填	类型	说明	示例
type	是	Enum	指上传的文件类型。枚举值包括：- 图像：IMAGE

音频：AUDIO
视频：VIDEO
文件：FILE | IMAGE | | fileId | 是 | String | 上传文件id，通过上传文件接口，完成文件上传后，在返回参数中获得。 | 202502********001001 |

请求示例

支持用 curl 命令或编程语言（如 Python、Java 等）调用接口，以下是 curl 命令示例。

curl --location 'https://api.tbox.cn/api/chat' 
--header 'Authorization: {your_token}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{"appId": {your_appId},"query":"你好","userId":"xxx"}'

返回参数

本 API 的返回内容会根据请求参数中 stream 参数值（true/false）来采用流式或非流式响应，您可以根据下述需求 list 来判断自身业务场景适配哪种响应方式。

需求 list	响应方式
当您的业务场景满足下述任一一条时：- 需要以打字机的效果来显示接口返回内容；

需要即时查看智能体回复；
需要同步处理返回内容； | 流式响应（stream=true） | | 当您的业务场景不满足上述内容时 | 非流式响应（stream=false） |

流式返回

流式返回的消息体结构如下：

参数名	类型	说明
id	Integer	对话 ID，当前对话的唯一标识。
event	String	当前流式返回的消息类型。
data	Object	返回内容详情。

data 定义

参数名	类型	说明
type	String	数据类型描述，如元数据、普通数据等，详情描述如下：- meta：包含联网搜索的相关内容。

header： 表示百宝箱开始将要开始返回chunk 内容。多输出场景下会有多个header。
chunk： 本次请求返回的具体消息内容。
thinking：当本次请求开启了思维链能力时，用于展示具体的思维链内容。 | | payload | String (JSONString) | 具体返回内容，实际结构会根据 type 的不同而变化，详细说明可参见：- data.type = header
data.type = chunk
data.type = meta
data.type = thinking |

当 data.type = header 时，payload 定义

参数名	类型	说明
extraParams	Object	额外输出参数
mediaType	String	输出的内容类型
requestId	String	请求ID
sessionId	String	sessionId 即 conversationId

当 data.type = chunk 时，payload 定义

参数名	类型	说明
type	String	类型标识符，如 `chunk`
lane	String	流水线标识（默认为 `default`）
text	String	当前文本流中返回的内容
conversationId	String	当前会话id
messageId	String	当前消息id

当 data.type = meta 时，payload 定义

参数名	类型	说明
entity	Object	节点信息。
event	String	事件名称，表示流程中的执行过程事件。
ext_data	JSONString	扩展信息，包含节点执行过程中的详细信息。

其中，entity 以及 ext_data 的定义信息可参见：附录。

当 data.type = thinking 时，payload 定义

说明：

仅智能体配置了支持思维链能力的大模型时，会返回当前内容。
当智能体为简单应用时，智能体中仅存在一个大模型， thinking 返回值与智能体的返回结果存在关联关系；
当智能体为工作流应用时，智能体中可能存在一到多个大模型，thinking 返回内容可能与智能体最终返回结果不相干。

参数名	类型	说明
entity	Object	节点信息。
event	String	事件名称，表示流程中的执行过程事件，详细说明可参见：流式响应事件。
ext_data	JSONString	扩展信息，包含节点执行过程中的详细信息。

其中，entity 以及 ext_data 的定义信息可参见：附录。

流式响应事件枚举

事件名称	说明
flow.graph.start	流程开始执行
flow.node.start	节点开始执行
flow.node.end	节点执行结束
flow.graph.end	流程执行结束
flow.node.llm.search.result	执行联网搜索
flow.node.llm.think.start	表示思维链开始输出
flow.node.llm.thinking	表示思维链输出中
flow.node.llm.think.end	表示思维链输出结束

返回示例

id:1
event:message
data:{"entity":{"node_type":"output","execute_id":"7","node_name":"输出内容","node_id":"OU_awwbf6"},"lane":"default","payload":"{"extraParams":{},"mediaType":"text","requestId":"test-yuhao-201","sessionId":"20250716Pj9q35266510"}","type":"header"}

id:2
event:message
data:{"lane":"default","payload":"{"text":"您","conversationId":"2025****3948","messageId":"2025****6765"}","type":"chunk"}

id:3
event:message
data:{"lane":"default","payload":"{"text":"提到","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:4
event:message
data:{"lane":"default","payload":"{"text":"的文件是指","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:5
event:message
data:{"lane":"default","payload":"{"text":"之前","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:6
event:message
data:{"lane":"default","payload":"{"text":"上传过的某个文件吗","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:7
event:message
data:{"lane":"default","payload":"{"text":"？能否请您提供一下","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:8
event:message
data:{"lane":"default","payload":"{"text":"该文件或者描述一下文件","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:9
event:message
data:{"lane":"default","payload":"{"text":"的具体内容，这样我才能","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:10
event:message
data:{"lane":"default","payload":"{"text":"更好地帮助您。如果您","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:11
event:message
data:{"lane":"default","payload":"{"text":"能分享文件链接","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:12
event:message
data:{"lane":"default","payload":"{"text":"或相关细节，那","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:13
event:message
data:{"lane":"default","payload":"{"text":"将非常有帮助。","conversationId":"2025****3948","messageId":"2025****6765}","type":"chunk"}

id:14
event:end
data:{"type":"end"}

非流式响应

参数名	类型	说明
errorCode	String	错误码，"0" 表示成功。
errorMsg	String	错误信息。
data	List	返回结果，详细说明可参见：ChatResponse 定义。
traceId	String	traceId，用于排查问题

ChatResponse 定义

参数名	类型	说明
requestId	String	请求ID
converstionId	String	当前会话 ID
messageId	String	当前消息 ID
result	List	返回结果，详细说明可参见：Answer 定义。
searchResult	List	联网搜索结果集合，仅开启并使用联网搜索能力时，有相关返回，详细说明可参见：SearchResult 定义。
reasoningContent	List	思维链集合，仅当智能体的大模型支持思维链能力时返回，详细说明可参见：ReasoningContent 定义。

Answer 定义

参数名	类型	说明
lane	String	流水线标识（默认为 `default`）
extraParams	Object	额外输出参数
mediaType	String	输出的内容类型
chunk	JSONString	输出内容，根据 mediaType 有不同的结构：- 如果 mediaType=text：chunk 直接表示输出的文本内容；

如果 mediaType=image：chunk 返回内容需要反序列化，其中 url 字段表示返回的图片 url 集合。 |

SearchResult 定义

参数名	类型	说明
action	String	参考链接
title	String	标题

ReasoningContent 定义

参数名	类型	说明
text	String	思维链内容
ext_data	Object	扩展信息
>>start_time	Long	思维链开始输出时间，时间戳，单位 s
>>end_time	Long	思维链输出结束时间，时间戳，单位 s
>>thinking_elapsed_secs	Int	思维链输出总耗时，单位 s
entity	Object	节点信息（工作流应用关心即可）
>>node_name	String	工作流节点名称，可以通过该字段判断思维链是哪个大模型节点产生的

返回示例

{
	"requestId": "b18ecc07-5db1-********e56ddf12581f",
	"conversationId": "2025****3948",
	"messageId": "2025****6765",
	"input_tokens": 100,
	"output_tokens": 200,
	"total_tokens": 300,
	"result": [{
    "lane":"default",
		"extraParams": {},
		"mediaType": "text",
		"chunk": "你好，有什么可以帮助你"
	}]
}

{
	"requestId": "b18ecc07-5db1-********e56ddf12581f",
	"conversationId": "2025****3948",
	"messageId": "2025****6765",
	"input_tokens": 100,
	"output_tokens": 200,
	"total_tokens": 300,
	"result": [{
    "lane":"default",
		"extraParams": {},
		"mediaType": "image",
		"chunk": "{"url":["https://mdn.alipayobjects.com/cto_doraemon/afts/img/iVe7Q6mHhpIAAAAAAAAAAAAAehe3AQBr/original"]}"
	}]
}

附录

paylod.entity 定义

参数名	类型	说明
node_type	String	节点类型，表示该节点功能
execute_id	String	节点执行顺序编号（字符串格式）
node_name	String	节点显示名称
node_id	String	节点唯一标识符

payload.ext_data 定义

参数名	类型	说明
start_time	Number (float)	节点开始时间戳（秒级）
end_time	Number (float)	节点结束时间戳（秒级）
input_params	JSONString	当前节点的输入参数
query	JSONString	用户输入查询内容
search_result	List	联网搜索参考资源明细
text	String	思考内容，仅 flow.node.llm.thinking 节点有相关返回。
thinking_elapsed_secs	Int	思维链输出总耗时，单位 s。仅 flow.node.llm.think.end 节点中有相关返回）

ext_data.input_params 定义

参数名	类型	说明
iconversationId	String	当前会话ID
requestId	String	请求唯一标识
historyChat	Array	历史对话记录（空数组表示无历史）

ext_data.query 定义

参数名	类型	说明
query	String	用户实际输入内容

ext_data.search_result 定义

参数名	类型	说明
action	String	参考链接
title	String	标题

常见问题

智能体调用过程中可能遇见的问题及解决方案，请参见：常见问题。