Stream 代理消息

Teams 代理在准备向用户发送聊天回复时可以提供有关其状态的实时更新,然后在生成响应内容时将响应内容流式传输到对话中。 使用这些技术,代理可以清楚地确认收到用户消息、传达生动性并最大限度地提高整体响应能力。

注意

使用 Teams SDK 实现此处显示的流式处理体验需要程序包 Microsoft.Teams.Apps 版本 2.1.0 或更高版本。 使用旧版 Teams SDK 的代理只能在代理和用户之间的一对一对话中使用流式处理 API,并且信息更新和响应生成将在旧版体验中呈现。

注意

使用 Teams SDK 实现此处显示的流式处理体验需要程序包 microsoft-teams-apps 版本 2.0.15 或更高版本。 使用旧版 Teams SDK 的代理只能在代理和用户之间的一对一对话中使用流式处理 API,并且信息更新和响应生成将在旧版体验中呈现。

注意

使用 Teams SDK 实现此处显示的流式处理体验需要程序包 @microsoft/teams.apps 版本 2.0.14 或更高版本。 使用旧版 Teams SDK 的代理只能在代理和用户之间的一对一对话中使用流式处理 API,并且信息更新和响应生成将在旧版体验中呈现。

用户体验

消息流包括两个阶段: 可选的信息更新,然后是消息内容流。

信息性更新

信息更新是代理在准备流式传输对用户消息的响应时可以选择显示的短文本。 它们显示在代理正在回复的聊天消息的正下方,而不是消息气泡中,并附有动画图标。 代理发送的每个新更新都会替换前一个更新。

根据用户请求进行的信息更新的屏幕截图。

汇报不会为对话创建通知或触发未读消息徽章。 在群组聊天、频道和会议聊天中,信息更新将显示给对话中的每个人。

消息内容流式传输

消息内容流在代理发出消息内容时,将消息内容块附加到对话气泡中。

代理开始流式处理时的响应的屏幕截图。

发出第一个内容区块将创建气泡并停止显示信息性更新。 随着流式传输内容的附加,气泡在对话中的位置保持固定,当代理发出流式处理完成信号时,气泡会变动。

使用扩展 Markdown 模式发送的流式邮件会逐渐呈现其格式设置,以提供流畅的阅读体验。 有关详细信息,请参阅 设置代理消息格式 。

流式处理开发人员的一般注意事项

代理每次对话只能维护一个开放流,但可以同时在多个对话中打开流。

每个信息性更新文本不得超过 1 KB 或 1000 个字符。

代理开始发出流式内容后,将不会显示其发出的任何进一步的信息性更新。

扩展 Markdown 模式 与消息内容流兼容,并支持渐进呈现格式。

流超时,并在代理写入第一个信息性更新或内容区块后 10 分钟自动关闭。

信息更新和消息内容流式处理旨在在接收的消息的活动处理程序的上下文中响应特定用户消息。 在 主动消息传递方案中不支持它们。

某些消息功能(如附件、AI 标签、反馈按钮和敏感度标签)仅在代理完成流式传输后才会呈现。 有关详细信息,请参阅 附件、 AI 内容标签和 用户反馈控件。

使用 Teams SDK 实现流式传输

流在传入消息活动上下文中公开。 使用 stream 对象发送信息性更新、发出内容区块,并在生成完成后完成响应。 SDK 会为你处理限制,因此你可以在模型生成区块时发出区块,而无需手动同步每个请求。 在 TypeScript 和 Python 中,SDK 会在处理程序结束时自动关闭流(如果尚未显式关闭它)。 在 C# 中,必须使用 writer.FinalizeResponseAsync(finalActivity)显式关闭流。

用于 TeamsStreamingWriter 编写信息性更新和从消息上下文流式传输内容。 追加所有内容区块后,通过调用 writer.FinalizeResponseAsync(finalActivity) 最终消息活动来显式关闭流。 C# SDK 不会在处理程序返回时自动关闭流。 当流式响应使用更丰富的格式时,请将最终消息活动的 TextFormat 属性设置为 extendedmarkdown。 某些消息功能(如 AI 标签或卡片)仅在流关闭后呈现。

teams.OnMessage(async (context, cancellationToken) =>
{
  TeamsStreamingWriter writer = TeamsStreamingWriter.CreateFromContext(context);

  await writer.SendInformativeUpdateAsync("Reviewing the latest project status...", cancellationToken);
  await Task.Delay(1000, cancellationToken);

  var finalActivity = new Activity
  {
    Type = ActivityTypes.Message,
    TextFormat = "extendedmarkdown",
    Text = """
    ## Project status

    - [x] API tests passed
    - [x] Deployment checks completed
    - [ ] Final sign-off pending

    The release is on track for Friday.
    """
  };

  await writer.AppendResponseAsync(finalActivity.Text, cancellationToken);
  await writer.FinalizeResponseAsync(finalActivity);
});

发出的内容可以包括 markdown 标题、任务列表和强调,以提高消息流入时的可读性。 如果包括其他消息功能(如 AI 标签或卡),则它们仅在流关闭后呈现。

使用传入消息活动上下文上的对象发送 stream 信息性更新并发出内容区块。 stream.update 可以使用不同的更新文本多次调用,并将 stream.emit 一块消息内容写入活动对话气泡中。 SDK 会为你处理限制,因此你可以在模型生成区块时发出区块,而无需手动同步请求。 如果未显式关闭流,SDK 将在消息处理程序退出时自动完成它。

用于 stream.emit 将内容块写入流。 Teams 收到区块后,它们将呈现到消息中。 第一次调用 stream.emit后,将不再显示信息性更新, stream.update 并且不会起作用。

app.on('message', async ({ activity, stream }) => {
  stream.update("Preparing a project status update...");
  await new Promise(resolve => setTimeout(resolve, 1000));

  const summary = [
    '## Project status',
    '',
    '- [x] API tests passed',
    '- [x] Build completed',
    '- [ ] Final sign-off pending',
    '',
    'The rollout is still on track for Friday.'
  ].join('\n');

  // AI labels and cards render only after the stream is closed.
  stream.emit(new MessageActivityInput(summary).withTextFormat('extendedmarkdown'));
});

相同的模式适用于渐进式流式传输的多部分响应,在每个区块到达时使用扩展的 Markdown 呈现标题、列表和内联强调。

使用传入消息活动上下文上的对象发送 stream 信息性更新并发出内容区块。 stream.update 可以使用不同的更新文本多次调用,并将 stream.emit 一块消息内容写入活动对话气泡中。 SDK 会为你处理限制,因此你可以在模型生成区块时发出区块,而无需手动同步请求。 如果未显式关闭流,SDK 将在消息处理程序退出时自动完成它。

用于 stream.emit 将内容块写入流。 Teams 收到区块后,它们将呈现到消息中。 第一次调用 stream.emit后,将不再显示信息性更新, stream.update 并且不会起作用。

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    ctx.stream.update("Preparing a status update...")
    await asyncio.sleep(1)

    status = """## Project status

- [x] API tests passed
- [x] Build completed
- [ ] Final sign-off pending

The rollout is still on track for Friday.
"""

    # AI labels and cards render only after the stream is closed.
    ctx.stream.emit(MessageActivityInput(text=status).with_text_format("extendedmarkdown"))

为了获得更自然的流式处理体验,请发出一系列 markdown 格式的文本区块,并让 Teams 在它们到达时逐步呈现它们。

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    ctx.stream.update("Starting the *extended* markdown stream...", "markdown")
    await asyncio.sleep(1)

    for message in [
        "### Release summary\n\n- [x] Build complete\n- [x] Tests passed\n",
        "- [ ] Final sign-off pending\n\nThe app is ready to ship once approval is received.\n",
        "**Important:** package validation is still running in the background.",
    ]:
        await asyncio.sleep(0.5)
        ctx.stream.emit(MessageActivityInput(text=message).with_text_format("extendedmarkdown"))

通过 REST API 实现流式处理

尽管有它的名字,但内容流并不依赖于 HTTP 流或类似技术。 在 HTTP API 级别,它是作为请求序列实现的。 每个请求要么设置要显示的新信息性更新文本,要么更新流式消息的内容。

打开一个流

若要开始流式传输,请向终结点发送一个活动有效负载 /conversations/<conversationId>/activities ,包括以下必需有效负载值 (以及其他所需值) :

  • type: typing
  • replyToId:正在回复的用户消息的 ID。 在一对一对话中是可选的,但流式处理和信息更新将在旧版体验中呈现。
  • text:第一个信息性更新文本。 如果跳过信息性更新阶段,则为第一个内容区块。
  • entities[0].type: streamInfo
  • entities[0].streamType: informative. 如果跳过信息性更新阶段并发送第一个内容区块,请设置为 streaming。
  • entities[0].streamSequence: 1
POST /conversations/<conversationId>/activities HTTP/1.1

{
  "type": "typing",
  "serviceurl": "<https://smba.trafficmanager.net/amer/>",
  "channelId": "msteams",
  "from": {
    "id": "<botId>",
    "name": "<BotName>"
  },
  "conversation": {
    "conversationType": "personal",
    "id": "<conversationId>"
  },
  "recipient": {
    "id": "<recipientId>",
    "name": "<recipientName>",
    "aadObjectId": "<recipient aad objecID>"
  },
  "locale": "en-US",
  "replyToId": "<userMessageId>",
  "text": "Searching through documents...",
  "entities":[
    {
      "type": "streaminfo",
      "streamType": "informative",
      "streamSequence": 1
    }
  ]
}

201 Created响应将包括一个带有属性id的 JSON 有效负载,其值必须用作entities.streamId所有后续请求中的值。

发送信息性更新和消息内容更新

打开流后,使用流的 ID 发送其他请求,以显示信息更新和流消息内容。 包括以下有效负载:

  • type: typing
  • replyToId:正在回复的用户消息的 ID。 在一对一对话中是可选的,但流式处理和信息更新将在旧版体验中呈现。
  • text:要显示的新信息性更新文本,或到目前为止生成的整个消息内容
  • entities[0].type: streamInfo
  • entities[0].streamType: informative 如果设置新的信息性更新文本, streaming 如果更新邮件内容
  • entities[0].streamSequence: <每个请求发送递增>

一旦开始发送消息内容,请不要发送任何进一步的信息更新,因为它们将不会显示。

流式处理消息内容时,每个请求都表示一次完整的消息更新,而不仅仅是要附加的新内容。 在生成内容时在本地累积内容,并将整个累积值作为有效负载发送 text 到每个请求中。 尝试更改上一个请求中提供的内容的请求将导致 403 ContentStreamNotAllowed 错误 Request streamed content should contain the previously streamed content消息。

每个流式处理请求可以包括表示消息功能的其他 entities 值,但在流关闭之前,大多数功能不会在 Teams 客户端中呈现。

该服务的速率限制为每个流每秒 1 个。 缓冲区生成的内容,以根据需要限制请求。

POST /conversations/<conversationId>/activities HTTP/1.1 
{
  "type": "typing",
  "serviceurl": "https://smba.trafficmanager.net/amer/",
  "channelId": "msteams",
  "from": {
    "id": "<botId>",
    "name": "<BotName>"
  },
  "conversation": {
    "conversationType": "personal",
    "id" : "<conversationId>"
  },
  "recipient": {
    "id": "<recipientId>",
    "name": "<recipientName>",
    "aadObjectId": "<recipient aad objecID>"
  },
  "locale": "en -US",
  "replyToId": "<userMessageId>",
  "text": "Searching through emails...",
  "entities":[
    {
      "type": "streaminfo",
      "streamId": "a-0000l",
      "streamType": "informative",
      "streamSequence": 2
    }
  ],
}

关闭流

消息生成完成后,通过发送具有以下有效负载属性的消息活动来关闭流:

  • type: message
  • replyToId:正在回复的用户消息的 ID。 在一对一对话中是可选的,但流式处理和信息更新将在旧版体验中呈现。
  • text:完整的消息内容
  • entities[0].type: streamInfo
  • entities[0].streamId: id 从初始响应获取的值
  • entities[0.streamType: final

不包含在 entities[0].streamSequence 最终请求有效负载中。

POST /conversations/<conversationId>/activities HTTP/1.1
{
  "type": "message",
  "serviceurl" : "https://smba.trafficmanager.net/amer/ ",
  "channelId": "msteams",
  "from": {
    "id": "<botId>",
    "name": "<BotName>"
  },
  "conversation": {
    "conversationType": "personal",
    "id" : "<conversationId>"
  },
  "recipient": {
    "id" : "recipientId>",
    "name": "<recipientName>",
    "aadObjectId": "<recipient aad objecID>"
  },
  "locale": "en-US",
  "replyToId": "<userMessageId>", // ID of the user's message that the agent is responding to. Required in conversations other than one-on-one chats.
  "text": "A brown fox jumped over the fence.", // (required) first streaming content.
  "entities":[
    {
      "type": "streaminfo",
      "streamId": "a-0000l", // // (required) must be present for any subsequent request after the first chunk.
      "streamType": "final", // (required) final is only allowed for the last message of the streaming.
    }
  ],
}

响应代码

以下是成功代码和错误代码:

成功代码

Http 状态代码 返回值 说明
201 streamId,这与activityId{"id":"1728640934763"} 代理在发送初始流式处理请求后返回此值。
对于任何后续的流式处理请求,是必需的 streamId 。
202 {} 任何后续流式处理请求的成功代码。

错误代码

Http 状态代码 错误代码 错误消息 说明
202 ContentStreamSequenceOrderPreConditionFailed PreCondition failed exception when processing streaming activity. 很少有流式处理请求可能会按顺序到达并被丢弃。 以无序方式接收请求时,将使用最新的流式处理请求(由 streamSequence确定)。 确保按顺序发送每个请求。
400 BadRequest 根据不同的场景,你可能会遇到各种错误消息,例如 Start streaming activities should include text 传入的有效负载不遵守或不包含必要的值。
403 ContentStreamNotAllowed Content stream is not allowed 用户或代理不允许使用流式处理 API 功能。
403 ContentStreamNotAllowed Content stream is not allowed on an already completed streamed message 代理无法连续流式传输已流式传输并完成的消息。
403 ContentStreamNotAllowed Content stream finished due to exceeded streaming time. 代理无法在 10 分钟的时限内完成流式传输过程。
403 ContentStreamNotAllowed Message size too large 代理发送的消息超过当前 消息大小 限制。
403 ContentStreamNotAllowed Request streamed content should contain the previously streamed content 流消息的传入内容不包含已流式传输的内容。
429 不适用 API calls quota exceeded 代理流式传输的消息数已超出配额。

代码示例

示例名称 Description Node.js C# Python
Teams SDK 流式处理示例 此示例演示如何在最新的 SDK 中流式传输代理响应并使用扩展的 Markdown 格式。 View View View
流式处理 + 扩展 Markdown 示例 此示例演示了在内容仍在流式传输时 Markdown 格式输出的渐进呈现。 View 不适用 View

另请参阅