Hinzufügen von Ablaufverfolgungsaktivitäten zu Ihrem Bot

GILT FÜR: SDK v4

Eine Ablaufverfolgungsaktivität ist eine Aktivität, die von Ihrem Bot an den Bot Framework Emulator gesendet werden kann. Sie können Ablaufverfolgungsaktivitäten verwenden, um einen Bot interaktiv zu debuggen, da diese Ihnen das Anzeigen von Informationen zu Ihrem Bot während der lokalen Ausführung ermöglichen.

Ablaufverfolgungsaktivitäten werden nur an den Emulator und nicht an andere Clients oder Kanäle gesendet. Vom Emulator werden sie im Protokoll angezeigt, aber nicht im Hauptbereich des Chats.

• Ablaufverfolgungsaktivitäten, die über den Turn-Kontext gesendet werden, fließen über die SendActivity-Handler, die für den Turn-Kontext registriert wurden.
• Über den Turn-Kontext gesendete Ablaufverfolgungsaktivitäten werden der eingehenden Aktivität zugeordnet, indem der Konversationsverweis angewendet wird, falls vorhanden. Bei einer proaktiven Nachricht handelt es sich bei der ReplyTo-ID um eine neue GUID.
• Unabhängig von der Art des Sendevorgangs wird für eine Ablaufverfolgungsaktivität niemals das Flag responded (Beantwortet) festgelegt.

Hinweis

Um Agents mit Ihrer Wahl von KI-Diensten, Orchestrierung und Wissen zu erstellen, sollten Sie das Microsoft 365 Agents SDK verwenden. Das Agents SDK unterstützt C#, JavaScript oder Python. Weitere Informationen zum Agents SDK finden Sie unter aka.ms/agents. Wenn Sie nach einer SaaS-basierten Agent-Plattform suchen, ziehen Sie Microsoft Copilot Studio in Betracht. Wenn Sie über einen vorhandenen Bot verfügen, der mit dem Bot Framework SDK erstellt wurde, können Sie Ihren Bot auf das Agents SDK aktualisieren. Sie können die wichtigsten Änderungen und Updates im Bot Framework SDK zu Agents SDK-Migrationsleitfaden überprüfen. Supporttickets für das Bot Framework SDK werden ab dem 31. Dezember 2025 nicht mehr bearbeitet.

Verwenden einer Ablaufverfolgungsaktivität

Zum Anzeigen einer Ablaufverfolgungsaktivität im Emulator benötigen Sie ein Szenario, bei dem Ihr Bot eine Ablaufverfolgungsaktivität sendet, z. B. zum Auslösen einer Ausnahme und Senden einer Ablaufverfolgungsaktivität über den onTurnError-Handler des Adapters.

Gehen Sie beim Senden einer Ablaufverfolgungsaktivität von Ihrem Bot wie folgt vor:

1. Erstellen Sie eine neue Aktivität.
   • Legen Sie die benötigte type-Eigenschaft auf „trace“ fest.
   • Legen Sie optional die Eigenschaften name, label, value und value type so fest, wie dies für die Ablaufverfolgung geeignet ist.
2. Verwenden Sie die SendActivity-Methode des Turn-Kontext-Objekts, um die Ablaufverfolgungsaktivität zu senden.
   • Mit dieser Methode werden Werte für die verbleibenden erforderlichen Eigenschaften der Aktivität basierend auf der eingehenden Aktivität hinzugefügt. Hierzu gehören die Eigenschaften channel ID, service URL, from und recipient.

Zeigen Sie eine Ablaufverfolgungsaktivität im Emulator wie folgt an:

1. Führen Sie den Bot lokal auf Ihrem Computer aus.
2. Testen Sie ihn mit dem Emulator.
   • Interagieren Sie mit dem Bot, und verwenden Sie die Schritte in Ihrem Szenario, um die Ablaufverfolgungsaktivität zu generieren.
   • Wenn Ihr Bot die Ablaufverfolgungsaktivität ausgibt, wird sie im Emulatorprotokoll angezeigt.

Hier ist eine Ablaufverfolgungsaktivität angegeben, die ggf. im folgenden Fall angezeigt wird: Sie führen den „Core Bot“ aus, ohne zuerst die QnAMaker-Wissensdatenbank einzurichten, die vom Bot verwendet wird.

Hinzufügen einer Ablaufverfolgungsaktivität zum OnError-Handler des Adapters

Der onTurnError-Handler fängt alle Ausnahmen ab, die vom Bot während eines Turns ausgelöst und nicht anderweitig abgefangen werden. Der Fehler-Handler ist ein guter Ort für eine Ablaufverfolgungsaktivität, da Sie eine benutzerfreundliche Nachricht an den Benutzer und Debuginformationen zur Ausnahme an den Emulator senden können.

Dieser Beispielcode stammt aus dem BeispielCore Bot. Das vollständige Beispiel finden Sie unter C#, JavaScript, Python oder Java.

C#

Mit dem OnTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeinformationen einzufügen, und an den Emulator gesendet.

AdapterWithErrorHandler.cs

Warnung

Es sieht so aus, als ob das gesuchte Beispiel verschoben wurde! Seien Sie sicher, dass wir daran arbeiten, dies zu lösen.

JavaScript

Mit dem onTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeninformationen einzufügen und diese an den Emulator zu senden.

index.js

Warnung

Es sieht so aus, als ob das gesuchte Beispiel verschoben wurde! Seien Sie sicher, dass wir daran arbeiten, dies zu lösen.

Java

Im Java SDK ist eine AdapterWithErrorHandler-Klasse als Teil des SDK im Paket com.microsoft.bot.integration enthalten. Mit dem onTurnError-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeninformationen einzufügen und diese an den Emulator zu senden. Der Quellcode für den Standardadapter wird unten angezeigt.

AdapterWithErrorHandler.java

setOnTurnError((turnContext, exception) -> {
    LoggerFactory.getLogger(AdapterWithErrorHandler.class).error("onTurnError", exception);


    return turnContext.sendActivities(
        MessageFactory.text(ERROR_MSG_ONE), MessageFactory.text(ERROR_MSG_TWO)
    ).thenCompose(resourceResponse -> sendTraceActivity(turnContext, exception))
        .thenCompose(stageResult -> {
            if (withConversationState != null) {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a
                // Web pages.
                return withConversationState.delete(turnContext)
                    .exceptionally(deleteException -> {
                        LoggerFactory.getLogger(AdapterWithErrorHandler.class)
                            .error("ConversationState.delete", deleteException);
                        return null;
                    });
            }
            return CompletableFuture.completedFuture(null);
        });
});

Python

Mit dem on_error-Handler des Adapters wird die Ablaufverfolgungsaktivität erstellt, um die Ausnahmeninformationen einzufügen und diese an den Emulator zu senden.

adapter_with_error_handler.py

Warnung

Es sieht so aus, als ob das gesuchte Beispiel verschoben wurde! Seien Sie sicher, dass wir daran arbeiten, dies zu lösen.

Nächste Schritte

• Unter Debuggen eines Bots mit Middleware zur Überprüfung wird beschrieben, wie Sie Middleware zum Ausgeben von Ablaufverfolgungsaktivitäten hinzufügen.
• Zum Debuggen eines bereitgestellten Bots können Sie Application Insights verwenden. Weitere Informationen finden Sie unter Hinzufügen von Telemetriefunktionen zu Ihrem Bot.
• Ausführliche Informationen zu den einzelnen Aktivitätstypen finden Sie unter Bot Framework-Aktivitätsschema.