Partilhar via

Reutilizar variáveis entre tópicos

  • Artigo

Importante

As capacidades e os recursos do Power Virtual Agents agora fazem parte do Microsoft Copilot Studio após investimentos significativos em IA generativa e integrações aprimoradas no Microsoft Copilot.

Alguns artigos e capturas de tela podem fazer referência ao Power Virtual Agents enquanto atualizamos a documentação e o conteúdo do treinamento.

As variáveis armazenam as respostas de seus clientes às perguntas de seu copiloto. Por exemplo, você pode salvar o nome de um cliente em uma variável chamada UserName. O copiloto pode tratar o cliente pelo nome enquanto a conversa continua.

Por padrão, o valor de uma variável só pode ser usado no tópico em que ela é criada. No entanto, é possível reutilizar o mesmo valor entre tópicos. Por exemplo, um tópico Bem-vindo solicita o nome e o email do cliente. No tópico Reserva de Compromisso, você quer que o copiloto lembre o que o cliente digitou e não pergunte novamente.

Uma maneira de reutilizar uma variável é transmitir a variável entre os tópicos. A outra maneira é tornar a variável global no escopo, e é isso que este artigo cobre. As variáveis globais são chamadas assim porque estão disponíveis em todos os tópicos em todo o copiloto.

As variáveis de copiloto se aplicam durante uma única sessão do usuário. Você especifica quais variáveis devem ser tratadas como variáveis de copiloto para distingui-las das variáveis no nível do tópico.

Criar uma variável global

Você cria uma variável global ao alterar o escopo de uma variável temática.

  1. Criar uma variável ou usar o painel Variáveis para abrir uma variável existente.

  2. No painel Propriedades da variável, selecione Global (acessível por qualquer tópico).

    O nome da variável receberá o prefixo Global. para diferenciá-lo das variáveis no nível do tópico. Por exemplo, a variável UserName é exibida como Global.UserName.

    Captura de tela mostrando o painel Propriedades da Variável, com Configuração global realçado.

  3. Salve o tópico.

    O nome de uma variável global deve ser exclusivo em todos os tópicos. No caso de um conflito, você precisará renomear a variável antes de salvar sua alteração.

Usar variáveis globais

Quando estiver escrevendo uma mensagem do copiloto em um nó de Mensagem ou em um nó de Pergunta, selecione o ícone {x} para exibir as variáveis disponíveis no tópico. As variáveis globais são listadas na guia Personalizado, juntamente com quaisquer variáveis de tópico. As variáveis são classificadas em ordem alfabética.

Captura de tela mostrando a seleção de uma variável global.

Encontre todos os tópicos usando uma variável global

Você pode encontrar onde uma variável global é definida e que outros tópicos a estão usando. Isso pode ser útil se você estiver trabalhando em um novo copiloto ou se tiver várias variáveis e ramificação de tópicos complexos.

  1. Selecione uma variável global na tela de criação ou abra o painel Variáveis e selecione uma variável global.

  2. No painel Propriedades da variável, na seção Referência, selecione qualquer um dos tópicos em que a variável é usada para ir diretamente para esse tópico e nó.

    Captura de tela mostrando a lista de tópicos usados por uma variável no painel Propriedades da Variável.

Ciclo de vida de variáveis globais

Por padrão, o valor de uma variável global persiste até a sessão terminar. O nó Desmarcar valores de variáveis redefine os valores de variáveis globais e é usado no tópico do sistema Redefinir conversa. Esse tópico pode ser acionado por redirecionamento ou quando o usuário digita uma frase de gatilho como "Começar de novo". Nesse caso, todas as variáveis globais são redefinidas.

Definir o valor de uma variável global de origens externas

Se quiser garantir que o copiloto inicie uma conversa com algum contexto, você pode inicializar uma variável global com uma fonte externa. Digamos que seu site exija que os usuários façam login. Como já sabe o nome de um usuário, o copiloto pode cumprimentar os clientes pelo nome antes que eles comecem a digitar a primeira pergunta.

  1. Selecione uma variável global.

  2. No painel Propriedades de variável, selecione Fontes externas podem definir valores.

Definir variáveis globais em um copiloto incorporado

Se estiver incorporando seu copiloto em uma página da Web simples, você poderá anexar variáveis e suas definições à URL do copiloto. Ou, se quiser um pouco mais de controle, você pode usar um bloco de código <script> para chamar e usar variáveis de forma programada.

O nome da variável na cadeia de consulta do URL deve corresponder ao nome da variável global sem o prefixo Global.. Por exemplo, uma variável global Global.UserName seria referida como UserName na consulta.

Os exemplos que se seguem fornecem uma declaração simples para as variáveis. Em um cenário de produção, é possível passar outra variável que já armazenou o nome do usuário como o parâmetro de consulta ou a definição de variável (por exemplo, se você tiver o nome de usuário em um script de entrada).

Anexe as variáveis e suas definições à URL do copiloto como parâmetros da cadeia de caracteres de consulta no formato de botURL?variableName1=variableDefinition1&variableName2=variableDefinition2.

Por exemplo:

O nome do parâmetro não faz distinção entre maiúsculas e minúsculas. username=Renata também funcionará neste exemplo.

Adicionar variáveis globais a uma tela personalizada

Você também pode adicionar a variável a uma tela personalizada.

  1. Na seção <script> na página em que você tem seu copiloto, defina as variáveis da seguinte maneira, substituindo variableName1 pelo nome da variável sem o prefixo Global. e variableDefinition1 pela definição. Separe as muitas variáveis com vírgulas (,).

       const store = WebChat.createStore({}, ({ dispatch }) => next => action => {
     if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
       dispatch({
          type: "WEB_CHAT/SEND_EVENT",
          payload: {
            name: "pvaSetContext",
            value: {
               "variableName1": "variableDefinition1",
               "variableName2": "variableDefinition2"
            }
          },
        });
      }
        return next(action);
    });

  2. Em sua seção <script>, ligue para store quando inserir seu copiloto, como no exemplo a seguir, store é chamado logo acima de onde styleOptions é chamado (você precisará substituir BOT_ID por sua ID do copiloto):

    const BOT_ID = "12345-5678";
const theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;

fetch(theURL)
    .then(response => response.json())
    .then(conversationInfo => {
        window.WebChat.renderWebChat(
            {
                directLine: window.WebChat.createDirectLine({
                    token: conversationInfo.token,
                }),
                store,
                styleOptions
            },
            document.getElementById('webchat')
        );
    })
    .catch(err => console.error("An error occurred: " + err));