Bots e SDKs

Artigo
11/14/2023

Você pode criar um bot que funcione no Microsoft Teams com uma das seguintes ferramentas ou funcionalidades:

Bots com o Microsoft Bot Framework

O bot do Teams consiste no seguinte:

Um serviço Web publicamente acessível hospedado por você.
Um Bot Framework para seu serviço Web.
Seu pacote de aplicativos do Teams, que conecta o cliente do Teams ao seu serviço Web.

Dica

Use o Portal do Desenvolvedor para registrar seu serviço Web com o Bot Framework e especificar as configurações do aplicativo. Para obter mais informações, confira gerenciar seus aplicativos com o Portal do Desenvolvedor para o Teams.

O Bot Framework é um SDK avançado usado para criar bots usando C#, Java, Python e JavaScript. Se você já tiver um bot baseado no Bot Framework, poderá modificá-lo facilmente para funcionar no Teams. Use C# ou Node.js para aproveitar nossos SDKs. Esses pacotes estendem as classes e os métodos básicos SDK do Construtor de Bot da seguinte maneira:

Use tipos de cartão especializados como o conector cartão para Grupos do Microsoft 365.
Defina dados de canal específicos do Teams em atividades.
Processar solicitações de extensão de mensagem.

Você pode desenvolver aplicativos do Teams em qualquer tecnologia de programação da Web e chamar as APIs REST do Bot Framework diretamente. Você deve executar o tratamento de token em todos os casos.

Bots com Power Virtual Agents

Power Virtual Agents é um serviço de chatbot criado na plataforma Microsoft Power e Bot Framework. O processo de desenvolvimento do Power Virtual Agent usa uma abordagem guiada, sem código e interface gráfica que capacita os membros da equipe a criar e manter facilmente um agente virtual inteligente. Depois de criar seu chatbot no portal Power Virtual Agents, você pode integrá-lo facilmente ao Teams. Para obter mais informações sobre como começar, consulte a documentação Power Virtual Agents.

Observação

Você não deve usar o Microsoft Power Platform para criar aplicativos que devem ser publicados na Microsoft Teams Store. Os aplicativos do Microsoft Power Platform podem ser publicados somente na loja de aplicativos de uma organização.

Bots com webhooks e conectores

Webhooks e conectores conectam seu bot aos seus serviços Web. Usando webhooks e conectores, você pode criar um bot para interação básica, como criar um fluxo de trabalho ou outros comandos simples. Elas estão disponíveis apenas na equipe em que você as cria e são destinadas a processos simples específicos ao fluxo de trabalho da sua empresa. Para obter mais informações, confira o que são webhooks e conectores.

Vantagens dos bots

Os bots no Microsoft Teams podem fazer parte de uma conversa privadas, um chat em grupo ou um canal em uma equipe. Cada escopo fornece oportunidades únicas e desafios para seu bot conversacional.

Em um canal.	Em um chat em grupo	Chat Privado
Alcance enorme	Menos membros	Maneira tradicional
Interações individuais concisas	@mention para bot	Bots de P e R
@mention para bot	Semelhante ao canal	Bots que contam piadas e fazem anotações

Em um canal.

Os canais contêm conversas em thread entre várias pessoas até 2000. Isso potencialmente dá ao seu bot um alcance enorme, mas as interações individuais devem ser concisas. Interações tradicionais de várias voltas não funcionam. Em vez disso, você deve procurar usar cartões interativos ou caixas de diálogo (conhecidos como módulos de tarefa no TeamsJS v1.x) ou mover a conversa para uma conversa individual para coletar muitas informações. Seu bot só tem acesso a mensagens em que ele está @mentioned. Você pode recuperar mensagens adicionais da conversa usando as permissões do Microsoft Graph no nível da organização.

Os bots funcionam melhor em um canal nos seguintes casos:

Notificações, em que você fornece um cartão interativo para os usuários obterem informações adicionais.
Comentários cenários como votações e pesquisas.
Um único ciclo de solicitação ou resposta resolve interações e os resultados são úteis para vários membros da conversa.
Bots sociais ou divertidos, em que você obtém uma imagem de gato incrível, escolhe aleatoriamente um vencedor e assim por diante.

Em um chat em grupo

Os chats de grupo são conversas não-encadeadas entre três ou mais pessoas. Tendem a ter menos membros do que um canal e são mais temporários. Semelhante a um canal, o bot só tem acesso a mensagens em que está @mentioned diretamente.

Nos casos em que os bots funcionam melhor em um canal também funcionam melhor em um chat em grupo.

Chat Privado

O chat privado é a maneira tradicional de um bot de conversação interagir com um usuário. Alguns exemplos de bots de chat ptivado são:

Bots de P e R
bots que iniciam fluxos de trabalho em outros sistemas.
bots que contam piadas.
bots que fazem anotações. Antes de criar chatbots individuais, considere se uma interface baseada em conversa é a melhor maneira de apresentar sua funcionalidade.

Desvantagens dos bots

Uma caixa de diálogo extensa entre o bot e o usuário é uma maneira lenta e complexa de concluir uma tarefa. Um bot que dá suporte a comandos excessivos, especialmente uma ampla gama de comandos, não é bem-sucedido ou exibido positivamente pelos usuários.

Ter experiências de vários turnos no chat

Uma caixa de diálogo extensa exige que o desenvolvedor mantenha o estado. Para sair desse estado, um usuário deve ter um tempo limite ou selecionar Cancelar. Além disso, o processo é entediante. Por exemplo, consulte o seguinte cenário de conversa:

USER: Agende uma reunião com Sara.

BOT: Encontrei 200 resultados, incluo um primeiro e sobrenome.

USER: Agende uma reunião com Sara Melo.

BOT: OK, a que hora você gostaria de se encontrar com Sara Melo?

USUÁRIO: 13h.

BOT: Em qual dia?

Suporte a muitos comandos

Como há apenas seis comandos visíveis no menu do bot atual, é improvável que algo mais seja usado com qualquer frequência. Bots que se aprofundam em uma área específica em vez de tentar ser um amplo trabalho de assistente funcionam melhor.

Manter uma grande base de dados de conhecimento

Uma das desvantagens dos bots é que é difícil manter uma grande base de dados de conhecimento de recuperação com respostas não classificadas. Os bots são mais adequados para interações rápidas e curtas e não passam por listas longas em busca de uma resposta.

Limitações e problemas conhecidos

Se você não conseguir criar um bot no Portal do Desenvolvedor, verifique o seguinte:

O registro de aplicativo está habilitado para usuários: quando um registro de aplicativo é desabilitado em toda a organização, os usuários (além de usuários com acesso Microsoft Entra administrador) não podem registrar novos aplicativos. Para permitir que os usuários registrem aplicativos, os administradores devem alternar Os usuários podem registrar aplicativos em Sim no centro de administração Microsoft Entra.
Forneça permissões a usuários específicos para registrar novos aplicativos:
- Para licenças do Microsoft 365 em que o limite de registro de aplicativo é de 250 aplicativos por usuário, verifique se o administrador do locatário adiciona Microsoft Entra ID a um usuário com as seguintes funções:
  Para obter informações sobre como atribuir funções, consulte Atribuir Microsoft Entra funções aos usuários.
- Para a licença do Microsoft 365 (plano P1, P2, E3 ou E5), em que o limite de registro do aplicativo é padrão para o limite de locatário (mais de 300.000) por usuário, verifique se o administrador do locatário adiciona Microsoft Entra ID a um usuário e atribui uma função Personalizada ao usuário com as seguintes permissões:
  - microsoft.directory/applications/create
  - microsoft.directory/applications/createAsOwner

Trechos de código

O código a seguir fornece um exemplo de uma atividade de bot para um escopo de equipe de canal:

C#
Node.js


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        // EncodeName: Converts the name to a valid XML name.
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
    };
    
    // MessageFactory.Text(): Specifies the type of text data in a message attachment.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends a message activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}


this.onMessage(async (turnContext, next) => {
    const mention = {
        mentioned: turnContext.activity.from,

        // TextEncoder().encode(): Encodes the supplied characters.
        text: `<at>${ new TextEncoder().encode(turnContext.activity.from.name) }</at>`,
    } as Mention;

    // MessageFactory.text(): Specifies the type of text data in a message attachment.
    const replyActivity = MessageFactory.text(`Hello ${mention.text}`);
    replyActivity.entities = [mention];

    await turnContext.sendActivity(replyActivity);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

O código a seguir fornece um exemplo de atividade de bot para um chat privado:

C#
Node.js


// Handle message activity
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Remove recipient mention text from Text property.
    // Use with caution because this function is altering the text on the Activity.
    turnContext.Activity.RemoveRecipientMention();
    var text = turnContext.Activity.Text.Trim().ToLower();

    // Sends a message activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(MessageFactory.Text($"Your message is {text}."), cancellationToken);
}

this.onMessage(async (context, next) => {
    // MessageFactory.text(): Specifies the type of text data in a message attachment.
    await context.sendActivity(MessageFactory.text("Your message is:" + context.activity.text));
    await next();
});

Exemplo de código

Nome do exemplo	Descrição	.NETCore	Node.js	Python	Manifesto
Bot de conversas do Teams	Este aplicativo de exemplo mostra como usar diferentes eventos de conversa de bot disponíveis na estrutura do bot v4.	View	View	View	Exibir
Exemplos de bot	Conjunto de exemplos de estrutura de bot v4	View	View	View

Próxima etapa

Manipuladores de atividade de bot