注意

首次使用 OpenAPI 的用户，建议先阅读API 介绍，了解使用 OpenAPI 的方式和使用限制。
调用工作流 API 时，响应信息中会返回 debug_url，通过浏览器访问此链接，即可通过可视化界面查看工作流的试运行过程，其中包含每个执行节点的输入输出等详细信息，帮助你在线调试或排障。如果 debug_url 中包括字符 \u0026，需要手动替换为 &，之后再访问此链接。

同步运行

工作流默认同步运行。你可以选择流式响应或非流式响应的方式运行应用中的指定工作流，运行工作流时需要通过请求参数 app_id 指定应用的 ID，以便工作流节点使用应用资源库的数据和知识。

非流式响应

执行工作流接口采用非流式响应模式，执行结果会直接封装在响应信息中返回给开发者，适用于不包含流式响应节点的工作流。
请求示例如下：

curl --location --request POST 'https://api.coze.cn/v1/workflow/run' \
  --header 'Authorization: Bearer pat_hfwkehfncaf****' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "workflow_id": "73664689170551*****",
    "parameters": {
      "user_id": "12345",
      "user_name": "George"
    },
    "app_id": "743962661420117****"
}'

你可以从响应信息查看工作流的执行结果，包含运行状态、结束节点的输出等信息。响应示例如下：

{ 
    "code": 0, 
    "cost": "0", 
    "data": "{\"output\":\"北京的经度为116.4074°E，纬度为39.9042°N。\"}", 
    "debug_url": "https://www.coze.cn/work_flow?execute_id=741364789030728****&space_id=736142423532160****&workflow_id=738958910358870****", 
    "msg": "Success", 
    "token": 98 
}

流式响应

执行工作流（流式响应）接口采用流式响应模式，在后端处理的同时发送响应信息，呈现类似打字机的效果。调用此 API 时需要使用流式响应方式接收响应数据，适用于以下场景：

包含开启了流式响应节点的工作流。输出节点、结束节点支持流式响应，包含这两个节点的工作流建议使用此 API。
包含问答节点的工作流。

请求示例如下：

curl --location --request POST 'https://api.coze.cn/v1/workflow/stream_run' \ 
--header 'Authorization: Bearer pat_fhwefweuk****' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{
    "workflow_id": "73664689170551*****", 
    "parameters": { 
        "user_id":"12345", 
        "user_name":"George"
    },
    "app_id":"743962661420117****" 
}

你可以从响应信息的 event 和 data 字段查看工作流的各个执行事件。你需要持续接收 Message 事件，直到观察到 Error、Done 或 Interrupt 事件。其中：

Message：工作流节点输出消息，例如输出节点、结束节点的输出消息。可以在 data 中查看具体的消息内容。
Error：报错。观察到此事件时，需要在 data 中查看 error_code 和 error_message，排查问题。
Interrupt：中断。观察到此事件时，表示工作流中断，此时 data 字段中包含具体的中断信息。
Done：结束。表示工作流执行结束，此时 data 中返回 debug_url。

响应示例如下：

id: 0 
event: Message 
data: {"content":"msg","node_is_finish":false,"node_seq_id":"0","node_title":"Message"} 
 
id: 1 
event: Message 
data: {"content":"为","node_is_finish":false,"node_seq_id":"1","node_title":"Message"} 
 
id: 2 
event: Message 
data: {"content":"什么小明要带一把尺子去看电影？\n因","node_is_finish":false,"node_seq_id":"2","node_title":"Message"} 
 
id: 3 
event: Message 
data: {"content":"为他听说电影很长，怕","node_is_finish":false,"node_seq_id":"3","node_title":"Message"} 
 
id: 4 
event: Message 
data: {"content":"坐不下！","node_is_finish":true,"node_seq_id":"4","node_title":"Message"} 
 
id: 5 
event: Message 
data: {"content":"{\"output\":\"为什么小明要带一把尺子去看电影？\\n因为他听说电影很长，怕坐不下！\"}","cost":"0.00","node_is_finish":true,"node_seq_id":"0","node_title":"","token":0} 
 
id: 6 
event: Done 
data: {"debug_url":"https://www.coze.cn/work_flow?execute_id=744119270952162****&space_id=743984899418202****\&workflow_id=743985075059477****"}

中断场景

包含问答节点和输入节点的工作流，需要使用执行工作流（流式响应）接口来调用应用，并在工作流中断时，调用恢复运行工作流（流式响应）回答问题或提交输入信息，并恢复运行工作流。对于问答节点，如果用户的响应和智能体预期提取的信息不匹配，例如缺少必选的字段，或字段数据类型不一致，工作流会再次中断并追问。如果询问 3 次仍未收到符合预期的回复，则判定为工作流执行失败。
以查看天气工作为例，完整的接口调用示例如下。

调用接口执行工作流（流式响应），要求查看天气。
请求示例如下：

curl --location 'https://api.coze.cn/v1/workflow/stream_run' \
--header 'Authorization: Bearer pat_vTG1****' \
--header 'Content-Type: application/json' \
--data '{
    "workflow_id": "739739507914235****",
    "parameters": {
        "BOT_USER_INPUT":"查看天气"
    },
    "app_id":"743962661420117****" 
}

触发问答节点，工作流中断，响应信息中返回智能体提出的问题，要求用户提供城市和日期。
返回示例如下：

id: 0
event: Message
data: {"content":"请问你想查看哪个城市、哪一天的天气呢","content_type":"text","node_is_finish":true,"node_seq_id":"0","node_title":"问答"}

id: 1
event: Interrupt
data: {"interrupt_data":{"data":"","event_id":"7404831988202520614/6302059919516746633","type":2},"node_title":"问答"}

调用接口恢复运行工作流（流式响应），回复智能体城市和日期。
请求示例如下：

curl --location 'https://api.coze.cn/v1/workflow/stream_resume' \
--header 'Authorization: Bearer pat_vTG1****' \
--header 'Content-Type: application/json' \
--data '{
    "event_id":"740483727529459****/433802199567434****",
    "interrupt_type":2,
    "resume_data":"杭州，2024-08-20",
    "workflow_id":"739739507914235****"
}

工作流执行完毕，完成天气查询，返回工作流输出消息。
返回示例如下：

id: 0 
event: Message 
data: {"content":"{\"output\":[{\"condition\":\"中到大雨\",\"humidity\":72,\"predict_date\":\"2024-08-20\",\"temp_high\":35,\"temp_low\":26,\"weather_day\":\"中到大雨\",\"wind_dir_day\":\"西风\",\"wind_dir_night\":\"西风\",\"wind_level_day\":\"3\",\"wind_level_night\":\"3\"}]}","content_type":"text","cost":"0","node_is_finish":true,"node_seq_id":"0","node_title":"End","token":386} 
 
id: 1 
event: Done 
data: {"debug_url":"https://www.coze.cn/work_flow?execute_id=744119270952162****&space_id=743984899418202****\&workflow_id=743985075059477****"}

异步运行

扣子支持异步运行工作流，适用于工作流执行耗时较长，导致运行超时的情况。异步运行时，工作流整体超时时间限制由 10 分钟延长至 24 小时，其他节点的超时时间限制不变，详细说明可参考低代码工作流使用限制。异步运行后可通过本接口返回的 execute_id 调用查询工作流异步运行结果接口获取工作流的执行结果。
API 调用流程如下：

调用执行工作流接口。其中请求参数 is_async 参数应设置为 true。
请求示例如下：

curl --location --request POST 'https://api.coze.cn/v1/workflow/run' \ 
--header 'Authorization: Bearer pat_hfwkehfncaf****' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
    "workflow_id": "73664689170551*****", 
    "parameters": { 
        "user_id":"12345", 
        "user_name":"George" 
    }, 
    "is_async": true,
    "app_id":"743962661420117****" 
}

从响应中获取到 execute_id，即异步运行的执行 ID。响应示例如下：

{ 
    "code": 0, 
    "debug_url": "https://www.coze.cn/work_flow?execute_id=742482313128840****&space_id=731375784444321****&workflow_id=74243949454920****", 
    "execute_id": "74248231312884****", 
    "msg": "Success" 
}

调用查询工作流异步运行结果接口。
在 API 请求中指定 execute_id。例如以下请求示例中，path 参数 743104097880585**** 是 execute_id。

curl --location 'https://api.coze.cn/v1/workflows/742963539464539****/run_histories/743104097880585****' \ 
--header 'Authorization: Bearer pat_********'

以下响应示例表示工作流异步执行完成，且状态为执行成功。如果执行异常，你还可以在响应信息中获取 debug_url，通过浏览器访问这个地址，可以查看各个节点的执行结果。

{
    "detail": { 
        "logid": "20241029152003BC531DC784F1897B****" 
    }, 
    "code": 0, 
    "msg": "", 
    "data": [ 
        { 
            "update_time": 1730174065, 
            "cost": "0.00000", 
            "output": "{\"Output\":\"{\\\"content_type\\\":1,\\\"data\\\":\\\"来找姐姐有什么事呀\\\",\\\"original_result\\\":null,\\\"type_for_model\\\":2}\"}", 
            "bot_id": "742963486232569****", 
            "token": "0", 
            "execute_status": "Success", 
            "connector_uid": "223687073464****", 
            "run_mode": 0, 
            "connector_id": "1024", 
            "logid": "20241029115423ED85C3401395715F726E", 
            "debug_url": "https://www.coze.cn/work_flow?execute_id=743104097880585****&space_id=730976060439760****&workflow_id=742963539464539****", 
            "error_code": "", 
            "error_message": "", 
            "execute_id": "743104097880585****", 
            "create_time": 1730174063 
        } 
    ] 
}

如何获取应用 ID？

运行工作流时需要通过请求参数 app_id 指定应用的 ID，以便工作流节点使用应用资源库的数据和知识。你可以通过应用的业务编排页面 URL 中获取应用 ID，也就是 URL 中 project-ide 参数后的一串字符，例如 https://www.coze.cn/space/739174157340921****/project-ide/743996105122521****/workflow/744102227704147**** 中，应用的 ID 为 743996105122521****。

发布为 API 服务