Creare un bot con Bot Framework SDK

SI APPLICA A: SDK v4

Questo articolo descrive come creare il primo bot con Bot Framework SDK per C#, Java, JavaScript o Python e come testare il bot con Bot Framework Emulator.

La creazione del primo bot non richiede una sottoscrizione di Azure o una risorsa servizio Bot di intelligenza artificiale di Azure. Questa guida introduttiva è incentrata sulla creazione del primo bot in locale. Per informazioni su come creare un bot in Azure, vedere Creare una risorsa di Azure Bot.

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, è consigliabile usare Microsoft Copilot Studio e leggere le informazioni sulla scelta della soluzione copilota appropriata.

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

Prerequisiti

C#

• .NET 6.0 SDK
• Bot Framework Emulator
• Conoscenza della programmazione ASP.NET Core e asincrona in C#

Modelli C#

Negli esempi di bot correnti si usano modelli .NET Core 3.1.

Visual Studio

• Visual Studio 2022 o versione successiva
• Modelli di Bot Framework v4 SDK per Visual Studio

Per aggiungere i modelli di bot a Visual Studio, scaricare e installare il file Bot Framework v4 SDK Templates for Visual Studio VSIX.

Nota

È possibile installare i modelli da Visual Studio.

1. Nel menu selezionare Estensioni e quindi Gestisci estensioni.
2. Nella finestra di dialogo Gestisci estensioni cercare e installare i modelli di Bot Framework v4 SDK per Visual Studio.

Per informazioni sulla distribuzione di bot .NET in Azure, vedere Come effettuare il provisioning e pubblicare un bot.

VS Code/INTERFACCIA della riga di comando

I modelli di .NET Core consentono di creare rapidamente nuovi bot di intelligenza artificiale conversazionale usando Bot Framework v4. A partire da maggio 2020, questi modelli e il codice generato richiedono .NET Core 3.1 o versione successiva.

Per installare i modelli di Bot Framework:

1. Aprire una finestra della console.

2. Scaricare e installare .NET Core SDK versione 3.1 o successiva.

3. È possibile usare questo comando per determinare le versioni dell'interfaccia della riga di comando di .NET Core installate.

   dotnet --version
   

4. Installare i tre modelli C# di Bot Framework: echo, core e modelli di bot vuoti.

   dotnet new -i Microsoft.Bot.Framework.CSharp.EchoBot
   dotnet new -i Microsoft.Bot.Framework.CSharp.CoreBot
   dotnet new -i Microsoft.Bot.Framework.CSharp.EmptyBot
   

5. Verificare che i modelli siano stati installati correttamente.

   dotnet new --list
   

Nota

I passaggi precedenti installano tutti e tre i modelli di Bot Framework. Non è necessario installare tutti i modelli e installare solo quelli che verranno usati. Questo articolo usa il modello echo bot .

Java

• Java 1.8 o versione successiva
• Bot Framework Emulator
• Visual Studio Code o l'IDE preferito, se si vuole modificare il codice del bot.
• Installare Maven
• Installare node.js versione 12.10 o successiva.
• Un account Azure se si vuole eseguire la distribuzione in Azure.

Modelli Java

Usare il generatore Yeoman per creare rapidamente un bot di intelligenza artificiale conversazionale usando le funzionalità di intelligenza artificiale di base in Bot Framework v4. Per altre informazioni, vedere yeoman.io.

Il generatore supporta tre diverse opzioni di modello, come illustrato di seguito.

Modello	Descrizione
Echo Bot	Un buon modello se vuoi un po ' più di "Hello World!", ma non molto di più. Questo modello gestisce le nozioni di base dell'invio di messaggi a un bot e l'elaborazione dei messaggi da parte del bot ripetendoli all'utente. Questo modello genera un bot che semplicemente "ripete" all'utente qualsiasi elemento che l'utente dice al bot.
Empty Bot	Un modello valido se si ha familiarità con Bot Framework v4 e si vuole semplicemente un progetto di base. È anche una buona opzione se si vuole prendere il codice di esempio dalla documentazione e incollarlo in un bot minimo per imparare.
Core Bot	Un modello valido se si vogliono creare bot avanzati, perché usa dialoghi a più turni e LUIS di Intelligenza artificiale di Azure per implementare la comprensione del linguaggio. Questo modello crea un bot in grado di estrarre luoghi e date per prenotare un volo.

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.

Installare Yeoman

1. Assicurarsi di aver installato node.js versione 12.10 o successiva.

2. Installare npm più recente.

   npm install -g npm
   

3. Installare Yeoman. Assicurarsi di installare a livello globale.

   npm install -g yo
   

4. Installare generator-botbuilder-java. Assicurarsi di installare a livello globale.

   npm install -g generator-botbuilder-java
   

5. Verificare che Yeoman e generator-botbuilder-java siano stati installati correttamente.

   yo botbuilder-java --help
   

JavaScript

• Node.js
• Bot Framework Emulator
• Conoscenza di restify e programmazione asincrona in JavaScript
• Visual Studio Code o l'IDE preferito, se si vuole modificare il codice del bot.

Modelli JavaScript e TypeScript

Per installare Yeoman e il generatore Yeoman per Bot Framework v4:

1. Aprire un terminale o un prompt dei comandi con privilegi elevati.

2. Passare alla directory relativa ai bot JavaScript. Crearne una se non esiste già.

   mkdir myJsBots
   cd myJsBots
   

3. Assicurarsi di avere le versioni più recenti di npm e Yeoman.

   npm install -g npm
   npm install -g yo
   

4. Installare il generatore Yeoman. Yeoman è uno strumento per la creazione di applicazioni. Per altre informazioni, vedere yeoman.io.

   npm install -g generator-botbuilder
   

   Nota

   L'installazione degli strumenti di compilazione di Windows elencati di seguito è necessaria solo se si usa Windows come sistema operativo di sviluppo. Per alcune installazioni, il passaggio di installazione per restify restituisce un errore correlato a node-gyp. In tale circostanza si può provare a eseguire questo comando con autorizzazioni elevate: Questa chiamata può anche bloccarsi senza uscire se Python è già installato nel sistema:

   Eseguire questo comando solo se si usa Windows.

   npm install -g windows-build-tools
   

Python

• Python 3.8.3
• Bot Framework Emulator
• Conoscenza della programmazione asincrona in Python

Creare e abilitare un ambiente virtuale

Un ambiente virtuale è una combinazione di uno specifico interprete Python e librerie diverse dalle impostazioni globali. L'ambiente virtuale è specifico di un progetto e viene mantenuto nella cartella del progetto. Un vantaggio dell'uso di un ambiente virtuale è che quando si sviluppa un progetto nel tempo, l'ambiente virtuale riflette sempre le dipendenze esatte del progetto. Per altre informazioni sugli ambienti virtuali, vedere Creazione di ambienti virtuali.

Passare alla directory in cui si vuole creare il bot. Eseguire quindi i comandi seguenti per la piattaforma preferita. Dopo aver attivato l'ambiente virtuale, la riga di comando o il terminale devono essere preceduti da (venv). In questo modo è possibile sapere che l'ambiente virtuale è attivo. È possibile disattivare l'ambiente virtuale in qualsiasi momento digitando : deactivate.

macOS/Linux

python3 -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate.bat

Modelli Python

Installare i pacchetti necessari eseguendo i comandi seguenti pip install :

pip install botbuilder-core
pip install asyncio
pip install aiohttp
pip install cookiecutter==1.7.0

Importante

Se si usa una versione a 32 bit di Python, assicurarsi di eseguire pip install cryptography==2.8anche .

Creare un bot

C#

Visual Studio

In Visual Studio creare un nuovo progetto bot e usare il modello Echo Bot (Bot Framework v4 - .NET Core 3.1). Per visualizzare solo i modelli di bot, scegliere il tipo di progetto Bot di intelligenza artificiale.

VS Code

Assicurarsi che sia installato .NET Core 3.1 o versione successiva.

1. In Visual Studio Code, aprire una nuova finestra del terminale.

2. Passare alla directory in cui si vuole creare il progetto bot.

3. Creare un nuovo progetto echo bot usando il comando seguente. Sostituire <your-bot-name> con il nome da usare per il progetto bot.

   dotnet new echobot -n <your-bot-name>
   

CLI

1. Aprire una nuova finestra del terminale.

2. Passare alla directory in cui si vuole creare il progetto bot.

3. Creare un nuovo progetto echo bot usando il comando seguente. Sostituire <your-bot-name> con il nome da usare per il progetto bot.

   dotnet new echobot -n <your-bot-name>
   

Grazie al modello, il progetto contiene tutto il codice necessario per creare il bot in questa guida introduttiva. Non è necessario altro codice per testare il bot.

È stato creato un bot echo che si è verificato un problema

Java

Eseguire il comando seguente per creare un bot echo dai modelli. Il comando usa le opzioni predefinite per i relativi parametri.

yo botbuilder-java -T "echo"

Yeoman richiede alcune informazioni per la creazione del bot. Per questa esercitazione usare i valori predefiniti.

? What's the name of your bot? (echo)
? What's the fully qualified package name of your bot? (com.mycompany.echo)
? Which template would you like to start with? (Use arrow keys) Select "Echo Bot"
? Looking good.  Shall I go ahead and create your new bot? (Y/n) Enter "y"

Il generatore supporta molte opzioni della riga di comando che è possibile usare per modificare le impostazioni predefinite del generatore o per effettuare il pre-seeding di un prompt. Le opzioni fanno distinzione tra maiuscole e minuscole.

Opzione di riga di comando	Descrizione
--help, -h	Elencare il testo della Guida per tutte le opzioni della riga di comando supportate
--botName, -N	Nome assegnato al progetto bot
--packageName, -P	Nome del pacchetto Java da usare per il bot
--template, -T	Modello utilizzato per generare il progetto. Le opzioni sono echo, empty, core. Per altre informazioni sui diversi modelli, vedere il repository GitHub per il linguaggio, C#, JavaScript, Python o Java.
--noprompt	Il generatore non richiederà conferma prima di creare un nuovo bot. Qualsiasi opzione relativa ai requisiti non passata nella riga di comando userà un valore predefinito ragionevole. Questa opzione è progettata per abilitare la generazione automatica di bot a scopo di test.

Grazie al modello, il progetto contiene tutto il codice necessario per creare il bot in questa guida introduttiva. Non è necessario alcun altro codice per testare il bot.

È stato creato un bot echo che si è verificato un problema

JavaScript

1. Usare il generatore per creare un bot echo.

   yo botbuilder
   

   Yeoman richiede alcune informazioni per la creazione del bot. Per questa esercitazione usare i valori predefiniti.

   ? What's the name of your bot? my-chat-bot
   ? What will your bot do? Demonstrate the core capabilities of the Microsoft Bot Framework
   ? What programming language do you want to use? JavaScript
   ? Which template would you like to start with? Echo Bot - https://aka.ms/bot-template-echo
   ? Looking good.  Shall I go ahead and create your new bot? Yes
   

Grazie al modello, il progetto contiene tutto il codice necessario per creare il bot in questa guida introduttiva. Non è necessario alcun altro codice per testare il bot.

È stato creato un bot echo che si è verificato un problema

Python

1. Dalla directory di lavoro eseguire il comando seguente per scaricare il modello echo bot e le relative dipendenze:

   cookiecutter https://github.com/microsoft/BotBuilder-Samples/releases/download/Templates/echo.zip
   

2. Verrà richiesto di assegnare al bot un nome e una descrizione. Immettere i valori seguenti:

   • bot_name: echo_bot
   • bot_description: bot che restituisce la risposta dell'utente.

   

È stato creato un bot echo che si è verificato un problema

Avviare il bot

C#

Visual Studio

In Visual Studio:

1. Aprire il progetto bot.
2. Eseguire il progetto senza eseguire il debug.
3. Visual Studio compila l'applicazione, la distribuisce in localhost e avvia il Web browser per visualizzare la pagina dell'applicazione default.htm .

A questo punto, il bot è in esecuzione in locale sulla porta 3978.

VS Code

In Visual Studio Code:

1. Aprire la cartella del progetto bot.

   Se viene richiesto di selezionare un progetto, selezionare quello per il bot creato.

2. Dal menu selezionare Esegui e quindi Esegui senza eseguire debug.

   • Se viene richiesto di selezionare un ambiente, selezionare .Net Core.
   • Se questo comando ha aggiornato le impostazioni di avvio, salvare le modifiche ed eseguire di nuovo il comando.

   Il comando run compila l'applicazione, la distribuisce in localhost e avvia il Web browser per visualizzare la pagina dell'applicazione default.htm .

A questo punto, il bot è in esecuzione in locale sulla porta 3978.

CLI

Da un prompt dei comandi o da un terminale:

1. Passare alla cartella del progetto per il bot.

2. Usare dotnet run per avviare il bot.

   dotnet run
   

3. Questo comando compila l'applicazione e la distribuisce in localhost.

La pagina Web predefinita dell'applicazione non verrà visualizzata, ma a questo punto il bot viene eseguito localmente sulla porta 3978.

È stato avviato il bot echo che si è verificato un problema

Java

1. Da un terminale passare alla directory in cui è stato salvato il bot, quindi eseguire i comandi elencati di seguito.

2. Compilare il progetto Maven e lo inserisce in un file di .jar (archivio).

   mvn package
   

3. Eseguire il bot in locale. Sostituire archive-name con il nome effettivo del comando precedente.

   java -jar .\target\<archive-name>.jar
   

A questo punto è possibile avviare l'emulatore.

È stato avviato il bot echo che si è verificato un problema

JavaScript

In un terminale o a un prompt dei comandi impostare le directory su quella creata per il bot e avviare il bot con il comando npm start.

cd my-chat-bot
npm start

A questo punto, il bot è in esecuzione in locale sulla porta 3978.

È stato avviato il bot echo che si è verificato un problema

Python

1. Dalla riga di comando o dal terminale modificare le directory in echo_bot.

   cd echo_bot
   

2. Installare le dipendenze per il modello echo bot.

   pip install -r requirements.txt 
   

3. Dopo aver installato le dipendenze, eseguire il comando seguente per avviare il bot:

   python app.py
   

   Si saprà che il bot è pronto per il test quando viene visualizzata l'ultima riga illustrata nello screenshot seguente:

   

4. Copiare l'indirizzo HTTP nell'ultima riga. Sarà necessario quando si usa l'emulatore per interagire con il bot.

È stato avviato il bot echo che si è verificato un problema

Avviare l'emulatore e connettere il bot

1. Avviare Bot Framework Emulator.

2. Selezionare Apri bot nella scheda Benvenuto dell'emulatore.

3. Immettere l'URL del bot, ovvero l'host locale e la porta, con /api/messages aggiunta al percorso. L'indirizzo è in genere: http://localhost:3978/api/messages.

   

4. Selezionare Connetti.

   Inviare un messaggio al bot e il bot risponderà.

   

L'emulatore è stato avviato e connesso al bot si è verificato un problema

Passaggi successivi

• Per informazioni su come eseguire il debug con Visual Studio o Visual Studio Code e Bot Framework Emulator, vedere Eseguire il debug di un bot.
• Per informazioni su devtunnel, vedere Tunneling (devtunnel).For information about devtunnel, see Tunneling (devtunnel).

Distribuire il bot in Azure