Stream-Agent-Nachrichten

Hinweis

  • Streaming-Agent-Nachrichten werden nur in Einzelchats unterstützt.
  • Teams unterstützt jeweils nur eine gleichzeitige Streamingantwort pro Chat.
  • Streaming ist allgemein im Web, desktop und mobil verfügbar.

Sie können Agent-Nachrichten streamen, um die Antworten eines Agents als kleine Updates an den Benutzer zu übermitteln, während die vollständige Antwort generiert wird, um die Benutzerfreundlichkeit zu verbessern. Häufig dauert es lange, bis Agents Antworten generieren, ohne die Benutzeroberfläche zu aktualisieren, was zu einer weniger ansprechenden Erfahrung führt.

Wenn Benutzer beobachten, wie der Agent seine Anfrage in Echtzeit verarbeitet, kann dies die Zufriedenheit und das Vertrauen erhöhen. Diese wahrgenommene Reaktionsfähigkeit und Transparenz verbessert die Benutzerbindung und verringert den Abbruch von Konversationen mit dem Agent.

Benutzererfahrung für Stream Nachrichten

Streaming-Agent-Nachrichten verfügen über zwei Arten von Updates:

  • Informative Updates: Informative Updates werden als blaue Statusanzeige am unteren Rand des Chats angezeigt. Es informiert den Benutzer über die laufenden Aktionen des Agents, während eine Antwort generiert wird.

    Screenshot: Informative Updates des Streamings für Agents

    Informative Nachrichten dürfen nicht mehr als 1 KB oder 1.000 Zeichen umfassen.

  • Antwortstreaming: Das Antwortstreaming wird als Eingabeindikator angezeigt. Es zeigt die Antwort des Agents an den Benutzer als kleine Updates an, während die vollständige Antwort generiert wird.

    Screenshot: Antwortstreaming der Agents

    • Schaltfläche "Beenden ": Mit der Schaltfläche können Benutzer Streamingantworten steuern, indem sie sie frühzeitig beenden. Sie ist standardmäßig während des Streamings verfügbar, sodass Benutzer Eingabeaufforderungen verfeinern oder neue senden können. Wenn Sie verstehen, wie die Schaltfläche "Streaming beenden" funktioniert, können Sie effektivere und benutzerfreundlichere Konversationsschnittstellen entwerfen.

    • Streaminginhalt: Während des Streamings müssen die Agent-Nachrichten den vorherigen gestreamten Inhalt enthalten.

      Beispiel: Dies ist ein Beispiel für eine akzeptable Streamingantwort.
      Ein braunes
      Ein Braunfuchs
      Ein Braunfuchs springt über den Zaun

      Nicht-Beispiel: Dies ist ein Beispiel für eine Streamingantwort, die einen Fehler zurückgibt.
      Ein braunes
      Hallo

      Weitere Informationen zum Fehler finden Sie unter Fehlercodes.

Implementieren des Streamings mit dem Teams SDK

Verwenden Sie Stream.Update , um informative Updates zu schreiben, bevor Sie mit dem Nachrichtenstream beginnen. Stream.Update kann mehrmals mit unterschiedlichem Aktualisierungstext aufgerufen werden.

Verwenden Sie Stream.Emit , um einen Teil des Inhalts in den Stream zu schreiben. Blöcke werden in die Nachricht gerendert, sobald sie von Teams empfangen werden. Nach dem ersten Aufruf von Stream.Emitwerden keine informativen Updates mehr angezeigt und Stream.Update haben keine Auswirkungen.

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

Verwenden Sie stream.update , um informative Updates zu schreiben, bevor Sie mit dem Nachrichtenstream beginnen. stream.update kann mehrmals mit unterschiedlichem Aktualisierungstext aufgerufen werden.

Verwenden Sie stream.emit , um einen Teil des Inhalts in den Stream zu schreiben. Blöcke werden in die Nachricht gerendert, sobald sie von Teams empfangen werden. Nach dem ersten Aufruf von stream.emitwerden keine informativen Updates mehr angezeigt und stream.update haben keine Auswirkungen.

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!"
});

Verwenden Sie stream.update , um informative Updates zu schreiben, bevor Sie mit dem Nachrichtenstream beginnen. stream.update kann mehrmals mit unterschiedlichem Aktualisierungstext aufgerufen werden.

Verwenden Sie stream.emit , um einen Teil des Inhalts in den Stream zu schreiben. Blöcke werden in die Nachricht gerendert, sobald sie von Teams empfangen werden. Nach dem ersten Aufruf von stream.emitwerden keine informativen Updates mehr angezeigt und stream.update haben keine Auswirkungen.

@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 Nachricht über die REST-API

Agent-Nachrichten können über die REST-API gestreamt werden. Streamingnachrichten unterstützen Rich-Text und Zitate. Anlagen, KI-Bezeichnungen, Feedbackschaltflächen und Vertraulichkeitsbezeichnungen sind nur für die endgültige Streamingnachricht verfügbar. Weitere Informationen finden Sie unter Anlagen und Agent-Nachrichten mit KI-generiertem Inhalt.

Wenn Ihr Agent Streaming über die REST-API aufruft, stellen Sie sicher, dass die nächste Streaming-API nur aufgerufen wird, nachdem eine erfolgreiche Antwort des anfänglichen API-Aufrufs empfangen wurde. Wenn Ihr Agent das SDK verwendet, überprüfen Sie, ob Sie ein NULL-Antwortobjekt von der Send-Aktivitätsmethode erhalten, um zu bestätigen, dass der vorherige Aufruf erfolgreich übertragen wurde.

Wenn Ihr Agent die Streaming-API zu schnell aufruft, treten möglicherweise Probleme auf, und das Streaming kann unterbrochen werden. Es wird empfohlen, dass Ihr Agent jeweils eine Nachricht streamt, um sicherzustellen, dass er die Streaming-API in einem konsistenten Tempo aufruft. Andernfalls wird die Anforderung möglicherweise gedrosselt. Puffern Sie die Token aus dem Modell für 1,5 bis zwei Sekunden, um einen reibungslosen Streamingprozess sicherzustellen.

Im Folgenden sind die Eigenschaften für Streaming-Agent-Nachrichten aufgeführt:

Eigenschaft Erforderlich Beschreibung
type ✔️ Unterstützte Werte sind entweder typing oder message.
• : typingVerwenden Sie beim Streamen der Nachricht.
• message: Wird für die letzte gestreamte Nachricht verwendet.
text ✔️ Der Inhalt der Nachricht, die gestreamt werden soll.
entities.type ✔️ Muss streamInfo sein.
entities.streamId ✔️ streamId Starten Sie das Streaming aus der ersten Streaminganforderung.
entities.streamType Typ der Streamingupdates. Unterstützte Werte sind , informativestreamingoder final. Der Standardwert ist streaming. final wird nur in der endgültigen Nachricht verwendet.
entities.streamSequence ✔️ Inkrementelle ganze Zahl für jede Anforderung.

Hinweis

Dies sind die Anforderungen für die Verwendung von streamSequence für REST-APIs:

  • Das erste muss die Zahl "1" sein.
  • Nachfolgende Zahlen (außer final) müssen eine monoton steigende ganze Zahl sein (z. B. 1-2-3>>).
  • Für die endgültige Nachricht streamSequence darf nicht festgelegt werden.

Führen Sie die folgenden Schritte aus, um das Streaming in Agents zu aktivieren:

  1. Streaming starten
  2. Fortsetzen des Streamings
  3. Endgültiges Streaming

Streaming starten

Der Agent kann entweder eine informative oder eine Streamingnachricht als erste Kommunikation senden. Die Antwort enthält die streamId, die für die Ausführung nachfolgender Aufrufe wichtig ist.

Ihr Agent kann mehrere informative Aktualisierungen senden, während er die Anforderung des Benutzers verarbeitet, z. B . Scannen durch Dokumente, Zusammenfassen von Inhalten und Relevante Arbeitselemente gefunden. Sie können diese Updates senden, bevor Ihr Agent die endgültige Antwort an den Benutzer generiert.


//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

Die folgende Abbildung zeigt ein Beispiel für das Starten des Streamings:

Screenshot: Starten des Streamings

Fortsetzen des Streamings

Verwenden Sie die , die streamId Sie von der ersten Anforderung erhalten haben, um entweder informative nachrichten oder Streamingnachrichten zu senden. Sie können mit informativen Updates beginnen und später zum Antwortstreaming wechseln , wenn die endgültige Antwort bereit ist.

Beginnen Sie mit informativen Updates

Wenn Ihr Agent eine Antwort generiert, senden Sie informative Aktualisierungen an den Benutzer, z. B . Scannen durch Dokumente, Zusammenfassen von Inhalten und Gefunden relevante Arbeitselemente. Stellen Sie sicher, dass Sie nachfolgende Aufrufe erst ausführen, nachdem der Agent eine erfolgreiche Antwort von den vorherigen Aufrufen erhalten hat.


// 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 { }

Die folgende Abbildung zeigt ein Beispiel für einen Agent, der informative Updates bereitstellt:

Screenshot: Informative Updates des Streamings.

Wechseln zum Antwortstreaming

Wenn Ihr Agent bereit ist, die endgültige Nachricht für den Benutzer zu generieren, wechseln Sie von der Bereitstellung informativer Updates zum Antwortstreaming. Für jedes Antwortstreamingupdate sollte der Nachrichteninhalt die neueste Version der endgültigen Nachricht sein. Dies bedeutet, dass Ihr Agent alle neuen Token enthalten sollte, die von den großen Sprachmodellen (Large Language Models, LLMs) generiert werden. Fügen Sie diese Token an die vorherige Nachrichtenversion an, und senden Sie sie dann an den Benutzer.

Der Drosselungsgrenzwert beträgt 1 Anforderung pro Sekunde. Sie müssen sicherstellen, dass der Agent die Anforderung innerhalb dieses Grenzwerts sendet. Der Agent kann anforderungen je nach Bedarf langsamer senden.


// 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{ }

Die folgende Abbildung zeigt ein Beispiel für einen Agent, der Updates in Blöcken bereitstellt:

Screenshot: Antwortstreaming

Endgültiges Streaming

Nachdem ihr Agent die Generierung der Nachricht abgeschlossen hat, senden Sie das Endstreamingsignal zusammen mit der endgültigen Nachricht. Für die letzte Nachricht ist messagedie type der -Aktivität . Hier legt der Agent alle Felder fest, die für die reguläre Nachrichtenaktivität zulässig sind, ist aber final der einzige zulässige Wert für 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{ }

Die folgende Abbildung zeigt ein Beispiel für die endgültige Antwort des Agents:

Screenshot: Letzte gestreamte Nachricht

Antwort des Streaming-Agents beenden

Mit der Schaltfläche können Benutzer Streamingantworten steuern. Die Schaltfläche Beenden ist standardmäßig während des Streamings verfügbar, sodass Benutzer eine Antwort frühzeitig beenden können. Benutzer können das Nachrichtenstreaming unterbrechen und ihre Eingabeaufforderungen verfeinern oder neue senden. Es verbessert die Konversationsverwaltung mit Agents, um die Benutzererfahrung zu verbessern.

Nachdem ein Benutzer die Nachrichtengenerierung beendet hat:

  • Agents behandeln beendete Antworten als unvollständig oder verworfen in der Unterhaltung.

  • Agents können den bereits gestreamten Inhalt nicht ändern.

  • Der folgende Fehler wird generiert, wenn ein Agent das Streamen einer Nachricht fortsetzt, die von einem Benutzer beendet wurde:

    Fehlerdetails Beschreibung
    HTTP-status-Code 403
    Fehlercode ContentStreamNotAllowed
    Fehlermeldung Der Inhaltsstream wurde vom Benutzer abgebrochen.
    Beschreibung Das Streaming wurde vom Benutzer beendet.

Antwortcodes

Im Folgenden finden Sie die Erfolgs- und Fehlercodes:

Erfolgscodes

HTTP-status-Code Rückgabewert Beschreibung
201 streamId, dies ist dasselbe wie activityId{"id":"1728640934763"} Der Agent gibt diesen Wert nach dem Senden der ersten Streaminganforderung zurück.
Für alle nachfolgenden Streaminganforderungen ist erforderlich streamId .
202 {} Erfolgscode für nachfolgende Streaminganforderungen.

Fehlercodes

HTTP-status-Code Fehlercode Fehlermeldung Beschreibung
202 ContentStreamSequenceOrderPreConditionFailed PreCondition failed exception when processing streaming activity. Einige Streaminganforderungen können außerhalb der Reihenfolge eingehen und verworfen werden. Die neueste Streaminganforderung, die von streamSequencebestimmt wird, wird verwendet, wenn Anforderungen ungeordnet empfangen werden. Stellen Sie sicher, dass jede Anforderung sequenziell gesendet wird.
400 BadRequest Je nach Szenario können verschiedene Fehlermeldungen auftreten, z. B. Start streaming activities should include text Die eingehende Nutzlast entspricht nicht den erforderlichen Werten oder enthält sie nicht.
403 ContentStreamNotAllowed Content stream is not allowed Die Streaming-API-Funktion ist für den Benutzer oder Agent nicht zulässig.
403 ContentStreamNotAllowed Content stream is not allowed on an already completed streamed message Ein Agent kann nicht kontinuierlich eine Nachricht streamen, die bereits gestreamt und abgeschlossen wurde.
403 ContentStreamNotAllowed Content stream finished due to exceeded streaming time. Der Agent konnte den Streamingprozess nicht innerhalb des strengen Zeitlimits von zwei Minuten abschließen.
403 ContentStreamNotAllowed Message size too large Der Agent hat eine Nachricht gesendet, die die aktuelle Größenbeschränkung für Nachrichten überschreitet.
403 ContentStreamNotAllowed Content stream was canceled by user Das Streaming wurde vom Benutzer beendet.
403 ContentStreamNotAllowed Request streamed content should contain the previously streamed content Der eingehende Inhalt für die Streamnachricht enthält nicht, was bereits gestreamt wurde.
429 – API calls quota exceeded Die Anzahl der vom Agent gestreamten Nachrichten hat das Kontingent überschritten.

Codebeispiel

Beispielname Beschreibung Node.js C# Python
Beispiel für den Teams-Streaming-Agent Diese Beispiel-App kann für Streamingszenarien in Teams mit Azure Open AI und Bot Framework v4 für den persönlichen Bereich verwendet werden. – View –
Konversationsstreaming-Agent Dies ist ein Konversationsstreaming-Agent mit Teams SDK. View View Anzeigen

Siehe auch

  • Last updated on