Das Aktivitätsprotokoll verstehen

Das Aktivitätsprotokoll ist ein standardisiertes Kommunikationsprotokoll, das in vielen Microsoft SDKs, Diensten und Clients verwendet wird. Das Aktivitätsprotokoll wird von Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams und dem Microsoft 365 Agents SDK verwendet. Das Aktivitätsprotokoll legt die Struktur einer Activity fest und beschreibt, wie Nachrichten, Ereignisse und Interaktionen von einem Kanal zu Ihrem Code und überall sonst dazwischen weitergeleitet werden. Agenten können sich mit einem oder mehreren Kanälen verbinden, um mit Nutzern zu interagieren und mit anderen Agenten zusammenzuarbeiten. Das Aktivitätsprotokoll standardisiert das Kommunikationsprotokoll mit jedem Client, mit dem Sie arbeiten, einschließlich Microsoft- und Nicht-Microsoft-Clients, sodass Sie keine benutzerdefinierte Logik für jeden Kanal erstellen müssen.

Was ist eine Aktivität?

Ein Activity ist ein strukturiertes JSON-Objekt, das jede Interaktion zwischen einem Benutzer und Ihrem Agenten repräsentiert. Die Aktivitäten sind nicht auf textbasierte Nachrichten beschränkt. Sie können verschiedene Arten von Interaktionen umfassen, wie zum Beispiel Ereignisse wie den Beitritt oder Austritt eines Benutzers für Clients, die mehrere Benutzer unterstützen, Schreibindikatoren, Datei-Uploads, Kartenaktionen und benutzerdefinierte Ereignisse, die Entwickler entwerfen.

Jede Aktivität enthält Metadaten zu:

  • Absender (von)
  • Wer soll es erhalten (Empfänger)
  • Der aktuelle Unterhaltungskontext
  • Der Kanal, aus dem sie stammt
  • Zeigt die Art der Interaktion
  • Payload-Daten

Aktivitätsschema – Schlüsseleigenschaften

Diese Spezifikation definiert das Aktivitätsprotokoll: Aktivitätsprotokoll - Aktivität. Zu den wichtigsten im Aktivitätsprotokoll definierten Eigenschaften gehören:

Eigenschaften Beschreibung des Dataflows
Id Wird typischerweise vom Kanal erzeugt, wenn die Aktivität von einem Kanal stammt
Type Der Typ bestimmt die Bedeutung einer Aktivität, zum Beispiel den Nachrichtentyp
ChannelID ChannelID referenziert den Kanal, von dem die Aktivität stammt. Beispiel: msteams.
From Der Absender der Aktivität (dies kann ein Nutzer oder ein Agent sein)
Recipient Der beabsichtigte Empfänger der Aktivität
Text Der Textinhalt der Nachricht
Attachment Reichhaltige Inhalte wie Karten, Bilder von Dateien

Zugriff auf Aktivitätsdaten

Um Aktionen vom TurnContext-Objekt auszuführen, müssen Entwickler auf die Daten in der Aktivität zugreifen.

In jeder Sprachversion des Microsoft 365 Agents SDK finden Sie eine TurnContext Klasse:

Anmerkung

Die Codebeispiele in diesem Artikel verwenden C#. Die Syntax und API-Struktur der JavaScript- und Python-Versionen sind ähnlich.

TurnContext ist ein wichtiges Objekt, das in jedem Gesprächsschritt im Microsoft 365 Agents SDK verwendet wird. Es ermöglicht den Zugriff auf die eingehende Aktivität, Methoden zum Senden von Antworten, das Management des Gesprächszustands und den Kontext, der für einen einzelnen Gesprächsschritt erforderlich ist. Nutzen Sie es, um den Kontext aufrechtzuerhalten, passende Antworten zu senden und effektiv mit Ihren Benutzern im Client oder Kanal zu interagieren. Jedes Mal, wenn Ihr Agent eine neue Aktivität von einem Kanal erhält, erstellt das Agents SDK eine neue TurnContext-Instanz und übergibt sie an Ihre registrierten Handler oder Methoden. Dieses Kontextobjekt existiert während der einzelnen Gesprächsrunde und wird dann verworfen, sobald die Runde endet.

Ein Umlauf wird als Roundtrip einer Nachricht definiert, die vom Client gesendet wird und bis zu Ihrem Code gelangt. Ihr Code verarbeitet diese Daten und kann optional eine Antwort zurücksenden, um die Gesprächsrunde abzuschließen. Diese Hin- und Rückfahrt kann in folgende Schritte unterteilt werden:

  1. Eingehende Aktivität: Der Benutzer sendet eine Nachricht oder führt eine Aktion aus, wodurch eine Aktivität erstellt wird.

  2. Ihr Code empfängt die Aktivität und der Agent verarbeitet sie mithilfe von TurnContext.

  3. Ihr Agent sendet eine oder mehrere Aktivitäten zurück.

  4. Der Umlauf endet und TurnContext wird verworfen.

Auf Daten von der Plattform zugreifen TurnContext wie:

var messageText = turnContext.Activity.Text;
var channelID = turnContext.Activity.ChannelId;

Dieses Codebeispiel zeigt einen vollständigen Konversationsdurchgang:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text;
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

Innerhalb der TurnContext-Klasse sind häufig verwendete Schlüsselinformationen enthalten:

  • Aktivität: Die primäre Methode, um Informationen aus der Aktivität zu erhalten
  • Adapter: Der Kanaladapter, der die Aktivität erstellt hat
  • TurnState: Der Zustand für den Turn

Aktivitätstypen

Der Typ einer Aktivität bestimmt, welche Anforderungen oder Erwartungen der weitere Verlauf der Aktivität zwischen Clients, Nutzern und Agenten stellt.

Hierzu gehören:

  • Meldung
  • ConversationUpdate
  • Veranstaltung
  • Invoke
  • Tastatureingabe

Meldung

Eine häufige Art von Aktivität ist der MessageActivity-Typ. Dieser Activity Typ kann Text, Anhänge und vorgeschlagene Aktionen enthalten.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text;
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

ConversationUpdate

Der ConversationUpdate-TypActivity benachrichtigt Ihren Agenten, wenn Mitglieder einer Unterhaltung beitreten oder diese verlassen. Nicht alle Clients unterstützen diese Benachrichtigung, aber Microsoft Teams unterstützt sie.

Das folgende Codebeispiel begrüßt neue Mitglieder in einer Unterhaltung:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Ereignisse

Der Event-Typ von Activity ist ein benutzerdefiniertes Ereignis, das Kanäle oder Clients verwenden, um strukturierte Daten an Ihren Agenten zu senden. Diese Daten sind in der Activity Nutzlaststruktur nicht vordefiniert.

Sie müssen eine Methode oder einen Routenhandler für den spezifischen Event Typ erstellen. Dann verwalten Sie die gewünschte Logik basierend auf den:

  • Name: Der Ereignisname oder die vom Client bereitgestellte Kennung
  • Wert: Ereignisnutzlast, die in der Regel ein JSON-Objekt ist
agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>
{
    var eventName = turnContext.Activity.Name;
    var eventValue = turnContext.Activity.Value;

    // custom event (E.g. a switch on eventName)
});

Invoke

Ein InvokeActivity-Typ von Aktivität ist eine spezielle Aktivität, die ein Client bei einem Agenten auslöst, um einen Befehl oder eine Operation auszuführen. Es ist mehr als nur eine Nachricht. Beispiele für diese Arten von Aktivitäten gibt es oft in Microsoft Teams für task/fetch und task/submit. Nicht alle Kanäle unterstützen diese Arten von Aktivitäten.

Tastatureingabe

Eine Eingabe vom Typ Activity ist eine Klassifizierung der Aktivität, die angibt, dass jemand gerade in einer Unterhaltung schreibt. Diese Aktivität kommt beispielsweise häufig in Gesprächen zwischen Menschen im Microsoft Teams-Client vor. Tippaktivitäten werden nicht in jedem Client unterstützt. Bemerkenswert ist, dass Microsoft 365 Copilot keine Tippaktivitäten unterstützt.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken);

Datensätze und Aktivitäten senden

Um Antworten zu senden, stellt der TurnContextmehrere Methoden zum Senden von Antworten zurück an den Benutzer bereit.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken); // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken); // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken); // send multiple activities in an Activity array
}

Mit Anlagen arbeiten

Agenten arbeiten häufig mit Anhängen, die Nutzer (oder sogar andere Agenten) übermitteln. Der Client sendet eine Message Aktivität, die einen Anhang enthält (es handelt sich nicht um einen spezifischen Aktivitätstyp). Ihr Code muss den Empfang der Nachricht mit dem Anhang verarbeiten, die Metadaten auslesen und die Datei sicher von der vom Client bereitgestellten URL abrufen. Typischerweise verschiebt man die Datei in den eigenen Speicherplatz.

So empfangen Sie eine Anlage

Der folgende Code zeigt, wie man einen Anhang empfängt.

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count > 0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        };
    }
}

Typischerweise sendet der Client eine authentifizierte GET Anfrage, um den tatsächlichen Inhalt des Anhangs zu erhalten. Jeder Adapter hat seine eigene Methode, diese Daten zu erhalten. Zum Beispiel Teams, OneDrive und so weiter. Es ist außerdem wichtig zu wissen, dass diese URLs typischerweise kurzlebig sind; Sie sollten daher nicht davon ausgehen, dass sie lange gültig bleiben. Diese Einschränkung ist der Grund, warum es wichtig ist, auf eigenen Speicher umzusteigen, falls Sie später auf die Inhalte zugreifen möchten.

Quellen

Es ist wichtig zu wissen, dass Anhang und Zitation nicht derselbe Objekttyp sind. Clients wie Microsoft Teams verarbeiten Zitationen auf individuelle Weise. Sie verwenden die Entitäten-Eigenschaft der Activity. Du kannst Zitate hinzufügen und activity.Entities.Add ein neues Entity Objekt hinzufügen, das die spezifische Citation Definition basierend auf deinem Client hat. Es wird als JSON-Objekt serialisiert, das der Client dann basierend darauf deserialisiert, wie es im Client gerendert wird. Grundsätzlich sind Anlagen Nachrichten, und Zitate können auf Anlagen verweisen und ein anderes Objekt sein, das in Entities der Activity-Nutzlast gesendet wird.

Kanalspezifische Überlegungen

Das Microsoft 365 Agents SDK ist als ein 'Hub' konzipiert, den Entwickler nutzen, um Agenten zu erstellen, die mit jedem Client arbeiten können, einschließlich der von uns unterstützten Clients. Es stellt Entwicklern die Tools zur Verfügung, um ihren eigenen Channel-Adapter unter Verwendung desselben Frameworks zu erstellen. Diese Architektur bietet Entwicklern Breite bei Agenten und bietet Clients Erweiterbarkeit, sich mit diesem Hub zu verbinden, der einen oder mehrere Kunden wie Microsoft Teams, Slack und weitere sein kann.

Verschiedene Kanäle haben unterschiedliche Fähigkeiten und Einschränkungen.

Sie können feststellen, aus welchem Kanal Sie die Aktivität erhalten haben, indem Sie die channelId-Eigenschaft in der Activity überprüfen.

Kanäle enthalten spezifische Daten, die nicht der generischen Activity Nutzlast in allen Kanälen entsprechen. Sie können auf diese Daten über die TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata)-Eigenschaft zugreifen, indem Sie sie durch Casting in Variablen für die Verwendung in Ihrem Code umwandeln.

Die folgenden Abschnitte fassen Überlegungen beim Arbeiten mit gängigen Clients zusammen.

Microsoft Teams

  • Unterstützt reichhaltige adaptive Karten mit erweiterten Funktionen.
  • Unterstützt das Aktualisieren und Löschen von Nachrichten.
  • Enthält spezifische Kanaldaten für Teams-Funktionen wie Erwähnungen, Besprechungsinformationen und mehr.
  • Unterstützt Aufrufaktivitäten für Aufgabenmodule.

Microsoft 365 Copilot

  • Fokussiert sich primär auf Nachrichtenaktivitäten.
  • Unterstützt Zitate und Referenzen in Antworten.
  • Erfordert Streaming-Antworten.
  • Begrenzte Unterstützung für Rich Karten und adaptive Karten.

Webchat/DirectLine

Webchat ist ein HTTP-Protokoll, das Agenten zur Kommunikation über HTTPS verwenden können.

  • Volle Unterstützung für alle Aktivitätstypen.
  • Unterstützt benutzerdefinierte Kanaldaten.

Nicht-Microsoft-Kanäle

Zu diesen Kanälen gehören Slack, Facebook und mehr.

  • Für bestimmte Aktivitätstypen könnte nur begrenzte Unterstützung geboten werden.
  • Das Rendering von Karten könnte unterschiedlich sein oder nicht unterstützt werden.
  • Überprüfen Sie stets die jeweilige Kanaldokumentation.

Nächste Schritte,

  • Last updated on