Grunderna i Microsoft Bot Framework

GÄLLER FÖR: SDK v4

En robot är en app som användarna interagerar med på ett konversationssätt med hjälp av text, grafik (till exempel kort eller bilder) eller tal. Azure AI Bot Service är en molnplattform. Den är värd för robotar och gör dem tillgängliga för kanaler som Microsoft Teams, Facebook eller Slack.

Bot Framework Service, som är en komponent i Azure AI Bot Service, skickar information mellan användarens robotanslutna app och roboten. Varje kanal kan innehålla ytterligare information i de aktiviteter som de skickar. Innan du skapar robotar är det viktigt att förstå hur en robot använder aktivitetsobjekt för att kommunicera med sina användare.

Det här diagrammet visar två aktivitetstyper, konversationsuppdatering och meddelande, som kan utbytas när en användare kommunicerar med en ekorobot.

Bot Framework Service skickar en konversationsuppdatering när en part ansluter till konversationen. När du till exempel startar en konversation med Bot Framework-emulatorn kan du se två konversationsuppdateringsaktiviteter (en för användaren som ansluter till konversationen och en för robotanslutningen). Om du vill särskilja dessa konversationsuppdateringsaktiviteter kontrollerar du vem som ingår i aktivitetens egenskap som lagts till av medlemmar.

Meddelandeaktiviteten innehåller konversationsinformation mellan parterna. I ett exempel på ekorobotar innehåller meddelandeaktiviteterna enkel text och kanalen återger den här texten. Alternativt kan meddelandeaktiviteten innehålla text som ska talas, föreslagna åtgärder eller kort som ska visas.

Dricks

Det är upp till varje kanal att implementera Bot Framework-protokollet och hur varje kanal gör det kan vara lite annorlunda. Vissa kanaler skickar till exempel konversationsuppdateringsaktiviteter först och vissa skickar konversationsuppdateringsaktiviteter när de har skickat den första meddelandeaktiviteten. En kanal kan innehålla både roboten och användaren i en konversationsuppdateringsaktivitet, medan en annan kan skicka två konversationsuppdateringsaktiviteter.

I det här exemplet skapade och skickade roboten en meddelandeaktivitet som svar på den inkommande meddelandeaktivitet som den hade tagit emot. En robot kan dock svara på andra sätt på en mottagen meddelandeaktivitet, och det är vanligt att en robot svarar på en konversationsuppdateringsaktivitet genom att skicka en meddelandeaktivitet med ett välkomstmeddelande. Mer information finns i hur du välkomnar en användare.

The Bot Framework SDK

Med Bot Framework SDK kan du skapa robotar som kan finnas i Azure AI Bot Service. Tjänsten definierar ett REST API och ett aktivitetsprotokoll för hur din robot och dina kanaler eller användare kan interagera. SDK bygger på det här REST-API:et och tillhandahåller en abstraktion av tjänsten så att du kan fokusera på konversationslogiken. Även om du inte behöver förstå REST-tjänsten för att använda SDK kan det vara till hjälp att förstå vissa av dess funktioner.

Robotar är appar som har ett konversationsgränssnitt. De kan användas för att flytta enkla, repetitiva uppgifter, till exempel att ta en middagsreservation eller samla in profilinformation, på automatiserade system som kanske inte längre kräver direkt mänsklig inblandning. Användarna kommunicerar med roboten med hjälp av text, interaktiva kort och tal. En robotinteraktion kan vara en snabb fråga med svar, eller ett avancerat samtal som på ett intelligent sätt ger åtkomst till tjänster.

Kommentar

Stöd för funktioner som tillhandahålls av SDK och REST API varierar beroende på kanal. Du kan testa din robot med hjälp av Bot Framework-emulatorn, men du bör också testa alla funktioner i roboten på varje kanal där du tänker göra roboten tillgänglig.

Interaktioner omfattar utbyte av aktiviteter, som hanteras i tur och ordning.

Aktiviteter

Varje interaktion mellan användaren (eller en kanal) och roboten representeras som en aktivitet. Bot Framework-aktivitetsschemat definierar de aktiviteter som kan utbytas mellan en användare eller kanal och en robot. Aktiviteter kan representera mänsklig text eller tal, app-till-app-meddelanden, reaktioner på andra meddelanden och så vidare.

Vänder

I ett samtal talar människor ofta en i taget och turas om att tala. Med en robot reagerar den vanligtvis på användarindata. I Bot Framework SDK består en tur av användarens inkommande aktivitet till roboten och alla aktiviteter som roboten skickar tillbaka till användaren som ett omedelbart svar. Du kan se en tur som den bearbetning som är associerad med att roboten tar emot en viss aktivitet.

En användare kan till exempel be en robot att utföra en viss uppgift. Roboten kan svara med en fråga för att få mer information om uppgiften, då den här svängen slutar. I nästa tur får roboten ett nytt meddelande från användaren som kan innehålla svaret på robotens fråga, eller så kan det representera ett ämnesbyte eller en begäran om att ignorera den första begäran om att utföra uppgiften.

Robotprogramstruktur

SDK definierar en robotklass som hanterar konversationsskälet för robotappen. Robotklassen:

• Identifierar och tolkar användarens indata.
• Orsaker till indata och utför relevanta uppgifter.
• Genererar svar om vad roboten gör eller har gjort.

SDK definierar också en adapterklass som hanterar anslutningen till kanalerna. Adaptern:

• Tillhandahåller en metod för att hantera begäranden från och metoder för att generera begäranden till användarens kanal.
• Innehåller en pipeline för mellanprogram, som omfattar turbearbetning utanför robotens turhanterare.
• Anropar robotens turhanterare och fångar fel som annars inte hanteras i turhanteraren.

Dessutom behöver robotar ofta hämta och lagra tillstånd varje tur. Tillståndet hanteras via klasser för lagring, robottillstånd och egenskapsåtkomst . SDK:t tillhandahåller inte inbyggd lagring, men tillhandahåller abstraktioner för lagring och några implementeringar av ett lagringslager. Avsnittet hantera tillstånd beskriver dessa tillstånds- och lagringsfunktioner.

SDK:t kräver inte att du använder ett specifikt programlager för att skicka och ta emot webbbegäranden. Bot Framework har mallar och exempel för ASP.NET (C#), restify (JavaScript) och aiohttp (Python). Du kan dock välja att använda ett annat programlager för din app.

När du skapar en robot med hjälp av SDK anger du koden för att ta emot HTTP-trafiken och vidarebefordra den till adaptern. Bot Framework innehåller några mallar och exempel som du kan använda för att utveckla dina egna robotar.

Kommentar

Bot Framework JavaScript-, C#- och Python-SDK:erna fortsätter att stödjas, men Java SDK dras tillbaka med slutligt långsiktigt stöd som slutar i november 2023.

Befintliga robotar som skapats med Java SDK fortsätter att fungera.

Om du vill skapa en ny robot kan du använda Microsoft Copilot Studio och läsa om hur du väljer rätt copilot-lösning.

Mer information finns i Framtiden för robotbygge.

Robotlogik

Robotobjektet innehåller konversationsskäl eller logik för en tur och exponerar en turhanterare, vilket är den metod som kan acceptera inkommande aktiviteter från robotkortet.

SDK:n innehåller ett par olika paradigm för att hantera robotlogiken.

• Aktivitetshanterare tillhandahåller en händelsedriven modell där inkommande aktivitetstyper och undertyper är händelserna. Överväg en aktivitetshanterare för robotar som har begränsade, korta interaktioner med användaren.
  • Använd en aktivitetshanterare och implementera hanterare för varje aktivitetstyp eller undertyp som roboten känner igen och reagerar på.
  • Använd en Teams-aktivitetshanterare för att skapa robotar som kan ansluta till Teams-kanalen. (Teams-kanalen kräver att roboten hanterar vissa kanalspecifika beteenden.)
• Dialogrutebiblioteket innehåller en tillståndsbaserad modell för att hantera en långvarig konversation med användaren.
  • Använd en aktivitetshanterare och en komponentdialogruta för i stort sett sekventiella konversationer. Mer information finns i om dialogrutor för komponenter och vattenfall.
• Implementera din egen robotklass och ange din egen logik för att hantera varje tur. Ett exempel finns i hur du skapar egna uppmaningar för att samla in användarindata.

Robotadaptern

Adaptern har en processaktivitetsmetod för att starta en sväng.

• Det tar begärandetexten (nyttolasten för begäran, översatt till en aktivitet) och begärandehuvudet som argument.
• Den kontrollerar om autentiseringshuvudet är giltigt.
• Det skapar ett kontextobjekt för svängen. Kontextobjektet innehåller information om aktiviteten.
• Det skickar kontextobjektet via dess pipeline för mellanprogram .
• Den skickar sedan kontextobjektet till robotobjektets turhanterare.

Adaptern:

• Formaterar och skickar svarsaktiviteter. Dessa svar är vanligtvis meddelanden för användaren, men kan även innehålla information som ska användas av användarens kanal direkt.
• Visar andra metoder som tillhandahålls av BOT Connector REST API, till exempel uppdateringsmeddelande och borttagningsmeddelande.
• Fångar fel eller undantag som inte på annat sätt fångas för svängen.

Turkontexten

Turn-kontextobjektet innehåller information om aktiviteten, till exempel avsändaren och mottagaren, kanalen och andra data som behövs för att bearbeta aktiviteten. Det gör det också möjligt att lägga till information under omsvängningen över olika lager i roboten.

Turkontexten är en av de viktigaste abstraktionerna i SDK:et. Den utför inte bara den inkommande aktiviteten till alla mellanprogramskomponenter och programlogik, utan ger också den mekanism där mellanprogramkomponenterna och robotlogik kan skicka utgående aktiviteter.

Mellanprogram

Mellanprogram liknar alla andra mellanprogram för meddelanden, som består av en linjär uppsättning komponenter som var och en körs i ordning, vilket ger var och en en en chans att arbeta med aktiviteten. Det sista steget i pipelinen för mellanprogram är ett återanrop till turhanteraren på robotklassen som programmet har registrerat med adapterns processaktivitetsmetod . Mellanprogram implementerar en påslagningsmetod som adaptern anropar.

Turhanteraren tar en turkontext som argument, vanligtvis bearbetar programlogik som körs i funktionen turhanterar den inkommande aktivitetens innehåll och genererar en eller flera aktiviteter som svar, vilket skickar dessa utgående aktiviteter med funktionen skicka aktivitet i turkontexten. Om du anropar sändningsaktiviteten i turn-kontexten anropas mellanprogramskomponenterna på de utgående aktiviteterna. Mellanprogramkomponenter körs före och efter robotens turhanterarfunktion. Körningen är till sin natur kapslad och kallas därför ibland för att vara som en lök.

Avsnittet mellanprogram beskriver mellanprogram på större djup.

Robottillstånd och lagring

Precis som med andra webbappar är en robot i sig tillståndslös. Tillståndet i en robot följer samma paradigm som moderna webbprogram, och Bot Framework SDK tillhandahåller abstraktioner för lagringslager och tillståndshantering för att göra det enklare att hantera tillstånd.

Avsnittet hantera tillstånd beskriver dessa tillstånds- och lagringsfunktioner.

Slutpunkt för meddelanden och etablering

Normalt behöver ditt program en REST-slutpunkt där meddelanden ska tas emot. Den måste också etablera resurser för din robot i enlighet med den plattform som du bestämmer dig för att använda.

Följ snabbstarten Skapa en robot för att skapa och testa en enkel ekorobot.

HTTP-information

Aktiviteter anländer till roboten från Bot Framework-tjänsten via en HTTP POST-begäran. Roboten svarar på den inkommande POST-begäran med en HTTP-statuskod på 200. Aktiviteter som skickas från roboten till kanalen skickas på ett separat HTTP POST till Bot Framework-tjänsten. Detta bekräftas i sin tur med en HTTP-statuskod på 200.

Protokollet anger inte i vilken ordning postbegäranden och deras bekräftelser görs. Men för att passa med vanliga HTTP-tjänstramverk är dessa begäranden vanligtvis kapslade, vilket innebär att den utgående HTTP-begäran görs från roboten inom omfånget för den inkommande HTTP-begäran. Det här mönstret illustreras i det tidigare diagrammet. Eftersom det finns två distinkta HTTP-anslutningar bakåt måste säkerhetsmodellen tillhandahålla båda.

Kommentar

Roboten har 15 sekunder på sig att bekräfta samtalet med statusen 200 i de flesta kanaler. Om roboten inte svarar inom 15 sekunder inträffar ett HTTP GatewayTimeout-fel (504).

Aktivitetsbearbetningsstacken

Nu ska vi gå in i föregående sekvensdiagram med fokus på ankomsten av en meddelandeaktivitet.

Kanalen skickar användarens meddelande till Azure AI Bot Service och tjänsten vidarebefordrar meddelandet till robotens meddelandeslutpunkt. Robotens svar skickas till användaren inom omfånget för svängen.

I exemplet ovan svarade roboten på meddelandeaktiviteten med en annan meddelandeaktivitet som innehåller samma textmeddelande. Bearbetningen börjar med HTTP POST-begäran, med aktivitetsinformationen som en JSON-nyttolast som anländer till webbservern. Ofta används ASP.NET projekt för C#-robotar, och ett populärt ramverk som Express eller restify används för JavaScript-Node.js robotar.

Adaptern, en integrerad komponent i SDK:et, är kärnan i SDK-körningen. Aktiviteten utförs som JSON i HTTP POST-brödtexten. Denna JSON deserialiseras för att skapa aktivitetsobjektet som sedan överlämnas till adaptern via dess processaktivitetsmetod . När du tar emot aktiviteten skapar adaptern en turkontext och anropar mellanprogrammet.

Som nämnts ovan tillhandahåller turkontexten mekanismen för roboten att skicka utgående aktiviteter, oftast som svar på en inkommande aktivitet. Turkontexten innehåller metoder för att skicka, uppdatera och ta bort aktivitetssvar . Varje svarsmetod körs i en asynkron process.

Viktigt!

Tråden som hanterar den primära robotens tur hanterar disponering av kontextobjektet när det är klart. Var noga med alla aktivitetsanrop så att await den primära tråden väntar på den genererade aktiviteten innan den slutför bearbetningen och tar bort turkontexten. Om ett svar (inklusive dess hanterare) tar längre tid och försöker agera på kontextobjektet kan ett kontextfel tas bort .

Robotmallar

Du måste välja vilken programnivå som ska användas för din app. Bot Framework har dock mallar och exempel för ASP.NET (C#), restify (JavaScript) och aiohttp (Python). Dokumentationen är skriven förutsatt att du använder någon av dessa plattformar, men SDK:t kräver inte det av dig. Se snabbstarten Skapa en robot för instruktioner om hur du kommer åt och installerar mallarna.

En robot är ett webbprogram och mallar tillhandahålls för varje språkversion av SDK:t. Alla mallar tillhandahåller en standardimplementering och ett nätverkskort för slutpunkter. Varje mall innehåller:

• Resursetablering
• En språkspecifik HTTP-slutpunktsimplementering som dirigerar inkommande aktiviteter till ett kort.
• Ett adapterobjekt
• Ett robotobjekt

Den största skillnaden mellan de olika malltyperna finns i robotobjektet. Mallarna är:

• Tom robot
  • Innehåller en aktivitetshanterare som välkomnar en användare till konversationen genom att skicka ett "hello world"-meddelande vid konversationens första tur.
• Ekorobot
  • Använder en aktivitetshanterare för att välkomna användare och upprepa användarindata.
• Kärnrobot
  • Samlar många funktioner i SDK:t och visar metodtips för en robot.
  • Använder en aktivitetshanterare för att välkomna användare.
  • Använder en komponentdialogruta och underordnade dialogrutor för att hantera konversationen.
  • Dialogrutorna använder funktionerna Language Understanding (LUIS) och QnA Maker.

Kommentar

Azure AI QnA Maker dras tillbaka den 31 mars 2025. Från och med den 1 oktober 2022 kan du inte skapa nya QnA Maker resurser eller kunskapsbaser för 2022. En nyare version av fråge- och svarsfunktionen är nu tillgänglig som en del av Azure AI Language.

Svar på anpassade frågor, en funktion i Azure AI Language, är den uppdaterade versionen av QnA Maker-tjänsten. Mer information om stöd för frågor och svar i Bot Framework SDK finns i Förstå naturligt språk.

Kommentar

Language Understanding (LUIS) dras tillbaka den 1 oktober 2025. Från och med den 1 april 2023 kan du inte skapa nya LUIS-resurser. En nyare version av språktolkning är nu tillgänglig som en del av Azure AI Language.

Conversational Language Understanding (CLU), en funktion i Azure AI Language, är den uppdaterade versionen av LUIS. Mer information om stöd för språktolkning i Bot Framework SDK finns i Förstå naturligt språk.

Ytterligare information

Hantera robotresurser

Du måste hantera resurserna för din robot, till exempel dess app-ID och lösenord, samt information för alla anslutna tjänster. När du distribuerar roboten behöver den säker åtkomst till den här informationen. För att undvika komplexitet beskriver de flesta av Bot Framework SDK-artiklarna inte hur du hanterar den här informationen.

• Allmän säkerhetsinformation finns i Bot Framework-säkerhetsriktlinjer.
• Information om hur du hanterar nycklar och hemligheter i Azure finns i Om Azure Key Vault.

Kanaladapter

Med SDK kan du också använda kanalkort, där själva adaptern dessutom utför de uppgifter som Bot Connector Service normalt skulle göra för en kanal.

SDK:et innehåller några kanalkort på vissa språk. Fler kanalkort är tillgängliga via Botkit- och Community-lagringsplatserna. Mer information finns i Bot Framework SDK-lagringsplatsens tabell med kanaler och kort.

The Bot Connector REST API

Bot Framework SDK omsluter och bygger på BOT Connector REST API. Om du vill förstå de underliggande HTTP-begäranden som stöder SDK kan du läsa artiklarna om anslutningsprogramautentisering och tillhörande artiklar. De aktiviteter som en robot skickar och tar emot överensstämmer med Bot Framework-aktivitetsschemat.

Nästa steg

• Information om tillståndets roll i robotar finns i Hantera tillstånd.
• Information om viktiga begrepp för att utveckla robotar för Microsoft Teams finns i Så här fungerar Microsoft Teams-robotar