用 Python 调用 Dify 或 Coze 工作流时，应关注哪些工程细节？
未标记
考查重点：接口契约与执行状态。核对凭据、输入和响应模式，区分运行查询与任务停止的标识；超时后先确认执行结果，按业务接口的幂等约定处理重试
本题目录
参考答案
核心回答
用 Python 调用这类工作流，重点是把接口契约、网络连接和业务执行状态分别管理。先核对应用是否发布、凭据权限、输入变量及输出结构；再按阻塞或流式模式配置超时并解析响应；最后保存运行标识，依据工作流状态判断成功、失败或等待处理。
HTTP 200 不等于业务成功，连接超时也不等于服务端已经停止。断线后有运行标识就先查状态或按平台接口续接，没有拿到标识则保留“结果未知”，不能直接重新提交。流程中若有创建工单、退款等写操作，还要由业务接口提供幂等或结果核对机制，不能假定工作流平台会消除重复副作用。
接口与凭据怎样接好
先确认部署地址、接口版本、已发布的工作流，以及开始节点要求的字段名、类型、必填条件和文件传递方式。输出也要有明确结构：哪个字段是最终结果、哪个字段表示错误，不能把任意节点输出都当成最终答案。
应用密钥由服务端从环境变量或凭据管理服务读取，通过平台规定的鉴权头发送；不放进浏览器，也不写进普通日志。终端用户身份由已认证的业务用户映射，不能把用户传来的任意字符串直接当成授权依据。Dify 与 Coze 的参数、事件和异步接口各有约定，应分别适配，不能只替换地址就共用全部请求和解析代码。
网络层复用 HTTPX 客户端与连接池，分别设置连接、读取、写入和连接池等待超时，并为整个业务操作设置总时限。读取超时通常约束等待下一块数据的时间，不是工作流的总运行时间；流式连接持续有数据，也可能超过业务允许的时长。反向代理和平台自身的限制同样需要核对，不能把某个云部署的固定秒数当成所有环境的通用规则。
流式响应怎样判断完成
阻塞模式按返回的 JSON 结构检查工作流状态和输出。流式模式先确认响应类型，再按 SSE 协议以空行划分完整事件，合并同一事件中的多行 data: 后解析 JSON，跳过注释和心跳；网络读取到的一块字节不一定是一条完整事件。
解析协议与解释业务事件是两层工作。Dify 把事件类型放在数据对象的 event 字段中；Coze 的工作流流式接口使用 Message、Error、Done、Interrupt 等事件。应使用对应平台的适配器处理输出、错误、结束与中断，不能把收到文字、连接关闭或任意结束事件都记为业务成功。
客户端应在拿到运行标识时及时保存，并保留最近已确认的状态。若没有收到可确认结果的终态就断流，先标记连接中断、执行结果待确认。重新建立网络连接、续接原运行和重新执行工作流是三种不同操作，只有平台明确提供的续接接口才能继续原运行的事件消费。
重试与业务状态怎样配合
业务记录应关联一次调用尝试、平台运行标识、当前状态、最终输出和错误原因；业务单号与平台运行标识分开保存。同一业务可能因人工重试产生多个运行，不能让旧运行的迟到结果覆盖新运行。
鉴权失败和参数错误先修正配置，不做无效重试。查询操作可按平台限制采用有上限的退避；执行请求出现限流、服务端错误或读取超时时，还要判断请求是否可能已被接收。尤其是写入型流程，重试前应查询已有运行或业务办理结果。
若下游业务接口支持幂等键，使用同一业务操作的稳定标识，并核对相同标识是否允许不同参数；若不支持，就需要业务侧的唯一约束、状态转换或结果核对。给工作流请求多传一个字段，并不会自动获得幂等保证。 工作流执行成功与退款、发货等业务办理成功也要分别记录，以业务接口返回的办理状态为准。
DifyPython
基于 Dify核心回答
接入 Dify 时，由 Python 业务服务持有应用密钥，调用已发布工作流，把开始节点输入映射到 inputs，再分别处理阻塞结果或 SSE 事件。Dify 的 Flask 接口把执行请求交给应用生成服务，工作流节点由 graphon 引擎运行；这里不是把 LangGraph 当成 Dify 的执行器。
接入层最关键的是分清两类标识：workflow_run_id 用于查询这次运行，task_id 用于请求停止任务。它们都不是业务单号或幂等键。流式接入应尽早保存这些标识，以最终状态和输出完成业务记录；断线后查询或显式续接原运行，不重复提交同一次业务。
从请求到结果
向 POST /v1/workflows/run 发送应用级 Bearer 凭据，请求包含 inputs、response_mode 和稳定的 user。例如工作流的开始节点定义了 target，才在 inputs 中传入这个名字；换成另一个工作流时，应重新核对输入定义。user 表示终端用户，同一用户的不同执行可以使用同一个值，它不负责请求去重。
response_mode=blocking 等待返回结果；response_mode=streaming 返回 text/event-stream。接收 workflow_started 时保存运行标识与任务标识，节点事件可用于展示执行进度；接收 workflow_finished 后检查 data.status，成功时再按约定读取 data.outputs，失败时保存 error。不能只凭 HTTP 200 或出现过节点输出就认定整个流程成功；遇到人工输入暂停，也应保留等待状态，而不是把连接结束记为失败。
固定版本的执行入口明确区分两种响应模式；流事件数据结构分别提供运行开始和运行完成的信息。
断线、续接与停止
已知 workflow_run_id 时，使用 GET /v1/workflows/run/{workflow_run_id} 查询运行状态、输出和错误。这个查询用于确认结果，不是重新执行流程；若请求在收到运行标识前就断开，不能声称已经能可靠查询原运行，需要结合平台日志或业务结果进一步核对。
这个版本还提供 GET /v1/workflow/{workflow_run_id}/events，由客户端使用原 user 主动续接事件流。include_state_snapshot=true 可先返回已执行节点的状态摘要；运行已结束时会发送完成事件。这不等于自动重连，也不是按事件游标逐条补齐所有历史事件。 接入层仍应以运行状态和最终输出确认结果，不能通过再次调用执行接口来“恢复连接”。具体约定见事件续接入口。
需要停止时，调用 POST /v1/workflows/tasks/{task_id}/stop，按接口要求传入 user，不能把 workflow_run_id 填进停止地址。停止接口调用任务停止服务；运行中的任务通过停止标记与引擎中止命令处理。停止请求返回成功，不应解释成已经撤销此前的业务写入，外部接口的办理结果仍需单独确认。
接入层怎样验证
先用一个输入输出明确的小流程确认字段映射，再覆盖成功、节点失败、人工暂停、收到运行标识后断线和停止请求等情况。若流程包含业务写入，还应模拟“下游已办理，但调用方没收到结果”后再次提交，核对是否重复办理；这部分保证依赖业务接口和接入层设计，不能由 Dify 的运行 ID 推导出来。
对应教程
- Python 调用 Dify 平台工作流：采用发布工作流、配置鉴权与输入、读取完成事件的调用主线，补充超时、状态查询、事件续接和重复副作用的处理。
参考资料
- 国内：扣子：执行工作流：依据其发布、权限和异步执行约定，说明不同平台的输入、执行模式与结果查询标识需要分别适配。
- 国内：扣子：执行工作流（流式响应）：采用其输出、错误、结束和中断事件的区分，说明流式解析器不能直接套用另一平台的事件名称与结构。
- 国内：腾讯云：实现第三方系统对接工作流：借鉴流程实例与业务记录分别建关联的设计，解释业务单号、运行标识和业务状态应怎样对应。
- 国内：阿里云：如何保证幂等性：采用显式幂等令牌及参数一致性的约定，说明安全重试依赖服务端支持，不能向任意工作流接口添加一个字段就获得保证。
- 国外：Dify：Get Started with the Dify API：依据应用密钥的服务端调用要求及终端用户区分方式，说明密钥与
user各自承担的职责。 - 国外：HTTPX：Timeouts：依据连接、读取、写入与连接池等待超时的定义，解释读取超时和业务总时限为何需要分开设置。
- 国外：MDN：Using server-sent events：采用空行分帧、多行数据合并和注释心跳的协议规则，说明流式接收不能把网络数据块直接当成完整事件。
