Perguntar com Cartões Adaptativos

Os Cartões Adaptativos permitem adicionar fragmentos de conteúdo aos agentes do Copilot Studio, que também podem ser trocados livremente com outras aplicações e serviços cloud. Para fornecer uma capacidade de conversação avançada no seu agente, pode incluir texto, gráficos e botões. Como são independentes da plataforma, pode personalizar facilmente os Cartões Adaptativos às suas necessidades.

Com um nó Cartão Adaptativo, o seu agente pode mostrar um Cartão Adaptativo que contém um ou mais botões Submeter e, opcionalmente, um ou mais campos de entrada de formulário. O seu agente armazena a entrada de utilizador em variáveis para utilização posterior na conversa.

O Copilot Studio inclui um estruturador de cartões adaptativos incorporado, que oferece as funcionalidades mais úteis do Estruturador de Cartões Adaptativos.

Em alternativa, pode:

• Utilizar uma representação JSON para o cartão que pretende mostrar ao utilizador.
• Utilize uma fórmula Power Fx para incluir informações dinâmicas no cartão.

Também pode controlar o comportamento do cartão, por exemplo, o que fazer quando o utilizador introduz uma resposta inválida ou se o nó pode ser interrompido.

O nó Cartão Adaptativo destina-se a cartões interativos, onde se espera que o utilizador submeta uma resposta. Os nós Mensagem e Pergunta podem ser utilizados para apresentar ao utilizador um cartão não interativo, para mostrar informações ao utilizador.

Adicionar um nó de Cartão Adaptativo

1. Selecione o ícone Adicionar nó por baixo do nó após o qual pretende adicionar um nó de Cartão Adaptativo e, em seguida, selecione Perguntar com Cartão Adaptativo.

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

3. No painel de propriedades do nó do Cartão Adaptativo, selecione Editar cartão adaptativo. O painel do estruturador do Cartão Adaptativo é aberto.

4. Adicione os elementos pretendidos ao seu cartão e configure as respetivas propriedades. Como alternativa, no painel Editor de payload do cartão, substitua o payload predefinido pelo literal JSON do seu cartão.

   Gorjeta

   O cartão deve conter pelo menos um botão Submeter, já que se trata de um cartão interativo que permite ao utilizador enviar informações ao agente. Se não tiver esse botão e se destinar apenas a mostrar informações, deve adicionar o seu cartão adaptativo a um nó de mensagem.

5. Quando terminar o design inicial, selecione Guardar e feche o painel do estruturador. Uma pré-visualização do seu cartão é apresentada 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 seu cartão estiverem incorretas, poderá atualizar manualmente a lista de variáveis e respetivos tipos selecionando Editar esquema no painel de propriedades do nó do Cartão Adaptativo.

   O seu Cartão Adaptativo interativo está pronto. Quando um utilizador do seu agente seleciona o botão Submeter num cartão, as variáveis de saída são preenchidas com as informações que o utilizador forneceu quando interagiu com o cartão.

Outras propriedades

Outras propriedades permitem controlar o comportamento do nó do Cartão Adaptativo, por exemplo:

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

Se o agente estiver a aguardar uma submissão de um Cartão Adaptativo e o utilizador enviar uma mensagem de texto em vez disso, essa resposta é considerada inválida, a menos que a mensagem acione uma interrupção. Neste caso, as propriedades seguintes determinam o comportamento.

• Número de novos pedidos: o número de vezes que o seu agente tenta obter uma submissão válida do cartão. Repetir até 2 vezes é a predefinição. Também pode selecionar Repetir uma vez ou Não repetir. A cada nova tentativa, o cartão é reenviado ao utilizador.

• Pedido para tentar novamente: utilize esta propriedade para definir a mensagem a enviar quando ocorre uma nova tentativa, juntamente com a repetição do cartão. Para definir uma mensagem de nova tentativa, selecione Personalizar e introduza o novo pedido.

• Permitir a mudança para outro tópico: se esta opção estiver selecionada (predefinição), uma mensagem a receber de um utilizador, enquanto o agente está a aguardar a submissão de um cartão, aciona uma interrupção e muda para outro tópico. Caso ocorra uma mudança de tópico, o cartão será novamente enviado para o utilizador assim que o tópico que causou a interrupção terminar.

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

Por predefinição, os Cartões Adaptativos permitem selecionar os seus botões de submissão várias vezes. Se um agente tiver Cartões Adaptativos consecutivos e o utilizador selecionar um botão num cartão anterior, o utilizador poderá deparar-se com um comportamento inesperado.

Para evitar que a ação de submissão de um cartão interfira com a de outro:

• Isolar ações de submissão: certifique-se de que cada Cartão Adaptativo tem o seu próprio identificador exclusivo e processadores de ações.

• Utilizar ações de submissão com dados exclusivos: ao definir as ações de submissão para os seus cartões, inclua identificadores ou payloads de dados que possam ajudar a diferenciar os cartões quando o utilizador seleciona um botão de submissão.

• Adicionar uma lógica robusta de tratamento de eventos ao seu agente: defina condições com base nos identificadores distintivos ou elementos de payload associados aos seus botões de submissão.

• Depurar e registar: adicione registos detalhados ao código de tratamento de eventos do seu agente para capturar a sequência de ações e identificar onde ocorrem submissões não intencionais.

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

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

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

2. No painel de propriedades do Nó do Cartão Adaptativo, mude para Fórmula. Selecionar Fórmula converte automaticamente a representação JSON do seu cartão numa 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 do Power Fx resultante, utilizando duas variáveis Topic.Title e Topic.Subtitle em vez do texto hard-coded do literal JSON. (Este exemplo pressupõe que as variáveis estão definidas no 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"
       }
     ]
   }