Perguntar com Cartões Adaptáveis

Cartões Adaptáveis permitem adicionar trechos de conteúdo aos agentes do Copilot Studio que também podem ser trocados abertamente com outros aplicativos e serviços de nuvem. Para oferecer uma capacidade de conversação avançada para o agente, você pode incluir texto, gráficos e botões. Como eles são independentes de plataforma, você pode facilmente personalizar os Cartões Adaptáveis de acordo com as suas necessidades.

Com um no do Cartão Adaptável, seu agente pode mostrar um Cartão Adaptável contendo um ou mais botões de envio e, opcionalmente, um ou mais campos de entrada de formulário. O agente armazena a entrada de usuário em variáveis para uso posterior na conversa.

O Copilot Studio inclui um designer de Cartão Adaptável integrado, que dá suporte aos recursos mais úteis, forma o Designer de Cartões Adaptáveis.

Se desejar, você pode usar:

• Use uma representação JSON para o cartão que você deseja mostrar ao usuário.
• Use uma Fórmula do Power Fx para incluir informações dinâmicas no cartão.

Você também pode controlar o comportamento do cartão, como o que fazer quando o usuário insere uma resposta inválida ou se o nó pode ser interrompido.

O no do Cartão Adaptável destina-se a cartões interativos, onde o usuário deve enviar uma resposta. Os nós Mensagem e Pergunta podem ser usados para apresentar ao usuário um cartão não interativo para exibir informações para o usuário.

Adicionar um nó Cartão Adaptável

1. Selecione o ícone Adicionar nó abaixo do nó após o qual você deseja adicionar um nó Cartão Adaptável e, em seguida, selecione Perguntar com Cartão Adaptável.

2. Selecione os três pontos (...) do nó e, em seguida, selecione Propriedades.

3. No painel Propriedades do nó do Cartão Adaptável, selecione Editar cartão adaptável. O painel Designer de cartão adaptável é aberto.

4. Adicione os elementos desejados para o cartão e configure as propriedades. Como alternativa, no painel Editor de carga útil do cartão, substitua o conteúdo padrão pelo literal de JSON do cartão.

   Gorjeta

   Seu cartão deve conter pelo menos um botão de envio, pois ele deve ser um cartão interativo que permita que um usuário envie informações de volta ao agente. Se ele não aparecer e se destinar apenas a mostrar informações, você deverá adicionar seu Cartão Adaptável a um nó de Mensagem.

5. Quando terminar o design inicial, selecione Salvar e feche o painel de designer. Uma visualização do cartão é exibida no nó. O Copilot Studio cria automaticamente variáveis de saída com base nas entradas especificadas no código.

   

   Gorjeta

   Se as variáveis de saída geradas para o cartão estiverem incorretas, você poderá atualizar manualmente a lista de variáveis e seus tipos selecionando Editar esquema no painel de Propriedades do nó do Cartão adaptável.

   Seu Cartão Adaptável interativo está pronto. Quando um usuário do agente seleciona um botão de envio em um cartão, as variáveis de saída são preenchidas com as informações fornecidas pelo usuário em sua interação com o cartão.

Outras propriedades

Outras propriedades permitem controlar o comportamento do nó Cartão Adaptável, como:

• Como o agente responde a uma resposta inválida
• Se puder ser interrompido

Se o agente estiver aguardando um envio de um Cartão Adaptável e o usuário enviar uma mensagem de texto, essa resposta será considerada inválida, a menos que a mensagem dispare uma interrupção. Nesse caso, as seguintes propriedades determinam o comportamento.

• Quantas novas solicitações: o número de vezes que seu agente tenta obter um envio válido do cartão. Repetir até 2 vezes é o padrão. Você também pode selecionar Repetir uma vez ou Não repetir. A cada repetição, o cartão é reenviado ao usuário.

• Repetir solicitação: use esta propriedade para definir uma mensagem a ser enviada quando ocorrer uma repetição, juntamente com uma repetição do cartão. Para definir uma mensagem de repetição, selecione Personalizar e insira a nova solicitação.

• Permitir a alternância para outro tópico: se selecionado (padrão), uma mensagem recebida de um usuário quando o agente está aguardando o envio de um cartão dispara uma interrupção e alterna para outro tópico. Se ocorrer uma alternância de tópico, o cartão será reenviado para o usuário assim que o tópico de interrupção terminar.

Comportamento do botão de envio para agentes com cartões consecutivos

Por projeto, os Cartões Adaptáveis permitem a seleção dos botões de envio várias vezes. Se um agente tiver Cartões Adaptáveis consecutivos e o usuário selecionar um botão em um cartão anterior, o usuário poderá experimentar um comportamento inesperado.

Para evitar que a ação de envio em um cartão interfira em outro:

• Isolar ações de envio: verifique se cada Cartão Adaptável tem seu próprio identificador exclusivo e manipuladores de ação.

• Use ações de envio com dados exclusivos: ao definir as ações de envio para os cartões, inclua identificadores exclusivos ou cargas úteis de dados capazes de ajudar a diferenciar os cartões quando o usuário seleciona um botão de enviar.

• Adicione uma lógica de processamento de eventos robusta ao agente: defina condições com base nos identificadores distintos ou elementos de conteúdo associados aos botões de envio.

• Depurar e registrar: adicione um registro detalhado ao código de tratamento de eventos do agente para capturar a sequência de ações e identificar onde ocorrem envios não intencionais.

Usar o Power Fx para tornar seu cartão dinâmico

Você pode usar uma fórmula do Power Fx para incluir informações dinâmicas em seu cartão fazendo referência a variáveis de seu tópico ou agente.

1. Selecione os três pontos (...) do nó e, em seguida, selecione Propriedades.

2. No painel Propriedades do Nó do Cartão Adaptável, alterne para Fórmula. A seleção de Fórmula converte automaticamente a representação JSON do cartão em uma fórmula do Power Fx.

   

   Por exemplo, comece com o seguinte literal JSON para um cartão:

   {
     "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
     "type": "AdaptiveCard",
     "version": "1.5",
     "body": [{
         "type": "ColumnSet",
         "columns": [{
             "type": "Column",
             "width": 2,
             "items": [{
                 "type": "TextBlock",
                 "text": "Tell us about yourself",
                 "weight": "Bolder",
                 "size": "Medium",
                 "wrap": true,
                 "style": "heading"
               }, {
                 "type": "TextBlock",
                 "text": "We just need a few more details to get you booked for the trip of a lifetime!",
                 "isSubtle": true,
                 "wrap": true
               }, {
                 "type": "Input.Text",
                 "id": "myName",
                 "label": "Your name (Last, First)",
                 "isRequired": true,
                 "regex": "^[A-Z][a-z]+, [A-Z][a-z]+$",
                 "errorMessage": "Please enter your name in the specified format"
               }
             ]
           }
         ]
       }
     ],
     "actions": [{
         "type": "Action.Submit",
         "title": "Submit"
       }
     ]
   }
   

   Aqui está a fórmula resultante do Power Fx, usando duas variáveis Topic.Title e Topic.Subtitle em vez do texto embutido em código do literal do JSON. (Este exemplo pressupõe que as variáveis sejam definidas em seu tópico.)

   {
     '$schema': "http://adaptivecards.io/schemas/adaptive-card.json",
     type: "AdaptiveCard",
     version: "1.5",
     body: [
       {
         type: "ColumnSet",
         columns: [
           {
             type: "Column",
             width: "2",
             items: [
               {
                 type: "TextBlock",
                 text: Topic.Title,
                 weight: "Bolder",
                 size: "Medium",
                 wrap: true,
                 style: "heading"
               },
               {
                 type: "TextBlock",
                 text: Topic.Subtitle,
                 isSubtle: true,
                 wrap: true
               },
               {
                 type: "Input.Text",
                 id: "myName",
                 label: "Your name (Last, First)",
                 isRequired: true,
                 regex: "^[A-Z][a-z]+, [A-Z][a-z]+$",
                 errorMessage: "Please enter your name in the specified format"
               }
             ]
           }
         ]
       }
     ],
     actions: [
       {
         type: "Action.Submit",
         title: "Submit"
       }
     ]
   }