Grundlegendes zum Aktivitätsprotokoll

Das Aktivitätsprotokoll ist ein Standardkommunikationsprotokoll, das innerhalb Microsofts bei vielen Microsoft SDKs, Diensten und Clients verwendet wird. Das Aktivitätsprotokoll wird von Microsoft 365 Copilot, Microsoft Copilot Studio und dem Microsoft 365 Agents SDK verwendet. Das Aktivitätsprotokoll definiert die Struktur einer Activity Und wie Nachrichten, Ereignisse und Interaktionen von einem 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 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 strukturiertes JSON-Objekt, das jede Interaktion zwischen einem Benutzer und Ihrem Agent darstellt. Aktivitäten sind nicht auf textbasierte Nachrichten beschränkt. Sie können verschiedene Arten von Interaktionen umfassen, z. B. Ereignisse wie das Beitreten oder Verlassen eines Benutzers für Clients, die mehrere Benutzer unterstützen, Eingabeindikatoren, Dateiuploads, Kartenaktionen und benutzerdefinierte Ereignisse, die von Entwicklern gestaltet werden.

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: Activity Protocol - Activity. Einige der im Aktivitätsprotokoll definierten Schlüsseleigenschaften sind:

Eigenschaft Beschreibung
Id Wird in der Regel vom Kanal generiert, wenn er von einem Kanal stammt
Type Der Typ steuert die Bedeutung einer Aktivität, z. B. nachrichtentyp
ChannelID Der ChannelID Verweis auf den Kanal, von dem die Aktivität stammt. Zum Beispiel: msteams.
From Der Absender der Aktivität (die ein Benutzer oder Agent sein kann)
Recipient Der beabsichtigte Empfänger der Aktivität
Text Der Textinhalt der Nachricht
Attachment Umfangreiche Inhalte wie Karten, Bilder von Dateien

Zugreifen auf Aktivitätsdaten

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

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

Hinweis

Die Codeausschnitte in diesem Artikel verwenden C#. Die Syntax und API-Struktur für die JavaScript- und Python-Versionen sind ähnlich.

Die TurnContext ist ein wichtiges Objekt, das bei jedem Gesprächswechsel im Microsoft 365 Agents 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. Verwenden Sie sie, um Kontext beizubehalten, geeignete Antworten zu senden und effektiv mit Ihren Benutzern in ihrem Client oder 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 oder Methoden. Dieses Kontextobjekt ist während der einzelnen Drehung vorhanden und wird dann gelöscht, sobald die Drehung endet.

Ein Durchgang wird als Roundtrip einer Nachricht definiert, die vom Client gesendet wird und die den Weg zu Ihrem Code zurücklegt. Ihr Code verarbeitet diese Daten und kann optional eine Antwort zurücksenden, um die Ausführung abzuschließen. Dieser Roundtrip kann in die folgenden Schritte unterteilt 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 Zug 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 definiert, was der Rest der Aktivität erfordert oder erwartet zwischen Clients, Benutzern und Agents.

Dazu gehören:

  • Nachricht
  • AktualisierungDesGesprächs
  • Ereignis
  • Aufrufen
  • Typing

Nachricht

Ein allgemeiner Aktivitätstyp ist der Nachrichtentyp von Activity. Dieser Activity Typ kann Text, Anlagen 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);
});

AktualisierungDesGesprächs

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

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

Ereignisse

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

Sie müssen eine Methode oder einen Routenhandler für den jeweiligen Event Typ erstellen. Verwalten Sie dann die gewünschte Logik basierend auf den:

  • Name: Der Ereignisname oder der Bezeichner des Clients
  • 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)
});

Aufrufen

Ein Aufruftyp von Activity ist ein bestimmter Aktivitätstyp, den ein Client in einen Agent aufruft, um einen Befehl oder vorgang auszuführen. Es ist 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 Arten von Aktivitäten.

Typing

Ein Eingabetyp der Activity ist eine Klassifizierung der Aktivität, die anzeigt, dass jemand in einem Gespräch schreibt. Diese Aktivität wird häufig in Gesprächen zwischen Menschen in der Microsoft Teams-Anwendung gesehen. Eingabeaktivitäten werden in jedem Client nicht unterstützt. Insbesondere unterstützt Microsoft 365 Copilot 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 bietet die TurnContextmehrere Optionen, um Antworten an den Benutzer zurückzusenden.

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 oft mit Anhängen, die von Benutzern (oder auch anderen Agenten) übermittelt werden. Der Client verschickt eine Aktivität Message, die eine Anlage enthält (es handelt sich nicht um einen spezifischen Aktivitätstyp). Ihr Code muss den Empfang der Nachricht mit der Anlage verarbeiten, die Metadaten lesen und die Datei sicher von der vom Client bereitgestellten URL abrufen. In der Regel verschieben Sie die Datei in Ihren eigenen Speicher.

So empfangen Sie eine Anlage

Der folgende Code zeigt, wie ein Anhang empfangen wird.

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 für die Anlage eine authentifizierte GET Anforderung, um den tatsächlichen Inhalt abzurufen. Jeder Adapter verfügt über eine eigene Möglichkeit zum Abrufen dieser Daten. Beispielsweise 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 die URLs lange gültig bleiben. Diese Einschränkung erklärt, warum es wichtig ist, auf eigenen Speicherplatz zu wechseln, wenn Sie später auf den Inhalt verweisen müssen.

Zitate

Es ist wichtig zu wissen, dass Anlage und Zitat nicht derselbe Objekttyp sind. Kunden wie Microsoft Teams behandeln Zitate auf eigene Weise. Sie verwenden die Entities-Eigenschaft der Activity. Sie können Zitate mit activity.Entities.Add und ein neues Entity Objekt hinzufügen, das die spezifische Citation Definition basierend auf Ihrem Client enthält. Es wird als JSON-Objekt serialisiert, das der Client dann basierend darauf deserialisiert, wie es im Client gerendert wird. Grundsätzlich sind Anlagen Teile von Nachrichten und Zitate können sich auf Anlagen beziehen und als ein weiteres Objekt in Entities der Activity Nutzlast gesendet werden.

Kanalspezifische Überlegungen

Die Microsoft 365 Agents SDK wird als "Hub" erstellt, den Entwickler zum Erstellen von Agents verwenden, die mit any Client arbeiten können, einschließlich der von uns unterstützten Clients. Es stellt die Tools bereit, mit denen Entwickler einen eigenen Kanaladapter mit demselben Framework erstellen können. Diese Architektur bietet Entwicklern Breite, wenn es um Agents geht, und bietet Erweiterbarkeit für Clients, um eine Verbindung mit diesem Hub herzustellen, was eine oder mehrere Clients wie Microsoft Teams, Slack und mehr sein kann.

Verschiedene Kanäle weisen unterschiedliche Funktionen und Einschränkungen auf.

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

Kanäle enthalten bestimmte Daten, die nicht der generischen Activity Nutzlast über alle Kanäle hinweg entsprechen. Sie können von der TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) Eigenschaft aus auf diese Daten zugreifen, indem Sie sie in Variablen umwandeln, die in Ihrem Code verwendet werden können.

In den folgenden Abschnitten werden Überlegungen zum Arbeiten mit gemeinsamen Clients zusammengefasst.

Microsoft Teams

  • Unterstützt ausgereifte Adaptive Karten mit erweiterten Funktionen.
  • Unterstützt Nachrichtenaktualisierungen und -löschungen.
  • Enthält spezifische Kanaldaten für Teams-Funktionen, wie etwa Erwähnungen und Meetinginformationen.
  • Unterstützt Aufrufaktivitäten für Aufgabenmodule.

Microsoft 365 Copilot

  • Konzentriert sich in erster Linie auf Nachrichtenaktivitäten.
  • Unterstützt Zitate und Verweise in Antworten.
  • Erfordert Streaming-Antworten.
  • Eingeschränkte Unterstützung für umfangreiche Karten und adaptive Karten.

Webchat/DirectLine

Webchat ist ein HTTP-Protokoll, mit dem Agents über HTTPS kommunizieren können.

  • Vollständige 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.

  • 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.

Nächste Schritte

  • Last updated on