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
Para criar agentes com sua escolha de serviços, orquestração e conhecimento de IA, considere usar o SDK de agentes do Microsoft 365. 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 por 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 seu bot para o SDK de agentes. Você pode revisar as principais alterações e atualizações nas diretrizes de migração do SDK do Bot Framework para o SDK de agentes. 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.
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 .
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 |
Descrição |
| 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
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
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
Mac OS
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.
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 |
Descrição |
--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.
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.
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.
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.
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.
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.
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.
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á.
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).