> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

扣子编程支持流式插件，低代码智能体或工作流在单次调用插件时，可以输出多条消息，每条消息能够以类似打字机的效果逐条动态显示，实现流式输出效果。
## 应用场景 {#595a7fd5}
流式插件适用于需要实时处理和展示连续消息流的场景，它能够提供动态的消息输出，增强用户体验，例如聊天机器人和实时通知场景。
## 注意事项 {#71775e89}
关于流式插件的相关注意事项如下：

* 绑定了流式插件的低代码智能体和应用不支持以卡片的形式输出消息，即便是流式插件绑定了卡片，也不会生效。
* 在低代码智能体中使用流式插件，流式输出的内容不会经过大模型处理，对于非流式输出的最后一条消息内容，可以选择是否需要大模型处理，而在工作流中使用流式插件，流式输出的内容都不会经过大模型节点处理。
* 仅基于已有服务创建的插件，支持配置流式插件；端插件和在 IDE 中创建的插件都不支持配置流式插件。
* 配置流式插件时，**编辑工具**页面中的**输出参数**无需配置。

## SSE 协议实现 {#e2f917e3}
配置流式插件，你的业务接口需要实现 Server-Sent Events (SSE) 传输协议，并遵守扣子编程插件所定义的数据协议规范。
### 基本约束 {#53b33dcb}

* 每个数据包最大为 250KB。
* 每个数据包间隔的超时时间为 60s。

### 数据结构定义 {#35ecbb4e}
数据结构定义说明如下：
:::tip 说明
* 生效维度表示字段的作用范围，包括流维度、数据包维度和消息维度。
* `data` 是数据对象经过 JSON 序列化后得到的数据，实际流转时是 []byte 类型。在某些日志输出中，可能会看到这些数据被编码为 Base64 格式，这是正常现象。
:::
<!-- @cols-width: 145,100,100,116,402 -->
| | | | | | \
|**字段** |**类型** |**是否必选** |**生效维度** |**字段说明** |
|---|---|---|---|---|
| | | | | | \
|id |\
| |string |\
| | |必选 |\
| | | |数据包维度 |事件 ID。 |\
| | | | |事件的唯一标识符，用于跟踪流式传输中的事件。浏览器会自动记录最后一个接收到的事件 ID，并在发生断开连接时，将此 ID 放入 HTTP 头部的`Last-Event-Id`字段中，以便重新连接时使用，实现基本的同步机制。通常，每个事件包都被赋予一个用户自定义的唯一标识符，例如 UUID。 |
| | | | | | \
|event |string |必选 |数据包维度 |事件名。 |
| | | | | | \
|data |[]byte |必选 |数据包维度 |消息数据，将 JSON 数据序列化为字节切片（[]byte），在编辑器中显示为 Base64 编码的字符串。 |\
| | | | | |\
| | | | | |
| | | | | | \
|data.stream_id |\
| |string |必选 |消息维度 |消息 ID。 |\
| | | | |在流式调用过程中，相同的`StreamId`表示连续的消息片段，属于同一条消息，而不同的`StreamId`则表示不同的消息。 |
| | | | | | \
|data.output_mode |Integer |可选 |消息维度 |当前 message 的输出模式： |\
| | | | | |\
| | | | |* 0：一次性完整输出消息 |\
| | | | |* 1：分多次输出消息 |\
| | | | | |\
| | | | |默认值为 0。 |
| | | | | | \
|data.return_type |\
| |Integer |可选 |\
| | | |消息维度 |最后一条 message 输出目标： |\
| | | | | |\
| | | | |* 0：输出到模型，模型总结后返回给用户 |\
| | | | |* 1：直接输出给用户 |\
| | | | | |\
| | | | |默认值为 0，当`output_mode`设置为 1 时，该值将被强制更改为 1。 |
| | | | | | \
|data.content_type |Integer |可选 |数据包维度 |本次数据包输出内容的类型，仅可传 0 表示文本，默认值为 0。 |
| | | | | | \
|data.context_mode |Integer |可选 |消息维度 |下次对话时，是否将这条消息加入聊天上下文： |\
| | | | | |\
| | | | |* 0：加入上下文 |\
| | | | |* 1：不加入上下文 |\
| | | | | |\
| | | | |默认值为 0。 |
| | | | | | \
|data.content |string |可选 |数据包维度 |业务接口返回内容 ，默认值为 nil。 |\
| | | | |在智能体中引用流式插件时，如果流式插件返回的任意一个事件包中 `content` 字段为空，会导致智能体最终返回空回复。建议设计流式插件输出时，避免事件包返回空的 `content` 字段。 |
| | | | | | \
|data.is_finish |\
| |bool |\
| | |必选 |\
| | | |流维度 |整个流是否结束。 |\
| | | | |只需在最后一个业务数据包中设置`is_finish`标志，无需发送额外的空数据包。 |
| | | | | | \
|data.is_last_msg |bool |必选 |消息维度 |是否为最后一条消息。 |
| | | | | | \
|data.is_last_packet_in_msg |bool |必选 |数据包维度 |是否为当前 message 的最后一个包。 |
| | | | | | \
|data.ext |map[string]string |可选 |数据包维度 |扩展字段，默认值为 nil。 |

以下是一个流请求的数据包标识示例：
<!-- @cols-width: 100,207,200,100,171 -->
| | |||| \
|message  |数据包维度 | | | |
|---|---|---|---|---|
| | | | | | \
|message 1 |\
| |数据包 1 |\
| |is_last_msg=false |\
| |is_finish=false |\
| |is_last_packet_in_msg=false |数据包 2 |\
| | |is_last_msg=false |\
| | |is_finish=false |\
| | |is_last_packet_in_msg=false |... |数据包 End |\
| | | | |is_last_msg=false |\
| | | | |is_finish=false |\
| | | | |is_last_packet_in_msg=true |
| | | | | | \
|message 2 |数据包 1 |\
| |is_last_msg=false |\
| |is_finish=false |\
| |is_last_packet_in_msg=false |数据包 2 |\
| | |is_last_msg=false |\
| | |is_finish=false |\
| | |is_last_packet_in_msg=false |... |数据包 End |\
| | | | |is_last_msg=false |\
| | | | |is_finish=false |\
| | | | |is_last_packet_in_msg=true |
| | | | | | \
|... |... |... |... |... |
| | | | | | \
|message End |数据包 1 |\
| |is_last_msg=true |\
| |is_finish=false |\
| |is_last_packet_in_msg=false |数据包 2 |\
| | |is_last_msg=true |\
| | |is_finish=false |\
| | |is_last_packet_in_msg=false |... |数据包 End |\
| | | | |is_last_msg=true |\
| | | | |is_finish=true |\
| | | | |is_last_packet_in_msg=true |

以下是一个数据包返回示例：
```Go
{    
    "id" : "xxxxx1",
    "event": "play",
    "data": {
        "is_last_msg":false,
        "is_finish":false,
        "is_last_packet_in_msg":false,
        "stream_id":"message1",
        "context_mode": 0,
        "output_mode": 0 ,
        "return_type": 0 ,
        "content_type": 0 ,
        "content": "{插件输出内容}",
        "ext":{
            "example1":"{xxx}",
            "example2":"1",
        }
    }
}
```

### 传输协议规范 {#bd8324fc}
实现 SSE 协议时，HTTP 响应头需满足如下要求。
<!-- @cols-width: 214,154,475 -->
| | | | \
|**响应头（Response Header）** |**取值（Value）** |**说明** |
|---|---|---|
| | | | \
|Content-Type |text/event-stream |\
| | |告知客户端该响应为事件流，用于区别普通的 HTTP 响应。 |
| | | | \
|Connection |keep-alive |SSE **是长连接**，需保持连接状态，防止客户端会误判数据传输已完成。 |
| | | | \
|Transfer-Encoding |chunked |采用**分块传输**编码，支持数据的流式推送。 |

### 数据 Schema 验证 {#aee5b835}
按照 SSE 的数据包协议进行返回，确保数据格式符合以下示例。

::::cols
@col 50
用 CURL 验证格式：
![Image=419x293](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4d91209700664efd86cc0075e639f2b9~tplv-goo7wpa0wc-image.image)


@col 50
用 Postman 验证格式：
![Image=1649x1027](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4c3a77a058ce4399aa16c24334ece2f4~tplv-goo7wpa0wc-image.image)


::::

## 配置流式插件 {#622920c1}
你已经创建了一个插件，API 接口已经实现 SSE 传输协议，并且 API 接口遵守扣子编程插件所定义的数据协议规范，详情请参考[快速搭建智能体列表查询插件](/tutorial/build_a_agent_query_plugin)。
1. 登录[扣子编程](https://code.coze.cn/home)。
2. 在页面顶部选择目标工作空间，然后在左侧导航栏中单击**资源库**。


3. 在**插件**页签下，单击目标插件。
4. 在插件详情页，单击**使用代码编辑工具**的图标。
   ![Image=749x189](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/a06998d97f454b3d8b3e8d1929298194~tplv-goo7wpa0wc-image.image)
5. 在**更新插件**页面，单击**编辑**。
6. 在 **openapi (填写 yaml)** 区域，找到需要配置为流式输出的接口，在`operationId`下添加`x-runMode: Streaming`，以开启该接口的流式输出模式。
   代码示例如下：
   ```YAML
   info:
       description: stream output demo
       title: Stream Demo
       version: v1
   openapi: 3.0.1
   paths:
       /your/stream/api:
           post:
               operationId: stream
               x-runMode: Streaming
               requestBody:
                   content:
                       application/json:
                           schema:
                               type: object
               responses:
                   "200":
                       content:
                           application/json:
                               schema:
                                   type: object
                       description: empty response
                   default:
                       description: ""
               summary: stream demo
   servers:
       - url: https://www.demo.com
   ```


配置完成后，你可以调试插件。如果插件输出结果符合预期，你就可以发布插件。
## 使用流式插件 {#ee905896}
你可以在智能体或工作流中使用流式插件，详情可参考[使用插件](/guides/use_plugin)。
:::notice 注意
在工作流中使用流式插件，请注意：

* **即时数据输出**：当执行到流式插件节点时，系统会直接输出流式插件返回的数据。只有当所有数据输出完毕后，工作流才会继续执行后续节点。
* **调试限制**：在工作流调试过程中，由于流式插件的特性，无法直接展示其输出效果。因此，为了查看流式插件的实际输出，建议在智能体中绑定使用了流式插件的工作流，以便观察和验证流式输出的实际效果。
:::
![Image=2044x1014](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/dd89d9b8ff6547fc83d9d0ae72733a81~tplv-goo7wpa0wc-image.image)