工作流组件调用
更新时间：2025-10-13
接口描述
调用通过工作流创建的组件。注意，组件中包含记忆节点和百度搜索组件时，不支持API/SDK调用。
接口定义
| URL | /v2/components/${component}/version/{$version}?action=tool_eval |
|---|---|
| Method | POST |
| Content-Type | application/json |
| Authorization | 请求签名(Bearer <AppBuilder API Key>)。API-Key的任一权限均支持组件调用 |
请求结构
POST /v2/components/${component}/version/{$version}?action=tool_eval HTTP/1.1
HOST: qianfan.baidubce.com
Authorization: Bearer <AppBuilder API Key>
Content-Type: application/json
{
"stream": true,
"parameters": {
"_sys_origin_query": "你好",
"_sys_file_urls": {},
"_sys_conversation_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"_sys_end_user_id": "xxx",
"_sys_chat_history": [
{
"role": "user",
"content": "xxx"
}
],
"input_variable_name": "xxx"
}
}请求参数
header参数
除公共头域外，无其它特殊头域。
请求path参数
| 字段 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| component | string | 是 | 组件ID。可以在个人空间-组件下查看。 |
| version | string | 否 | 组件版本。 如果不指定version，可以使用如下的url，默认使用组件最新版本： /v2/components/${component_id} 如果要指定version，可以使用版本号。 例如：/v2/components/${component_id}/version/2 可以使用tag指定version，tag相当于一个指针，指向特定版本号，当版本升级时调用者不需要更新。 例如：/v2/components/${component_id}/version/latest 表示最新版本。 如果当前最新版本是2，则该url等价于/v2/components/${component_id}/version/2 当上线组件最新版本3时，latest相当于/v2/components/${component_id}/version/3 |
请求query参数
| 变量 | 类型 | 必填 | 说明 |
|---|---|---|---|
| action | string | 否 | 调用方式。 默认值是tool_eval。 |
请求body参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| stream | bool | 是 | 是否流式返回。 可选值： true：流式。 false：非流式。 |
| parameters | dict | 是 | 调用传参，具体见下文Parameters对象定义 |
| full_params | bool | 否 | 默认为true，为false时仅展示部分参数，为true时展示全部参数。 |
Parameters对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| _sys_origin_query | string | 是 | 用户query。对应画布中开始节点的系统参数rawQuery。 |
| _sys_file_urls | dict | 否 | 文件路径。对应画布中开始节点的系统参数fileUrls，格式为{"文件名": "文件路径"}，例如{"xxx.pdf": "http:///"}。 |
| _sys_conversation_id | string | 否 | 对话id。对应画布中开始节点的系统参数conversation_id，可通过新建会话接口创建。当前仅透传该字段，并不获取里面的上下文信息。 |
| _sys_end_user_id | string | 否 | 终端用户id。对应画布中开始节点的系统参数end_user_id。 |
| _sys_chat_history | list[Message] | 否 | 组件使用的累计对话历史。对应画布中开始节点的系统参数chatHistory。 |
| input_variable_name | object | 否 | 用户自定义添加的参数。对应画布中开始节点用户新增的参数。 注意：用户自定义参数和系统参数为一级，同在parameters中。 例如： "parameters": {"_sys_origin_query": "今天有什么新闻","custom_count": 4} |
Message对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| role | string | 是 | 对话角色。 user：用户。 assistant：agent。 在message中必须是user与assistant交替(一问一答)。 |
| content | string | 是 | 对话内容，文字内容。 |
响应参数
响应header参数
除公共头域外，无其它特殊头域。
响应body参数
全部参数
当请求参数full_params为true或无full_params参数时，返回以下全部参数。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| request_id | string | 是 | 请求request_id |
| code | string | 否 | 错误代码，当发生异常时返回 |
| message | string | 否 | 错误消息，当发生异常时返回 |
| conversation_id | string | 是 | 会话标识UUID。 |
| message_id | string | 是 | 一问或一答的标识UUID。 |
| trace_id | string | 是 | 调用标识UUID。 |
| user_id | string | 是 | 开发者UUID（计费依赖）。 |
| end_user_id | string | 否 | 终端用户ID。 |
| status | string | 是 | 当前对话状态。 running:对话进行过程中。 done：对话结束。 error：执行过程发生错误。 interrupt：中断 |
| role | string | 是 | 当前消息来源，默认tool 。 |
| content | list[Content] | 否 | 当前组件返回内容的主要payload，List[Content]，每个 Content 包括了当前 event 的一个元素，具体见下文Content对象定义。 |
Content对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 代表event 类型。该字段的取值决定了下面text字段的内容结构。枚举值： text、json、code、files、urls、oral_text、references、image、chart、audio、function_call。 |
| name | string | 是 | 介绍当前yield内容的step name。 |
| text | dict object | 是 | 代表当前 event 元素的内容，每一种 event 对应的 text 结构固定。 |
| visible_scope | string | 是 | 可见范围。 枚举值： all ：全部，包括大模型和用户。 llm：大模型。 user：用户。 默认为all。 |
| usage | dict | 否 | 大模型的token用量，具体见下文Usage对象定义。 |
| metrics | dict | 是 | 耗时信息，具体见下文Metrics对象定义。 |
| event | dict | 是 | 标识返回内容的结构、顺序、状态，具体见下文Event对象定义。 |
Usage对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prompt_tokens | int | 是 | 输入token消耗 |
| completion_tokens | int | 是 | 输出token消耗 |
| total_tokens | int | 是 | 总token消耗 |
| nodes | list[node] | 否 | 工作流节点大模型token消耗信息，列表元素具体见下文Node对象定义。 |
Node对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| node_id | string | 是 | 节点id |
| models_usage | list[model_usage] | 是 | 模型消耗列表，元素见下文model_usage对象定义。 |
model_usage对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model_name | string | 是 | 模型名称 |
| prompt_tokens | int | 是 | 输入token消耗 |
| completion_tokens | int | 是 | 输出token消耗 |
| total_tokens | int | 是 | 总token消耗 |
Metrics对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| begin_time | string | 是 | 请求开始时间，示例："2000-01-01T10:00:00.560430"。 |
| duration | float | 是 | 从请求到当前event总耗时，保留3位有效数字，单位秒s。 |
Event对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| id | string | 是 | 节点id。 |
| status | string | 是 | 事件执行状态。 枚举值： preparing：运行中。 running：运行中。 error：错误。 done：执行完成。 |
| name | string | 是 | 事件名。 一级深度有： component，组件api。 functioncall，自主规划agent。 chatflow，工作流agent。 二级深度是组件ID。 三级深度是组件content_type。 示例： /component/eaaccc60e222418abc0f4d3d372018af/node/ 433b4cf184064daf88e8383adc83e35f |
| created_time | string | 是 | 当前event发送时间。 |
| error_code | string | 否 | 错误码。 |
| error_message | string | 否 | 错误细节。 |
关键参数
当请求参数full_params为false时，仅返回以下关键参数。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| request_id | string | 是 | 请求 request_id |
| code | string | 否 | 错误代码，当发生异常时返回 |
| message | string | 否 | 错误消息，当发生异常时返回 |
| status | string | 是 | 当前对话状态: running:对话进行过程中。 done：对话结束。 error：执行过程发生错误。 interrupt：中断 |
| content | list[Content] | 否 | 当前组件返回内容的主要payload，List[Content]，每个 Content 包括了当前 event 的一个元素，具体见下文Content对象定义。 |
Content
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 代表event 类型。该字段的取值决定了下面text字段的内容结构。枚举值： text、json、code、files、urls、oral_text、references、image、chart、audio、function_call。 |
| text | dict object | 是 | 代表当前 event 元素的内容，每一种 event 对应的 text 结构固定。 |
| event | dict | 是 | 标识返回内容的结构、顺序、状态，具体见下文Event对象定义。 |
Event对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| status | string | 是 | 事件执行状态: 枚举值： preparing：运行中。 running：运行中。 error：错误。 done：执行完成。 |
| error_code | string | 否 | 错误码。 |
| error_message | string | 否 | 错误细节。 |
请求curl示例
// 请求带版本号
curl --location 'https://qianfan.baidubce.com/v2/components/bf4ded94-feed-48d9-848a-14f713eb2318/version/4' \
--header 'Authorization: Bearer <AppBuilder API Key>' \
--header 'Content-Type: application/json' \
--data '{
"stream": false,
"parameters": {
"_sys_origin_query": "今天的天气如何，10个字回答",
"_sys_file_urls": {
"abc.png": "https://vcg02.cfp.cn/creative/vcg/800/new/VCG21gic6370954.jpg"
},
"_sys_conversation_id": "32fad7d0-1f8c-4d59-9e63-61f5d602c156",
"_sys_end_user_id": "david1980",
"_sys_chat_history": [
{
"role": "user",
"content": "你好啊"
}
],
"custom_variable1": "abc",
"custom_variable2": 1.23
}
}'
// 请求不带版本号走最新版本
curl --location 'https://qianfan.baidubce.com/v2/components/bf4ded94-feed-48d9-848a-14f713eb2318' \
--header 'Authorization: Bearer authorization string' \
--header 'Content-Type: application/json' \
--data '{
"stream": false,
"parameters": {
"_sys_origin_query": "今天的天气如何，10个字回答",
"_sys_file_urls": {
"abc.png": "https://vcg02.cfp.cn/creative/vcg/800/new/VCG21gic6370954.jpg"
},
"_sys_conversation_id": "32fad7d0-1f8c-4d59-9e63-61f5d602c156",
"_sys_end_user_id": "david1980",
"_sys_chat_history": [
{
"role": "user",
"content": "你好啊"
}
],
"custom_variable1": "abc",
"custom_variable2": 1.23
}
}'
// 请求带latest标签
curl --location 'https://qianfan.baidubce.com/v2/components/ba098d65-b40b-4162-b89e-d9498a1c1453/version/latest' \
--header 'Authorization: Bearer <AppBuilder API Key>' \
--header 'Content-Type: application/json' \
--data '{
"stream": false,
"parameters": {
"_sys_origin_query": "今天的天气如何，10个字回答",
"_sys_file_urls": {
"abc.png": "https://vcg02.cfp.cn/creative/vcg/800/new/VCG21gic6370954.jpg"
},
"_sys_conversation_id": "32fad7d0-1f8c-4d59-9e63-61f5d602c156",
"_sys_end_user_id": "david1980",
"_sys_chat_history": [
{
"role": "user",
"content": "你好啊"
}
],
"custom_variable1": "abc",
"custom_variable2": 1.23
}
}'正确响应示例
// 返回非流式效果
{
"conversation_id": "32fad7d0-1f8c-4d59-9e63-61f5d602c156",
"message_id": "7b6fab29-d11e-4544-9f84-a0afb9f8e4c9",
"trace_id": "c5de1b79-bd5b-49c1-9ffc-0dfebda92eda",
"user_id": "a00dd7b8-70ec-4312-9e23-29c8e1a11f4f",
"end_user_id": "david1980",
"status": "done",
"role": "tool",
"content": [
{
"type": "text",
"name": "结束",
"text": {
"info": "今天天气晴朗明媚。"
},
"visible_scope": "all",
"usage": {
"prompt_tokens": 8,
"completion_tokens": 4,
"total_tokens": 12,
"nodes": [
{
"node_id": "9e9a5d07684c43fd84011c0d376a2d63",
"models_usage": [
{
"model_name": "ERNIE-3.5-8K",
"prompt_tokens": 8,
"completion_tokens": 4,
"total_tokens": 12
}
]
}
]
},
"metrics": {
"begin_time": "2024-12-26T16:14:12.851127",
"duration": 0.806
},
"event": {
"id": "95e5dfb87e86405eaed52207f62d404e",
"status": "done",
"name": "/component/3435ce76fc744c019b4923b15e9cf985/node/95e5dfb87e86405eaed52207f62d404e",
"created_time": "2024-12-26T16:14:13.657471",
"error_code": "",
"error_message": ""
}
}
]
}
// 返回流式效果
data: {
"conversation_id": "32fad7d0-1f8c-4d59-9e63-61f5d602c156",
"message_id": "948763ff-d4a1-46f8-bcf2-b0ebd67f28e2",
"trace_id": "c5de1b79-bd5b-49c1-9ffc-0dfebda92eda",
"user_id": "a00dd7b8-70ec-4312-9e23-29c8e1a11f4f",
"end_user_id": "david1980",
"status": "running",
"role": "tool",
"content": [
{
"type": "text",
"name": "结束",
"text": {
"info": "今天天气晴朗明媚。"
},
"visible_scope": "all",
"usage": {
"prompt_tokens": 8,
"completion_tokens": 4,
"total_tokens": 12,
"nodes": [
{
"node_id": "9e9a5d07684c43fd84011c0d376a2d63",
"models_usage": [
{
"model_name": "ERNIE-3.5-8K",
"prompt_tokens": 8,
"completion_tokens": 4,
"total_tokens": 12
}
]
}
]
},
"metrics": {
"begin_time": "2024-12-26T16:18:51.374206",
"duration": 0.732
},
"event": {
"id": "95e5dfb87e86405eaed52207f62d404e",
"status": "done",
"name": "/component/3435ce76fc744c019b4923b15e9cf985/node/95e5dfb87e86405eaed52207f62d404e",
"created_time": "2024-12-26T16:18:52.106022",
"error_code": "",
"error_message": ""
}
}
]
}
data: {
"conversation_id": "32fad7d0-1f8c-4d59-9e63-61f5d602c156",
"message_id": "cceca15a-6b1a-41e9-b484-836f78da9383",
"trace_id": "c5de1b79-bd5b-49c1-9ffc-0dfebda92eda",
"user_id": "a00dd7b8-70ec-4312-9e23-29c8e1a11f4f",
"end_user_id": "david1980",
"status": "done",
"role": "tool",
"content": []
}错误响应示例
HTTP/1.1 401 OK
{
"request_id": "ae2225f7-1c2e-427a-a1ad-5413b762957d",
"code": "PermissionDeniedError",
"message": "没有权限"
}流式请求、核心参数响应示例
data: {"request_id": "e36cd5a2-e9bf-43e3-bb72-03548953803d", "code": "", "message": "", "status": "running", "content": [{"type": "json", "text": {"data": "{\"out\":\"\\n\\n老鼠开了家奶酪厂，贴出招聘启事：“诚聘猫咪保安一名，主要负责试吃工作，工资日结——毕竟都是临时工！”\"}"}, "event": {"status": "done", "error_code": "", "error_message": ""}}]}
data: {"request_id": "e36cd5a2-e9bf-43e3-bb72-03548953803d", "code": "", "message": "", "status": "done", "content": []}非流式请求、全部参数响应示例
{
"request_id": "ed9d2002-6b72-402c-8de2-1d651c014037",
"conversation_id": "177b191f-1780-444c-bed0-1ab4f460b06f",
"message_id": "af89f92d-0ee1-432b-95dd-8cad3f29014c",
"trace_id": "ed9d2002-6b72-402c-8de2-1d651c014037",
"user_id": "646a308c-7ece-4787-b164-5ae907d0cd3a",
"end_user_id": "",
"role": "tool",
"content": [
{
"type": "json",
"name": "结束",
"text": {
"data": "{\"out\":\"\\n\\n老鼠对猫说：\\\"你这速度，是不是该更新你的爪机系统了？\\\"\"}"
},
"visible_scope": "all",
"raw_data": {
"cn_name": "结束",
"node_id": "6f872c46641e4ee1abc96d636ac3288f",
"origin_response": {
"node_content": [
{
"node_id": "6f872c46641e4ee1abc96d636ac3288f",
"outputs": {
"out": "\n\n老鼠对猫说：\"你这速度，是不是该更新你的爪机系统了？\""
}
}
]
}
},
"usage": {
"prompt_tokens": 21,
"completion_tokens": 214,
"total_tokens": 235,
"nodes": [
{
"node_id": "f8dfbb5a6159493c8a10bc1038ed7ca1",
"models_usage": [
{
"model_name": "deepseek-r1",
"prompt_tokens": 21,
"completion_tokens": 214,
"total_tokens": 235
}
]
}
]
},
"metrics": {
"begin_time": "2025-08-21T20:11:56.430634",
"duration": 8.465
},
"event": {
"id": "6f872c46641e4ee1abc96d636ac3288f",
"status": "done",
"name": "/component/f217468aaaa944c89194ff22d5bccee9/node/6f872c46641e4ee1abc96d636ac3288f",
"created_time": "2025-08-21T20:12:04.895696",
"error_code": "",
"error_code_int": 0,
"error_message": ""
}
}
],
"status": "done"
}