Bot de comando no Teams

O Microsoft Teams permite automatizar tarefas simples e repetitivas em uma conversa. Você pode criar um bot de comando que pode responder a comandos simples enviados em chats com Cartões Adaptativos. Você pode criar um modelo de bot de comando no Microsoft 365 Agents Toolkit (anteriormente conhecido como Teams Toolkit) que responde aos comandos de chat exibindo a interface do usuário usando um Cartão Adaptável. Isso permite que os usuários enviem mensagens no Teams e seu aplicativo pode fornecer uma resposta conforme necessário.

O modelo de bot de comando é criado usando o SDK TeamsFx, que fornece um conjunto simples de funções no Microsoft Bot Framework. O bot de comando pode ser usado em diferentes cenários, como verificar o status do tíquete e recuperar informações de ajuda.

Vantagens

• Automatiza tarefas simples e repetitivas com um comando de chat.
• Simplifica o modelo de programação com o SDK do TeamsFx, criado no SDK do Bot Framework.
• Suporta expressões regulares para processar comandos.

Instalação do bot de comando

Dependendo do escopo necessário, um bot de comando precisa ser instalado em uma equipe ou em um chat em grupo ou como um aplicativo pessoal. Durante a instalação, você pode selecionar o escopo onde deseja adicionar e usar o bot:

• Para abrir o bot no escopo pessoal, selecione Abrir.

• Para abrir o bot em um escopo compartilhado, selecione o canal, o chat ou a reunião necessário na lista e mova a caixa de diálogo para selecionar Ir.

  

Para obter mais opções de instalação, consulte configurar opções de instalação padrão. Para desinstalar, consulte Remover um aplicativo do Teams.

Comando e resposta

Os bots de comando e resposta TeamsFx são criados usando o SDK do Bot Framework. O SDK do Bot Framework fornece um manipulador de mensagens integrado para lidar com a atividade de mensagens recebidas, o que exige que você entenda o conceito do Bot Framework, como o modelo de conversa orientada a eventos. O SDK do TeamsFx fornece uma camada de abstração de comando-resposta para permitir que os usuários se concentrem em lidar com a solicitação de comando de acordo com a necessidade comercial, sem aprender o SDK do Bot Framework.

O SDK do TeamsFx efetua pull do middleware do Bot Framework para lidar com a integração com os manipuladores de atividades subjacentes. Se o texto da mensagem recebida corresponder ao padrão de comando fornecido em uma TeamsFxBotCommandHandler instância, o middleware manipulará a atividade de mensagem de entrada e invocará a função correspondente handlerCommandReceived . O middleware chama context.sendActivity para enviar a resposta de comando retornada da handlerCommandReceived função para o usuário.

Personalizar inicialização

Você precisa criar ConversationBot para responder ao comando em um chat. Você pode inicializar o com seu adaptador ou personalizá-lo após a ConversationBot inicialização.

/** JavaScript/TypeScript: src/internal/initialize.js(ts) **/
const commandApp = new ConversationBot({
  // The bot id and password to create CloudAdapter.
  // See https://aka.ms/about-bot-adapter to learn more about adapters.
  adapterConfig: {
    MicrosoftAppId: config.botId,
    MicrosoftAppPassword: config.botPassword,
    MicrosoftAppType: "MultiTenant",
  },
  command: {
    enabled: true,
    commands: [new HelloWorldCommandHandler()],
  },
});

builder.Services.AddSingleton<HelloWorldCommandHandler>();
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Command = new CommandOptions()
        {
            Commands = new List<ITeamsCommandHandler> { sp.GetService<HelloWorldCommandHandler>() }
        }
    };

    return new ConversationBot(options);
});

Personalizar adaptador

// Create your own adapter
const adapter = new CloudAdapter(...);

// Customize your adapter, e.g., error handling
adapter.onTurnError = ...

const bot = new ConversationBot({
    // use your own adapter
    adapter: adapter;
    ...
});

// Or, customize later
bot.adapter.onTurnError = ...

Adicionar comando e resposta

Você pode executar as seguintes etapas para adicionar comandos e respostas:

"commandLists": [
  {
    "commands": [
        {
            "title": "helloWorld",
            "description": "A helloworld command to send a welcome message"
        },
        {
            "title": "doSomething",
            "description": "A sample do something command"
        }
    ]
  }
]

    {
           "type": "AdaptiveCard",    
           "body": [
               {
                   "type": "TextBlock",
                   "size": "Medium",
                   "weight": "Bolder",
                   "text": "Your doSomething Command is added!"
               },
         {
                   "type": "TextBlock",
                   "text": "Congratulations! Your hello world bot now includes a new DoSomething Command",
                   "wrap": true
         }
      ],
      "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
      "version": "1.4"
    }

const doSomethingCard = require("./adaptiveCards/doSomethingCommandResponse.json");
const { AdaptiveCards } = require("@microsoft/adaptivecards-tools");
const { CardFactory, MessageFactory } = require("botbuilder");

class DoSomethingCommandHandler {
  triggerPatterns = "doSomething";

  async handleCommandReceived(context, message) {
    // verify the command arguments which are received from the client if needed.
    console.log(`App received message: ${message.text}`);

    const cardData = {
      title: "doSomething command is added",
      body: "Congratulations! You have responded to doSomething command",
    };

    const cardJson = AdaptiveCards.declare(doSomethingCard).render(cardData);
    return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
  }
}

module.exports = {
  DoSomethingCommandHandler,
};

/** TypeScript **/
import { Activity, CardFactory, MessageFactory, TurnContext } from "botbuilder";
import {
 CommandMessage,
 TeamsFxBotCommandHandler,
 TriggerPatterns,
 MessageBuilder,
} from "@microsoft/teamsfx";
import doSomethingCard from "./adaptiveCards/doSomethingCommandResponse.json";
import { AdaptiveCards } from "@microsoft/adaptivecards-tools";
import { CardData } from "./cardModels";

export class DoSomethingCommandHandler implements TeamsFxBotCommandHandler {
 triggerPatterns: TriggerPatterns = "doSomething";

 async handleCommandReceived(
   context: TurnContext,
   message: CommandMessage
 ): Promise<string | Partial<Activity>> {
   // verify the command arguments which are received from the client if needed.
   console.log(`App received message: ${message.text}`);

   const cardData: CardData = {
     title: "doSomething command is added",
     body: "Congratulations! You have responded to doSomething command",
   };

   const cardJson = AdaptiveCards.declare(doSomethingCard).render(cardData);
   return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
 }
}

using MyCommandApp.Models;
using AdaptiveCards.Templating;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;
using Microsoft.TeamsFx.Conversation;
using Newtonsoft.Json;

namespace MyCommandApp.Commands
{
    public class DoSomethingCommandHandler : ITeamsCommandHandler
    {
        private readonly ILogger<HelloWorldCommandHandler> _logger;
        private readonly string _adaptiveCardFilePath = Path.Combine(".", "Resources", "DoSomethingCommandResponse.json");

        public IEnumerable<ITriggerPattern> TriggerPatterns => new List<ITriggerPattern>
        {
            new RegExpTrigger("doSomething")
        };

        public HelloWorldCommandHandler(ILogger<HelloWorldCommandHandler> logger)
        {
            _logger = logger;
        }

        public async Task<ICommandResponse> HandleCommandAsync(ITurnContext turnContext, CommandMessage message, CancellationToken cancellationToken = default)
        {
            _logger?.LogInformation($"App received message: {message.Text}");

            // Read Adaptive Card template
            var cardTemplate = await File.ReadAllTextAsync(_adaptiveCardFilePath, cancellationToken);

            // Render Adaptive Card content
            var cardContent = new AdaptiveCardTemplate(cardTemplate).Expand
            (
                new HelloWorldModel
                {
                    title: "doSomething command is added",
                    body: "Congratulations! You have responded to doSomething command",
                }
            );

            // Build attachment
            var activity = MessageFactory.Attachment
            (
                new Attachment
                {
                    ContentType = "application/vnd.microsoft.card.adaptive",
                    Content = JsonConvert.DeserializeObject(cardContent),
                }
            );

            // send response
            return new ActivityCommandResponse(activity);
        }
    }
}

/** Update ConversationBot  in src/internal/initialize.js(ts) **/
const commandApp = new ConversationBot({
  //...
  command: {
    enabled: true,
    commands: [ 
      new HelloWorldCommandHandler(),
      new DoSomethingCommandHandler()], // newly added command handler
  },
});

/** Update ConversationBot in Program.cs **/
builder.Services.AddSingleton<HelloWorldCommandHandler>();
builder.Services.AddSingleton<DoSomethingCommandHandler>(); // Add doSomething command handler to service container
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Command = new CommandOptions()
        {
            Commands = new List<ITeamsCommandHandler>
            { 
                sp.GetService<HelloWorldCommandHandler>(),
                sp.GetService<DoSomethingCommandHandler>(),  // Register doSomething command handler to ConversationBot
            }
        }
    };

    return new ConversationBot(options);
});

Personalizar padrão de gatilho

O padrão padrão para disparar um comando é por meio de uma palavra-chave definida. Você também pode coletar e processar informações adicionais recuperadas da palavra-chave de gatilho. Além da correspondência de palavra-chave, você também pode definir seu padrão de gatilho com expressões regulares e corresponder com message.text com mais controles.

Você pode encontrar qualquer grupo de captura em message.matches, ao usar expressões regulares. Por exemplo, se o reboot myMachineusuário inserir , message.matches[1], ele captura myMachine. O exemplo a seguir usa uma expressão regular para capturar cadeias de caracteres após reboot:

class HelloWorldCommandHandler {
  triggerPatterns = /^reboot (.*?)$/i; //"reboot myDevMachine";
  async handleCommandReceived(context, message) {
    console.log(`Bot received message: ${message.text}`);
    const machineName = message.matches[1];
    console.log(machineName);
    // Render your Adaptive Card for reply message
    const cardData = {
      title: "Your Hello World Bot is Running",
      body: "Congratulations! Your hello world bot is running. Click the button below to trigger an action.",
    };
    const cardJson = AdaptiveCards.declare(helloWorldCard).render(cardData);
    return MessageFactory.attachment(CardFactory.adaptiveCard(cardJson));
  }
}

Criar comando e resposta usando o Cartão Adaptável com conteúdo dinâmico

O Cartão Adaptável fornece uma linguagem de modelo para permitir que os usuários renderizem conteúdo dinâmico com o mesmo layout (o modelo). Por exemplo, use um Cartão Adaptável para renderizar uma lista de itens, como itens de tarefas pendentes ou atribuir bugs que variam entre diferentes usuários.

Você pode executar as seguintes etapas para criar comando e resposta usando o Cartão Adaptável com conteúdo dinâmico:

1. Adicione o arquivo JSON do modelo de Cartão Adaptável na bot/adaptiveCards pasta.
2. No arquivo de código em que o manipulador de comandos existe, por exemplo, myCommandHandler.ts. Importe o arquivo JSON do modelo de Cartão Adaptável.
3. Modele os dados do seu card.
4. Use MessageBuilder.attachAdaptiveCard no modelo com dados dinâmicos do card.

Se necessário, você pode adicionar novos cartões para seu aplicativo. Para obter mais informações sobre como criar diferentes tipos de Cartões Adaptáveis com uma lista ou uma tabela de conteúdo dinâmico usando ColumnSet e FactSet, consulte amostra.

Acesso Microsoft Graph

Se você estiver respondendo a um comando que precisa acessar os dados do Microsoft Graph de um usuário do Teams já conectado, poderá fazer isso por logon único (SSO) com o token de usuário do Teams. Leia mais sobre como o Kit de Ferramentas para Agentes pode ajudá-lo a adicionar o logon único ao aplicativo Teams.

Conectar-se a APIs existentes

Se você não tiver o SDK necessário e precisar invocar APIs externas em seu código, o comando Microsoft 365 Agents: Conectar-se a uma API na extensão Microsoft Visual Studio Code (VS Code) Agents Toolkit ou o comando atk add api-connection na CLI do Microsoft 365 Agents Toolkit (anteriormente conhecida como CLI TeamsFx) pode ser usada para inicializar o código para chamar APIs de destino. Para obter mais informações, consulte configurar conexão de API.

Perguntas frequentes

Exemplo de código

A tabela a seguir fornece um exemplo de código simples para criar uma funcionalidade de comando para um bot:

Guias passo a passo

Siga o guia passo a passo para criar o bot de Comando do Teams.

Confira também

• Noções básicas sobre conversas
• Criar bots para o Teams
• Crie seu primeiro aplicativo de bot usando JavaScript
• Mensagens proativas
• Cartões Adaptáveis
• TeamsFx SDK
• Bot Framework SDK
• Middleware do Bot Framework
• Manipuladores de atividade de bot
• Conversas orientadas a eventos usando um manipulador de atividades