Ereignis oder Aktivität senden

2025-06-20

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 Agenten 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 verwendet werden, der entscheidet, ob und wie die Aktivitäten verwendet werden. 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 Literal-Wert
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 in der 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.

Serverseitige Tools über API.

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

Clientseitige Tools über Ereignisaktivitäten.

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 eine Nutzlast wie die folgende 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 Agenten 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 des Inhalts Ihres Agententhemas können Sie mithilfe des Code-Editors eine dedizierte Clientaufgabenaktion für Ihren Agent registrieren.

Zum 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

Zusätzlich zu Ereignisaktivitäten können Sie über den Knoten Aktivität ausführen auch Aktivitäten anderer Art senden. Die Arten von Aktivitäten, die Sie senden können, sind eine Teilmenge der im Bot Framework Schema – ActivityTypes-Klasse 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:

Eingabe: Sendet eine Eingabeaktivität, die der Kanal nehmen kann, um einen Eingabeindikator auf dem Client auszuwählen und anzuzeigen.
Invoke und Invoke-Antwort werden für Microsoft Teams verwendet. Sie erstellen ein Thema mit einem Aufruftrigger, um einen eingehenden Aufruf von Teams abzufangen, und verwenden einen Aufrufantwortaktivitätsknoten , um eine entsprechende Antwort an Teams zurückzusenden.
Handoff sendet eine Übergabeaktivität mit expliziter Kontrolle über den Wert. Eine Übergabe wird für externe Kanäle verwendet, z. B. AudioCodes.

Freigeben über