Expor comandos de barra de agentes e aplicativos

Os comandos de barramento ajudam os usuários a descobrir e usar a funcionalidade de comando nomeado em agentes e aplicativos do Teams.

Se o seu agente ou aplicativo tiver funcionalidades que os usuários devem ser capazes de invocar com comandos nomeados, você poderá adicionar uma configuração que torne esses comandos rapidamente detectáveis e acessíveis na caixa de redação de mensagens no Teams. Os comandos de barra nomeados podem ajudar os usuários a acessar orientações, criar tarefas de acompanhamento pessoais ou gerenciar opções de personalização.

Experiência do usuário

Os comandos de barra no Teams são atalhos baseados em texto que permitem que os usuários executem ações na caixa de redação em conversas. Quando um usuário insere um / em uma caixa de composição vazia, o Teams exibe um menu de preenchimento automático contendo comandos internos para tarefas comuns expostas por agentes ou aplicativos no contexto atual.

O recurso de comandos de barra permite que aplicativos e agentes adicionem seus próprios comandos a essa lista para ajudar os usuários a descobrir e usá-los.

Este vídeo mostra como funciona um comando de barra em um agente ou aplicativo do Teams.

Comandos de barra

Aplicativos e agentes podem expor experiências de comando de barra por meio da configuração de aplicativo ou agente de duas maneiras principais:

  • Comandos de barra do agente: exiba comandos nomeados para os usuários no menu de preenchimento automático de comandos de barra.
  • Comandos de barra de extensão de mensagem: permita que os usuários ativem as extensões de mensagem do seu aplicativo ou agente com um comando de barra.

Esses tipos de comandos de barra são suportados em todas as plataformas do cliente, incluindo dispositivos móveis.

Importante

As mensagens direcionadas e os comandos de barra do agente são fundamentais para o design do agente para conversas em grupo e exigem um tratamento cuidadoso das expectativas de privacidade do usuário. A seleção de um comando de agente alterna a caixa de redação para o modo de mensagem direcionada. Uma mensagem direcionada iniciada pelo usuário é entregue apenas ao agente selecionado, e o agente pode responder de forma privada ao usuário.

Para obter mais informações, consulte práticas recomendadas e diretrizes de design.

Comandos de barra do agente

Os comandos de barra do agente permitem que os agentes exibam comandos nomeados que os usuários podem invocar de forma privada em canais, chats em grupo e chats de reunião. Os comandos de barra são úteis para funcionalidades que os usuários precisam acessar de forma rápida e privada em conversas em grupo.

Em canais, chats em grupo e chats de reunião, o menu de preenchimento automático de comando de barra inclui todos os comandos registrados pelos agentes na conversa atual. Cada comando é exibido com sua descrição e o nome e ícone de seu agente, tornando-os detectáveis e distinguindo entre comandos com o mesmo nome.

Invocar um comando no menu alterna a caixa de redação para o modo de mensagem direcionada para o agente e insere o nome do comando como o texto da mensagem. Selecionar Enviar envia a mensagem direcionada ao agente. Por exemplo, um agente de gerenciamento de projetos ou aplicativo de bot pode expor comandos como /create-task transformar a conversa atual em uma tarefa rastreada com base no contexto, ou /status-check comando que pode receber um número de item de trabalho e retornar informações sobre ela.

Comandos de barra para extensões de mensagem do tipo ação

Aplicativos que implementam extensões de mensagem do tipo ação podem expor essas ações como comandos de barra. Quando um usuário seleciona um no menu de preenchimento automático, o Teams abre o módulo de tarefa ou caixa de diálogo associado. Ativar um comando de barra de extensão de mensagem abre apenas o módulo ou a caixa de diálogo; Ele não envia uma mensagem. Extensões de mensagem do tipo de pesquisa não podem ser expostas como comandos de barra.

Os comandos de barra de extensão de mensagem podem ser configurados para aparecer como entradas de preenchimento automático na caixa de composição e na caixa de comando do Teams.

Comandos de menção em agentes

Use @mention comandos em seus agentes e aplicativos quando os usuários precisarem se dirigir diretamente a um agente ou bot específico. A mensagem é entregue ao agente mencionado e o agente responde de acordo com o contexto da conversa. Por exemplo, um usuário pode @mention um agente de gerenciamento de projetos em um canal e inserir atribuir para criar uma tarefa de acompanhamento a partir do contexto da conversa.

Para obter mais informações sobre @mention comandos, consulte @Mention.

Adicionar comandos

Comandos de barra e mensagens direcionadas são configurados no manifesto do aplicativo ou agente. Declarar comandos no manifesto torna os comandos visíveis no Teams, enquanto a implementação do aplicativo ou agente determina como cada comando é tratado depois que o usuário o envia.

Barra e @mention comandos para agentes

Barra e @mention comandos exigem que um agente opte por receber mensagens direcionadas, Para obter mais informações, consulte receber mensagens direcionadas.

Gatilhos: barra e @mention

A triggers propriedade define onde um comando aparece e como os usuários podem invocá-lo na experiência de redação do Teams. Para listas de comandos de agente, use mention quando o comando deve aparecer no menu de comando tradicional @mention , use slash quando o comando deve aparecer no seletor de comandos de barra ou inclua ambos os valores quando o mesmo comando deve estar disponível em ambos os pontos de entrada.

Declare comandos e seus gatilhos configurando a seção do manifesto bots[].commandLists[] . O exemplo de manifesto a seguir mostra um agente que dá suporte a mensagens direcionadas e expõe três comandos por meio de barra, menção e gatilhos combinados:

{
  "bots": [
    {
      "botId": "{{BOT_ID}}",
      "scopes": ["personal", "team", "groupChat"],
      "supportsTargetedMessages": true,
      "commandLists": [
        {
          "scopes": ["personal", "team", "groupChat"],
          "triggers": ["slash"],
          "commands": [
            {
              "title": "summarize",
              "description": "Summarize the conversation"
            }
          ]
        },
        {
          "scopes": ["personal", "team", "groupChat"],
          "triggers": ["mention"],
          "commands": [
            {
              "title": "assign",
              "description": "Assign a follow-up task"
            }
          ]
        },
        {
          "scopes": ["personal", "team", "groupChat"],
          "triggers": ["slash", "mention"],
          "commands": [
            {
              "title": "review",
              "description": "Review a document"
            }
          ]
        }
      ]
    }
  ]
}

• Como é necessário para comandos de barra, este trecho de código de exemplo:

  • supportsTargetedMessages é definido como true para permitir que o agente receba mensagens direcionadas em conversas em grupo.
  • summarize é configurado como um comando de barra.
  • assign é configurado como um @mention comando.
  • review é configurado como um comando de barra e um @mention comando.

Comandos de barra para extensões de mensagem do tipo ação

Use a propriedade de para expor extensões triggers de composeExtensions[].commands[] mensagem como comandos de barra.

{
    "composeExtensions": [
        {
            "botId": "{{BOT_ID}}",
            "commands": [
                {
                    "id": "summarizeCommand",
                    "type": "action",
                    "title": "Summarize",
                    "description": "Summarize a document",
                    "context": ["compose", "commandBox"]
                },
                {
                    "id": "draftCommand",
                    "type": "action",
                    "title": "Draft",
                    "description": "Draft a document",
                    "context": ["compose", "commandBox"],
                    "triggers": ["slash"]
                },
                {
                    "id": "reviewCommand",
                    "type": "action",
                    "title": "Review",
                    "description": "Review a document",
                    "context": ["compose", "commandBox"],
                    "triggers": ["slash"]
                }
            ]
        }
    ]
}

Neste exemplo, está disponível nos contextos configurado da caixa de composição e comando, summarizeCommand mas não é exposto como um comando de barra. As draftCommand ações and reviewCommand declaram o gatilho de barra, para que apareçam como comandos de barra nos pontos de entrada com suporte.

Implementar manipulação de comando nomeado de agente

A configuração de comandos de barra do agente só os exibe para os usuários no cliente do Teams, mas não ajuda na sua implementação.

Quando um usuário ativa um comando de barra do agente, o Teams alterna a caixa de redação para o modo de mensagem direcionada e insere o nome do comando e, em seguida, retorna o controle ao usuário para permitir que ele insira mais texto e envie a mensagem. O manipulador de mensagens do agente é responsável por usar o conteúdo da mensagem para determinar se ela deve ser interpretada como uma invocação de comando e manipulá-la adequadamente.

Consulte práticas recomendadas e diretrizes de design para obter outras diretrizes de tratamento de mensagens.

Práticas recomendadas e diretrizes de design

Escolha o gatilho que corresponde a como os usuários invocarão o comando. Ofereça comandos de barra para ações comuns que os usuários precisam acessar de forma rápida, repetida e privada. Eles funcionam melhor para ações específicas do usuário, como exibir configurações, criar tarefas de acompanhamento ou verificar o status pessoal, especialmente quando os usuários se beneficiam da descoberta e reutilização da ação na caixa de redação. Use um comando @menção quando os usuários precisarem se dirigir a um agente específico ou confiar no contexto da conversa. Ofereça ambos somente quando cada um for um ponto de entrada natural para o mesmo comportamento.

Como acontece com todas as atividades baseadas em mensagens, o design de comportamentos de comando de barra deve considerar cuidadosamente se o usuário espera uma mensagem pública ou privada como resposta em conversas em grupo. Para obter diretrizes gerais sobre a visibilidade da resposta do agente, consulte as práticas recomendadas de mensagens direcionadas e as diretrizes de design.

Mantenha o conjunto de comandos pequeno e focado. Ofereça suporte a prompts de linguagem natural quando os usuários precisam de uma experiência mais conversacional, mas reserve comandos de barra para as ações mais repetíveis.

Mantenha os nomes dos comandos de barra curtos e orientados para a ação. Use aliases para comandos de alta frequência quando eles melhorarem a capacidade de descoberta e use iniciadores de prompt para prompts mais longos ou mais abertos.

Forneça descrições claras dos comandos para melhorar a capacidade de descoberta, incluindo qualquer entrada esperada além do nome do comando.

Conteúdo relacionado

  • Última atualização em