Visão geral das variáveis

As variáveis existem em quatro níveis, ou escopos:

  • Variáveis de tópico você só pode usar nos tópicos onde você as cria. Este escopo é o padrão para as variáveis que você cria.
  • Variáveis globais você pode usar em todos os tópicos. Você pode alterar o escopo de qualquer variável de tópico para torná-la uma variável global.
  • Variáveis do sistema que o Copilot Studio cria automaticamente para um agente. Eles fornecem informações mais contextuais sobre a conversa ou o usuário. Estão disponíveis em todos os tópicos.
  • Variáveis de ambiente que você cria no Power Platform. Elas são definidas como apenas leitura no Copilot Studio. Elas armazenam as chaves e os valores dos parâmetros, que poderão então servir como entrada para vários outros objetos do aplicativo, incluindo o Copilot Studio. Separar os parâmetros dos objetos de consumo permite alterar os valores dentro do mesmo ambiente ou ao migrar soluções para outros ambientes. A alternativa é deixar valores de parâmetros codificados nos componentes que os usam.

Tipos de variáveis

Cada variável tem um tipo base. O tipo base determina quais valores a variável podem armazenar e quais operadores que você pode usar ao criar uma expressão lógica com ela.

Tipo Description
String Uma sequência de caracteres usada para representar texto
booleano Um valor lógico que só pode ser true ou false
Número Qualquer número real
Tabela Uma lista de valores, mas todos os valores devem ser do mesmo tipo
Gravar Uma coleção de pares nome-valor em que os valores podem ser de qualquer tipo
Data e hora Uma data, hora, dia da semana ou mês em relação a um ponto no tempo
Escolha Uma lista de valores de cadeia de caracteres com sinônimos associados
Em Branco Um espaço reservado para "sem valor" ou "valor desconhecido"; para obter mais informações, consulte Em branco na documentação do Power Fx

Você define o tipo de uma variável na primeira vez que atribui um valor a ela. Depois disso, o tipo é fixo e você não pode atribuir valores de nenhum outro tipo. Por exemplo, se você atribuir o valor inicial 1 a uma variável, defina seu tipo como Número. Se você tentar atribuir um valor de Cadeia de caracteres como "apples", receberá um erro.

Quando você testa um agente, uma variável pode aparecer temporariamente com o tipo desconhecido. Uma variável desconhecida ainda não tem um valor.

A ordem das variáveis é determinada de cima para baixo na tela de criação. Os nós na parte superior da tela de criação são considerados antes dos nós na parte inferior.

Quando você cria ramificações com nós Condição, as ramificações são ordenadas da esquerda para a direita. Os nós na ramificação mais à esquerda são considerados antes dos nós na ramificação mais à direita.

Entidades

O Copilot Studio usa entidades para identificar tipos específicos de informação das respostas de um usuário. As informações identificadas são salvas em uma variável do tipo apropriado para as informações. A tabela a seguir lista o tipo base de variável associado a entidades predefinidas.

Entidade Tipo base de variável
Opções de múltipla escolha Escolha
Resposta completa do usuário String
Idade Número
booleano booleano
Cidade String
Cor String
Continent String
País ou região String
Data e hora Data e hora
Email String
Evento String
Inteiro Inteiro
Linguagem String
Dinheiro Número
Número Número
Ordinal Número
Organização String
Percentual Número
Nome da pessoa String
Número de telefone String
Ponto de interesse String
Velocidade Número
Estadual String
Endereço String
Temperatura Número
URL String
Peso Número
CEP String
Entidade personalizada Escolha

Variáveis de ambiente

Variáveis de ambiente são um conceito do Power Platform. As variáveis de ambiente permitem o cenário básico de gerenciamento do ciclo de vida do aplicativo (ALM) de mover um aplicativo entre ambientes da Power Platform. Nesse cenário, o aplicativo permanece exatamente o mesmo, exceto por algumas referências externas importantes que são diferentes entre o ambiente de origem e o ambiente de destino.

Use as variáveis do ambiente da mesma forma que as variáveis de tópico, globais e do sistema. A principal diferença é que, no Copilot Studio, as variáveis de ambiente são somente leitura. Os criadores do agente não podem modificar variáveis de ambiente no Copilot Studio. No entanto, os administradores podem alterar o valor das variáveis de ambiente no Power Apps. Em Copilot Studio, você pode usar o painel Variáveis para ver informações sobre uma variável de ambiente. O painel de propriedades de variáveis também tem um link para o Power Apps, a experiência de criação para variáveis de ambiente.

A versão publicada de um agente que usa variáveis de ambiente tem os valores definidos para essas variáveis quando você publica o agente. Sempre que um administrador atualizar variáveis de ambiente, você deverá republicar quaisquer agentes que usem essas variáveis para que as alterações sejam efetivas no runtime. No entanto, há uma exceção: você não precisa republicar seus agentes quando o valor de uma variável de ambiente do tipo segredo é alterado. Ao contrário de outras variáveis de ambiente, as variáveis secretas são recuperadas no runtime.

Os tipos de variável de ambiente no Copilot Studio são mapeados para tipos de dados do Power Apps da seguinte maneira:

Digite no Copilot Studio Digite no Power Apps
Número decimal Número
JSON Detecte o tipo a partir do valor. Caso não seja JSON=> Não especificado (erro de validação)
Texto String
Sim/Não booleano
Fonte de dados String
Secret String

Note

Erros de variável de ambiente são visíveis no chat de teste e durante a publicação. No entanto, esses erros não são mostrados na lista Tópico porque não são variáveis de tópico.

Variáveis do sistema

Cada agente vem com variáveis de sistema internas que fornecem informações extras sobre uma conversa.

Captura de tela das variáveis de sistema em um tópico do agente.

Note

Para obter mais informações sobre variáveis agente habilitadas para voz, consulte Usar variáveis de voz.

O Copilot Studio não mostra todas as variáveis do sistema. Para acessar variáveis ocultas do sistema, use uma Fórmula do Power Fx.

Para usar variáveis do sistema em uma fórmula do Power Fx, adicione System. antes do nome da variável. Por exemplo, para incluir a variável do sistema User.DisplayName em uma fórmula, consulte-a como System.User.DisplayName.

Name Tipo Definição
Atividade.Anexos tabela Os anexos de arquivo que o usuário fornece.
Atividade.Canal opção O ID do canal da conversa atual.
Activity.ChannelData any Um objeto que contém conteúdo específico do canal.
Activity.ChannelId cadeia O ID do canal da conversa atual, como uma cadeia de caracteres.
Activity.From.Id cadeia ID exclusivo do remetente específico do canal.
Activity.From.Name cadeia Nome amigável específico do canal do usuário remetente.
Activity.Nome cadeia O nome do evento.
Activity.Recipient.Id cadeia A propriedade Tipo de atividade de entrada.
Activity.Recipient.Name cadeia Representa o nome de exibição do agente no canal. No contexto do canal de telefonia, o valor dessa variável é o número de telefone ao qual o agente está anexado.
Atividade.Texto cadeia A mensagem mais recente enviada pelo usuário.
Tipo de Atividade opção Tipo de atividade.
Activity.TypeId cadeia Tipo de atividade, como uma cadeia de caracteres.
Activity.Value any Valor indeterminado.
Bot.EnvironmentId cadeia O identificador do ambiente do agente.
Bot.Id cadeia A ID do agente.
Bot.Name cadeia O nome do seu agente.
Bot.SchemaName cadeia O nome do esquema do agente.
Bot.TenantId cadeia A ID de locatário do agente.
ClientPluginActions opção Coleção de Ações de Plug-in de Cliente Dinâmico a serem consideradas para orquestração generativa.
Conversation.Id cadeia O ID exclusivo da conversa atual.
Conversation.InTestMode booleano Sinalizador booliano que representa se a conversa está acontecendo na tela de teste.
Conversation.LocalTimeZone cadeia Nome do fuso horário que o usuário deve usar no formato do banco de dados de Fuso Horário IANA.
Conversation.LocalTimeZoneOffset datetime A diferença de horário em relação ao UTC para o fuso horário local no momento.
Error.Code cadeia O código de erro para o erro atual.
A mensagem de erro para o erro atual.
Erro.Mensagem cadeia A mensagem de erro para o erro atual.
Observação: essa variável só é compatível se o gatilho for On Error.
FallbackCount Número Essa variável conta as vezes em que um tópico não pôde ser correspondida à entrada do usuário.
Observação: essa variável só é compatível se o gatilho for On Unknown Intent.
InactivityTimer.Continue booleano Sinalizador booliano que representa se o temporizador precisa continuar.
Observação: essa variável só é compatível se o gatilho for Inactivity.
InactivityTimer.Count Número Número de vezes que o temporizador OnInactivity foi acionado devido à inatividade do usuário após o tempo configurado.
Observação: essa variável só é compatível se o gatilho for Inactivity. Saiba mais no gatilho de inatividade sobre como configurar gatilhos de inatividade e usar essas variáveis.
LastMessage.Id cadeia ID da mensagem anterior enviada pelo usuário.
ÚltimaMensagem.Texto cadeia A mensagem anterior enviada pelo usuário.
Recognizer.ExtractedEntities opção Representa as entidades extraídas da mensagem disparadora.
Observação: essa variável só é compatível se o gatilho for On Select Intent.
Recognizer.IntentOptions opção Representa as opções de intenção quando o reconhecedor retorna resultados ambíguos.
Observação: essa variável só é compatível se o gatilho for On Select Intent.
Recognizer.SelectedIntent opção Representa a intenção selecionada do reconhecedor.
Observação: essa variável só é compatível se o gatilho for On Select Intent.
Recognizer.TriggeringMessage.Id cadeia A ID da mensagem do usuário que acionou o tópico atual.
Recognizer.TriggeringMessage.Text cadeia A mensagem do usuário que acionou o tópico atual.
Razão.MultiplosTópicosCorrespondidos cadeia Usado para determinar por que vários tópicos foram correspondidos.
Observação: essa variável só é compatível se o gatilho for On Select Intent.
Motivo de Login opção Usado para determinar qual opção de entrada é necessária ao acionar o tópico.
Observação: essa variável só é compatível se o gatilho for On Sign In.
Usuário.Idioma opção Essa variável é usada para definir a localidade de idioma do usuário por conversa.

Variáveis para autenticação integrada (padrão)

As variáveis a seguir estão disponíveis para agentes configurados para se autenticarem com a Microsoft. Essa configuração usa a autenticação do Microsoft Entra ID e é o padrão para novos agentes.

Para obter mais informações, consulte Variáveis de autenticação.

Name Tipo Definição
Usuário.NomeDeExibição cadeia O nome de exibição do usuário que está atualmente falando com o agente.
Usuário.Email cadeia O endereço de e-mail do usuário que está falando com o agente.
Usuário.PrimeiroNome cadeia O primeiro nome do usuário que está falando com o agente.
Id do Usuário cadeia O ID exclusivo do usuário que está falando com o agente.
Usuário.EstáLogado booleano Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não.
Sobrenome do Usuário cadeia O nome da família do usuário que está falando com o agente.
User.PrincipalName cadeia O nome UPN do usuário que está falando atualmente com o agente.

Variáveis para autenticação manual com OAuth 2 Genérico

As variáveis a seguir estão disponíveis para agentes configurados para usar o provedor de serviços Genérico OAuth 2.

Name Tipo Definição
User.AccessToken cadeia O token de acesso para o usuário se autenticar com o agente.
Usuário.NomeDeExibição cadeia O nome de exibição do usuário que está atualmente falando com o agente.
Id do Usuário cadeia O ID exclusivo do usuário que está falando com o agente.
Usuário.EstáLogado booleano Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não.

Variáveis para autenticação manual com o Microsoft Entra ID

As variáveis a seguir estão disponíveis para agentes configurados para usar os provedores de serviço do Microsoft Entra ID (anteriormente Azure Active Directory).

Name Tipo Definição
User.AccessToken cadeia O token de acesso para o usuário se autenticar com o agente.
Usuário.NomeDeExibição cadeia O nome de exibição do usuário que está atualmente falando com o agente.
Usuário.Email cadeia O endereço de e-mail do usuário que está falando com o agente.
Usuário.PrimeiroNome cadeia O primeiro nome do usuário que está falando com o agente.
Id do Usuário cadeia O ID exclusivo do usuário que está falando com o agente.
Usuário.EstáLogado booleano Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não.
Sobrenome do Usuário cadeia O nome da família do usuário que está falando com o agente.
User.PrincipalName cadeia O nome principal do usuário que está falando com o agente.

Variáveis para agentes habilitados para voz

As variáveis a seguir estão disponíveis apenas em agentes habilitados para voz.

Note

Para obter mais informações sobre variáveis agente habilitadas para voz, consulte Usar variáveis de voz.

Name Tipo Definição
Activity.InputDTMFKeys cadeia O valor bruto da chave DTMF da telefonia.
Activity.SpeechRecognition.Confiança Número A pontuação de confiança para o resultado inteiro da hipótese de Recuperação de Site do Azure, 0 a 1.
Activity.SpeechRecognition.MinimallyFormattedText cadeia Texto ligeiramente formatado do resultado da hipótese de Recuperação de Site do Azure. Por exemplo, "Quinhentos dólares." As palavras são escritas por extenso, mas a capitalização básica e a pontuação são incluídas.
Activity.UserInputType opção O tipo de entrada mais recente do usuário que interage com o agente. O valor pode ser teste, fala ou DTMF.
Conversation.OnlyAllowDTMF booleano Sinalizador booliano que representa se o IVR deve ser definido para o modo somente DTMF no tempo de execução.
Conversation.SipUuiHeaderValue cadeia A cadeia de caracteres de cabeçalho UUI usada para passar o contexto para o IVR no início da chamada.
  • Last updated on