Grundlagen des Microsoft Bot Framework

GILT FÜR: SDK v4

Ein Bot ist eine App, mit der Benutzer in Form einer Konversation mithilfe von Text, Grafiken (z.B. Karten oder Bilder) oder Sprache interagieren. Azure KI Bot Service ist eine Cloudplattform. Sie hostet Bots und stellt sie Kanälen zur Verfügung, z. B. Microsoft Teams, Facebook oder Slack.

Der Bot Framework Service ist eine Komponente von Azure KI Bot Service und sendet Informationen zwischen der mit dem Bot verbundenen App des Benutzers und dem Bot hin und her. Jeder Kanal kann zusätzliche Informationen in die gesendeten Aktivitäten einfügen. Vor dem Erstellen von Bots sollten Sie sich unbedingt damit vertraut machen, wie ein Bot Aktivitätsobjekte nutzt, um mit seinen Benutzern zu kommunizieren.

Dieses Diagramm veranschaulicht zwei Aktivitätstypen, Unterhaltungsaktualisierungen und Nachrichten, die möglicherweise ausgetauscht werden, wenn ein Benutzer mit einem Echobot kommuniziert.

Der Bot Framework Service kann beispielsweise eine Konversationsaktualisierung senden, wenn ein Teilnehmer der Konversation beitritt. Zu Beginn einer Konversation mit dem Bot Framework Emulator sind beispielsweise zwei Aktivitäten für die Konversationsaktualisierung vorhanden (eine für den Benutzer, der der Konversation beitritt, und eine für den beitretenden Bot). Um diese Aktivitäten zur Aktualisierung von Unterhaltungen zu unterscheiden, prüfen Sie, wer in der Eigenschaft der hinzugefügten Mitglieder der Aktivität enthalten ist.

Mit der Aktivität vom Typ Nachricht werden Konversationsinformationen zwischen den Teilnehmern übertragen. In einem Beispiel mit einem Echobot enthalten die Nachrichtenaktivitäten einfachen Text, der vom Kanal gerendert wird. Alternativ hierzu kann die Nachrichtenaktivität auch gesprochenen Text, vorgeschlagene Aktionen oder Karten enthalten, die angezeigt werden sollen.

Tipp

Es liegt an jedem Kanal, das Bot-Framework-Protokoll zu implementieren und wie jeder Kanal dies tut, kann ein wenig anders sein. Beispielsweise senden einige Kanäle zuerst Unterhaltungsaktualisierungs-Aktivitäten und einige Aktivitäten zum Senden von Unterhaltungsaktualisierungen, nachdem sie die erste Nachrichtenaktivität gesendet haben. Ein Kanal kann sowohl den Bot als auch den Benutzer in einer Unterhaltungsaktualisierungs-Aktivität enthalten, während ein anderer möglicherweise zwei Unterhaltungsaktualisierungs-Aktivitäten sendet.

In diesem Beispiel hat der Bot eine Nachrichtenaktivität als Antwort auf die erhaltene eingehende Nachrichtenaktivität erstellt und gesendet. Ein Bot kann jedoch auch auf andere Weise auf eine empfangene Nachrichtenaktivität reagieren. Es ist üblich, dass ein Bot auf eine Unterhaltungsaktualisierungs-Aktivität mit dem Senden einer Nachrichtenaktivität mit einer Willkommensnachricht reagiert. Weitere Informationen finden Sie unter Begrüßung eines Benutzers.

Das Bot Framework SDK

Mit dem Bot Framework SDK können Sie Bots erstellen, die im Azure KI Bot Service gehostet werden können. Der Dienst definiert eine REST-API und ein Aktivitätsprotokoll für die Interaktion zwischen Ihrem Bot und Kanälen oder Benutzern. Das SDK baut auf dieser REST-API auf und bietet eine Abstraktion des Diensts, sodass Sie sich auf die Unterhaltungslogik konzentrieren können. Obwohl Sie den REST-Dienst nicht verstehen müssen, um das SDK zu verwenden, können einige seiner Features hilfreich sein.

Bots sind Apps, die über eine Unterhaltungsschnittstelle verfügen. Sie können verwendet werden, um einfache, sich wiederholende Aufgaben, z.B. das Aufnehmen einer Tischreservierung zum Abendessen oder das Erfassen von Profilinformationen auf automatisierte Systeme zu übertragen, die u.U. keinen direkten Benutzereingriff mehr erfordern. Benutzer kommunizieren mit einem Bot mithilfe von Text, interaktiven Karten und Spracheingabe/-ausgabe. Bei einer Botinteraktion kann es sich um eine kurze Frage und Antwort oder auch um eine komplexe Konversation handeln, die auf intelligente Weise den Zugriff auf Dienste bereitstellt.

Hinweis

Die Unterstützung für Features, die vom SDK und der REST-API bereitgestellt werden, variiert je nach Kanal. Sie können Ihren Bot mit dem Bot Framework Emulator testen, sollten aber auch alle Features Ihres Bots in jedem Kanal testen, in dem Sie Ihren Bot verfügbar machen möchten.

Interaktionen umfassen den Austausch von Aktivitäten, die in Turnsbehandelt werden.

Aktivitäten

Jede Interaktion zwischen dem Benutzer (oder einem Kanal) und dem Bot wird als Aktivität dargestellt. Das Bot-Framework-Aktivitätsschema definiert die Aktivitäten, die zwischen einem Benutzer oder Kanal und einem Bot ausgetauscht werden können. Aktivitäten können menschlichen Text oder Sprache, App-zu-App-Benachrichtigungen, Reaktionen auf andere Nachrichten usw. darstellen.

Turns

In einer Konversation sprechen die Personen häufig einzeln. Sie wechseln sich also ab. Ein Bot reagiert im Allgemeinen auf die Eingabe eines Benutzers. Im Bot Framework SDK besteht ein Turn (Durchlauf) aus der eingehenden Aktivität des Benutzers für den Bot und einer beliebigen Aktivität, die vom Bot als direkte Antwort zurück an den Benutzer gesendet wird. Sie können einen Durchlauf als die Verarbeitung betrachten, die damit verbunden ist, dass der Bot eine bestimmte Aktivität erhält.

Beispielsweise kann ein Benutzer einen Bot bitten, eine bestimmte Aufgabe auszuführen. Der Bot antwortet möglicherweise mit einer Frage, um weitere Informationen über die Aufgabe zu erhalten, zu welchem Zeitpunkt dieser Durchlauf endet. Im nächsten Durchlauf erhält der Bot eine neue Nachricht des Benutzers, die die Antwort auf die Frage des Bots enthalten kann, aber auch eine Änderung des Themas oder eine Aufforderung, die ursprüngliche Aufforderung zur Ausführung der Aufgabe zu ignorieren, darstellen kann.

Struktur der Botanwendung

Das SDK definiert eine Bot-Klasse, die die Unterhaltungsgrundlegung für die Bot-App behandelt. Die Bot-Klasse:

• Erkennt und interpretiert die Benutzereingabe.
• Überlegt sich die Eingaben und führt die entsprechenden Aufgaben aus.
• Generiert Antworten darüber, was der Bot tut oder getan hat.

Das SDK definiert auch eine Adapter-Klasse, die die Konnektivität mit den Kanälen verarbeitet. Der Adapter:

• Stellt eine Methode zum Behandeln von Anforderungen und Methoden zum Generieren von Anforderungen an den Kanal des Benutzers bereit.
• Enthält eine Middleware-Pipeline, die die Durchlaufverarbeitung außerhalb des Turn-Handlers Ihres Bots umfasst.
• Ruft den Turn-Handler des Bots auf und fängt Fehler ab, die sonst nicht im Turn-Handler behandelt werden.

Darüber hinaus müssen Bots häufig jeden Turn-Zustand abrufen und speichern. Der Zustand wird über Storage-, Bot State- und Eigenschaftsaccessor-Klassen behandelt. Das SDK bietet keinen integrierten Speicher, bietet aber Abstraktionen für den Speicher und einige Implementierungen einer Speicherebene. Im Thema Verwalten des Zustands werden diese Zustands- und Speicher-Features beschrieben.

Das SDK erfordert nicht, dass Sie eine bestimmte Anwendungsebene zum Senden und Empfangen von Webanforderungen verwenden. Die Bot-Framework hat Vorlagen und Beispiele für ASP.NET (C#), restify (JavaScript) und aiohttp (Python). Sie können jedoch eine andere Anwendungsebene für Ihre App verwenden.

Wenn Sie einen Bot mit dem SDK erstellen, geben Sie den Code an, um den HTTP-Datenverkehr zu empfangen und an den Adapter weiterzuleiten. Das Bot Framework bietet einige Vorlagen und Beispiele, mit denen Sie eigene Bots entwickeln können.

Hinweis

Die JavaScript-, C#- und Python-SDKs für Bot Framework werden weiterhin unterstützt, das Java-SDK wird jedoch eingestellt und der langfristige Support endet im November 2023.

Bestehende Bots, die mit dem Java SDK erstellt wurden, werden weiterhin funktionieren.

Für das erstellen eines neuen Bots sollten Sie Microsoft Copilot Studio verwenden und lesen, wie Sie die richtige Copilot-Lösung auswählen.

Weitere Informationen finden Sie unter Die Zukunft des Bot-Buildings.

Botlogik

Das Bot-Objekt enthält die Unterhaltungsgrundsätze oder Logik für einen Durchlauf und macht einen Turn-Handler verfügbar. Dies ist die Methode, mit der eingehende Aktivitäten vom Bot-Adapter akzeptiert werden können.

Das SDK bietet ein paar verschiedene Paradigmen zum Verwalten Ihrer Botlogik.

• Aktivitätshandler stellen ein ereignisgesteuertes Modell bereit, in dem die eingehenden Aktivitätstypen und Untertypen die Ereignisse sind. Ziehen Sie einen Aktivitätshandler für Bots in Betracht, die begrenzte, kurze Interaktionen mit dem Benutzer haben.
  • Verwenden Sie einen Aktivitätshandler und implementieren Sie Handler für jeden Aktivitätstyp oder Untertyp, den Ihr Bot erkennen und auf den er reagieren soll.
  • Verwenden Sie einen Teamaktivitäts-Handler, um Bots zu erstellen, die eine Verbindung mit dem Teams-Kanal herstellen können. (Der Teams-Kanal erfordert, dass der Bot ein kanalspezifisches Verhalten verarbeitet.)
• Die Dialogbibliothek bietet ein zustandsbasiertes Modell zum Verwalten einer langlaufenden Konversation mit dem Benutzer.
  • Verwenden Sie einen Aktivitätshandler und einen Komponentendialog für weitgehend sequenzielle Unterhaltungen. Weitere Informationen finden Sie unter Komponenten- und Wasserfalldialoge.
• Implementieren Sie Ihre eigene Bot-Klasse und stellen Sie ihre eigene Logik für die Behandlung der einzelnen Durchläufe bereit. Ein Beispiel finden Sie in der Erstellung eigener Eingabeaufforderungen zum Sammeln von Benutzereingaben.

Der Botadapter

Der Adapter verfügt über eine Prozessaktivitäts-Methode zum Starten eines Durchlaufs.

• Er akzeptiert den Anforderungstext (die Anforderungsnutzlast, übersetzt in eine Aktivität) und den Anforderungsheader als Argumente.
• Er überprüft, ob der Authentifizierungsheader gültig ist.
• Er erstellt ein Kontext-Objekt für den Durchlauf. Das Kontextobjekt enthält Informationen zur Aktivität.
• Das Kontextobjekt wird über die Middleware-Pipeline gesendet.
• Anschließend wird das Kontextobjekt an den Turn-Handler des Botobjekts gesendet.

Der Adapter tut auch Folgendes:

• Formatiert und sendet Antwortaktivitäten. Diese Antworten sind in der Regel Nachrichten für den Benutzer, können aber auch Informationen enthalten, die direkt vom Kanal des Benutzers genutzt werden.
• Zeigt andere Methoden an, die von der Bot-Connector-REST-API bereitgestellt werden, z. B. Aktualisieren von Nachrichten und Löschen von Nachrichten.
• Erfasst Fehler oder Ausnahmen, die nicht andernfalls für den Durchlauf abgefangen werden.

Der Durchlaufkontext

Das Durchlaufkontext-Objekt (turn context) enthält Informationen zur Aktivität, z.B. den Absender und Empfänger, den Kanal und andere Daten, die zum Verarbeiten der Aktivität benötigt werden. Außerdem ermöglicht das Objekt das Hinzufügen von Informationen während des Turns für mehrere Ebenen des Bots.

Der Turn-Kontext ist eine der wichtigsten Abstraktionen im SDK. Er überträgt nicht nur die eingehende Aktivität an alle Middlewarekomponenten und die Anwendungslogik, sondern stellt auch den Mechanismus bereit, mit dem die Middlewarekomponenten und die Botlogik ausgehende Aktivitäten senden können.

Middleware

Die Middleware ist ähnlich aufgebaut wie jede andere Messagingmiddleware. Sie besteht aus einem linearen Satz von Komponenten, die nacheinander ausgeführt werden, sodass jede Komponente einen Vorgang für die Aktivität ausführen kann. In der letzten Phase der Middlewarepipeline erfolgt ein Rückruf an den Turn-Handler für die Botklasse, die die Anwendung mit der Methode Prozessaktivität des Adapters registriert hat. Middleware implementiert eine On-Turn-Methode, die der Adapter aufruft.

Der Turn-Handler akzeptiert einen Turn-Kontext als Argument. Die in der Turn-Handlerfunktion ausgeführte Anwendungslogik verarbeitet in der Regel den Inhalt der eingehenden Aktivität und erzeugt als Antwort eine oder mehrere Aktivitäten, die mit der Funktion send activity des Turn-Kontexts nach außen gesendet werden. Durch den Aufruf von send activity für den Turn-Kontext werden die Middlewarekomponenten für die ausgehenden Aktivitäten aufgerufen. Middlewarekomponenten werden vor und nach der Turn-Handlerfunktion des Bots ausgeführt. Die Ausführung ist grundsätzlich geschachtelt und wird daher manchmal als eine Art Zwiebel bezeichnet.

Im Thema Middleware wird Middleware ausführlicher beschrieben.

Bot State und Storage

Wie bei anderen Web-Apps ist ein Bot inhärent zustandslos. Der Zustand in einem Bot basiert auf den gleichen Paradigmen wie bei modernen Webanwendungen, und das Bot Framework SDK bietet Abstraktionen für die Speicherebene und die Statusverwaltung, um die Statusverwaltung zu vereinfachen.

Im Thema Verwalten des Zustands werden diese Zustands- und Speicher-Features beschrieben.

Messaging-Endpunkt und -Bereitstellung

In der Regel benötigt Ihre Anwendung einen REST-Endpunkt, an dem Nachrichten empfangen werden. Er muss auch Ressourcen für Ihren Bot gemäß der Plattform bereitstellen, die Sie verwenden möchten.

Folgen Sie der Schnellstartanleitung zum Erstellen eines Bots, um einen einfachen Echo-Bot zu erstellen und zu testen.

HTTP-Details

Aktivitäten kommen im Bot vom Bot Framework-Dienst über eine HTTP POST-Anforderung an. Der Bot antwortet auf die eingehende POST-Anforderung mit dem HTTP-Statuscode 200. Aktivitäten, die vom Bot an den Kanal gesendet werden, werden in einer separaten HTTP POST-Anforderung an den Bot Framework-Dienst gesendet. Dies wird wiederum mit dem HTTP-Statuscode 200 bestätigt.

Im Protokoll ist aber nicht die Reihenfolge angegeben, in der diese POST-Anforderungen und die zugehörigen Bestätigungen durchgeführt werden. Damit sie zu allgemeinen HTTP-Dienstframeworks passen, sind diese Anforderungen normalerweise geschachtelt. Dies bedeutet, dass die ausgehende HTTP-Anforderung vom Bot innerhalb des Bereichs der eingehenden HTTP-Anforderung gesendet wird. Dieses Muster ist in dem oben abgebildeten Diagramm dargestellt. Da hier zwei einzelne HTTP-Verbindungen aufeinander folgen, muss das Sicherheitsmodell beide abdecken.

Hinweis

Der Bot hat 15 Sekunden Zeit, um den Anruf mit einem Zustand 200 in den meisten Kanälen zu bestätigen. Wenn der Bot nicht innerhalb von 15 Sekunden reagiert, tritt ein HTTP-GatewayTimeout-Fehler (504) auf.

Stapel für die Aktivitätsverarbeitung

Wir verwenden das vorherige Sequenzdiagramm erneut, aber nun liegt der Schwerpunkt auf dem Eintreffen einer Nachrichtenaktivität.

Der Kanal sendet die Nachricht des Benutzers an den Azure KI Bot Service und der Dienst leitet die Nachricht an den Messaging-Endpunkt des Bots weiter. Die Antwort des Bots wird innerhalb des Bereichs des Durchlaufs an den Benutzer gesendet.

Im obigen Beispiel hat der Bot auf die Nachrichtenaktivität mit einer anderen Nachrichtenaktivität geantwortet, die die gleiche Textnachricht enthält. Die Verarbeitung beginnt damit, dass die HTTP POST-Anforderung auf dem Webserver ankommt. Dabei werden die Aktivitätsinformationen als JSON-Nutzlast übertragen. Häufig werden ASP.NET-Projekte für C#-Bots verwendet, und ein beliebtes Framework wie Express oder restify wird für JavaScript-Node.js-Bots verwendet.

Der Adapter, eine integrierte Komponente des SDK, ist das Kernstück der SDK-Runtime. Die Aktivität wird als JSON (JavaScript Object Notation) im HTTP-POST-Text übertragen. Dieses JSON-Objekt wird deserialisiert, um das Activity-Objekt zu erstellen, das dann über seine Prozessaktivitäts-Methode an den Adapter übergeben wird. Der Adapter erstellt nach dem Empfang der Aktivität einen Turn-Kontext und ruft die Middleware auf.

Der Turn-Kontext stellt wie bereits erwähnt den Mechanismus bereit, mit dem der Bot ausgehende Aktivitäten sendet (in der Regel als Reaktion auf eine eingehende Aktivität). Der Turn-Kontext stellt Antwortmethoden zum Senden, Aktualisieren und Löschen von Aktivitäten bereit. Jede Antwortmethode wird in einem asynchronen Prozess ausgeführt.

Wichtig

Der Thread, der den primären Botdurchlauf verarbeitet, löscht am Ende das Kontextobjekt. Stellen Sie sicher, dass Sie für alle Aktivitätsaufrufe await verwenden, damit der primäre Thread auf die generierte Aktivität wartet, bevor er die Verarbeitung beendet und den Turn-Kontext löscht. Wenn eine Antwort (einschließlich der Handler) sehr lange dauert und versucht wird, Vorgänge für das Kontextobjekt durchzuführen, tritt ggf. ein Fehler der Art Context was disposed (Kontext wurde verworfen) auf.

Botvorlagen

Sie müssen die Anwendungsebene für Ihre App auswählen; Das Bot Framework verfügt jedoch über Vorlagen und Beispiele für ASP.NET (C#), restify (JavaScript) und aiohttp (Python). In der Dokumentation wird davon ausgegangen, dass Sie eine dieser Plattformen verwenden, aber das SDK setzt dies nicht voraus. Anweisungen zum Zugreifen auf und Installieren der Vorlagen finden Sie in der Schnellstartanleitung zum Erstellen eines Bots.

Ein Bot ist eine Webanwendung und für jede Sprachversion des SDK werden Vorlagen bereitgestellt. Alle Vorlagen bieten eine standardmäßige Endpunktimplementierung und einen Adapter. Jede Vorlage enthält Folgendes:

• Ressourcenbereitstellung
• Eine sprachspezifische HTTP-Endpunktimplementierung, die eingehende Aktivitäten an einen Adapter weiterleitet.
• Ein Adapter-Objekt
• Ein Bot-Objekt

Der Hauptunterschied zwischen den verschiedenen Vorlagentypen liegt im Bot-Objekt. Die Vorlagen sind:

• Empty Bot
  • Enthält einen Aktivitätshandler, der einen Benutzer zur Unterhaltung begrüßt, indem eine „Hello World“-Nachricht an die erste Unterhaltung gesendet wird.
• Echo-Bot
  • Verwendet einen Aktivitätshandler, um Benutzer willkommen zu heißen und Benutzereingaben zurückzugeben.
• Core Bot
  • Vereint viele Features des SDK und veranschaulicht bewährte Methoden für einen Bot.
  • Verwendet einen Aktivitätshandler, um Benutzer zu begrüßen.
  • Verwendet einen Komponentendialog und untergeordnete Dialoge zum Verwalten der Unterhaltung.
  • Die Dialoge verwenden die Features Language Understanding (LUIS) und QnA Maker.

Hinweis

Azure KI QnA Maker wird am 31. März 2025 eingestellt. Ab dem 01. Oktober 2022 können Sie keine neuen QnA Maker-Ressourcen oder Wissensdatenbanken mehr erstellen. Eine neuere Version der Funktionalität „Fragen und Antworten“ ist jetzt als Teil von Azure KI Language verfügbar.

Benutzerdefiniertes Fragen und Antworten, eine Azure KI Language-Funktion, ist die aktualisierte Version des QnA Maker-Diensts. Weitere Informationen zur Unterstützung von Fragen und Antworten im Bot Framework SDK finden Sie unter Natürliches Sprachverständnis.

Hinweis

Language Understanding (LUIS) wird am 1. Oktober 2025 eingestellt. Ab dem 1. April 2023 können Sie keine neuen LUIS-Ressourcen erstellen. Eine neuere Version von Language Understanding ist jetzt als Teil von Azure KI Language verfügbar.

Conversational Language Understanding (CLU), ein Feature von Azure KI Language, ist die aktualisierte Version von LUIS. Weitere Informationen zur Unterstützung von Language Understanding im Bot Framework SDK finden Sie unter Natürliches Sprachverständnis.

Weitere Informationen

Verwalten von Bot-Ressourcen

Sie müssen die Ressourcen für Ihren Bot verwalten, z. B. die App-ID und das Passwort sowie Informationen für alle verbundenen Dienste. Wenn Sie Ihren Bot bereitstellen, benötigt er sicheren Zugriff auf diese Informationen. Um Komplexität zu vermeiden, beschreiben die meisten Artikel zu Bot Framework SDKs nicht, wie diese Informationen verwaltet werden.

• Allgemeine Sicherheitsinformationen finden Sie unter Bot-Framework-Sicherheitsrichtlinien.
• Informationen zur Verwaltung von Schlüsseln und Geheimnissen in Azure finden Sie unter Über Azure Key Vault.

Kanaladapter

Mit dem SDK können Sie auch Kanaladapter verwenden, in denen der Adapter selbst zusätzlich die Aufgaben ausführt, die der Bot Connector Service für einen Kanal normal ausführen würde.

Das SDK stellt einige Kanaladapter in einigen Sprachen bereit. Weitere Kanaladapter sind über die Botkit- und Community-Repositorys verfügbar. Weitere Informationen finden Sie in der Repository-Tabelle zu Bot Framework SDKs mit Kanälen und Adaptern.

Die Bot-Connector-REST-API

Das Bot Framework SDK umschließt und baut auf der Bot-Connector-REST-API auf. Wenn Sie die zugrunde liegenden HTTP-Anforderungen verstehen möchten, die das SDK unterstützen, lesen Sie die Connector-Authentifizierung und die zugehörigen Artikel. Die Aktivitäten, die ein Bot sendet und empfängt, entsprechen dem Bot-Framework-Aktivitätsschema.

Nächste Schritte

• Informationen zur Rolle des Zustands in Bots finden Sie unter Verwalten des Zustands.
• Informationen zu den wichtigsten Konzepten der Entwicklung von Bots für Microsoft Teams finden Sie unter Funktionsweise von Microsoft Teams-Bots.