Сообщения агента Stream

Примечание.

  • Потоковые сообщения агента поддерживаются только в индивидуальных чатах.
  • Teams поддерживает только один одновременный ответ потоковой передачи на чат.
  • Потоковая передача обычно доступна в Интернете, на компьютерах и мобильных устройствах.

Вы можете передавать потоковые сообщения агента, чтобы доставлять ответы агента пользователю в виде небольших обновлений, пока генерируется полный ответ, чтобы улучшить взаимодействие с пользователем. Часто агентам требуется много времени для генерации ответов без обновления пользовательского интерфейса, что приводит к снижению привлекательности взаимодействия.

Когда пользователи наблюдают, как агент обрабатывает их запрос в режиме реального времени, это может повысить их удовлетворенность и доверие. Такая воспринимаемая скорость реагирования и прозрачность повышает вовлеченность пользователей и снижает вероятность отказа от разговора с оператором.

Пользовательский интерфейс сообщений Stream

У агента потоковой передачи сообщений есть два типа обновлений.

  • Информационные обновления: информационные обновления появляются в облаке потокового сообщения и информируют пользователя о текущих действиях агента во время создания ответа. Он text остается видимым до тех пор, пока его не заменит следующее информативное обновление или потоковое содержимое.

    На снимке экрана показаны информативные обновления агентов о потоковой передаче.

    Информативные сообщения не должны превышать 1 КБ или 1000 символов.

  • Потоковая передача ответов: потоковая передача ответов заменяет информативное обновление и отображает ответ агента в облаке сообщения по мере его создания.

    Снимок экрана: потоковая передача ответов агентов.

    • Кнопка "Стоп": эта кнопка позволяет пользователям управлять потоковыми ответами, останавливая их на ранней стадии. Он доступен по умолчанию во время потоковой передачи, позволяя пользователям уточнять запросы или отправлять новые. Понимание того, как работает кнопка остановки потоковой передачи, может помочь в разработке более эффективных и удобных диалоговых интерфейсов.

    • Постепенное форматирование: Teams будет постепенно визуализировать форматирование потоковых сообщений, отправленных в расширенном режиме Markdown, чтобы обеспечить плавное чтение. Дополнительные сведения см. в статье Форматирование сообщений агента.

    • Потоковое содержимое: во время потоковой передачи сообщения агента должны содержать предыдущий потоковый контент.

      Пример: Это пример приемлемого отклика при потоковой передаче.
      Коричневый
      Бурая лиса
      Бурая лиса перепрыгивает через забор

      Не пример: Это пример ответа потоковой передачи, возвращающего ошибку.
      Коричневый
      Здравствуйте!

      Дополнительные сведения об ошибке см. в разделе "Коды ошибок".

Реализация потоковой передачи с помощью пакета SDK для Teams

Используется Stream.Update для написания информационных обновлений перед началом потока сообщений. Stream.Update может вызывать несколько раз с разным текстом обновления.

Используется Stream.Emit для записи фрагмента контента в поток. Фрагменты будут отображаться в сообщении сразу после их получения Teams. После первого звонка в Stream.Emit, информационные обновления больше не будут отображаться и Stream.Update не будут иметь никакого эффекта.

app.OnMessage(async (context, cancellationToken) =>
{   
   context.Stream.Update("Testing");
   await Task.Delay(1000);
   context.Stream.Emit("hello");
   context.Stream.Emit(", ");
   context.Stream.Emit("world!");
});

Используется stream.update для написания информационных обновлений перед началом потока сообщений. stream.update может вызывать несколько раз с разным текстом обновления.

Используется stream.emit для записи фрагмента контента в поток. Фрагменты будут отображаться в сообщении сразу после их получения Teams. После первого звонка в stream.emit, информационные обновления больше не будут отображаться и stream.update не будут иметь никакого эффекта.

app.on('message', async ({ activity, stream }) => {
  stream.update("Thinking...");
  await new Promise(resolve => setTimeout(resolve, 1000))  
  stream.emit('hello');
  stream.emit(', ');
  stream.emit('world!');

  // result message: "hello, world!"
});

Используется stream.update для написания информационных обновлений перед началом потока сообщений. stream.update может вызывать несколько раз с разным текстом обновления.

Используется stream.emit для записи фрагмента контента в поток. Фрагменты будут отображаться в сообщении сразу после их получения Teams. После первого звонка в stream.emit, информационные обновления больше не будут отображаться и stream.update не будут иметь никакого эффекта.

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

    # Stream messages with delays using ctx.stream.emit
    for message in STREAM_MESSAGES:
        # Add some randomness to timing
        await asyncio.sleep(random())

        ctx.stream.emit(message)

Передача сообщений Stream через REST API

Сообщения агента можно передавать в потоковом режиме через REST API. Потоковые сообщения поддерживают форматирование текста и цитирование. Вложение, метка ИИ, кнопка обратной связи и метки конфиденциальности доступны только для окончательного сообщения потоковой передачи. Дополнительные сведения см. во вложениях, метках содержимого ИИ и элементах управления отзывами пользователей.

Когда агент вызывает потоковую передачу через REST API, обязательно вызывайте следующий API потоковой передачи только после получения успешного ответа от первоначального вызова API. Если агент использует SDK, убедитесь, что получен объект ответа null от метода send activity, чтобы подтвердить, что предыдущий вызов был успешно передан.

Если агент слишком быстро вызывает API потоковой передачи, могут возникнуть проблемы, а потоковая передача может быть прервана. Рекомендуется выполнять потоковую передачу агентом по одному сообщению за раз, чтобы вызывать API потоковой передачи в согласованном темпе. Если нет, запрос может быть отрегулирован. Поместите маркеры в буфер из модели на 1,5–две секунды, чтобы обеспечить плавный процесс потоковой передачи.

Ниже приведены свойства для потоковых сообщений агента.

Property Обязательный Описание
type ✔️ Поддерживаемые значения: или typingmessage.
typing• : использование при потоковой передаче сообщения.
message• : использование для конечного потокового сообщения.
text ✔️ Содержимое сообщения, которое необходимо передать. Teams отображает это значение в облаке сообщения агента. При informative обновлении текст остается видимым до тех пор, пока его не заменит следующее обновление или первый потоковый блок. Действие запуска потоковой передачи, которое пропускает text , отклоняется.
entities.type ✔️ Необходимое значение — streamInfo.
entities.streamId ✔️ streamId Начните потоковую передачу из первоначального запроса на потоковую передачу.
entities.streamType Тип потоковых обновлений. Поддерживаемые значения: informative, streaming, или final. Значение по умолчанию — streaming. final используется только в заключительном сообщении.
entities.streamSequence ✔️ Инкрементное целое число для каждого запроса.

Примечание.

Для REST API streamSequence должны начинаться с 1 и увеличиваться на 1 для каждого последующего запроса потоковой передачи. Не настроен streamSequence на итоговое сообщение. Анимация ввода текста в Teams недоступна, пока открыта трансляция. Если у вашего агента еще нет содержимого ответа, отправьте информативное сообщение вместо пустого или пустого текста.

Чтобы включить потоковую передачу в агентах, выполните следующие действия.

  1. Начать потоковую передачу
  2. Продолжить потоковую передачу
  3. Финальная потоковая передача

Начать потоковую передачу

Агент может отправить либо информативное, либо потоковое сообщение в качестве исходной связи. Ответ включает streamId, который важен для выполнения последующих вызовов.

Действие запуска потоковой передачи должно включать text. Если text отсутствует, запрос завершается сбоем с ответом 400 BadRequest и сообщением Start streaming activities should include textоб ошибке. Teams отображает это значение в облаке сообщений, поэтому используйте информативное обновление для первого действия. Дополнительные сведения см. в разделе "Коды ошибок".

Ваш агент может отправлять несколько информативных обновлений при обработке запроса пользователя, например при просмотре документов, обобщении контента и найденных релевантных рабочих элементах. Эти обновления можно отправить до того, как агент создаст окончательный ответ пользователю.


//Ex: An agent sends the first request with content & the content is informative loading message.

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",
  "text": "Searching through documents...", //(required) first informative loading message.
  "entities":[
    {
      "type": "streaminfo",
      "streamType": "informative", // informative or streaming; default= streaming.
      "streamSequence": 1 // (required) incremental integer; must be present for start and continue streaming request, but must not be set for final streaming request.
    }
  ],
}

201 created { "id": "a-0000l" } // return stream id

На следующем рисунке показан пример запуска потоковой передачи:

Снимок экрана: начало потоковой передачи.

Продолжить потоковую передачу

Используйте сообщение streamId , полученное в результате первоначального запроса, для отправки информационных или потоковых сообщений. Вы можете начать с информативных обновлений , а позже, когда будет готов окончательный ответ, переключиться на потоковую передачу ответов .

Начните с информативных обновлений

По мере формирования ответа агентом отправляйте пользователю информативные обновления, например о просмотре документов, резюмировании контента и найденных релевантных рабочих элементах. Убедитесь, что вы будете совершать последующие звонки только после того, как агент получит успешный ответ на предыдущие.

Каждое информативное обновление заменяет предыдущее в облаке сообщений и остается видимым для пользователя до появления следующего обновления или первого потокового блока.


// Ex: An agent sends the second request with content & the content is informative loading message.

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",
  "text": "Searching through emails...", // (required) second informative loading message.
  "entities":[
    {
      "type": "streaminfo",
      "streamId": "a-0000l", // // (required) must be present for any subsequent request after the first chunk.
      "streamType": "informative", // informative or streaming; default= streaming.
      "streamSequence": 2 // (required) incremental integer; must be present for start and continue streaming request, but must not be set for final streaming request.
    }
  ],
} 
202 0K { }

На следующем рисунке показан пример агента, предоставляющего информативные обновления:

Снимок экрана показывает информативные обновления потоковой передачи.

Переключение на потоковую передачу ответов

После того как ваш агент будет готов создать окончательное сообщение для пользователя, переключитесь с предоставления информативных обновлений на потоковую передачу ответов. Для каждого обновления потока ответов содержимое сообщения должно содержать последнюю версию окончательного сообщения. Это означает, что агент должен включать все новые маркеры, создаваемые большими языковыми моделями (LLM). Добавьте эти маркеры к предыдущей версии сообщения и отправьте его пользователю.

Ограничение регулирования составляет 1 запрос в секунду. Необходимо убедиться, что агент отправит запрос в пределах этого ограничения. При необходимости агент может отправлять запросы медленнее.


// Ex: An agent sends the third request with content & the content is actual streaming content.

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" ,
  "text": "A brown fox", // (required) first streaming content.
  "entities":[
    {
      "type": "streaminfo",
      "streamId": "a-0000l", // // (required) must be present for any subsequent request after the first chunk.
      "streamType": "streaming", // informative or streaming; default= streaming.
      "streamSequence": 3 // (required) incremental integer; must be present for start and continue streaming request, but must not be set for final streaming request.
    }
  ],
}
202 0K{ }



// Ex: An agent sends the fourth request with content & the content is actual streaming content.

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" ,
  "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": "streaming", // informative or streaming; default= streaming.
      "streamSequence": 4 // (required) incremental integer; must be present for start and continue streaming request, but must not be set for final streaming request.
    }
  ],
}
202 0K{ }

На следующем рисунке показан пример агента, предоставляющего обновления по частям:

Снимок экрана: потоковая передача ответа.

Финальная потоковая передача

После того как ваш агент завершит генерацию сообщения, отправьте сигнал конечной потоковой передачи вместе с заключительным сообщением. Для заключительного type сообщения действие равно message. Здесь агент устанавливает все поля, разрешенные для обычного действия с сообщениями, но final является единственным допустимым значением для streamType.


// Ex: An agent sends the second request with content && the content is informative loading message.

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",
  "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.
    }
  ],
  }
202 0K{ }

На следующем изображении показан пример окончательного ответа агента:

Снимок экрана: финальное потоковое сообщение.

Остановка потокового ответа агента

Эта кнопка позволяет пользователям управлять потоковыми ответами. Кнопка "Стоп" доступна по умолчанию во время потоковой передачи, что позволяет пользователям остановить ответ раньше времени. Пользователи могут прерывать поток сообщений и уточнять свои запросы или отправлять новые. Это расширяет возможности управления беседами с помощью агентов для улучшения взаимодействия с пользователем.

После того как пользователь прекратит создание сообщений:

  • Агенты считают остановленные ответы неполными или отброшенными в беседе.

  • Агенты не могут изменять уже переданный контент.

  • Следующая ошибка возникает, если агент продолжает потоковую передачу сообщения, остановленного пользователем:

    Сведения об ошибке Описание
    Код состояния Http 403
    Код ошибки ContentStreamNotAllowed
    Сообщение об ошибке Поток содержимого отменен пользователем.
    Описание Потоковая передача была остановлена пользователем.

Коды ответа

Ниже приведены коды успеха и ошибок.

Коды успешного выполнения

Код состояния 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. Агенту не удалось завершить процесс потоковой передачи в течение двух минут.
403 ContentStreamNotAllowed Message size too large Агент отправил сообщение, превышающее текущее ограничение размера сообщения .
403 ContentStreamNotAllowed Content stream was canceled by user Потоковая передача была остановлена пользователем.
403 ContentStreamNotAllowed Request streamed content should contain the previously streamed content Входящее содержимое для сообщения потока не содержит того, что уже было передано в потоковом режиме.
429 Н/Д API calls quota exceeded Количество сообщений, переданных в потоковом режиме агентом, превысило квоту.

Пример кода

Название примера Описание Node.js C# Python
Пример агента потоковой передачи Teams Этот пример приложения можно использовать для потоковых сценариев в Teams с использованием Azure Open AI and Bot Framework версии 4 для личной области. Н/Д Просмотр Н/Д
Агент потоковой передачи бесед Это агент потоковой передачи бесед с пакетом SDK Teams. Просмотр Просмотр Просмотр

См. также

  • Last updated on