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
Para criar agentes com sua escolha de serviços de IA, orquestração e conhecimento, considere usar o SDK do Microsoft 365 Agents. O SDK de Agentes tem suporte para C#, JavaScript ou Python. Você pode saber mais sobre o SDK de Agentes em aka.ms/agents. Se você estiver procurando uma plataforma de agente baseada em SaaS, considere o Microsoft Copilot Studio. Se você tiver um bot existente criado com o SDK do Bot Framework, poderá atualizar o bot para o SDK de Agentes. Você pode examinar as principais alterações e atualizações nas orientações de migração do SDK do Bot Framework para o SDK do Agents. Os tíquetes de suporte para o SDK do Bot Framework não serão mais atendidos a partir de 31 de dezembro de 2025.
Pré-requisitos
Modelos C#
Os exemplos de bot atuais usam modelos do .NET Core 3.1.
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.
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. |
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).