Criar um bot com o SDK do Bot Framework

Artigo
10/24/2023

APLICA-SE A: SDK v4

Este artigo descreve como criar seu primeiro bot com o Bot Framework SDK 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 do Azure AI. 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, consulte Criar um recurso de Bot do Azure.

Nota

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

Os bots existentes construídos com o Java SDK 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 copilot certa.

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

Pré-requisitos

SDK do .NET 6.0
Emulador de Bot Framework
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
Código VS / CLI

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

Nota

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

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

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

Os Modelos .NET Core ajudarão você a criar rapidamente novos bots de IA conversacional 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:

Abra uma janela do console.
Baixe e instale o .NET Core SDK 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 echo, core e empty bot.

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
```

Nota

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 usará. Este artigo faz uso do modelo echo bot .

Java 1.8 ou posterior
Emulador de Bot Framework
Visual Studio Code ou seu IDE favorito, se você quiser editar o código do bot.
Instalar o Maven
Instale 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 conversacional usando os principais recursos de IA no Bot Framework v4. Para obter mais informações, consulte yeoman.io.

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

Modelo	Description
Echo Bot	Um bom modelo se você quiser um pouco mais do que "Hello World!", mas não muito mais. Este modelo lida com o básico 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 diga 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 você quiser pegar 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árias voltas e o Azure AI LUIS para implementar o entendimento de linguagem. Este modelo cria um bot que pode extrair lugares e datas para reservar um voo.

Nota

O Language Understanding (LUIS) será aposentado em 1 de outubro de 2025. A partir de 1 de abril de 2023, não será possível criar novos recursos LUIS. Uma versão mais recente do entendimento de idiomas agora está disponível como parte do Azure AI Language.

O entendimento de linguagem conversacional (CLU), um recurso do Azure AI Language, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte à compreensão de linguagem no Bot Framework SDK, consulte Compreensão de linguagem natural.

Instalar o Yeoman

Certifique-se de ter instalado node.js versão 12.10 ou posterior.
Instale o npm mais recente.
```
npm install -g npm
```
Instale o Yeoman. Certifique-se de instalar globalmente.
```
npm install -g yo
```
Instale generator-botbuilder-java. Certifique-se de instalar globalmente.
```
npm install -g generator-botbuilder-java
```
Verifique se Yeoman e generator-botbuilder-java foram instalados corretamente.
```
yo botbuilder-java --help
```

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

Modelos JavaScript e TypeScript

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

Abra um terminal ou um prompt de comando elevado.
Alterne para o diretório de seus bots JavaScript. Crie-o primeiro se ainda não tiver um.
```
mkdir myJsBots
cd myJsBots
```
Certifique-se de ter as versões mais recentes do npm e Yeoman.
```
npm install -g npm
npm install -g yo
```
Instale o gerador Yeoman. Yeoman é uma ferramenta para criar aplicações. Para obter mais informações, consulte yeoman.io.
```
npm install -g generator-botbuilder
```
Nota

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 este for o caso, você pode tentar executar este comando com permissões elevadas. Esta chamada também pode travar sem sair se o Python já estiver instalado no seu sistema:

Execute este comando apenas se estiver no Windows.
```
npm install -g windows-build-tools
```

Python 3.8.3
Emulador de Bot Framework
Conhecimento de programação assíncrona em Python

Criar e habilitar um ambiente virtual

Um ambiente virtual é uma combinação de um interpretador Python específico e bibliotecas que são diferentes de suas configurações globais. O ambiente virtual é específico para um projeto e é mantido na pasta do projeto. Um benefício ao 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, consulte Criação de ambientes virtuais.

Navegue até o diretório onde você deseja criar seu bot. Em seguida, execute os seguintes comandos para a sua plataforma preferida. Depois de ativar seu ambiente virtual, sua linha de comando/terminal deve ser precedida de (venv). Isso permite que você saiba que o ambiente virtual está ativo. Você pode desativar seu 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 Python

Instale os pacotes necessários executando os seguintes pip install comandos:

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 também pip install cryptography==2.8o .

Criar um bot

No Visual Studio, crie um novo projeto de bot e use o modelo Echo Bot (Bot Framework v4 - .NET Core 3.1 ). Para ver apenas modelos de bot, escolha o tipo de projeto AI Bots .

Certifique-se de que o .NET Core 3.1 ou posterior está instalado.

No Visual Studio Code, abra uma nova janela de terminal.
Vá para o diretório no qual você deseja criar seu projeto de bot.
Crie um novo projeto echo bot usando o seguinte comando. Substitua <your-bot-name> pelo nome a ser usado para seu projeto de bot.
```
dotnet new echobot -n <your-bot-name>
```

Abra uma janela de terminal nova.
Vá para o diretório no qual você deseja criar seu projeto de bot.
Crie um novo projeto echo bot usando o seguinte comando. Substitua <your-bot-name> pelo nome a ser usado para seu projeto de 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 mais código para testar seu bot.

Eu criei um bot de eco que encontrei um problema

Execute o seguinte comando para criar um bot de eco a partir de modelos. O comando usa opções padrão para seus parâmetros.

yo botbuilder-java -T "echo"

Yeoman solicita algumas informações para criar seu bot. Para este 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 suporta muitas opções de linha de comando que você pode usar para alterar os padrões do gerador ou para pré-semear um prompt. As opções diferenciam maiúsculas de minúsculas.

Opção de linha de comando	Description
`--help, -h`	Listar texto de ajuda para todas as opções de linha de comando suportadas
`--botName, -N`	O nome dado ao projeto 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`, `core`. Para obter mais informações sobre os diferentes modelos, consulte o repositório GitHub para sua linguagem, C#, JavaScript, Python ou Java.
`--noprompt`	O gerador não solicitará confirmação antes de criar um novo bot. Qualquer opção de requisito não passada na linha de comando usará um valor padrão razoável. Esta opção destina-se a permitir 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 seu bot.

Eu criei um bot de eco que encontrei um problema

Use o gerador para criar um bot de eco.

yo botbuilder

Yeoman solicita algumas informações para criar seu bot. Para este 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 seu bot.

Eu criei um bot de eco que encontrei um problema

No diretório de trabalho, execute o seguinte comando para baixar o modelo de bot echo e 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 seu bot. Introduza os seguintes valores:
- bot_name: echo_bot
- bot_description: Um bot que ecoa a resposta do usuário.

Eu criei um bot de eco que encontrei um problema

Inicie seu bot

No Visual Studio:

Abra seu projeto de 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 do default.htm aplicativo.

Neste ponto, seu bot está sendo executado localmente na porta 3978.

No código do Visual Studio:

Abra a pasta do projeto do bot.

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

Neste ponto, seu bot está sendo executado localmente na porta 3978.

A partir de um prompt de comando ou terminal:

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

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

Eu comecei o bot de eco eu encontrei um problema

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

Agora você está pronto para iniciar o emulador.

Eu comecei o bot de eco eu encontrei um problema

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

cd my-chat-bot
npm start

Neste ponto, seu bot está sendo executado localmente na porta 3978.

Eu comecei o bot de eco eu encontrei um problema

A partir da linha de comando/terminal, altere os diretórios para echo_bot.
```
cd echo_bot
```
Instale as dependências para o modelo echo bot.
```
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 seu bot está pronto para testar quando vir a última linha mostrada na captura de tela abaixo:
Copie o endereço http na última linha. Você precisará dele quando usar o emulador para interagir com seu bot.

Eu comecei o bot de eco eu encontrei um problema

Inicie o emulador e conecte seu bot

Inicie o emulador do Bot Framework.
Selecione Open Bot na guia Bem-vindo do emulador.
Insira o URL do seu bot, que é seu host e porta locais, com /api/messages adicionado ao caminho. Normalmente, o endereço é: http://localhost:3978/api/messages.
Em seguida, selecione Conectar.

Envie uma mensagem para seu bot e ele responderá.

Eu comecei o emulador e conectado ao meu bot eu encontrei um problema

Próximos passos

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

Implantar seu bot no Azure

Partilhar via

Criar um bot com o SDK do Bot Framework

Pré-requisitos

Modelos C#

Modelos Java

Instalar o Yeoman

Modelos JavaScript e TypeScript

Criar e habilitar um ambiente virtual

Modelos Python

Criar um bot

Inicie seu bot

Inicie o emulador e conecte seu bot

Próximos passos

Recursos adicionais