Compartilhar via

Trabalhar com variáveis

Você pode usar variáveis para armazenar as respostas dos clientes e reutilizar seu conteúdo posteriormente na conversa.

Você também pode usar variáveis para criar expressões lógicas que direcionam dinamicamente o cliente por diferentes caminhos de conversa. Por exemplo, salve o nome de um cliente em uma variável chamada "customerName," e o agente pode se dirigir ao cliente pelo nome enquanto a conversa continua.

As variáveis também podem ser passadas e retornadas de Outros tópicos e Fluxos do Power Automate.

Criar uma variável

Qualquer nó que retorna uma saída, como um nó Question , cria automaticamente uma variável de saída do tipo apropriado.

Captura de tela de um

Gorjeta

Renomeie os nós para torná-los mais fáceis de identificar. Selecione o campo de nome do nó para atualizar o nome diretamente, ou selecione os três pontos (...) do nó e selecione Renomear no menu. Você também pode renomear nós no editor de código.

Não é possível renomear os nós de Gatilho e os nós Ir para etapa.

Os nomes do nó podem ter até 500 caracteres.

Escolha uma entidade para usar

Os nós de Pergunta são criados com opções de múltipla escolha por padrão. Para usar uma entidade predefinida ou personalizada diferente, selecione a caixa Identificar e selecione o tipo de informação desejado.

Captura de tela do nó Pergunta com o painel

Renomear uma variável

As variáveis criadas automaticamente recebem um nome padrão ao ser criadas. Uma prática recomendada é dar às suas variáveis nomes significativos para deixar sua finalidade clara para qualquer pessoa que precise manter seu agente.

  1. Selecione a variável. O painel Propriedades da variável é exibido.

  2. Em Nome da variável, insira o nome desejado para sua variável.

Definir uma variável

Normalmente, você usa um nó de Pergunta para armazenar a entrada do usuário em uma variável. No entanto, pode haver situações em que você deseja definir o valor de uma variável por conta própria. Nesses casos, use um nó Definir valor da variável.

  1. Selecione o ícone Adicionar nó no nó após o qual você deseja adicionar um nó Definir valor da variável.

  2. Selecione Gerenciamento> devariável Definir um valor variável. Um nó Definir valor da variável aparece na tela.

  3. Selecione a caixa em Definir variável, e então selecione Criar uma nova variável. Uma nova variável é criada. Seu tipo é desconhecido até que você atribua um valor a ele.

    Captura de tela do nó

  4. Para Valor de destino, atribua um valor usando uma das seguintes opções:

    • Digite um valor literal
    • Selecione uma variável existente do mesmo tipo.
    • Use uma Fórmula do Power Fx. As fórmulas do Power Fx são úteis para tipos mais complexos onde os valores literais não podem ser usados, tais como os tipos Tabela e Registro.

Usar variáveis em nós de ação

Quando você usa uma variável em um nó action , se seu tipo base corresponder a um tipo de parâmetro especificado para um fluxo ou para uma habilidade do Bot Framework, você poderá alimentá-la para esse parâmetro. A saída dos nós de Ação gera novas variáveis.

Para obter mais contexto, consulte os cenários de exemplo em Chamar um fluxo de agente de um tópico e usar variáveis de entrada e saída para passar informações.

Usar valores literais para entradas de variável

Nos nós em que é possível definir um valor para os parâmetros de entrada, você sempre pode inserir um valor literal em vez de selecionar outra variável como o valor.

Captura de tela mostrando o uso de um valor literal para um parâmetro de entrada de variável chamado productName.

O nó tenta interpretar valores literais como uma cadeia de caracteres, um número ou um booliano. Por exemplo, 123 é interpretado como um número. Se você quiser que ele seja interpretado como um valor de cadeia, você pode empacotar o valor em aspas duplas, como esta: "123".

Para alguns cenários (por exemplo, cenários que usam tipos complexos), pode ser necessário usar uma Fórmula do Power Fx para definir um tipo específico.

Usar variáveis de ambiente em segredos do Azure Key Vault

Uma variável de ambiente pode fazer referência a um segredo no Cofre de Chaves. Variáveis de ambiente secretas são um caso especial de variáveis de ambiente com considerações exclusivas.

Para criar uma variável de ambiente secreta no portal do Power Apps, você deve configurar seu Key Vault.

Para autorizar o Copilot Studio a ler este Key Vault, você deve realizar as seguintes ações:

  1. Atribua a função de Usuário de Segredos do Key Vault ao aplicativo Microsoft Copilot Studio Service.

  2. Para autorizar todos os agentes do ambiente a acessar o segredo, crie uma marca AllowedEnvironments no segredo e adicione as IDs de ambiente permitidas separadas por vírgulas.

  3. Para autorizar apenas agentes específicos do ambiente a usar esse Key Vault, crie uma marca AllowedAgents e coloque o identificador do agente no formato {envId}/{schemaName}. Para vários valores, separe os valores com vírgulas.

    Se você atingir o número máximo de caracteres, mas ainda precisar adicionar mais agentes, adicione outra marca com um nome descritivo, mas exclusivo (por exemplo: AllowedAgents2).

O valor do segredo é armazenado em cache no tempo de execução do Diálogo por cinco minutos. As leituras malsucedidas são armazenadas em cache por 30 segundos.

Aviso

Ao adicionar o segredo no agente, você pode expor o valor desse segredo. Qualquer pessoa que possa editar o agente no ambiente pode adicionar um nó de mensagem e retornar o valor das variáveis de ambiente secretas em uma mensagem.

Painel Variáveis

O painel Variáveis é onde você pode exibir todas as variáveis disponíveis para um tópico, independentemente de em quais nós elas são definidas ou usadas. Para cada variável, você pode selecionar se ela pode receber seu valor de outros tópicos, retornar seu valor para outros tópicos ou ambos. Você também pode selecionar uma variável para editar suas propriedades no painel Propriedades da variável.

Para abrir o painel Variáveis , selecione Variáveis na barra de menus do tópico.

Captura de tela do painel Variáveis, com o botão Variáveis realçado.

Painel Propriedades da variável

No painel Propriedades variáveis , você pode renomear uma variável, ver onde seu agente a usa ou convertê-la em uma variável global. No entanto, você não pode converter uma variável global de volta em uma variável de tópico. Você também pode selecionar se uma variável de tópico pode receber valores ou passar seu valor para outros tópicos.

Para abrir o painel de Propriedades da variável de uma variável, selecione a variável desejada no painel Variáveis. Você também pode abrir o painel Propriedades variáveis de qualquer nó que usa variáveis, selecionando a variável desejada.

Passando variáveis entre tópicos

Ao redirecionar um tópico para outro, você pode passar os valores das variáveis do tópico de origem para o tópico de destino e também retornar valores do tópico de destino para o tópico de origem. A passagem de variáveis entre tópicos é especialmente útil quando você já tem informações de que o tópico precisa. Seus usuários certamente apreciam não ter que responder às mesmas perguntas mais de uma vez.

Receber valores de outros tópicos

Quando um tópico define uma variável (por exemplo, em um nó de Pergunta), o agente faz a pergunta ao usuário para preencher o valor da variável. Se o valor já tiver sido adquirido pelo agente em um tópico anterior, não há motivo para fazer a pergunta novamente. Nesses casos, você pode definir a variável como Receber valores de outros tópicos. Quando outro tópico redireciona para este, ele pode então passar uma variável ou um valor literal nesta variável e ignorar a questão completamente. A experiência do usuário ao falar com o agente é simples.

Neste exemplo, usamos dois tópicos: Saudação e Conversar com o Cliente. Ambos os tópicos pedem o nome do cliente. No entanto, se o tópico Saudação for executado primeiro, o tópico Conversar com o Cliente ignora sua pergunta. Em vez disso, ele usa o valor da variável passada do tópico Saudação.

Aqui está o fluxo do tópico Conversar com o Cliente:

Captura de tela do fluxo de conversa do tópico Conversar com o Cliente.

Conforme mostrado no painel de teste, se esse tópico for acionado primeiro, ele perguntará ao usuário: "Como devo chamá-lo?" Ele armazena o valor em uma variável de cadeia de caracteres chamada customerName. A variável customerName também é definida para obter seu valor de outros tópicos. O tópico termina com a mensagem: "Espero que você esteja tendo um dia maravilhoso, customerName!"

Aqui está o fluxo do tópico Saudação:

Captura de tela do fluxo de conversa do tópico Saudação.

Conforme mostrado no painel de teste, se esse tópico for acionado primeiro, ele perguntará ao usuário: "Qual é o seu nome?" Ele armazena o valor em uma variável de cadeia de caracteres chamada customerName. O tópico envia a mensagem: "Prazer em conhecê-lo, customerName!" Em seguida, ele redireciona para o tópico Conversar com o Cliente que envia a mensagem: "Espero que você esteja tendo um dia maravilhoso, customerName!" Observe, no entanto que o tópico Conversar com o Cliente pulou a pergunta sobre o nome do usuário novamente. Em vez disso, ele usou o valor da variável customerName informada do tópico Saudação.

Por fim, aqui está a segunda conversa novamente, desta vez sob a perspectiva do tópico Conversar com o Cliente:

Captura de tela do fluxo de conversa do tópico Conversar com o Cliente quando o tópico Saudação é disparado primeiro.

Vamos percorrer as etapas para configurar um tópico para receber valores de outros tópicos. Nosso cenário de exemplo usa o tópico predefinido Saudação como o tópico de origem e um novo tópico Conversar com o Cliente como o tópico de destino, mas as mesmas etapas funcionam para qualquer tópico que deve usar um valor de um tópico anterior quando possível.

Configurar o tópico de destino

O tópico de destino é o tópico para o qual está sendo redirecionado, aquele que recebe valores de outros tópicos. Em nosso exemplo, é Conversar com o Cliente.

  1. Crie um novo tópico e chame-o de "Conversar com o Cliente".

  2. Adicione frases de gatilho como "fale comigo", "converse comigo", "bata um papo comigo".

  3. Adicione um nó Pergunta e insira "Como devo chamá-lo?" na mensagem.

  4. Em Identificar, selecione a entidade predefinida Nome da pessoa.

  5. Selecione o nome da variável. O painel Propriedades da variável é aberto.

  6. Substitua o nome padrão por "customerName" e selecione Receber valores de outros tópicos.

    Captura de tela do painel 'Propriedades da variável' mostrando a variável customerName e suas propriedades.

  7. Adicionar um nó Mensagem.

  8. Na caixa de mensagem, digite "Espero que você esteja tendo um dia maravilhoso, ".

  9. Selecione o ícone Inserir variável ({x}) e escolha customerName.

  10. Selecione o espaço após a variável e digite "!".

  11. Salve o tópico.

Configurar a fonte de dados

O tópico de origem é o tópico que faz o redirecionamento, aquele que fornece o valor e o passa para o tópico de destino. Em nosso exemplo, é Saudação.

  1. Vá para o tópico Saudação e exclua os nós padrão, exceto o nó de Gatilho.

  2. Adicione um nó Pergunta e insira "Qual é o seu nome?" na mensagem.

  3. Em Identificar, selecione a entidade predefinida Nome da pessoa.

  4. Substitua o nome padrão por "customerNameFromGreeting".

  5. Adicionar um nó Mensagem.

  6. Na caixa de mensagem, digite "Prazer em conhecê-lo, ".

  7. Selecione o ícone Inserir variável ({x}) e escolha customerNameFromGreeting.

  8. Selecione o espaço após a variável e digite "!".

  9. Adicione um nó de Redirecionamento e selecione o tópico de destino Conversar com o Cliente.

  10. Selecione Adicionar entrada, e então selecione a variável do tópico de destino para o qual você deseja passar um valor.

    Captura de tela do tópico Saudação com a variável customerName adicionada como entrada em um nó de redirecionamento.

  11. Selecione o ícone >, e, em seguida, selecione a variável cujo valor você deseja passar, customerNameFromGreeting, neste exemplo.

    O nó Redirecionamento deve parecer com este:

    Captura de tela do nó Redirecionar concluído no tópico Saudação.

  12. Salve o tópico.

Retornar valores aos tópicos originais

Em um agente, um tópico destina-se a coletar uma informação específica. Vários outros tópicos podem chamá-lo e esperar que ele retorne as informações como uma variável. A variável se torna parte do tópico de origem e pode ser usada como qualquer outra variável. As informações obtidas pelo agente ficam disponíveis em todos os tópicos, reduzindo a necessidade de variáveis globais.

Vamos continuar com o exemplo da seção anterior. Fazemos uma nova pergunta no tópico Conversar com o Cliente e depois retornamos a resposta para o tópico Saudação.

Configure o tópico de origem para uma variável retornada

Quando você está retornando uma variável para um tópico, o tópico de origem é o tópico que fornece o valor a ser informado de volta para o tópico original. Neste exemplo, o tópico de origem é Conversar com o Cliente.

  1. Ir para o tópico da fonte.

  2. Adicione um nó Pergunta e insira "Em que cidade você mora?" na mensagem.

  3. Em Identificar, selecione a entidade predefinida Cidade.

  4. Select a variável para abri-la no painel Propriedades da variável. Nomeie-o como "customerCity" e selecione Retornar valores para os tópicos originais.

    Captura de tela do tópico Conversar com o Cliente com a variável customerCity e suas propriedades destacadas.

  5. Adicionar um nó Mensagem.

  6. Selecione o ícone Inserir variável ({x}) e escolha customerCity.

  7. Após a variável na caixa de mensagem, insira "deve ser bonito nesta época do ano!".

  8. Salve o tópico.

Configure o tópico de destino para uma variável retornada

Quando você está retornando uma variável para um tópico, o tópico de destino é o tópico que recebe valores do tópico atual. Em nosso exemplo, o tópico de destino é Saudação.

  1. Ir para o tópico de destino.

  2. A variável selecionada no tópico de origem deve aparecer no nó Redirecionar como uma variável de saída.

    Captura de tela do fluxo de conversa do tópico Saudação com a variável returned em um nó Redirecionar.

  3. Salve o tópico.

Analisar valores

O nó Analisar valor permite que você converta um valor de um tipo em um valor de outro tipo. Um caso de uso comum para o nó Parse value é converter JSON bruto. Por exemplo, um agente chama um fluxo, que, por sua vez, chama uma API. A API retorna um resultado. Agora você precisa de uma maneira de analisar esse resultado e retornar uma ou mais variáveis primitivas. Com o nó Analisar valor, você pode enviar todo o resultado da API como uma cadeia de caracteres, como o seguinte:

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

O nó Analisar valor pode converter a variável de cadeia de caracteres que você tem agora em uma variável do tipo Registro, para a qual o editor do Power Fx fornece conclusão de código e sugestões do IntelliSense.

Além de analisar cadeias de caracteres JSON, um uso principal do nó Analisar valor é analisar objetos sem tipo no runtime. O caso de uso mais comum é quando você recebe um evento e precisa analisar o valor dele. Ou talvez você queira analisar a propriedade System.Activity.ChannelData, que varia por canal durante o tempo de execução.

Se você precisar analisar informações de um evento proveniente do Teams, consulte a documentação do desenvolvedor do Teams para encontrar um exemplo da aparência do evento esperado. Em seguida, você pode seguir as instruções nesta seção, usando o evento de exemplo como informação adicional.

Para adicionar um nó Analisar valor a um tópico:

  1. Selecione o ícone Adicionar nó no nó após o qual você deseja analisar um valor, aponte para Gerenciamento de Variáveis e selecione Analisar valor.

  2. Adicione um nó Analisar valor e selecione a variável que deseja analisar.

    Captura de tela mostrando a seleção da variável a ser analisada.

  3. Selecione o tipo de dados. Nesse caso, escolha Dos Dados de Exemplo.

    Captura de tela mostrando a seleção do tipo de dados para um nó Analisar Valor.

  4. Selecione Obter Esquema do Exemplo de JSON, insira o exemplo JSON desejado no editor que é aberto e selecione Confirmar.

    Captura de tela mostrando o editor em que você insere dados JSON de exemplo.

  5. Por fim, selecione a variável para manter o valor analisado. Normalmente, você criaria uma nova variável.

    Captura de tela mostrando como criar uma variável para manter um valor analisado diretamente do nó Analisar valor.

    A variável de saída agora tem o tipo esperado: registro.

    Captura de tela mostrando que a variável que contém os dados analisados tem o tipo esperado: registro.

Conteúdo relacionado

  • Last updated on