Basisbeginselen van het Microsoft Bot Framework

VAN TOEPASSING OP: SDK v4

Een bot is een app waarmee gebruikers communiceren op een gesprekswijze, met behulp van tekst, afbeeldingen (zoals kaarten of afbeeldingen) of spraak. Azure AI Bot Service is een cloudplatform. Het host bots en maakt ze beschikbaar voor kanalen, zoals Microsoft Teams, Facebook of Slack.

De Bot Framework Service, een onderdeel van de Azure AI Bot Service, verzendt informatie tussen de app die is verbonden met de bot en de bot van de gebruiker. Elk kanaal kan aanvullende informatie bevatten in de activiteiten die ze verzenden. Voordat u bots maakt, is het belangrijk om te begrijpen hoe een bot activiteitsobjecten gebruikt om met de gebruikers te communiceren.

Dit diagram illustreert twee activiteitstypen, gespreksupdates en berichten die kunnen worden uitgewisseld wanneer een gebruiker communiceert met een echobot.

Bot Framework Service verzendt een gespreksupdate wanneer een partij deelneemt aan het gesprek. Als u bijvoorbeeld een gesprek start met de Bot Framework Emulator, ziet u mogelijk twee activiteiten voor het bijwerken van gesprekken (één voor de gebruiker die deelneemt aan het gesprek en één voor de bot die deelneemt). Als u deze gespreksupdateactiviteiten wilt onderscheiden, controleert u wie is opgenomen in de leden die de eigenschap van de activiteit hebben toegevoegd .

De berichtactiviteit bevat gespreksinformatie tussen de partijen. In een voorbeeld van een echobot bevatten de berichtactiviteiten eenvoudige tekst en het kanaal geeft deze tekst weer. De berichtactiviteit kan ook tekst bevatten die moet worden gesproken, voorgestelde acties of kaarten die moeten worden weergegeven.

Tip

Het is aan elk kanaal om het Bot Framework-protocol te implementeren en hoe elk kanaal dit doet, kan iets anders zijn. Sommige kanalen verzenden bijvoorbeeld eerst activiteiten voor gespreksupdates en sommige activiteiten voor het bijwerken van gesprekken nadat ze de eerste berichtactiviteit hebben verzonden. Een kanaal kan zowel de bot als de gebruiker bevatten in de ene gespreksupdateactiviteit, terwijl een ander kanaal twee activiteiten voor het bijwerken van gesprekken kan verzenden.

In dit voorbeeld heeft de bot een berichtactiviteit gemaakt en verzonden als reactie op de binnenkomende berichtactiviteit die deze had ontvangen. Een bot kan echter op andere manieren reageren op een ontvangen berichtactiviteit en het is gebruikelijk dat een bot reageert op een gespreksupdateactiviteit door een berichtactiviteit met een welkomstbericht te verzenden. Zie voor meer informatie hoe u een gebruiker verwelkomt.

De Bot Framework SDK

Met de Bot Framework SDK kunt u bots bouwen die kunnen worden gehost op de Azure AI Bot Service. De service definieert een REST API en een activiteitenprotocol voor de manier waarop uw bot en kanalen of gebruikers kunnen communiceren. De SDK bouwt voort op deze REST API en biedt een abstractie van de service, zodat u zich kunt richten op de gesprekslogica. Hoewel u de REST-service niet hoeft te begrijpen om de SDK te gebruiken, kan het handig zijn om bepaalde functies ervan te begrijpen.

Bots zijn apps die een gespreksinterface hebben. Ze kunnen worden gebruikt om eenvoudige, terugkerende taken, zoals het nemen van een dinerreservering of het verzamelen van profielgegevens, te verplaatsen naar geautomatiseerde systemen die mogelijk geen directe menselijke interventie meer vereisen. Gebruikers communiceren met een bot met behulp van tekst, interactieve kaarten en spraak. Een botinteractie kan een snelle vraag en een antwoord zijn, of kan een geavanceerd gesprek zijn waarmee op intelligente wijze toegang tot services wordt geboden.

Notitie

Ondersteuning voor functies van de SDK en REST API verschilt per kanaal. U kunt uw bot testen met behulp van de Bot Framework Emulator, maar u moet ook alle functies van uw bot testen op elk kanaal waarin u uw bot beschikbaar wilt maken.

Interacties omvatten de uitwisseling van activiteiten, die op hun beurt worden verwerkt.

Activiteiten

Elke interactie tussen de gebruiker (of een kanaal) en de bot wordt weergegeven als een activiteit. Het Bot Framework-activiteitenschema definieert de activiteiten die kunnen worden uitgewisseld tussen een gebruiker of kanaal en een bot. Activiteiten kunnen menselijke tekst of spraak vertegenwoordigen, app-naar-app-meldingen, reacties op andere berichten, enzovoort.

Draait

In een gesprek spreken mensen vaak een-op-een-tijd, waarbij ze om beurten spreken. Met een bot reageert het over het algemeen op gebruikersinvoer. Binnen de Bot Framework SDK bestaat een beurt uit de binnenkomende activiteit van de gebruiker naar de bot en eventuele activiteiten die de bot als onmiddellijke reactie naar de gebruiker stuurt. U kunt een beurt beschouwen als de verwerking die is gekoppeld aan de bot die een bepaalde activiteit ontvangt.

Een gebruiker kan bijvoorbeeld een bot vragen om een bepaalde taak uit te voeren. De bot reageert mogelijk met een vraag om meer informatie over de taak te krijgen, op welk moment deze beurt eindigt. Bij de volgende beurt ontvangt de bot een nieuw bericht van de gebruiker die het antwoord op de vraag van de bot kan bevatten, of een wijziging van het onderwerp of een aanvraag om de eerste aanvraag te negeren om de taak uit te voeren.

Bottoepassingsstructuur

De SDK definieert een botklasse die de gespreksredenering voor de bot-app afhandelt. De botklasse:

• Herkent en interpreteert de invoer van de gebruiker.
• Redenen voor de invoer en het uitvoeren van relevante taken.
• Hiermee worden antwoorden gegenereerd over wat de bot doet of heeft gedaan.

De SDK definieert ook een adapterklasse die de connectiviteit met de kanalen afhandelt. De adapter:

• Biedt een methode voor het verwerken van aanvragen van en methoden voor het genereren van aanvragen naar het kanaal van de gebruiker.
• Bevat een middleware-pijplijn, waaronder turnverwerking buiten de turn-handler van uw bot.
• Roept de draaihandler van de bot aan en onderschept fouten die anders niet in de turnhandler worden verwerkt.

Bovendien moeten bots vaak elke keer de status ophalen en opslaan. Status wordt verwerkt via opslag-, botstatus- en eigenschapstoegangsklassen. De SDK biedt geen ingebouwde opslag, maar biedt wel abstracties voor opslag en enkele implementaties van een opslaglaag. In het onderwerp statusbeheer worden deze status- en opslagfuncties beschreven.

Voor de SDK hoeft u geen specifieke toepassingslaag te gebruiken om webaanvragen te verzenden en te ontvangen. Bot Framework bevat sjablonen en voorbeelden voor ASP.NET (C#), restify (JavaScript) en aiohttp (Python). U kunt er echter voor kiezen om een andere toepassingslaag voor uw app te gebruiken.

Wanneer u een bot maakt met behulp van de SDK, geeft u de code op om het HTTP-verkeer te ontvangen en door te sturen naar de adapter. Bot Framework biedt enkele sjablonen en voorbeelden die u kunt gebruiken om uw eigen bots te ontwikkelen.

Notitie

De Sdk's voor Bot Framework JavaScript, C# en Python blijven ondersteund, maar de Java SDK wordt buiten gebruik gesteld met definitieve langetermijnondersteuning die eindigt op november 2023.

Bestaande bots die zijn gebouwd met de Java SDK blijven functioneren.

Voor het bouwen van nieuwe bots kunt u Microsoft Copilot Studio gebruiken en lezen over het kiezen van de juiste copilot-oplossing.

Zie De toekomst van botbouw voor meer informatie.

Botlogica

Het botobject bevat de gespreksredenering of logica voor een draai en maakt een draaihandler beschikbaar. Dit is de methode waarmee binnenkomende activiteiten van de botadapter kunnen worden geaccepteerd.

De SDK biedt een aantal verschillende paradigma's voor het beheren van uw botlogica.

• Activiteitshandlers bieden een gebeurtenisgestuurd model waarin de binnenkomende activiteitstypen en subtypen de gebeurtenissen zijn. Overweeg een activiteitshandler voor bots die beperkte, korte interacties met de gebruiker hebben.
  • Gebruik een activiteitshandler en implementeer handlers voor elk activiteitstype of subtype dat uw bot herkent en reageert.
  • Gebruik een Teams-activiteitshandler om bots te maken die verbinding kunnen maken met het Teams-kanaal. (Het Teams-kanaal vereist dat de bot bepaalde kanaalspecifieke gedragingen afhandelt.)
• De dialoogvensterbibliotheek biedt een model op basis van status voor het beheren van een langlopend gesprek met de gebruiker.
  • Gebruik een activiteitshandler en een onderdeeldialoogvenster voor grotendeels sequentiële gesprekken. Zie voor meer informatie over dialoogvensters voor onderdelen en watervallen.
• Implementeer uw eigen botklasse en geef uw eigen logica voor het verwerken van elke beurt. Zie voor een voorbeeld hoe u uw eigen prompts maakt om gebruikersinvoer te verzamelen.

De botadapter

De adapter heeft een procesactiviteitsmethode voor het starten van een draai.

• Hierbij wordt de aanvraagbody (de nettolading van de aanvraag, vertaald naar een activiteit) en de aanvraagheader als argumenten gebruikt.
• Er wordt gecontroleerd of de verificatieheader geldig is.
• Er wordt een contextobject voor de beurt gemaakt. Het contextobject bevat informatie over de activiteit.
• Het contextobject wordt verzonden via de middleware-pijplijn .
• Vervolgens wordt het contextobject verzonden naar de draaihandler van het botobject.

De adapter ook:

• Hiermee worden antwoordactiviteiten opgemaakt en verzonden. Deze antwoorden zijn meestal berichten voor de gebruiker, maar kunnen ook informatie bevatten die rechtstreeks door het kanaal van de gebruiker moet worden gebruikt.
• Biedt andere methoden van de REST API voor botconnector, zoals het bijwerken van een bericht en het verwijderen van berichten.
• Onderschept fouten of uitzonderingen die anders niet voor de beurt zijn opgetreden.

De beurtcontext

Het contextobject turn biedt informatie over de activiteit, zoals de afzender en ontvanger, het kanaal en andere gegevens die nodig zijn om de activiteit te verwerken. Het maakt ook het toevoegen van informatie mogelijk tijdens de omslag over verschillende lagen van de bot.

De beurtcontext is een van de belangrijkste abstracties in de SDK. Niet alleen wordt de binnenkomende activiteit naar alle middlewareonderdelen en de toepassingslogica uitgevoerd, maar biedt het ook het mechanisme waarbij de middleware-onderdelen en de botlogica uitgaande activiteiten kunnen verzenden.

Middleware

Middleware is vergelijkbaar met alle andere berichten-middleware, bestaande uit een lineaire set onderdelen die elk op volgorde worden uitgevoerd, waardoor elk een kans krijgt om op de activiteit te werken. De laatste fase van de middleware-pijplijn is een callback naar de turn-handler op de botklasse die de toepassing heeft geregistreerd bij de procesactiviteitsmethode van de adapter. Middleware implementeert een in-turnmethode die door de adapter wordt aangeroepen.

De turn-handler gebruikt een turncontext als argument, meestal verwerkt de toepassingslogica die wordt uitgevoerd in de functie turn handler de inhoud van de inkomende activiteit en genereert een of meer activiteiten in reactie, waarbij deze uitgaande activiteiten worden verzonden met behulp van de functie Activiteit verzenden in de turncontext. Als u activiteit verzenden aanroept op de turncontext, worden de middleware-onderdelen aangeroepen voor de uitgaande activiteiten. Middlewareonderdelen worden uitgevoerd voor en na de handlerfunctie van de bot. De uitvoering is inherent genest en, als zodanig, wordt soms aangeduid als een ui.

In het onderwerp middleware wordt middleware uitgebreider beschreven.

Botstatus en -opslag

Net als bij andere web-apps is een bot inherent staatloos. Status binnen een bot volgt dezelfde paradigma's als moderne webtoepassingen en de Bot Framework SDK biedt opslaglaag- en statusbeheerabstracties om statusbeheer eenvoudiger te maken.

In het onderwerp statusbeheer worden deze status- en opslagfuncties beschreven.

Eindpunt voor berichten en inrichting

Normaal gesproken heeft uw toepassing een REST-eindpunt nodig waarop berichten moeten worden ontvangen. Het moet ook resources inrichten voor uw bot in overeenstemming met het platform dat u besluit te gebruiken.

Volg de quickstart Een bot maken om een eenvoudige echobot te maken en te testen.

HTTP-details

Activiteiten komen aan bij de bot vanuit de Bot Framework-service via een HTTP POST-aanvraag. De bot reageert op de binnenkomende POST-aanvraag met een HTTP-statuscode van 200. Activiteiten die van de bot naar het kanaal worden verzonden, worden verzonden op een afzonderlijke HTTP POST naar de Bot Framework-service. Dit wordt op zijn beurt bevestigd met een 200 HTTP-statuscode.

Het protocol geeft niet de volgorde op waarin deze POST-aanvragen en hun bevestigingen worden gedaan. Deze aanvragen zijn echter genest om te voldoen aan algemene HTTP-serviceframeworks, wat betekent dat de uitgaande HTTP-aanvraag wordt gedaan vanuit de bot binnen het bereik van de binnenkomende HTTP-aanvraag. Dit patroon wordt geïllustreerd in het eerdere diagram. Omdat er twee afzonderlijke HTTP-verbindingen naar achteren zijn, moet het beveiligingsmodel beide bieden.

Notitie

De bot heeft 15 seconden om de oproep te bevestigen met een status 200 op de meeste kanalen. Als de bot niet binnen 15 seconden reageert, treedt er een HTTP GatewayTimeout-fout (504) op.

De activiteitsverwerkingsstack

Laten we inzoomen op het vorige sequentiediagram met een focus op de aankomst van een berichtactiviteit.

Het kanaal verzendt het bericht van de gebruiker naar de Azure AI Bot Service en de service stuurt het bericht door naar het berichteindpunt van de bot. Het antwoord van de bot wordt verzonden naar de gebruiker binnen het bereik van de beurt.

In het bovenstaande voorbeeld heeft de bot gereageerd op de berichtactiviteit met een andere berichtactiviteit die hetzelfde tekstbericht bevat. De verwerking begint met de HTTP POST-aanvraag, waarbij de activiteitsgegevens die als een JSON-nettolading worden uitgevoerd, binnenkomend op de webserver. Vaak worden ASP.NET projecten gebruikt voor C#-bots en wordt een populair framework zoals Express of restify gebruikt voor JavaScript-Node.js bots.

De adapter, een geïntegreerd onderdeel van de SDK, is de kern van de SDK-runtime. De activiteit wordt uitgevoerd als JSON in de HTTP POST-hoofdtekst. Deze JSON wordt gedeserialiseerd om het activiteitsobject te maken dat vervolgens wordt overgedragen aan de adapter via de procesactiviteitsmethode . Bij het ontvangen van de activiteit maakt de adapter een turncontext en roept de middleware aan.

Zoals hierboven vermeld, biedt de turncontext het mechanisme voor de bot voor het verzenden van uitgaande activiteiten, meestal in reactie op een binnenkomende activiteit. De turncontext biedt reactiemethoden voor het verzenden, bijwerken en verwijderen van activiteiten . Elke responsmethode wordt uitgevoerd in een asynchroon proces.

Belangrijk

De thread die de primaire bot verwerkt, heeft betrekking op het verwijderen van het contextobject wanneer dit is voltooid. Zorg ervoor dat await alle activiteitsoproepen worden aanroepen , zodat de primaire thread op de gegenereerde activiteit wacht voordat de verwerking wordt voltooid en de beurtcontext wordt verwijderd. Als een antwoord (met inbegrip van de handlers) een aanzienlijke hoeveelheid tijd in beslag neemt en probeert te reageren op het contextobject, kan er een contextfout worden verwijderd .

Botsjablonen

U moet het gebruik van de toepassingslaag voor uw app kiezen; Bot Framework bevat echter sjablonen en voorbeelden voor ASP.NET (C#), restify (JavaScript) en aiohttp (Python). De documentatie wordt geschreven, ervan uitgaande dat u een van deze platforms gebruikt, maar de SDK vereist deze niet van u. Zie de quickstart Een bot maken voor instructies over het openen en installeren van de sjablonen.

Een bot is een webtoepassing en sjablonen worden geleverd voor elke taalversie van de SDK. Alle sjablonen bieden een standaardeindpunt-implementatie en -adapter. Elke sjabloon bevat:

• Inrichten van resources
• Een taalspecifieke IMPLEMENTATIE van een HTTP-eindpunt waarmee binnenkomende activiteiten worden gerouteerd naar een adapter.
• Een adapterobject
• Een botobject

Het belangrijkste verschil tussen de verschillende sjabloontypen is in het botobject. De sjablonen zijn:

• Lege bot
  • Bevat een activiteitshandler die een gebruiker in het gesprek verwelkomt door een 'hallo wereld'-bericht te verzenden op de eerste beurt van het gesprek.
• Echobot
  • Maakt gebruik van een activiteitshandler om gebruikers te verwelkomen en gebruikersinvoer weer te geven.
• Kernbot
  • Brengt veel functies van de SDK samen en demonstreert aanbevolen procedures voor een bot.
  • Gebruikt een activiteitshandler om gebruikers te verwelkomen.
  • Maakt gebruik van een onderdeeldialoogvenster en onderliggende dialoogvensters om het gesprek te beheren.
  • In de dialoogvensters worden functies van Language Understanding (LUIS) en QnA Maker gebruikt.

Notitie

Azure AI QnA Maker wordt op 31 maart 2025 buiten gebruik gesteld. Vanaf 1 oktober 2022 kunt u geen nieuwe resources of kennisbanken voor QnA Maker maken. Een nieuwere versie van de vraag- en antwoordmogelijkheid is nu beschikbaar als onderdeel van Azure AI Language.

Aangepaste vraagantwoorden, een functie van Azure AI Language, is de bijgewerkte versie van de QnA Maker-service. Zie Natuurlijke taalbegrip voor meer informatie over vraag- en antwoordondersteuning in de Bot Framework SDK.

Notitie

Language Understanding (LUIS) wordt op 1 oktober 2025 buiten gebruik gesteld. Vanaf 1 april 2023 kunt u geen nieuwe LUIS-resources maken. Er is nu een nieuwere versie van taalkennis beschikbaar als onderdeel van Azure AI Language.

Conversational Language Understanding (CLU), een functie van Azure AI Language, is de bijgewerkte versie van LUIS. Zie Natuurlijke taalkennis voor meer informatie over ondersteuning voor taalkennis in de Bot Framework SDK.

Aanvullende informatie

Botresources beheren

U moet de resources voor uw bot, zoals de app-id en het wachtwoord, en ook informatie voor verbonden services beheren. Wanneer u uw bot implementeert, heeft deze beveiligde toegang tot deze informatie nodig. Om complexiteit te voorkomen, beschrijven de meeste Bot Framework SDK-artikelen niet hoe u deze informatie beheert.

• Zie Bot Framework-beveiligingsrichtlijnen voor algemene beveiligingsinformatie.
• Zie Over Azure Key Vault voor het beheren van sleutels en geheimen in Azure.

Kanaaladapters

Met de SDK kunt u ook kanaaladapters gebruiken, waarbij de adapter zelf ook de taken uitvoert die de Bot Connector Service normaal zou doen voor een kanaal.

De SDK biedt enkele kanaaladapters in sommige talen. Er zijn meer kanaaladapters beschikbaar via de Botkit- en Community-opslagplaatsen. Zie de tabel met kanalen en adapters van de Bot Framework SDK-opslagplaats voor meer informatie.

De REST API voor botconnector

De Bot Framework SDK verpakt en bouwt voort op de REST API van de Bot Connector. Als u meer wilt weten over de onderliggende HTTP-aanvragen die ondersteuning bieden voor de SDK, raadpleegt u de connectorverificatie en de bijbehorende artikelen. De activiteiten die een bot verzendt en ontvangt, voldoen aan het Bot Framework-activiteitsschema.

Volgende stappen

• Zie de beheerstatus voor meer informatie over de rol van status in bots.
• Zie Hoe Microsoft Teams-bots werken om inzicht te hebben in de belangrijkste concepten van het ontwikkelen van bots voor Microsoft Teams