Nozioni di base su Microsoft Bot Framework

  • Articolo

SI APPLICA A: SDK v4

Un bot è un'app con cui gli utenti interagiscono in modo discorsivo usando testo, grafica (come schede o immagini) o parlato. Azure AI servizio Bot è una piattaforma cloud. Ospita i bot e li rende disponibili ai canali, ad esempio Microsoft Teams, Facebook o Slack.

Il servizio Bot Framework, che è un componente del servizio Bot di intelligenza artificiale di Azure, invia informazioni tra l'app connessa al bot dell'utente e il bot. Ogni canale può includere informazioni aggiuntive nelle attività inviate. Prima di creare bot, è importante comprendere in che modo un bot usa oggetti attività per comunicare con gli utenti.

Questo diagramma illustra due tipi di attività, l'aggiornamento della conversazione e il messaggio, che potrebbero essere scambiati quando un utente comunica con un bot echo.

diagramma delle attività

Il servizio Bot Framework invia un aggiornamento della conversazione quando un'entità partecipa alla conversazione. Ad esempio, all'avvio di una conversazione con Bot Framework Emulator, è possibile che vengano visualizzate due attività di aggiornamento della conversazione( una per l'utente che partecipa alla conversazione e una per l'aggiunta al bot). Per distinguere queste attività di aggiornamento della conversazione, controllare chi è incluso nella proprietà aggiunta dei membri dell'attività.

L'attività del messaggio contiene informazioni di conversazione tra le parti. In un esempio di bot Echo, le attività messaggio presentano testo semplice e il canale eseguirà il rendering di questo testo. In alternativa, l'attività messaggio può contenere testo da pronunciare, azioni suggerite o schede da visualizzare.

Suggerimento

Spetta a ogni canale implementare il protocollo bot Framework e come ogni canale lo fa potrebbe essere leggermente diverso. Ad esempio, alcuni canali inviano prima attività di aggiornamento della conversazione e alcune attività di aggiornamento della conversazione dopo l'invio della prima attività di messaggio. Un canale può includere sia il bot che l'utente in un'attività di aggiornamento della conversazione, mentre un altro potrebbe inviare due attività di aggiornamento della conversazione.

In questo esempio il bot ha creato e inviato un'attività messaggio in risposta all'attività di messaggio in entrata che aveva ricevuto. Tuttavia, un bot può rispondere in altri modi a un'attività messaggio ricevuta ed è comune che un bot risponda a un'attività di aggiornamento della conversazione inviando un'attività di messaggio con un messaggio di benvenuto. Per altre informazioni, vedere come accogliere un utente.

The Bot Framework SDK

Bot Framework SDK consente di creare bot che possono essere ospitati nell'servizio Bot di intelligenza artificiale di Azure. Il servizio definisce un'API REST e un protocollo di attività per il modo in cui il bot e i canali o gli utenti possono interagire. L'SDK si basa su questa API REST e fornisce un'astrazione del servizio in modo che sia possibile concentrarsi sulla logica di conversazione. Anche se non è necessario comprendere il servizio REST per l'uso dell'SDK, la comprensione di alcune delle funzionalità può essere utile.

I bot sono app con un'interfaccia di conversazione. Possono essere usati per attività semplici e ripetitive, come la prenotazione di una cena o la raccolta di informazioni sul profilo, e nei sistemi automatizzati che non richiedono più necessariamente l'intervento umano diretto. Gli utenti conversano con un bot usando testo, schede interattive e parlato. Un'interazione con un bot può essere un rapido scambio domanda-risposta oppure una conversazione sofisticata che fornisce l'accesso ai servizi in modo intelligente.

Nota

Il supporto per le funzionalità fornite dall'SDK e dall'API REST varia in base al canale. È possibile testare il bot usando Bot Framework Emulator, ma è anche necessario testare tutte le funzionalità del bot in ogni canale in cui si intende rendere disponibile il bot.

Le interazioni comportano lo scambio di attività, gestite a turno.

Attività

Ogni interazione tra l'utente (o un canale) e il bot viene rappresentato come attività. Lo schema attività di Bot Framework definisce le attività che possono essere scambiate tra un utente o un canale e un bot. Le attività possono rappresentare testo umano o parlato, notifiche da app a app, reazioni ad altri messaggi e così via.

Turni

In una conversazione, le persone parlano spesso una alla volta, a turno. Un bot reagisce in genere all'input dell'utente. In Bot Framework SDK un turno è costituito dall'attività dell'utente che giunge al bot e da qualsiasi attività inviata dal bot all'utente come risposta immediata. È possibile considerare un turno come l'elaborazione associata al bot che riceve una determinata attività.

Ad esempio, un utente potrebbe chiedere a un bot di eseguire un'attività specifica. Il bot potrebbe rispondere con una domanda per ottenere altre informazioni sull'attività, a questo punto termina questo turno. Al turno successivo, il bot riceve un nuovo messaggio dall'utente che potrebbe contenere la risposta alla domanda del bot oppure potrebbe rappresentare una modifica dell'oggetto o una richiesta di ignorare la richiesta iniziale per eseguire l'attività.

Struttura dell'applicazione bot

L'SDK definisce una classe bot che gestisce il motivo di conversazione per l'app bot. Classe bot:

  • Riconosce e interpreta l'input dell'utente.
  • Motivi relativi all'input ed esegue attività pertinenti.
  • Genera risposte sulle operazioni eseguite dal bot o eseguite.

L'SDK definisce anche una classe adapter che gestisce la connettività con i canali. Adattatore:

  • Fornisce un metodo per la gestione delle richieste da e metodi per la generazione di richieste al canale dell'utente.
  • Include una pipeline middleware, che include l'elaborazione dei turni all'esterno del gestore dei turni del bot.
  • Chiama il gestore dei turni del bot e rileva gli errori non altrimenti gestiti nel gestore dei turni.

Inoltre, i bot spesso devono recuperare e archiviare lo stato ogni turno. Lo stato viene gestito tramite classi di archiviazione, stato del bot e funzioni di accesso alle proprietà. L'SDK non fornisce risorse di archiviazione predefinite, ma fornisce astrazioni per l'archiviazione e alcune implementazioni di un livello di archiviazione. L'argomento sulla gestione dello stato descrive queste funzionalità di stato e archiviazione.

Un bot ha elementi di connettività e ragionamento e un'astrazione per lo stato

L'SDK non richiede l'uso di un livello applicazione specifico per inviare e ricevere richieste Web. Bot Framework include modelli ed esempi per ASP.NET (C#), restify (JavaScript) e aiohttp (Python). Tuttavia, è possibile scegliere di usare un livello applicazione diverso per l'app.

Quando si crea un bot usando l'SDK, si fornisce il codice per ricevere il traffico HTTP e inoltrarlo all'adapter. Bot Framework fornisce alcuni modelli ed esempi che è possibile usare per sviluppare bot personalizzati.

Nota

Gli SDK JavaScript, C# e Python di Bot Framework continueranno a essere supportati, ma Java SDK verrà ritirato con il supporto finale a lungo termine che termina a novembre 2023.

I bot esistenti creati con Java SDK continueranno a funzionare.

Per la creazione di nuovi bot, prendere in considerazione l'uso di Power Virtual Agents e leggere la scelta della soluzione chatbot appropriata.

Per altre informazioni, vedere Il futuro della compilazione di bot.

Logica del bot

L'oggetto bot contiene il ragionamento o la logica di conversazione per un turno ed espone un gestore dei turni, ovvero il metodo che può accettare attività in ingresso dall'adattatore bot.

L'SDK offre un paio di paradigmi diversi per la gestione della logica del bot.

  • I gestori di attività forniscono un modello basato su eventi in cui i tipi di attività in ingresso e i sottotipi sono gli eventi. Si consideri un gestore di attività per i bot con interazioni limitate e brevi con l'utente.
    • Usare un gestore attività e implementare i gestori per ogni tipo di attività o sottotipo a cui il bot riconosce e reagisce.
    • Usare un gestore attività di Teams per creare bot in grado di connettersi al canale di Teams. Il canale di Teams richiede che il bot gestisca un comportamento specifico del canale.
  • La libreria dialogs fornisce un modello basato su stato per gestire una conversazione a esecuzione prolungata con l'utente.
    • Usare un gestore attività e un dialogo componente per conversazioni in gran parte sequenziali. Per altre informazioni, vedere informazioni sui dialoghi componenti e a cascata.
  • Implementare la propria classe bot e fornire la propria logica per la gestione di ogni turno. Per un esempio, vedere come creare richieste personalizzate per raccogliere l'input dell'utente.

Il bot adapter

L'adattatore dispone di un metodo di attività del processo per avviare un turno.

  • Accetta il corpo della richiesta (il payload della richiesta, convertito in un'attività) e l'intestazione della richiesta come argomenti.
  • Verifica se l'intestazione di autenticazione è valida.
  • Crea un oggetto contesto per il turno. L'oggetto contesto include informazioni sull'attività.
  • Invia l'oggetto contesto tramite la pipeline middleware .
  • Invia quindi l'oggetto contesto al gestore dei turni dell'oggetto bot.

Anche l'adattatore:

  • Formatta e invia attività di risposta. Queste risposte sono in genere messaggi per l'utente, ma possono includere anche informazioni da utilizzare direttamente dal canale dell'utente.
  • Visualizza altri metodi forniti dall'API REST del bot Connessione or, ad esempio aggiornare il messaggio ed eliminare il messaggio.
  • Intercetta errori o eccezioni non rilevate diversamente per il turno.

Contesto del turno

L'oggetto contesto di turno fornisce informazioni sull'attività come il mittente e il destinatario, il canale e altri dati necessari per elaborare l'attività. Consente anche l'aggiunta di informazioni durante il turno tra vari livelli del bot.

Il contesto di turno è una delle astrazioni più importanti dell'SDK. Non solo esegue l'attività in ingresso a tutti i componenti middleware e la logica dell'applicazione, ma fornisce anche il meccanismo in base al quale i componenti middleware e la logica del bot possono inviare attività in uscita.

Middleware

Il middleware è analogo a qualsiasi altro middleware di messaggistica ed è costituito da un set lineare di componenti che vengono eseguiti in ordine, dando a ognuno la possibilità di operare sull'attività. Lo stadio finale della pipeline middleware è un callback al gestore dei turni sulla classe del bot che l'applicazione ha registrato con il metodo process activity dell'adapter. Il middleware implementa un metodo on turn che l'adapter chiama.

Il gestore dei turni accetta un contesto di turno come argomento, in genere la logica dell'applicazione in esecuzione all'interno della funzione del gestore dei turni elabora il contenuto dell'attività in ingresso e genera una o più attività in risposta, inviando queste attività in uscita usando la funzione di invio dell'attività sul contesto di turno. Se si chiama send activity sul contesto del turno, i componenti middleware verranno richiamati sulle attività in uscita. I componenti middleware sono eseguiti prima e dopo la funzione del gestore dei turni del bot. L'esecuzione è intrinsecamente annidata e, di conseguenza, talvolta definita come una cipolla.

L'argomento middleware descrive il middleware in modo più approfondito.

Stato e archiviazione del bot

Come per altre app Web, un bot è intrinsecamente senza stato. Lo stato all'interno di un bot segue gli stessi paradigmi delle applicazioni Web moderne e Bot Framework SDK fornisce astrazioni di gestione dello stato e livello di archiviazione per semplificare la gestione dello stato.

L'argomento sulla gestione dello stato descrive queste funzionalità di stato e archiviazione.

Endpoint di messaggistica e provisioning

In genere, l'applicazione richiederà un endpoint REST in corrispondenza del quale ricevere messaggi. Sarà anche necessario effettuare il provisioning delle risorse per il bot in base alla piattaforma che si decide di usare.

Seguire la guida introduttiva Creare un bot per creare e testare un semplice bot echo.

Dettagli HTTP

Le attività arrivano al bot dal servizio Bot Framework tramite una richiesta HTTP POST. Il bot risponde alla richiesta POST in arrivo con un codice di stato HTTP 200. Le attività inviate dal bot al canale vengono trasmesse su una richiesta HTTP POST separata al servizio Bot Framework, confermata a sua volta con un codice di stato HTTP 200.

Il protocollo non specifica l'ordine in cui vengono effettuate queste richieste POST e i relativi riconoscimenti. Per adattarsi tuttavia ai framework di servizio HTTP comuni, queste richieste sono generalmente annidate, ovvero la richiesta HTTP in uscita viene eseguita dal bot nell'ambito della richiesta HTTP in entrata. Questo modello è illustrato nel diagramma precedente. Data la presenza di due distinte connessioni HTTP consecutive, il modello di sicurezza deve prevedere entrambe.

Nota

Il bot ha 15 secondi per confermare la chiamata con stato 200 nella maggior parte dei canali. Se il bot non risponde entro 15 secondi, si verifica un errore GatewayTimeout HTTP (504).

Flusso di elaborazione dell'attività

Esaminiamo ora il diagramma sequenza precedente con lo stato attivo sull'arrivo di un'attività di messaggio.

Diagramma sequenza che illustra come un'attività viene elaborata da un bot.

Nell'esempio precedente, il bot rispondeva all'attività messaggio con un'altra attività messaggio contenente lo stesso messaggio di testo. L'elaborazione inizia con la richiesta HTTP POST, con le informazioni sull'attività trasmesse come payload JSON fino al server Web. Spesso, i progetti ASP.NET vengono usati per i bot C# e un framework diffuso, ad esempio Express o restify, viene usato per i bot javaScript Node.js.

L'adapter, un componente integrato dell'SDK, è il componente di base del runtime SDK. L'attività viene eseguita come codice JSON nel corpo della richiesta HTTP POST. Questo codice JSON viene deserializzato per creare l'oggetto attività che viene quindi passato all'adattatore tramite il relativo metodo di attività del processo. Quando riceve l'attività, l'adapter crea un contesto di turno e chiama il middleware.

Come accennato in precedenza, il contesto di turno consente al bot di inviare attività in uscita, il più delle volte in risposta a un'attività in ingresso. Il contesto dei turni fornisce metodi di risposta alle attività di invio, aggiornamento ed eliminazione. Ogni metodo di risposta viene eseguito in un processo asincrono.

Importante

Il thread che gestisce il turno del bot primario gestisce l'eliminazione dell'oggetto di contesto al termine dell'operazione. Assicurarsi di usare await per le chiamate di attività in modo che il thread principale attenda l'attività generata prima di completare la sua elaborazione ed eliminare il contesto di turno. Se una risposta, compresi i relativi gestori, richiede un tempo significativo e prova ad agire su un oggetto di contesto, può ottenere un errore di contesto eliminato.

Modelli di bot

È necessario scegliere l'uso del livello applicazione per l'app; Bot Framework include tuttavia modelli ed esempi per ASP.NET (C#), restify (JavaScript) e aiohttp (Python). La documentazione viene scritta presupponendo che si usi una di queste piattaforme, ma l'SDK non ne richiede l'uso. Vedere la guida introduttiva Creare un bot per istruzioni su come accedere e installare i modelli.

Un bot è un'applicazione Web e vengono forniti modelli per ogni versione del linguaggio dell'SDK. Tutti i modelli forniscono un'implementazione dell'endpoint e un adattatore predefiniti. Ogni modello include:

  • Provisioning delle risorse
  • Implementazione dell'endpoint HTTP specifica del linguaggio che indirizza le attività in ingresso a un adattatore.
  • Oggetto adapter
  • Oggetto bot

La differenza principale tra i diversi tipi di modello è nell'oggetto bot. I modelli sono:

  • Bot vuoto
    • Include un gestore attività che accoglie un utente nella conversazione inviando un messaggio "hello world" al primo turno della conversazione.
  • Bot Echo
    • Usa un gestore attività per accogliere gli utenti e ripetere l'input dell'utente.
  • Bot principale
    • Riunisce molte funzionalità dell'SDK e illustra le procedure consigliate per un bot.
    • Usa un gestore attività per accogliere gli utenti.
    • Usa un dialogo componente e i dialoghi figlio per gestire la conversazione.
    • Le finestre di dialogo usano le funzionalità LUIS (Language Understanding) e QnA Maker.

Nota

Azure AI QnA Maker verrà ritirato il 31 marzo 2025. A partire dal 1° ottobre 2022, non potrai creare nuove risorse o Knowledge Base di QnA Maker. Una versione più recente della funzionalità di domande e risposte è ora disponibile come parte del linguaggio di intelligenza artificiale di Azure.

La risposta alle domande personalizzate, una funzionalità del linguaggio di intelligenza artificiale di Azure, è la versione aggiornata del servizio QnA Maker. Per altre informazioni sul supporto di domande e risposte in Bot Framework SDK, vedere Comprensione del linguaggio naturale.

Nota

Language Understanding (LUIS) verrà ritirato il 1° ottobre 2025. A partire dal 1° aprile 2023, non sarà possibile creare nuove risorse LUIS. Una versione più recente di Language Understanding è ora disponibile come parte del linguaggio di intelligenza artificiale di Azure.

CLU (Conversational Language Understanding), una funzionalità del linguaggio di intelligenza artificiale di Azure, è la versione aggiornata di LUIS. Per altre informazioni sul supporto per la comprensione del linguaggio in Bot Framework SDK, vedere Comprensione del linguaggio naturale.

Informazioni aggiuntive

Gestione delle risorse del bot

Sarà necessario gestire le risorse per il bot, ad esempio l'ID app e la password, nonché le informazioni per tutti i servizi connessi. Quando si distribuisce il bot, sarà necessario un accesso sicuro a queste informazioni. Per evitare complessità, la maggior parte degli articoli di Bot Framework SDK non descrive come gestire queste informazioni.

Adattatori di canale

L'SDK consente anche di usare schede di canale, in cui l'adattatore stesso esegue anche le attività normalmente eseguite dal servizio Bot Connessione or per un canale.

L'SDK fornisce alcuni adattatori di canale in alcune lingue. Sono disponibili più schede di canale tramite i repository Botkit e Community. Per altre informazioni, vedere la tabella dei canali e degli adattatori del repository bot Framework SDK.

API REST del bot Connessione or

Bot Framework SDK esegue il wrapping e si basa sull'API REST bot Connessione or. Per comprendere le richieste HTTP sottostanti che supportano l'SDK, vedere gli articoli relativi all'autenticazione Connessione or e associati. Le attività inviate e ricevute da un bot sono conformi allo schema dell'attività di Bot Framework.

Passaggi successivi