Criar um bot com o SDK do Bot Framework

Artigo
07/16/2024

APLICA-SE A: SDK v4

Este artigo descreve como criar seu primeiro bot com o SDK do Bot Framework para C#, Java, JavaScript ou Python e como testar seu bot com o Bot Framework Emulator.

Criar seu primeiro bot não requer uma assinatura do Azure ou um recurso do Serviço de Bot de IA do Azure. Este guia de início rápido se concentra na criação do seu primeiro bot localmente. Se quiser saber como criar um bot no Azure, confira Criar um recurso de Bot do Azure.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copiloto certa.

Para obter mais informações, confira O futuro da criação de bots.

Pré-requisitos

SDK do .NET 6.0
Bot Framework Emulator
Conhecimento de ASP.Net Core e programação assíncrona em C#

Modelos C#

Os exemplos de bot atuais usam modelos do .NET Core 3.1.

Visual Studio
VS Code / CLI

Para adicionar os modelos de bot ao Visual Studio, faça download e instale os Modelos de SDK do Bot Framework v4 para o arquivo VSIX do Visual Studio.

Observação

Você pode instalar os modelos de dentro do Visual Studio.

No menu, selecione Extensões e Gerenciar extensões.
Na caixa de diálogo Gerenciar extensões, localize e instale os modelos de SDK do Bot Framework v4 para o Visual Studio.

Para obter informações sobre como implantar bots .NET no Azure, confira como provisionar e publicar um bot.

Os Modelos do .NET Core ajudarão você a criar bots de IA de conversação rapidamente usando o Bot Framework v4. A partir de maio de 2020, esses modelos e o código que eles geram exigem o .NET Core 3.1 ou posterior.

Para instalar os modelos do Bot Framework:

Kudu uma janela do console.
Faça download e instale o SDK do .NET Core versão 3.1 ou posterior.
Você pode usar esse comando para determinar quais versões da interface de linha de comando do .NET Core estão instaladas.
```
dotnet --version
```

Instale os três modelos C# do Bot Framework: os modelos de bot de eco, núcleo e vazio.

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

Verifique se os modelos foram instalados corretamente.
```
dotnet new --list
```

Observação

As etapas acima instalam todos os três modelos do Bot Framework. Você não precisa instalar todos os modelos e pode instalar apenas os que você usará. Este artigo faz uso do modelo de bot de eco.

Java 1.8 ou posterior
Bot Framework Emulator
Visual Studio Code ou seu IDE favorito, se você quiser editar o código de bot.
Instale o Maven
Instale o node.js versão 12.10 ou posterior.
Uma conta do Azure se você quiser implantar no Azure.

Modelos Java

Use o gerador Yeoman para criar rapidamente um bot de IA de conversação usando as principais capacidades de IA no Bot Framework v4. Para obter mais informações, confira yeoman.io.

O gerador suporta três opções de modelo diferentes, como mostrado abaixo.

Modelo	Descrição
Bot de Eco	Um bom modelo se você quiser um pouco mais do que "Olá, Mundo!", mas não muito mais. Esse modelo lida com os conceitos básicos de enviar mensagens para um bot e fazer com que o bot processe as mensagens repetindo-as de volta para o usuário. Este modelo produz um bot que simplesmente "ecoa" de volta para o usuário qualquer coisa que o usuário diz ao bot.
Bot Vazio	Um bom modelo se você estiver familiarizado com o Bot Framework v4 e simplesmente quiser um projeto esqueleto básico. Também uma boa opção se quiser copiar o código de exemplo da documentação e colá-lo em um bot mínimo para aprender.
Bot Principal	Um bom modelo se você quiser criar bots avançados, pois ele usa caixas de diálogo de vários turnos e o LUIS de IA do Azure para implementar o reconhecimento de linguagem. Este modelo cria um bot que pode extrair lugares e datas para reservar um voo.

Observação

O reconhecimento de linguagem (LUIS) será desativado em 1º de outubro de 2025. A partir de 1º de abril de 2023, você não poderá criar recursos do LUIS. Uma versão mais recente do reconhecimento de linguagem já está disponível como parte da Linguagem de IA do Azure.

A compreensão da linguagem coloquial (CLU), um recurso da Linguagem de IA do Azure, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte ao reconhecimento de linguagem no SDK do Bot Framework, confira Reconhecimento de linguagem natural.

Instalar o Yeoman

Verifique se você tem a versão 12.10 ou posterior do node.js instalada.
Instale a última versão do npm.
```
npm install -g npm
```
Instale o Yeoman. Certifique-se de instalá-lo globalmente.
```
npm install -g yo
```
Instale o generator-botbuilder-java. Certifique-se de instalá-lo globalmente.
```
npm install -g generator-botbuilder-java
```
Verifique se o Yeoman e o generator-botbuilder-java foram instalados corretamente.
```
yo botbuilder-java --help
```

Node.js
Bot Framework Emulator
Conhecimento de restify e programação assíncrona em JavaScript
Visual Studio Code ou seu IDE favorito, se você quiser editar o código de bot.

Modelos de JavaScript e TypeScript

Para instalar o Yeoman e o gerador do Yeoman para Bot Framework v4:

Kudu um prompt de comandos com privilégios elevados ou terminais.
Alterne para o diretório dos seus bots do JavaScript. Crie-o primeiro se você ainda não tiver um.
```
mkdir myJsBots
cd myJsBots
```
Verifique se você tem as últimas versões do npm e do Yeoman.
```
npm install -g npm
npm install -g yo
```
Instale o gerador do Yeoman. O Yeoman é uma ferramenta para criar aplicativos. Para obter mais informações, confira yeoman.io.
```
npm install -g generator-botbuilder
```
Observação

A instalação das ferramentas de compilação do Windows listadas abaixo só é necessária se você usar o Windows como seu sistema operacional de desenvolvimento. Para algumas instalações, a etapa de instalação do Restify está dando um erro relacionado ao node-gyp. Se esse for o caso, você poderá tentar executar esse comando com permissões elevadas. Essa chamada também pode ficar suspensa sem sair se o python já estiver instalado no seu sistema:

Só execute este comando se estiver no Windows.
```
npm install -g windows-build-tools
```

Python 3.8.3
Bot Framework Emulator
Conhecimento da programação assíncrona em Python

Criar e habilitar um ambiente virtual

Um ambiente virtual é uma combinação de um interpretador de Python específico e bibliotecas que são diferentes das suas configurações globais. O ambiente virtual é específico a um projeto e é mantido na pasta do projeto. Um benefício de usar um ambiente virtual é que, à medida que você desenvolve um projeto ao longo do tempo, o ambiente virtual sempre reflete as dependências exatas do projeto. Para saber mais sobre ambientes virtuais, confira Criação de ambientes virtuais.

Navegue até o diretório onde deseja criar seu bot. Em seguida, execute os seguintes comandos para sua plataforma preferida. Depois de ativar o ambiente virtual, a linha de comando/terminal deve ser precedida por (venv). Isso permite que você saiba que o ambiente virtual está ativo. Você pode desativar o ambiente virtual a qualquer momento digitando: deactivate.

macOS/Linux

python3 -m venv venv
source venv/bin/activate

Windows

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

Modelos de Python

Instale os pacotes necessários executando os comandos pip install a seguir:

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

Importante

Se você estiver usando uma versão de 32 bits do Python, certifique-se de executar opip install cryptography==2.8.

Criar um bot

No Visual Studio, crie um projeto de bot e use o modelo Bot (Bot Framework v4 – .NET Core 3.1) de eco. Para mostrar apenas os modelos de bot, escolha Bots de IA no tipo de projeto.

Verifique se o NET Core 3.1 ou posterior está instalado.

No Visual Studio Code, abra uma janela de terminal.
Acesse o diretório onde deseja criar seu projeto.
Crie um projeto de bot de eco usando o comando a seguir. Substitua <your-bot-name> pelo nome a ser usado para o projeto do seu bot.
```
dotnet new echobot -n <your-bot-name>
```

Kudu uma nova janela de terminal.
Acesse o diretório onde deseja criar seu projeto.
Crie um projeto de bot de eco usando o comando a seguir. Substitua <your-bot-name> pelo nome a ser usado para o projeto do seu bot.
```
dotnet new echobot -n <your-bot-name>
```

Graças ao modelo, seu projeto contém todo o código necessário para criar o bot neste início rápido. Você não precisa de nenhum código adicional para testar o bot.

Eu criei um bot de eco Encontrei um problema

Execute o seguinte comando para criar um bot de eco com base nos modelos. O comando usa opções padrão para os parâmetros.

yo botbuilder-java -T "echo"

Yeoman pede-lhe alguma informação para criar o seu bot. Neste tutorial, use os valores padrão.

? 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"

O gerador oferece suporte a muitas opções de linha de comando que podem ser usadas para alterar os padrões do gerador ou para pré-semear uma solicitação. As opções diferenciam maiúsculas de minúsculas.

Opção de linha de comando	Descrição
`--help, -h`	Listar o texto de ajuda para todas as opções de linha de comando com suporte
`--botName, -N`	O nome dado ao projeto de bot
`--packageName, -P`	O nome do pacote Java a ser usado para o bot
`--template, -T`	O modelo usado para gerar o projeto. As opções são: `echo`, `empty` e `core`. Para obter mais informações sobre os diferentes modelos, confira o repositório GitHub para a linguagem, C#,JavaScript, Python ou Java.
`--noprompt`	O gerador não solicitará confirmação antes de criar um bot. Quaisquer opções de requisito não passadas na linha de comando usarão um valor padrão razoável. Essa opção destina-se a habilitar a geração automatizada de bots para fins de teste.

Graças ao modelo, seu projeto contém todo o código necessário para criar o bot neste início rápido. Você não precisa de nenhum outro código para testar o bot.

Eu criei um bot de eco Encontrei um problema

Use o gerador para criar um bot de eco.

yo botbuilder

Yeoman pede-lhe alguma informação para criar o seu bot. Neste tutorial, use os valores padrão.

? 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

Graças ao modelo, seu projeto contém todo o código necessário para criar o bot neste início rápido. Você não precisa de nenhum outro código para testar o bot.

Eu criei um bot de eco Encontrei um problema

No diretório de trabalho, execute o seguinte comando para fazer download do modelo de bot de eco e de suas dependências:
```
cookiecutter https://github.com/microsoft/BotBuilder-Samples/releases/download/Templates/echo.zip
```
Você será solicitado a dar um nome e uma descrição ao bot. Insira os valores a seguir:
- bot_name: echo_bot
- bot_description: Um bot que ecoa a resposta do usuário.

Eu criei um bot de eco Encontrei um problema

Inicie seu bot

No Visual Studio:

Kudu o projeto do seu bot.
Execute o projeto sem depuração.
O Visual Studio cria o aplicativo, implanta-o no localhost e inicia o navegador da Web para exibir a página default.htm do aplicativo.

Neste ponto, seu bot está em execução localmente na porta 3978.

No Visual Studio Code:

Abra a pasta do projeto do seu bot.

Se for solicitado a selecionar um projeto, selecione o do bot que criou.
No menu, selecione Executar e Executar sem depuração.
- Se for solicitado a selecionar um ambiente, selecione, .Net Core.
- Se esse comando atualizou suas configurações de inicialização, salve as alterações e execute novamente o comando.
O comando executado cria o aplicativo, implanta-o no localhost e inicia o navegador da Web para exibir a página default.htm do aplicativo.

Neste ponto, seu bot está em execução localmente na porta 3978.

Em um prompt de comando ou terminal:

Altere os diretórios na pasta do projeto do seu bot.
Use dotnet run para iniciar o bot.
```
dotnet run
```
Essa etapa cria o aplicativo e o implanta no localhost.

A página da Web padrão do aplicativo não será exibida, mas, neste momento, o bot está sendo executado localmente na porta 3978.

Comecei o bot de eco e encontrei um problema

Em um terminal, navegue até o diretório onde você salvou o bot e execute os comandos listados abaixo.
Crie o projeto Maven e empacote-o em um arquivo .jar (arquivo morto).
```
mvn package
```
Execute o bot localmente. Substitua o nome do arquivo morto pelo nome real do comando anterior.
```
java -jar .\target\<archive-name>.jar
```

Agora, você está pronto para iniciar o Emulator.

Comecei o bot de eco e encontrei um problema

Em um terminal ou prompt de comando, altere os diretórios para aquele criado para o seu bot e inicie-o com npm start.

cd my-chat-bot
npm start

Neste ponto, seu bot está em execução localmente na porta 3978.

Comecei o bot de eco e encontrei um problema

No terminal da linha de comando, altere os diretórios para echo_bot.
```
cd echo_bot
```
Instale as dependências do modelo de bot de eco.
```
pip install -r requirements.txt 
```
Depois que as dependências forem instaladas, execute o seguinte comando para iniciar o bot:
```
python app.py
```
Você saberá que o bot está pronto para teste quando vir a última linha mostrada na captura de tela abaixo:
Copie o endereço http da última linha. Você precisará dele quando usar o Emulator para interagir com seu bot.

Comecei o bot de eco e encontrei um problema

Iniciar o emulador e conectar seu bot

Instale o Emulator do Bot Framework.
Selecione Abrir Bot na guia Bem-vindo do Emulator.
Insira a URL do bot, que é o host e a porta locais, com /api/messages adicionado ao caminho. O endereço geralmente é: http://localhost:3978/api/messages.
Depois, selecione Conectar.

Envie uma mensagem para seu bot e ele responderá com uma mensagem.

Comecei o emulador e me conectei ao meu bot , tive um problema

Próximas etapas

Para obter informações sobre como depurar usando o Visual Studio ou Visual Studio Code e o Bot Framework Emulator, confira Depurar um bot.
Para obter informações sobre devtunnel, consulte Túnel (devtunnel).

Implantar seu bot no Azure

Compartilhar via

Criar um bot com o SDK do Bot Framework

Pré-requisitos

Modelos C#

Modelos Java

Instalar o Yeoman

Modelos de JavaScript e TypeScript

Criar e habilitar um ambiente virtual

Modelos de Python

Criar um bot

Inicie seu bot

Iniciar o emulador e conectar seu bot

Próximas etapas

Recursos adicionais