Ereignis oder Aktivität senden

Copilot Studio bietet eine Reihe von Knoten, die Sie für Aktivitäten verwenden können, die keine Nachrichten sind: den Knoten "Ereignisaktivität ", den Knoten "Aktivität aufrufen " und andere aktivitätsbezogene Knoten, die das Aktivitätsprotokoll unterstützt.

Was ist das Aktivitätsprotokoll?

Das Aktivitätsprotokoll ist ein zentrales Transportkonzept in Copilot Studio. Das Aktivitätsprotokoll ermöglicht eine nahtlose Kommunikation zwischen Benutzern und Agents. Es definiert eine standardisierte Struktur für alle Interaktionen und kategorisiert sie in verschiedene Aktivitätstypen.

Ereignisaktivitäten und Nachrichtenaktivitäten sind zwei unterschiedliche Typen innerhalb des Aktivitätsprotokolls, die jeweils eindeutigen Zwecken in Kommunikationsworkflows dienen.

Nachrichtenaktivitäten stellen die grundlegenden Kommunikationseinheiten zwischen Benutzern und Agenten dar, die hauptsächlich Text-, Medien- oder adaptive Karteninhalte enthalten. Sie sind für direkte Interaktionen konzipiert, bei denen ein Benutzer eine Abfrage oder Anweisung vorschreibt und der Agent entsprechend antwortet.

Ereignisaktivitäten werden dagegen in der Regel verwendet, um nichtverbale Aktionen oder vom System generierte Updates zu kennzeichnen. Sie ermöglichen eine asynchrone Kommunikation und lösen bestimmte Funktionalitäten oder Workflows aus, ohne dass eine direkte Benutzerinteraktion erforderlich ist. Beispielsweise kann eine Ereignisaktivität einen Agent darüber benachrichtigen, dass ein Benutzer einer Unterhaltung beitritt oder sich der Umgebungskontext ändert.

Senden von Ereignissen

Der Knoten "Ereignisaktivität " wurde für das Senden von Ereignisaktivitäten entwickelt. Ereignisaktivitäten werden vom Agenten gesendet und können vom Kanal abgefangen und genutzt werden, wobei der Kanal entscheidet, ob und wie er diese Aktivitäten nutzt. Wenn Sie ein Ereignis senden, geben Sie ihm einen Namen und können dann einen Wert für das Ereignis festlegen. Dieser Wert kann ein beliebiges Format aufweisen:

• Ein primitiver Literalwert
• Ein Variablenverweis
• Eine Power Fx-Formel.

Der Wert wird als JSON-Literal serialisiert und der ausgehenden Aktivität hinzugefügt.

Zu den Verwendungsmöglichkeiten dieses Knotens gehören:

• Konfigurieren Sie ein benutzerdefiniertes Webchat-Steuerelement für die Behandlung von Ereignissen, die vom Agent gesendet werden. Sie können beispielsweise nach einem Ereignis suchen, das der Agent zurückgibt, und auf der Seite eine Aktion ausführen. Das 04.api/c.incoming-activity-event-Beispiel im Microsoft Bot Framework-Web-Chat-Beispiel-Repository auf GitHub demonstriert, wie die Ereignisbehandlung funktionieren könnte.
• Verwenden Sie Ereignisaktivitäten, um AudioCodes-Aufzeichnungsdienste zu steuern, z. B. zum Starten oder Beenden der Anrufaufzeichnung. Weitere Informationen finden Sie unter Aufzeichnen von Anrufen.

Verwenden von Clienttools

Während der Orchestrierung stellen wir das Sprachmodell mit einer Reihe von Tools bereit. Die meisten Menschen denken über Tools nach, die externe Systeme aufrufen.

Wir können jedoch auch Ereignisaktivitäten verwenden, um Tools vom Client auszuführen.

Wenn der Orchestrator entscheidet, ein Clienttool auszuführen, sendet der Agent eine Ereignisaktivität an den Client, einschließlich der im Tool definierten Eingaben.

Der Agent sendet die Aktivität und wartet dann, bis der Client die Aktion ausführt und ein Ergebnis zurückgibt. Wenn der Client fertig ist, sendet er eine Ereignisaktivität, die die Antwort an den Agent enthält. Der Agent übernimmt diese Antwort als Reaktion des Tools und setzt die Orchestrierung fort.

Beispielnutzlasten für Clienttools

Angenommen, wir haben ein Clienttool, das den Text auf einer PowerPoint-Folie abruft.

Die Eingaben sind die Seitenzahl, und die Ausgabe ist der Text auf der Folie.

Der Agent könnte ein Payload wie folgt senden:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "from": { 
        "id": "d9c0dcf9-4045-8062-535b-73fb4dfee954", 
        "role": 0 
    }, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "page": 5      
    } 
} 

Nachdem der Vorgang abgeschlossen ist, sendet der Client dem Agent eine Nutzlast wie:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "content": "QA slide. Next steps"      
    } 
} 

Einrichten von Clienttools

Es gibt zwei Möglichkeiten zum Registrieren von Clienttools.

Als Teil der Inhalte Ihres Agent-Themas können Sie im Code-Editor eine dedizierte Client-Task-Aktion für Ihren Agenten registrieren.

Beispiel:

description: this tool retrieves the content of a powerpoint slide 
schemaName: GetSlideContent 
    dialog: 
      kind: TaskDialog 
      action: 
        kind: InvokeClientTaskAction 
        clientActionInputSchema: 
          kind: Record 
          properties: 
            page: 
            displayName: Page Number 
            description: The number of the slide 
            isRequired: true 
              type: Number 
        clientActionResponseSchema: 
          kind: Record 
          properties: 
            content: 
            displayName: Slide Content 
            description: The content of the slide 
              type: String 

Manchmal sind die verfügbaren Tools dynamisch, basierend auf dem Kontext des Hostingclients. Um mehr Flexibilität zu ermöglichen, können Ersteller eine Systemvariable festlegen, um andere Clienttools, die für diese Sitzung verwendet werden können, dynamisch festzulegen.

- kind: SetVariable 
  id: setVariable_76NZWK 
  variable: System.ClientPluginActions 
  value: |- 
    =[ 
      { 
        Description: "this tool retrieves the content of a powerpoint slide", 
        Identifier: "GetSlideContent", 
        Name: "GetSlideContent", 
        Response: {mode: "Generated"}, 
        Inputs: [ 
          { 
            Description: "The name of the menu for the form to launch", 
            IsAutomatic: true, 
            IsRequired: true, 
            Name: "Page Number", 
            PropertyName: "page", 
            Type: { 
              '$kind': "Number" 
            } 
          } 
        ], 
        Outputs: [ 
          { 
            Description: "The content of the slide", 
            Name: "Slide Content", 
            PropertyName: "content", 
            Type: { 
              '$kind': "String" 
            } 
          } 
        ] 
      } 
    ] 

Senden anderer Aktivitätstypen

Neben Ereignisaktivitäten können Sie mit dem Knoten Invoke activity auch Aktivitäten anderer Typen senden. Die Arten von Aktivitäten, die Sie senden können, sind eine Teilmenge der im Bot Framework Schema – ActivityTypes Class angebotenen Aktivitäten. Wenn Sie diesen Knoten verwenden, wählen Sie den Typ der Aktivität aus und legen dann optional einen Namen oder Wert fest.

Gängige Typen sind:

• Schreiben sendet eine Schreibaktivität, die der Kanal erkennen und verwenden kann, um auf dem Client eine Tippanzeige anzuzeigen.
• Invoke und Invoke-Antwort werden für Microsoft Teams verwendet. Sie erstellen ein Topic mit einem Invoke-Trigger, um ein eingehendes Invoke von Teams abzufangen, und verwenden einen Knoten vom Typ Invoke response activity, um eine entsprechende Antwort an Teams zu senden.
• Übergabe sendet eine Übergabeaktivität mit expliziter Kontrolle über den Wert. Eine Übergabe wird für externe Kanäle verwendet, z. B. AudioCodes.

Verwandte Inhalte

• Mit globalen Variablen arbeiten
• Das Erscheinungsbild eines Agent anpassen