Grundlegendes zum Aktivitätsprotokoll

Das Aktivitätsprotokoll ist das Kommunikationsprotokoll und Standardprotokoll, das in vielen Microsoft-SDKs, -Diensten und -Clients verwendet wird. Dazu gehören Microsoft 365 Copilot, Microsoft Copilot Studio und das Microsoft 365 Agents SDK. Das Aktivitätsprotokoll definiert die Form einer Activity Und wie Nachrichten, Ereignisse und Interaktionen vom Kanal zu Ihrem Code und überall dazwischen fließen. Agents können eine Verbindung mit einem oder mehreren Kanälen herstellen, um mit Benutzern zu interagieren und mit anderen Agents zu arbeiten. Das Aktivitätsprotokoll standardisiert das Kommunikationsprotokoll zwischen jedem Client, mit dem Sie arbeiten, einschließlich Microsoft- und Drittanbieterclients, sodass Sie keine benutzerdefinierte Logik pro Kanal erstellen müssen, mit dem Sie arbeiten.

Was ist eine Aktivität?

Ein Activity strukturiertes JSON-Objekt, das jede Interaktion zwischen einem Benutzer und Ihrem Agent darstellt. Aktivitäten sind nicht nur textbasierte Nachrichten, sondern können verschiedene Arten von Interaktionen umfassen, einschließlich Ereignissen wie das Beitreten oder Verlassen eines Benutzers in Clients, die mehrere Benutzer unterstützen, Eingabeindikatoren, Dateiuploads, Kartenaktionen und benutzerdefinierte Ereignisse, die Entwickler selbst entwerfen.

Jede Aktivität enthält Metadaten zu:

• Wer hat es gesendet (von)
• Wer sollte ihn empfangen (Empfänger)
• Der Gesprächskontext
• Der Kanal, von dem er stammt
• Art der Interaktion
• Die Nutzlastdaten

Aktivitätsschema – Schlüsseleigenschaften

Diese Spezifikation definiert das Aktivitätsprotokoll: Aktivitätsprotokoll - Aktivität. Einige der im Activity-Protokoll definierten Schlüsseleigenschaften sind:

Zugreifen auf Aktivitätsdaten

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

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

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

Das TurnContext ist ein wichtiges Objekt, das bei jedem Gesprächswechsel im Microsoft 365 Agents Software Development Kit (SDK) verwendet wird. Sie bietet Zugriff auf die eingehende Aktivität, Methoden zum Senden von Antworten, die Verwaltung des Unterhaltungszustands und den Kontext, der für die Behandlung einer einzelnen Unterhaltung erforderlich ist. Es wird verwendet, um Kontext zu verwalten, geeignete Antworten zu senden und effektiv mit Ihren Benutzern in ihrem Client/Kanal zu interagieren. Jedes Mal, wenn Ihr Agent eine neue Aktivität von einem Kanal empfängt, erstellt das Agents SDK eine neue TurnContext Instanz und übergibt sie an ihre registrierten Handler/Methoden. Dieses Kontextobjekt ist während der einzelnen Drehung vorhanden und wird dann gelöscht, sobald die Drehung endet.

Ein Umlauf wird als Verlauf einer Nachricht definiert, die vom Client gesendet wird und in Ihrem Code ankommt. Ihr Code verarbeitet diese Daten und kann optional eine Antwort zurücksenden, um den Umlauf abzuschließen. Dieser Rundtrip kann in folgende Bereiche aufgeteilt werden:

1. Eingehende Aktivität: Der Benutzer sendet eine Nachricht oder führt eine Aktion aus, die eine Aktivität erstellt.
2. Ihr Code empfängt die Aktivität und der Agent verarbeitet sie mit TurnContext.
3. Ihr Agent sendet eine oder mehrere Aktivitäten zurück.
4. Der Umlauf endet und TurnContext wird verworfen.

Zugreifen auf Daten aus dem TurnContext, z. B.:

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

Dieser Codeausschnitt zeigt ein Beispiel für eine vollständige Drehung:

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 umfassen häufig verwendete Schlüsselinformationen Folgendes:

• Aktivität: Die wichtigste Möglichkeit zum Abrufen von Informationen aus der Aktivität
• Adapter: Der Kanaladapter, der die Aktivität erstellt hat
• TurnState: Der Zustand für die Drehung

Aktivitätstypen

Der Typ einer Aktivität ist wichtig, da sie definiert, was in den restlichen Aktivitäten zwischen Clients, Benutzern und Agents erforderlich oder erwartet wird.

Nachricht

Ein allgemeiner Aktivitätstyp ist der Nachrichtentyp , der ActivityText, Anlagen und vorgeschlagene Aktionen enthalten kann, um einige häufige Verwendungen für diesen Typ zu nennen.

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 Agent, wenn Mitglieder einer Unterhaltung beitreten oder diese verlassen. Nicht alle Clients unterstützen dies; ein bemerkenswerter Client, der dies tut, ist Microsoft Teams.

Der folgende Codeausschnitt 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.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Ereignisse

Die EreignistypenActivity sind benutzerdefinierte Ereignisse, die es Kanälen oder Clients ermöglichen, strukturierte Daten an Ihren Agenten zu senden, die nicht in der Activity Struktur der Nutzlast vordefiniert sind.

Sie müssen einen Methoden-/Routenhandler für den jeweiligen Event-Typ erstellen und dann die gewünschte Logik basierend auf dieser verwalten.

Name – Der Ereignisname oder der Bezeichner vom Client 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 Aufruftyp von Activity ist eine bestimmte Art von Aktivität, die ein Client an einen Agent aufruft, um einen Befehl oder Vorgang auszuführen, und nicht nur eine Nachricht. Beispiele für diese Arten von Aktivitäten sind in Microsoft Teams für task/fetch und task/submit. Nicht alle Kanäle unterstützen diese Art von Aktivitäten.

Typing

Ein Eingabetyp der Activity ist eine Klassifizierung der Aktivität, die anzeigt, dass jemand in einem Gespräch schreibt. Dies wird häufig in zwischenmenschlichen Gesprächen im Microsoft Teams-Client zum Beispiel gesehen. Eingabeaktivitäten werden in jedem Client nicht unterstützt, und insbesondere Microsoft 365 Copilot unterstützt keine Eingabeaktivitäten.

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

Erstellen und Senden von Aktivitäten

Zum Senden von Antworten stellt der "TurnContext" mehrere Methoden zum Senden von Antworten 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
}

Arbeiten mit Anlagen

Es ist üblich, dass Agents mit Anlagen arbeiten, die von Benutzern (oder sogar anderen Agents) übermittelt wurden. Der Client sendet eine Message Aktivität, die eine Anlage enthält (es ist keine bestimmte Art von Aktivität), und Ihr Code muss den Empfang der Nachricht mit der Anlage verarbeiten, die Metadaten lesen und die Datei sicher aus der URL abrufen, die der Client bereitgestellt hat. Es wäre typisch, die Datei dann in Ihren eigenen Speicher zu verschieben.

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

In der Regel sendet der Client zum Empfangen des Dokuments auf der Anlage eine authentifizierte GET Anforderung zum Abrufen des tatsächlichen Inhalts – jeder Adapter verfügt über eine eigene Möglichkeit, diese Daten abzurufen, z. B. Teams, OneDrive usw. Es ist auch wichtig zu wissen, dass diese URLs in der Regel kurzlebig sind, und gehen Sie daher nicht davon aus, dass sie dort bleiben, weshalb der Wechsel zu Ihrem eigenen Speicher wichtig ist, wenn Sie später darauf verweisen müssen.

Zitate

Es ist wichtig zu wissen, dass Anlage und Zitat nicht derselbe Objekttyp sind. Zitate werden von Clients, wie Microsoft Teams, auf ihre eigene Weise bearbeitet. Sie verwenden die Entität-Eigenschaft des Activity-Objekts und können mit activity.Entities.Add ein neues Entity-Objekt hinzufügen, das die spezifische Citation-Definition entsprechend Ihrem Client enthält. Es würde 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 wird als "Hub" erstellt, mit dem Entwickler Agents erstellen können, die mit jedem beliebigen Client arbeiten können, einschließlich der clients, die wir unterstützen und die Tools bereitstellen, mit denen Entwickler ihren eigenen Kanaladapter mit demselben Framework erstellen können. Dies bietet Entwicklern Bandbreite, wenn es um Agenten geht, und ermöglicht Kunden die Erweiterbarkeit, um sich mit diesem Hub zu verbinden, der ein oder mehrere Clients wie Microsoft Teams, Slack und mehr umfassen kann.

Verschiedene Kanäle weisen unterschiedliche Funktionen und Einschränkungen auf, und es folgt eine Zusammenfassung der Überlegungen beim Arbeiten mit gemeinsamen Clients.

Sie können den Kanal, von dem Sie die Aktivität erhalten haben, überprüfen, indem Sie die channelId-Eigenschaft im Activity inspizieren.

Kanäle enthalten spezifische Daten, die nicht der generischen Activity Nutzlast über alle Kanäle entsprechen, und diese können über TurnContext.Activity.ChannelData abgerufen und in Variablen umgewandelt werden, um sie in Ihrem Code zu verwenden.

Microsoft Teams

• Unterstützt umfangreiche adaptive Karten mit erweiterten Features
• Unterstützt Nachrichtenaktualisierungen und -löschungen
• Enthält spezifische Kanaldaten für Teams-Funktionen (Erwähnungen, Besprechungsinformationen und mehr)
• Unterstützt Aufrufaktivitäten für Aufgabenmodule

Microsoft 365 Copilot

• In erster Linie auf Nachrichtenaktivitäten konzentriert
• Unterstützt Zitate und Verweise in Antworten
• Erfordert gestreamte Antworten
• Eingeschränkte Unterstützung für umfangreiche Karten/adaptive Karten

WebChat/DirectLine

Web Chat ist ein HTTP-Protokoll, das für Agents zum Sprechen über HTTPS verwendet wird.

• Vollständige Unterstützung für alle Aktivitätstypen
• Unterstützt benutzerdefinierte Kanaldaten

Kanäle von Drittanbietern

Dazu gehören Slack, Facebook und mehr.

• Möglicherweise gibt es eingeschränkte Unterstützung für bestimmte Aktivitätstypen.
• Kartenrendering kann anders oder nicht unterstützt werden
• Überprüfen Sie immer die Dokumentation zu bestimmten Kanälen.